diff --git a/README.md b/README.md index 83f544e7a3b020fd85a40721e2cd1ee3419a67a9..518ddaafef030118642695477f3b8759dbc24910 100644 --- a/README.md +++ b/README.md @@ -51,7 +51,7 @@ ├── docs/ # 项目文档 │ ├── 00-项目要求/ # 项目要求、验收标准、评分标准(教师发布,勿改) │ ├── 01-需求文档/ # 需求规格说明书 -│ ├── 02-设计文档/ # 架构、数据库、接口与跨技术栈命名规范 +│ ├── 02-设计文档/ # 业务流程、架构、数据库、接口与跨技术栈命名规范 │ ├── 03-测试文档/ # 测试计划、测试报告 │ ├── 04-会议记录/ # 小组会议纪要 │ └── 05-总结答辩/ # 项目总结报告、答辩材料 diff --git "a/docs/01-\351\234\200\346\261\202\346\226\207\346\241\243/\351\234\200\346\261\202\350\247\204\346\240\274\350\257\264\346\230\216\344\271\246.md" "b/docs/01-\351\234\200\346\261\202\346\226\207\346\241\243/\351\234\200\346\261\202\350\247\204\346\240\274\350\257\264\346\230\216\344\271\246.md" index 7efe1b893c124386d8eebd0ccf9a09c667a261ca..ed610fd2ab2815560e703d33d47440e91953bd71 100644 --- "a/docs/01-\351\234\200\346\261\202\346\226\207\346\241\243/\351\234\200\346\261\202\350\247\204\346\240\274\350\257\264\346\230\216\344\271\246.md" +++ "b/docs/01-\351\234\200\346\261\202\346\226\207\346\241\243/\351\234\200\346\261\202\350\247\204\346\240\274\350\257\264\346\230\216\344\271\246.md" @@ -11,6 +11,10 @@ |---|---|---|---| | v0.1 | 2026-07-24 | 全体成员(罗皓晨统稿) | 形成并统一需求规格,明确四类角色、必做功能、4 项选做、7 项挑战、单店 B2C 边界、核心状态与六人模块职责 | +## 业务流程设计入口 + +本文件是正式需求的唯一事实源,不再按负责人拆分个人需求文件。跨角色、跨模块和包含状态变化的详细图统一维护在 [`../02-设计文档/process/业务流程设计.md`](../02-设计文档/process/业务流程设计.md);流程图只负责可视化本文件已经确认的业务语义,不替代功能需求、异常规则和验收标准。 + ## 一、引言 ### 1.1 编写目的 @@ -130,6 +134,8 @@ flowchart LR D --> E[重复取消不重复回补] ``` +F01~F13 的分模块详细流程、跨模块分支和异常回滚见 [`业务流程设计`](../02-设计文档/process/业务流程设计.md#三f01f13-核心业务流程)。本节只保留商城总体链路和需求级取消规则。 + ### 2.4 功能模块清单 | 模块编号 | 模块名称 | 优先级 | 对应验收项 | 负责人 | diff --git "a/docs/02-\350\256\276\350\256\241\346\226\207\346\241\243/interface/interface-gxy.md" "b/docs/02-\350\256\276\350\256\241\346\226\207\346\241\243/interface/interface-gxy.md" index 9abcd11448165f0949b1cbf6adcb2219767f00ed..f21332d95b3c6c7f99278951d845dd92000a2e5f 100644 --- "a/docs/02-\350\256\276\350\256\241\346\226\207\346\241\243/interface/interface-gxy.md" +++ "b/docs/02-\350\256\276\350\256\241\346\226\207\346\241\243/interface/interface-gxy.md" @@ -15,10 +15,10 @@ - 通用约定(前缀、鉴权、成功/失败响应包装、ProblemDetails、分页、幂等、状态码等)一律以总《接口设计》第一章为准,本文件不重复,只在接口内标注差异。 - 命名(模块词根、路径、`operationId`、Schema、错误码、字段大小写)以《[命名规范.md](../命名规范.md)》为准:Catalog 词根 `categories`/`products`/`product_images`,Review 词根 `reviews`/`review_images`。 - 状态枚举对外统一使用英文 `PascalCase`(规范 2.2),不暴露整数序号;数据库落库使用 `lower_snake_case`,二者映射见第六章枚举附录。本文件所有 `status`、`stockStatus`、`reason` 字段值均为对外 PascalCase。 -- 关联的 `DBxxx` 为本人 `DB021`~`DB040` 区间的临时登记,需与 `database-gxy.md` 交叉确认后固定;当前标记“待数据库确认”。 +- 关联的 `DBxxx` 为本人 `DB021`~`DB040` 区间的临时登记,需与 `docs/02-设计文档/database/database-gxy.md` 交叉确认后固定;当前标记“待数据库确认”。 - 覆盖需求:M02-01(F04、F05)、M02-02(F06)、M06-01(F11)、M07(X01)、C04;其中 C04 复用 M02-01 的同一列表接口,仅替换底层搜索实现,返回口径不变。 -### 关联数据表(临时登记,待 `database-gxy.md` 确认) +### 关联数据表(临时登记,待 `docs/02-设计文档/database/database-gxy.md` 确认) | DBxxx | 表(标准词根) | 所属模块 | 主要接口 | |---|---|---|---| @@ -1210,7 +1210,7 @@ ## 五、待确认事项 -1. `DB021`~`DB025` 编号需与本人 `database-gxy.md` 交叉确认并固定;表字段、约束、索引以数据库设计为准。 +1. `DB021`~`DB025` 编号需与本人 `docs/02-设计文档/database/database-gxy.md` 交叉确认并固定;表字段、约束、索引以数据库设计为准。 2. A124、A142、A143 依赖 Ordering(韦乾强)提供“订单项归属 + 订单完成状态 + 是否存在订单关联”的应用契约,需在联调前确认契约形态。 3. 罗皓晨只协作提供 C07 缓存基础设施与 Key 规范;Catalog 负责人维护缓存失效时机及 C04 的 PostgreSQL `pg_trgm`/GIN 查询与索引设计。 4. 上传体积超限(A127、A141)统一引用总《接口设计》1.10 已登记的 `COMMON.PAYLOAD_TOO_LARGE`(413);本文件不重复自建 `COMMON.*` 错误码。 @@ -1227,4 +1227,4 @@ | 评价资格原因 `reason` | A143 | `Eligible` / `OrderNotCompleted` / `AlreadyReviewed` | 由订单与评价状态计算,不落库 | 可评价及不可评价原因 | | 排序方向 `sortOrder` | A102、A120、A140 | `asc` / `desc`(小写,规范 1.11.3) | — | 升序 / 降序 | -> 落库值仅为跨文档参考,最终以 `database-gxy.md` 与实体映射为准;已删除商品在购物端按“不存在”处理,不作为对外枚举值暴露。 +> 落库值仅为跨文档参考,最终以 `docs/02-设计文档/database/database-gxy.md` 与实体映射为准;已删除商品在购物端按“不存在”处理,不作为对外枚举值暴露。 diff --git "a/docs/02-\350\256\276\350\256\241\346\226\207\346\241\243/interface/interface-lhc.md" "b/docs/02-\350\256\276\350\256\241\346\226\207\346\241\243/interface/interface-lhc.md" index 4fbfaa56689a0e991c1f2cbb61321661bf8f81a4..6640b65e82872d27e54c9f19c375e423dfd1e0db 100644 --- "a/docs/02-\350\256\276\350\256\241\346\226\207\346\241\243/interface/interface-lhc.md" +++ "b/docs/02-\350\256\276\350\256\241\346\226\207\346\241\243/interface/interface-lhc.md" @@ -24,17 +24,17 @@ - C07 不新增缓存管理 HTTP 接口,继续复用 Catalog 的首页和商品详情接口;缓存命中与降级不得改变公开契约。 - C10 登记存活和就绪两个公共健康检查接口。它们不使用 `/api` 前缀,也不返回通用业务包装。 - 对象存储、Redis、RabbitMQ、Outbox/Inbox 和 Worker 属于内部基础设施或异步契约,不为了占用编号而创建无业务依据的公共 HTTP 接口。 -- 当前 `database-lhc.md` 尚未建立,Messaging 接口的关联数据表暂标记为“待数据库设计确认”;接口实现前必须补齐 DBxxx、字段、约束和索引追踪。 +- 当前 `docs/02-设计文档/database/database-lhc.md` 尚未建立,Messaging 接口的关联数据表暂标记为“待数据库设计确认”;接口实现前必须补齐 DBxxx、字段、约束和索引追踪。 ## 二、接口清单 | 编号 | 模块 | 需求编号 | 名称 | 方法 | 路径 | operationId | 请求 Schema | 响应 Schema | 鉴权 | 关联 DBxxx | 状态 | |---|---|---|---|---|---|---|---|---|---|---|---| -| A501 | Messaging | X03-FR03 | 查询本人消息列表 | GET | `/api/messages` | `Messaging_ListMessages` | Query 参数 | `MessageListResponse` | BuyerOnly / MerchantOnly | 待 `database-lhc.md` 确认 | 待评审 | -| A502 | Messaging | X03-FR04 | 查询本人消息详情 | GET | `/api/messages/{messageId}` | `Messaging_GetMessage` | Route 参数 | `MessageDetailResponse` | BuyerOnly / MerchantOnly | 待 `database-lhc.md` 确认 | 待评审 | -| A503 | Messaging | X03-FR05 | 查询本人未读消息数 | GET | `/api/messages/unread-count` | `Messaging_GetUnreadCount` | 无 | `UnreadMessageCountResponse` | BuyerOnly / MerchantOnly | 待 `database-lhc.md` 确认 | 待评审 | -| A504 | Messaging | X03-FR06 | 标记本人单条消息已读 | POST | `/api/messages/{messageId}/read` | `Messaging_MarkMessageRead` | Route 参数 | `MarkMessageReadResponse` | BuyerOnly / MerchantOnly | 待 `database-lhc.md` 确认 | 待评审 | -| A505 | Messaging | X03-FR07 | 标记本人当前消息全部已读 | POST | `/api/messages/read-all` | `Messaging_MarkAllMessagesRead` | 无 | `MarkAllMessagesReadResponse` | BuyerOnly / MerchantOnly | 待 `database-lhc.md` 确认 | 待评审 | +| A501 | Messaging | X03-FR03 | 查询本人消息列表 | GET | `/api/messages` | `Messaging_ListMessages` | Query 参数 | `MessageListResponse` | BuyerOnly / MerchantOnly | 待 `docs/02-设计文档/database/database-lhc.md` 确认 | 待评审 | +| A502 | Messaging | X03-FR04 | 查询本人消息详情 | GET | `/api/messages/{messageId}` | `Messaging_GetMessage` | Route 参数 | `MessageDetailResponse` | BuyerOnly / MerchantOnly | 待 `docs/02-设计文档/database/database-lhc.md` 确认 | 待评审 | +| A503 | Messaging | X03-FR05 | 查询本人未读消息数 | GET | `/api/messages/unread-count` | `Messaging_GetUnreadCount` | 无 | `UnreadMessageCountResponse` | BuyerOnly / MerchantOnly | 待 `docs/02-设计文档/database/database-lhc.md` 确认 | 待评审 | +| A504 | Messaging | X03-FR06 | 标记本人单条消息已读 | POST | `/api/messages/{messageId}/read` | `Messaging_MarkMessageRead` | Route 参数 | `MarkMessageReadResponse` | BuyerOnly / MerchantOnly | 待 `docs/02-设计文档/database/database-lhc.md` 确认 | 待评审 | +| A505 | Messaging | X03-FR07 | 标记本人当前消息全部已读 | POST | `/api/messages/read-all` | `Messaging_MarkAllMessagesRead` | 无 | `MarkAllMessagesReadResponse` | BuyerOnly / MerchantOnly | 待 `docs/02-设计文档/database/database-lhc.md` 确认 | 待评审 | | A506 | Infrastructure | C10-FR06 | API 存活检查 | GET | `/health/live` | `Infrastructure_GetLiveness` | 无 | `HealthStatusResponse` | Anonymous | 无 | 待评审 | | A507 | Infrastructure | C10-FR06 | API 就绪检查 | GET | `/health/ready` | `Infrastructure_GetReadiness` | 无 | `ReadinessStatusResponse` | Anonymous | 无 | 待评审 | @@ -109,7 +109,7 @@ - 模块 / Tag:Messaging - 需求编号:X03-FR03、X03-FR10、X03-FR11 - 负责人:罗皓晨 -- 关联数据表:待 `database-lhc.md` 确认 +- 关联数据表:待 `docs/02-设计文档/database/database-lhc.md` 确认 - 当前状态:待评审 - 用途:按创建时间倒序分页查询当前用户自己的消息。 - 方法与路径:`GET /api/messages` @@ -210,7 +210,7 @@ - 模块 / Tag:Messaging - 需求编号:X03-FR04、X03-FR11 - 负责人:罗皓晨 -- 关联数据表:待 `database-lhc.md` 确认 +- 关联数据表:待 `docs/02-设计文档/database/database-lhc.md` 确认 - 当前状态:待评审 - 用途:查询当前用户拥有的一条完整站内消息。 - 方法与路径:`GET /api/messages/{messageId}` @@ -289,7 +289,7 @@ - 模块 / Tag:Messaging - 需求编号:X03-FR05、C06-FR05 - 负责人:罗皓晨 -- 关联数据表:待 `database-lhc.md` 确认 +- 关联数据表:待 `docs/02-设计文档/database/database-lhc.md` 确认 - 当前状态:待评审 - 用途:为消息入口角标、首次连接和断线重连补偿提供当前未读总数。 - 方法与路径:`GET /api/messages/unread-count` @@ -351,7 +351,7 @@ - 模块 / Tag:Messaging - 需求编号:X03-FR06 - 负责人:罗皓晨 -- 关联数据表:待 `database-lhc.md` 确认 +- 关联数据表:待 `docs/02-设计文档/database/database-lhc.md` 确认 - 当前状态:待评审 - 用途:幂等地记录当前用户一条消息的首次已读时间。 - 方法与路径:`POST /api/messages/{messageId}/read` @@ -418,7 +418,7 @@ - 模块 / Tag:Messaging - 需求编号:X03-FR07 - 负责人:罗皓晨 -- 关联数据表:待 `database-lhc.md` 确认 +- 关联数据表:待 `docs/02-设计文档/database/database-lhc.md` 确认 - 当前状态:待评审 - 用途:将操作开始时当前用户已经存在的未读消息批量标记为已读。 - 方法与路径:`POST /api/messages/read-all` @@ -740,7 +740,7 @@ Ordering、Payment 和 AfterSales 使用统一 `MessagingSourceEventV1` 信封 ### 7.2 实现前必须补齐 -- 创建并评审 `database-lhc.md`,登记消息表及必要的唯一约束、用户未读查询索引和关联 A501~A505。 +- 创建并评审 `docs/02-设计文档/database/database-lhc.md`,登记消息表及必要的唯一约束、用户未读查询索引和关联 A501~A505。 - 由 Ordering、Payment、AfterSales 负责人确认 5.1 已登记的事件映射和接收账号;这些契约不占 HTTP Axxx 编号。 - 在后端脚手架建立后形成真实 OpenAPI,并保证 `operationId`、Schema、状态码和错误码与本文件一致。 - 在测试计划中登记 X03、C06 和 C10 的分页、越权、重复已读、并发全部已读、断线重连、多标签页、多实例和健康检查场景。 diff --git "a/docs/02-\350\256\276\350\256\241\346\226\207\346\241\243/interface/interface-zhy.md" "b/docs/02-\350\256\276\350\256\241\346\226\207\346\241\243/interface/interface-zhy.md" index 715e70153e66b28200f3d41a3de6645689922fd2..ceeb82f3a024728b87535b56f4bfb7afc541709d 100644 --- "a/docs/02-\350\256\276\350\256\241\346\226\207\346\241\243/interface/interface-zhy.md" +++ "b/docs/02-\350\256\276\350\256\241\346\226\207\346\241\243/interface/interface-zhy.md" @@ -8,7 +8,7 @@ > **当前状态**:已汇总到主文档,个人文件继续保留用于贡献与评审追踪;实现、OpenAPI 和联调以 `../接口设计.md` 为准 > **关联规范**:`docs/02-设计文档/接口设计.md` v0.1 + `docs/02-设计文档/命名规范.md` + `docs/02-设计文档/Git团队协作流程.md` > **关联根命名空间**:`Mall.Modules.Payment`、`Mall.Modules.AfterSales` -> **关联数据库**:DB081~DB100(**待评审**:`database-zhy.md` 尚未创建,本文档字段暂时按命名规范推断) +> **关联数据库**:DB081~DB100(**待评审**:`docs/02-设计文档/database/database-zhy.md` 尚未创建,本文档字段暂时按命名规范推断) --- @@ -26,7 +26,7 @@ 4. `operationId` 统一 `_`,全小写 PascalCase 拼接。 5. 业务错误码格式:`PAYMENT.` / `AFTER_SALES.`;支付对账错误统一使用 `PAYMENT.RECONCILIATION_`,仍归属 Payment 模块,不建立独立 Reconciliation 业务模块。 6. 涉及资金、状态、回调的接口强制 `Idempotency-Key`(按 1.12.1)。 -7. 字段同时承担数据库来源的,在"关联数据表"标注推断;正式评审以 `database-zhy.md` 为准。 +7. 字段同时承担数据库来源的,在"关联数据表"标注推断;正式评审以 `docs/02-设计文档/database/database-zhy.md` 为准。 --- @@ -2235,7 +2235,7 @@ RefundDetailResponse { ### 4.1 不在本文件范围 -- `database-zhy.md`(DB081~DB100)—— 单独分支 `chore/database-zhy` 推进 +- `docs/02-设计文档/database/database-zhy.md`(DB081~DB100)由数据库设计任务单独推进。 - C08 FR11~FR15 扩展接口(dev 当前只有 FR01~FR10)—— 单独 PR 处理 - 集成事件命名最终确认(与罗皓晨对齐 M00 集成事件规范) - AdminOnly Policy 命名(与罗皓晨 M00 公共 HTTP 接口对齐) diff --git "a/docs/02-\350\256\276\350\256\241\346\226\207\346\241\243/process/README.md" "b/docs/02-\350\256\276\350\256\241\346\226\207\346\241\243/process/README.md" new file mode 100644 index 0000000000000000000000000000000000000000..6cd91f8360f11be4c963da5188cf3e63ad2f7881 --- /dev/null +++ "b/docs/02-\350\256\276\350\256\241\346\226\207\346\241\243/process/README.md" @@ -0,0 +1,221 @@ +# 业务流程目录与填写说明 + +> 适用目录:`docs/02-设计文档/process/` +> +> 目标:按负责人分目录、按业务模块分文档维护流程;需求规格仍保持一份,不按个人拆分。 + +## 一、目录怎么分 + +```text +process/ +├─ README.md # 目录、分工、模板和检查标准 +├─ 业务流程设计.md # 全局核心基线、状态基线、跨模块交接和追踪索引 +├─ tyh/ # 唐宇昊 +├─ gxy/ # 顾欣月 +├─ zhh/ # 朱惠惠 +├─ wqq/ # 韦乾强 +├─ zhy/ # 张海洋 +└─ lhc/ # 罗皓晨 +``` + +维护边界: + +- [`业务流程设计.md`](业务流程设计.md) 只保留全局核心链路、公共状态、跨模块直接交接、文档索引和成熟度,不长期重复保存个人模块的完整细节。 +- 每位负责人只在本人目录维护文档;一个业务模块或挑战项对应一份文档。 +- 统稿人只建立目录、文件名、空模板、核心基线和交接约束,不代替负责人填写模块主流程、状态转换或异常细节。 +- 个人模块文档完成并通过交叉评审后,根文档中的同类详细图改为链接;迁移期间不得同时修改两份相同流程。 +- 文件名使用“稳定模块编号 + 中文名称 + 流程”,例如 `M04-订单流程.md`、`C03-订单超时流程.md`。 + +## 二、每个人从哪里开始 + +每位负责人只需要按下面顺序操作: + +1. 在 [`../../01-需求文档/需求规格说明书.md`](../../01-需求文档/需求规格说明书.md) 找到本人模块的完整章节,确认前置条件、主流程、异常流程、状态和验收标准。 +2. 在 [`业务流程设计.md`](业务流程设计.md) 找到本人负责的 F01~F13 核心状态和跨模块入口、出口。 +3. 在本人目录找到对应模块文档;只有负责人本人填写业务细节。 +4. 画 X/C 前先确认其基础 F、核心接入状态和不可变结果,不能另起一套主链路。 +5. 跨模块部分在本人图中标出模块节点,并请直接协作人确认;统稿人再同步根文档交接图。 +6. 业务流程评审后,按流程中的业务动作、输入输出、状态和异常结果派生接口能力,并反查接口、数据库和架构是否完整承接。 +7. 完成后更新根追踪索引的文档链接和成熟度。 + +流程图只表达业务动作、判断、状态和异常结果。HTTP 路径、DTO、数据库字段、类名和部署命令分别回到接口、数据库和架构文档维护。 + +设计顺序固定为“需求确认 → 业务流程 → 接口/数据库/架构落地”。接口跟着流程走:Axxx 只能在业务流程完成后用于契约映射,不能把接口清单直接拼成流程,也不能用现有接口的缺失或冲突反向覆盖已确认的业务状态和分支。“接口文档先行”仅表示接口必须先于代码实现和调用方修改完成确认,不表示接口先于业务流程。 + +## 三、核心流程是唯一扩展基线 + +所有 X/C 流程都必须建立在 F01~F13 之上: + +- 图内必须标明基础 F、直接模块入口、接入时的核心状态、扩展出口以及回归的核心状态。 +- 扩展可以增加自己的数据和状态,但不能自行修改核心账号、商品或订单状态机。 +- 扩展失败不能破坏核心订单、支付、库存、快照和权限结果。 +- 需要改变核心流程时,先修改主需求和对应 F 流程并重新评审,不能让扩展图反向覆盖核心流程。 +- 基础 F 尚未确认时,扩展最多标记为“待交叉评审”,不能标记为“已确认”。 + +允许分层接入,但必须最终追溯到核心 F,例如: + +```text +C06 实时推送 → X03 持久化消息 → F08/F09/F10/F12 的已提交业务事实 +C08 退款对账 → X04 售后退款 → F09/F10 的订单项和支付事实 +``` + +## 四、负责人目录与模块文档 + +| 负责人 | 目录 | 核心模块文档 | 扩展/挑战文档 | 主要联调人 | +|---|---|---|---|---| +| 唐宇昊 | `tyh/` | `M01-用户与鉴权流程.md`、`M06-03-后台用户管理流程.md` | `M08-收藏与浏览历史流程.md` | 顾欣月、罗皓晨 | +| 顾欣月 | `gxy/` | `M02-分类与商品流程.md`、`M06-01-后台商品管理流程.md` | `M07-商品评价流程.md`、`C04-中文搜索流程.md` | 朱惠惠、韦乾强、罗皓晨 | +| 朱惠惠 | `zhh/` | `M03-购物车流程.md` | `C01-秒杀流程.md` | 顾欣月、韦乾强、张海洋 | +| 韦乾强 | `wqq/` | `M04-订单流程.md`、`M06-02-商家履约流程.md` | `C03-订单超时流程.md` | 朱惠惠、张海洋、罗皓晨 | +| 张海洋 | `zhy/` | [`M05-支付流程.md`](zhy/M05-支付流程.md)、`M10-售后流程.md` | `C08-支付回调与对账流程.md` | 韦乾强、罗皓晨 | +| 罗皓晨 | `lhc/` | `M09-站内消息流程.md` | `C06-实时推送流程.md`、`C07-缓存流程.md`、`C10-高可用流程.md` | 各相关业务负责人 | + +以上只规定目录、文件名、负责人和联调关系,不代表统稿人已经替负责人完成流程内容。跨模块流程不能由单方标记为“已确认”。 + +## 五、每张流程图必须包含什么 + +一张可评审的业务流程图至少应表达: + +1. 基础 F,以及扩展从核心流程哪个状态或确定结果开始。 +2. 谁触发流程,以及触发入口。 +3. 直接上游模块、传入的业务事实和状态。 +4. 必要的登录、角色、资源归属或状态前置条件。 +5. 主要业务动作和会改变结果的判断分支。 +6. 成功结果、状态变化和直接下游模块出口。 +7. 失败、拒绝、超时或并发冲突后的状态。 +8. 涉及取消、失败时的回滚或补偿责任。 +9. 扩展完成后回到哪个核心结果,或者作为哪个核心结果的旁路能力。 +10. 不得改变的核心状态、权限、金额、库存、快照和事实来源。 + +普通流程建议控制在 8~15 个节点。图过长时按业务阶段拆成两张,不要在一个节点中堆积整段需求文字。 + +业务图中的节点使用“查询本人钱包”“确认支付”“取消订单”等业务动作,不使用 Axxx、HTTP 路径、Controller 或 DTO 名称代替。图评审完成后,可在正文后追加“流程步骤 → Axxx”的映射表,用于派生接口契约和暴露契约缺口。 + +跨模块流程实行“双表达”:业务 Mermaid 图内部必须出现直接上游模块、输入事实、入口状态、直接下游模块和确定出口;同时在《业务流程设计》3.8 更新独立的模块交接图,集中说明成功、拒绝、状态竞争和事务失败分别回到哪里。独立交接图不能替代业务图中的模块节点。 + +## 六、可直接复制的模板 + +### 6.1 普通业务流程模板 + +````markdown +## 一、X01 商品评价与重复评价拦截 + +> - 覆盖:X01、M07 +> - 主责人:顾欣月 +> - 需求来源:《需求规格说明书》M07 +> - 基础核心流程:F09、F06 +> - 直接入口:M04 已完成且属于当前买家的订单项 +> - 扩展出口:M07 评价记录;M02 商品详情公开评价 +> - 回归核心结果:订单仍为 Completed +> - 不得改变:订单快照、商品销售状态、价格和库存 + +```mermaid +flowchart TD + A["买家从已完成订单进入评价"] --> B{"已登录且订单项属于本人?"} + B -- "否" --> X["拒绝操作"] + B -- "是" --> C{"订单项是否允许评价?"} + C -- "否" --> Y["提示不可评价原因"] + C -- "是" --> D["提交评分、内容和图片"] + D --> E{"是否重复评价?"} + E -- "是" --> Z["拒绝重复提交"] + E -- "否" --> F["保存评价"] + F --> G["商品详情展示评价结果"] +``` + +关键规则: + +- 写与图中判断直接相关的规则,不复制完整需求。 +- 无待确认项时写“无”。 + +待确认: + +- 与订单模块确认“已完成”的唯一判断口径。 +```` + +### 6.2 状态流转模板 + +````markdown +## 一、X04 售后状态流转 + +> - 覆盖:X04、M10 +> - 主责人:张海洋 +> - 需求来源:《需求规格说明书》M10 +> - 基础核心流程:F09、F10、F12 +> - 直接入口:M04 本人 Paid、Shipped 或完成后 7 天内的订单项 +> - 扩展出口:M10 售后结果;退款时由 M05 幂等退回钱包 +> - 回归核心结果:订单保持原核心履约状态 +> - 不得改变:订单项实付快照和核心订单状态 + +```mermaid +stateDiagram-v2 + [*] --> 待审核: 买家提交申请 + 待审核 --> 已撤销: 买家在审核前撤销 + 待审核 --> 已拒绝: 审核拒绝 + 待审核 --> 退款中: 仅退款审核通过 + 待审核 --> 待退货: 退货退款审核通过 + 待退货 --> 待收货: 买家提交退货 + 待收货 --> 退款中: 商家确认收货 + 退款中 --> 已退款: 钱包退款成功 + 退款中 --> 退款失败: 钱包退款失败 + 退款失败 --> 退款中: 幂等重试 + 已撤销 --> [*] + 已拒绝 --> [*] + 已退款 --> [*] +``` + +关键规则: + +- 每条箭头必须能在需求中找到触发条件。 +- 不确定的状态不要自行新增,写入“待确认”。 +```` + +## 七、成熟度怎么填写 + +| 状态 | 使用条件 | +|---|---| +| 待细化 | 只有登记项,还没有完整流程图 | +| 初稿 | 已覆盖主流程和主要异常,但负责人尚未完成自查 | +| 待交叉评审 | 负责人已对照需求自查,等待关联模块确认边界 | +| 已确认 | 主责人、直接协作人和所依赖的核心 F 负责人均已确认,需求文字、状态和出入口一致 | + +成熟度只表示“流程文档的确认程度”,不代表接口、代码或测试已经完成。 +基础 F 未确认时,依赖它的扩展流程不得标记为“已确认”。 + +## 八、提交前检查 + +- [ ] 图中的 F、X、C、M 编号与需求一致。 +- [ ] 已写清基础 F、核心接入状态和回归结果。 +- [ ] Mermaid 图内部包含直接上游模块输入和直接下游模块出口。 +- [ ] 跨模块流程已同步更新 3.8 独立交接图,且包含成功与失败出口。 +- [ ] 主流程、拒绝分支、失败分支和最终结果齐全。 +- [ ] 状态名称与需求规格说明书一致。 +- [ ] 没有增加或覆盖核心账号、商品、订单或支付状态。 +- [ ] 扩展失败不会改变核心权限、金额、库存、快照和事实来源。 +- [ ] 先完成业务流程和状态评审,再建立“流程步骤 → Axxx”映射。 +- [ ] Mermaid 节点使用业务动作,没有用接口编号、HTTP 路径或 DTO 代替流程。 +- [ ] 没有自行发明接口编号、字段名或数据库状态码。 +- [ ] 跨模块流程已找直接协作人和基础 F 负责人评审。 +- [ ] 已更新追踪矩阵或登记表中的成熟度。 +- [ ] Mermaid 代码块能够正常渲染。 +- [ ] 相对链接有效,文件保持 UTF-8 编码。 +- [ ] 已运行 `git diff --check`。 + +## 九、不会画时怎么处理 + +先按下面格式把文字发给统稿人或直接协作人,不要凭猜测补图: + +```text +流程编号: +基础核心流程: +触发人: +直接上游模块与输入: +开始状态: +正常步骤: +失败情况: +直接下游模块与输出: +最终或回归状态: +不得改变的核心结果: +当前不确定点: +``` + +业务规则未确认时,保留“待确认”,不得为了让图看起来完整而自行补造业务语义。 diff --git "a/docs/02-\350\256\276\350\256\241\346\226\207\346\241\243/process/zhy/M05-\346\224\257\344\273\230\346\265\201\347\250\213.md" "b/docs/02-\350\256\276\350\256\241\346\226\207\346\241\243/process/zhy/M05-\346\224\257\344\273\230\346\265\201\347\250\213.md" new file mode 100644 index 0000000000000000000000000000000000000000..3f901185d927d2e422cb8a2d6d5722c469654872 --- /dev/null +++ "b/docs/02-\350\256\276\350\256\241\346\226\207\346\241\243/process/zhy/M05-\346\224\257\344\273\230\346\265\201\347\250\213.md" @@ -0,0 +1,224 @@ +# M05 支付流程 + +> 负责人:张海洋 +> 覆盖:M05-01、F10 +> 基础核心流程:F08、F09 +> 直接协作:韦乾强(M04 Ordering)、罗皓晨(M09 消息) +> 文档状态:初稿,待张海洋自审及 Ordering 交叉评审 +> 需求事实源:[需求规格说明书 M05-01](../../../01-需求文档/需求规格说明书.md) 的“M05-01 模拟支付(F10)”完整七节 + +## 一、范围与事实来源 + +本模块负责买家“小金库”的余额查询、模拟充值、充值记录、统一收银台、模拟支付和支付记录查询。它不接入真实支付渠道,不处理银行卡、第三方支付账户、真实资金结算、售后退款或 C08 异步回调。 + +本文先依据需求确定业务参与者、状态、判断分支、事务结果和模块出入口,再由这些流程步骤派生接口能力。A401~A408 只用于流程完成后的契约映射和缺口检查,不能反向决定或拼接业务流程。 + +| 设计对象 | 当前成熟度 | 本文处理 | +|---|---|---| +| M05-01/F10 需求 | 完整定义 | 作为业务语义事实源 | +| 本文业务流程 | 初稿 | 先确认角色、状态、分支、事务边界和模块出入口 | +| A401~A408 接口 | 部分定义、未冻结 | 由流程派生并做映射;冲突记为接口待评审项 | +| DB081~DB100 数据库设计 | 模板/占位 | 本文不发明表字段、枚举编码和索引 | +| X04/C08 | 独立扩展 | 只登记接入点,不混入 F10 核心状态机 | + +## 二、模块直接出入口 + +```mermaid +flowchart LR + ID["M01 Identity
已认证买家、角色和账号状态"] -->|"BuyerOnly 通过"| PAY["M05 Payment
钱包、充值、支付记录"] + ORD["M04 Ordering
订单号、买家归属、持久化应付金额、当前状态和支付截止时间"] -->|"本人订单事实"| PAY + PAY -->|"充值成功:确定余额和充值流水"| BUYER["买家钱包/充值记录页面"] + PAY -->|"支付成功:确定支付记录
原子推进 PendingPayment → Paid"| ORD + ORD -->|"Paid 订单"| MERCHANT["M06-02 商家待发货入口"] + PAY -. "事务提交后的支付成功事实" .-> MSG["M09 消息持久化/通知"] + TIMEOUT["C03 超时取消"] -->|"竞争 PendingPayment"| ORD + + ID -->|"游客、非买家、账号禁用或令牌失效"| X["拒绝访问,不返回钱包与订单数据"] + ORD -->|"非本人或不存在"| Y["按不存在/无权限处理,不泄露归属"] + PAY -->|"状态竞争或事务失败"| Z["返回当前最终状态
钱包不产生部分扣款"] +``` + +边界约束: + +- M05 只接受订单标识,不接受客户端指定最终扣款金额;实际金额来自 M04 已持久化订单事实。 +- M04、M05 位于同一模块化单体事务边界时,通过公开应用能力协调原子结果,不跨模块访问内部仓储。 +- 支付成功事实只能在支付事务整体成功后交给 M09;具体事件名、Outbox 和 Worker 重试方式由系统架构设计承接,不进入业务流程图。 + +## 三、小金库充值流程 + +```mermaid +flowchart TD + ID["M01:已认证且状态正常的买家"] --> A["查询本人钱包余额"] + A --> B["买家输入模拟充值金额并携带防重复标识"] + B --> C{"金额 > 0、≤ 10000 元
且最多两位小数?"} + C -- "否" --> X["拒绝充值,不增加余额"] + C -- "是" --> D{"该防重复标识已有处理结果?"} + D -- "同标识同请求" --> E["返回首次确定结果,不重复到账"] + D -- "同标识不同金额" --> Y["拒绝标识被不同请求复用"] + D -- "否" --> F["开启充值事务"] + F --> G["原子增加本人余额并记录充值流水和首次结果"] + G --> H{"事务提交成功?"} + H -- "否" --> Z["整体回滚,余额和流水均不改变"] + H -- "是" --> I["返回最新余额和确定充值结果"] + I --> J["买家可查询本人充值记录"] +``` + +充值结果要求: + +- 同一买家、同一充值动作和同一防重复标识只产生一次到账效果。 +- 首次确定结果必须可恢复,不能只存在于会丢失的临时介质中;具体持久化方式由接口和数据库设计承接。 +- 查询和写入全部按当前买家隔离,商家与管理员没有入口。 + +## 四、收银台与模拟支付主流程 + +```mermaid +flowchart TD + ID["M01 直接输入:已认证买家"] --> A["从下单成功页、订单列表或详情进入统一收银台"] + ORD["M04 直接输入:订单号、归属、持久化应付金额、当前状态和支付截止时间"] --> A + A --> B["服务端读取本人订单事实与本人钱包余额"] + B --> C{"订单当前状态?"} + C -- "Paid" --> P0["返回已有确定支付结果,不重复扣款"] + C -- "Cancelled/其他不可支付状态" --> X["拒绝支付并展示当前最终状态"] + C -- "PendingPayment" --> D{"余额充足?"} + D -- "否" --> E["说明差额并进入第三章充值流程"] + E --> B + D -- "是" --> F["买家确认支付并携带防重复标识"] + F --> G{"该防重复标识已有处理结果?"} + G -- "同标识同请求" --> P0 + G -- "同标识不同订单/请求" --> Y["拒绝标识被不同请求复用"] + G -- "否" --> H["开启支付事务并重新读取订单、金额和余额"] + H --> I["对本人钱包执行余额充足条件扣减"] + I --> J{"余额扣减条件命中?"} + J -- "否" --> R["整体回滚并返回余额不足或当前状态"] + J -- "是" --> K["条件推进本人订单 PendingPayment → Paid"] + K --> L{"订单状态条件更新成功?"} + L -- "否" --> R + L -- "是" --> M["记录钱包流水、确定支付记录、首次结果和待发布支付成功事实"] + M --> N{"支付事务提交成功?"} + N -- "否" --> R + N -- "是" --> O["M05 直接输出:支付记录已落库,订单为 Paid"] + O --> P["M04 展示最新详情;M06-02 可查询待发货订单"] +``` + +主流程不规定数据库锁的具体取得顺序,但必须满足以下原子结果: + +```text +钱包扣款成功 ++ 支付钱包流水已写入 ++ 支付记录已写入 ++ 首次处理结果已写入 ++ 订单 PendingPayment → Paid ++ 待发布的支付成功事实已写入 += 同一事务提交成功 +``` + +任一步失败时整体回滚,不允许出现“余额已扣但订单未支付”或“订单已支付但没有支付记录”的部分结果。 + +## 五、核心状态与并发竞争 + +F10 不增加“支付中”等订单状态。同步模拟支付提交前,订单仍是 `PendingPayment`;事务成功后直接成为 `Paid`。 + +```mermaid +stateDiagram-v2 + [*] --> PendingPayment: F08 下单事务成功 + PendingPayment --> Paid: F10 支付事务成功 + PendingPayment --> Cancelled: F09 主动取消或 C03 超时取消成功 + Paid --> Paid: 重复支付返回已有结果 + Cancelled --> Cancelled: 支付重试被拒绝 +``` + +支付与取消竞争: + +```mermaid +flowchart LR + A["订单 PendingPayment"] --> B["F10 支付事务
条件推进为 Paid"] + A --> C["F09/C03 取消事务
条件推进为 Cancelled"] + B --> D{"谁先成功更新状态?"} + C --> D + D -->|"支付胜出"| E["Paid;扣款、记录和支付成功事实同时提交"] + D -->|"取消胜出"| F["Cancelled;支付整体回滚且钱包不扣款"] + D -->|"本方未胜出"| G["重新查询并返回订单当前最终状态"] +``` + +## 六、结果查询与页面反馈 + +```mermaid +flowchart TD + A["已认证买家进入钱包、收银台或支付记录页"] --> B{"查询类型"} + B -- "钱包余额" --> C["返回本人实时余额"] + B -- "充值记录" --> D["分页返回本人充值记录"] + B -- "收银台" --> E["返回本人订单金额、状态、余额和可支付性"] + B -- "订单支付结果" --> F["返回已确定支付结果
无记录时的响应语义待评审"] + B -- "支付记录/详情" --> G["仅返回本人支付记录"] + C --> H["页面展示确定状态和下一步"] + D --> H + E --> H + F --> H + G --> H + A -->|"资源非本人"| X["404/403,不泄露他人记录"] +``` + +网络中断或结果未知时,客户端使用原防重复标识重试,或执行“查询订单支付结果”动作;当前该动作映射为 A406。不得生成新标识诱导重复付款。 + +## 七、异常、回滚与责任 + +| 场景 | M05 处理 | 最终状态/责任 | +|---|---|---| +| 游客、商家、管理员访问 | 拒绝 | 不返回钱包或支付数据 | +| 订单不存在或不属于当前买家 | 按不存在/无权限处理 | 不泄露归属 | +| 充值金额非法 | 拒绝充值 | 余额、流水不变 | +| 余额不足 | 不开启或回滚支付事务 | 订单保持 `PendingPayment` | +| 订单已支付 | 返回已有确定结果 | 订单保持 `Paid`,不重复扣款 | +| 订单已取消 | 拒绝支付 | 订单保持 `Cancelled` | +| 同一防重复标识、同一请求重试 | 返回首次确定结果 | 不重复产生副作用 | +| 同一防重复标识、不同请求 | 返回标识复用冲突 | 不执行新副作用 | +| 支付与取消并发 | 状态条件唯一胜出 | `Paid` 与 `Cancelled` 只能成立一个 | +| 钱包、订单、记录或支付成功事实任一步失败 | 整个支付事务回滚 | 不产生部分扣款或部分状态 | +| 事务后消息发布失败 | 保留已提交支付事实 | M09 按架构确定的可靠机制重试 | + +## 八、由流程派生的接口契约映射 + +本节是第二至七章业务流程的下游映射,不是流程输入。先确认“要完成什么业务动作、处于什么状态、成功或失败后得到什么结果”,再决定由哪个接口承载。若现有 Axxx 与流程冲突,先记录接口缺口并修改接口设计;只有业务需求本身变化时,才回到前文重新评审流程。 + +| 已确认流程能力 | 当前派生接口 | 接口必须承载的业务结果 | 当前状态 | +|---|---|---|---| +| 查询本人钱包余额 | A401 | 仅返回当前买家的确定余额 | 待交叉评审 | +| 对本人钱包模拟充值 | A402 | 校验金额并幂等、原子地产生余额和充值流水结果 | 待交叉评审 | +| 查询本人充值记录 | A403 | 按当前买家隔离并分页返回充值记录 | 待交叉评审 | +| 打开本人订单收银台 | A404 | 基于 M04 持久化订单事实返回金额、状态、余额和可支付性 | 待交叉评审 | +| 确认模拟支付 | A405 | 幂等提交原子支付事务,并处理与取消的状态竞争 | 待交叉评审 | +| 查询订单支付结果 | A406 | 返回当前买家该订单的确定支付结果 | 待交叉评审 | +| 查询本人支付记录 | A407 | 按当前买家隔离并分页返回支付记录 | 待交叉评审 | +| 查询本人支付详情 | A408 | 仅返回当前买家可访问的单笔支付详情 | 待交叉评审 | + +接口详细定义与实现必须承接上述流程结果。当前接口设计拟使用 `Idempotency-Key` 承载“防重复标识”,并需满足接口设计 1.12 的幂等与并发规则以及 4.6 的资金类持久化幂等约束;HTTP 状态码、请求字段和错误码不得反向写入业务图。 + +## 九、扩展接入边界 + +- X04 售后退款通过 Payment 的公开应用能力幂等退回小金库,不直接修改钱包内部数据;不属于本文 F10 主流程。 +- C08 从“支付确认阶段”接入重复/乱序回调与每日对账;在明确替换 F10 的哪个同步步骤之前,不得让同步结果和异步回调同时成为最终支付事实。 +- X03/M09 只消费支付事务提交后的支付成功事实;消息失败不能反向修改支付或订单状态。具体事件名和可靠投递机制由系统架构设计派生。 + +## 十、由流程反查出的接口与数据待评审项 + +1. 已支付订单进入收银台时,流程要求返回已有确定结果;现有 A404 同时出现“非 `PendingPayment` 返回 409”和“已支付收银台仍可读”,接口语义需要按流程统一。 +2. 同 Key、同请求重放必须返回首次确定结果;现有 A405 对已支付订单定义为 `409 PAYMENT.ALREADY_PAID`,还需区分“原 Key 重放”和“新 Key 再次请求”并确认响应。 +3. 最终扣款金额必须来自 M04 持久化订单事实;A405 的 `expectedAmount` 只能承担客户端旧值冲突保护,不能成为扣款事实。 +4. 充值和支付幂等结果必须可恢复;A405 不得把 Redis 作为唯一幂等事实,接口 4.6.2 已要求资金类幂等记录使用数据库唯一约束。 +5. F10 同步核心流程不包含迟到回调;A406 的“取消订单收到迟到成功支付”属于 C08,`PAYMENT.NOT_FOUND` 也不能只根据订单是否为 `PendingPayment/Paid` 推断。 +6. 流程只要求每个买家拥有独立钱包且无钱包记录时余额语义确定;A401 尚未确认钱包是在注册时创建还是首次查询时按需初始化。 +7. 需求尚未定义充值记录和支付记录的 `Pending/Failed/Succeeded` 状态机;A403/A407 草案中的这些状态不能反向写进流程,需先完成业务确认。 +8. DB081~DB100 尚未形成可实施的完整表定义,数据库字段、约束和索引必须由数据库设计任务另行确认。 + +## 十一、验收证据清单 + +- [ ] 合法充值即时到账,重复充值不重复增加余额。 +- [ ] 非法金额、越权钱包和非买家身份被拒绝。 +- [ ] 本人 `PendingPayment` 订单支付后,余额、流水、支付记录、订单和待发布支付成功事实一致。 +- [ ] 余额不足不扣款,订单保持 `PendingPayment`。 +- [ ] 已支付订单重复提交不重复扣款,返回既有结果。 +- [ ] 已取消订单不能通过重试进入 `Paid`。 +- [ ] 支付与主动/超时取消并发时只有一个最终状态。 +- [ ] 模拟任一步失败时事务整体回滚。 +- [ ] 网络结果未知时使用原防重复标识或结果查询动作得到确定结果。 +- [ ] 保留页面、接口响应、数据库事务结果和可靠消息重试证据。 diff --git "a/docs/02-\350\256\276\350\256\241\346\226\207\346\241\243/process/\344\270\232\345\212\241\346\265\201\347\250\213\350\256\276\350\256\241.md" "b/docs/02-\350\256\276\350\256\241\346\226\207\346\241\243/process/\344\270\232\345\212\241\346\265\201\347\250\213\350\256\276\350\256\241.md" new file mode 100644 index 0000000000000000000000000000000000000000..0ba020ff1b9f823c6b0d6e7adc49e67daf1da94b --- /dev/null +++ "b/docs/02-\350\256\276\350\256\241\346\226\207\346\241\243/process/\344\270\232\345\212\241\346\265\201\347\250\213\350\256\276\350\256\241.md" @@ -0,0 +1,689 @@ +# 业务流程设计 + +> 组别:24级1班第7组 统稿人:罗皓晨 共同编写:唐宇昊、顾欣月、朱惠惠、韦乾强、张海洋、罗皓晨 +> +> 编写日期:2026-07-24 版本:v0.1 +> +> 当前状态:部分定义;F01~F13 已对照总需求和教师验收完成基线校准,仍待各主责人交叉评审;X/C 只能基于核心流程扩展 + +## 修订记录 + +| 版本 | 日期 | 修改人 | 修改说明 | +|---|---|---|---| +| v0.1 | 2026-07-24 | 全体成员(罗皓晨统稿) | 建立集中式业务流程设计,覆盖核心主链路,并对照 F01~F13 需求与验收校准状态、模块交接、X/C 扩展点和核心结果保护规则 | + +## 一、文档定位与事实来源 + +本文档集中维护跨角色、跨模块、包含状态或异常分支的业务流程图,用于避免在主需求正文中堆叠复杂图示。 + +成员补充流程前先阅读 [`README.md`](README.md),按负责人、固定模板、成熟度和检查清单统一维护本文档。 + +文档职责: + +- [`../../01-需求文档/需求规格说明书.md`](../../01-需求文档/需求规格说明书.md) 定义正式范围、角色、业务规则、异常和验收,是需求事实源。 +- 本文档把已确认需求转换为可评审的参与者、主流程、状态、异常和模块出入口,不新增、删除或改变需求。 +- [`../系统架构设计.md`](../系统架构设计.md) 说明 API、Application、数据库、Worker、Redis、RabbitMQ 和事务等技术实现关系。 +- [`../接口设计.md`](../接口设计.md) 根据已确认流程中的业务动作和模块交接,定义 HTTP 路径、请求响应、鉴权、错误码和幂等契约。 +- [`../数据库设计.md`](../数据库设计.md) 定义表、字段、约束、索引和状态存储。 + +发生冲突时,以教师只读基线和主需求文档中已经确认的业务语义为准;本文档必须随主需求修正,不能反向用图覆盖文字规则。 + +设计顺序为“需求确认 → 业务流程 → 接口/数据库/架构落地”。流程先确定业务要发生什么,接口再承载流程中的动作与结果;现有 Axxx 只能用于流程完成后的映射和缺口检查,不能用接口清单反向拼接业务流程。“接口文档先行”只约束代码实现阶段,即接口契约必须先于实现与调用方变更确认。 + +## 二、绘图与维护约定 + +### 2.1 图的边界 + +本文档使用: + +- `flowchart TD` 表达角色操作、业务判断、成功和失败分支; +- `stateDiagram-v2` 表达订单等业务对象的合法状态流转; +- 简单跨模块关系直接写在节点标签中,不展开 Controller、DTO、SQL 或消息中间件细节。 + +技术调用时序仍放在系统架构设计,实体关系仍放在数据库设计。 + +### 2.2 图的阅读规则 + +- 每张图标明覆盖的 M/F/X/C 编号和主责人。 +- 判断节点的分支必须有明确含义。 +- 图只展示关键路径,完整字段规则、异常文本和验收证据回到主需求对应章节阅读。 +- PostgreSQL 始终是业务事实来源;缓存、消息和前端状态不改变业务结果。 +- 跨模块流程由主责人和直接协作人共同评审。 + +### 2.3 核心流程与扩展规则 + +F01~F13 是本项目业务流程基线。X01~X04 和 C01、C03、C04、C06、C07、C08、C10 必须从核心流程的明确业务结果接入,不得另画一套互相冲突的注册、商品、订单、支付或履约主链路。 + +每个扩展流程必须写明: + +1. 基于哪些 F01~F13; +2. 从核心流程哪个结果或状态接入; +3. 扩展结束后回到哪个核心结果,或作为哪个核心结果的旁路能力; +4. 不得改变的核心状态、权限、金额、库存、快照和事实来源。 + +扩展可以拥有独立数据和独立状态,但不得自行修改核心订单状态机、公开商品可见范围或角色权限。确需改变核心流程时,必须先修订主需求和本章对应 F 流程并重新评审,再调整扩展图。基础 F 尚未确认时,扩展只能保持“初稿”或“待交叉评审”,不能标记为“已确认”。 + +## 三、F01~F13 核心业务流程 + +### 3.0 商城核心闭环总览 + +> 覆盖:F01~F13 +> +> 作用:所有 X/C 流程选择接入点时的总基线 + +```mermaid +flowchart LR + A["游客浏览已上架商品
F04~F06"] --> B{"是否执行买家操作?"} + B -- "否" --> A + B -- "是" --> B1{"已有正常买家登录态?"} + B1 -- "否" --> C["注册或登录
F01~F02"] + B1 -- "是" --> E["维护本人购物车
F07"] + C --> E + C -. "可选维护" .-> D["维护本人资料与地址
F03"] + D -. "返回购物流程" .-> E + E --> E1["选择地址并由 M01 校验本人归属"] + E1 --> F["服务端校验并提交订单
F08"] + F --> G["订单进入 PendingPayment"] + G --> H{"买家支付还是主动取消?"} + H -- "支付" --> I["小金库原子支付
F10"] + I --> J["订单进入 Paid"] + J --> K["商家查询并发货
F12"] + K --> L["订单进入 Shipped"] + L --> M["买家确认或到期自动完成
F09"] + M --> N["订单进入 Completed"] + H -- "主动取消" --> O["订单进入 Cancelled
并原子回补库存 F09"] + + P["商家维护分类、商品和上下架
F11"] -->|"已上架结果"| A + Q["管理员禁用或启用买家/商家
F13"] --> Q1{"M01 账号治理结果"} + Q1 -- "正常" --> Q2["目标用户后续可主动登录"] + Q2 -. "用户主动发起" .-> C + Q1 -- "禁用" --> Q3["旧令牌失效;后续登录和受保护请求被拒绝"] +``` + +核心闭环的不可变结果: + +- 公开浏览只暴露已上架商品;商品详情的价格和库存不能替代下单时的服务端校验。 +- 下单成功必然得到唯一 `PendingPayment` 订单、订单项与地址快照,并完成一次库存扣减。 +- `PendingPayment` 只能由一次有效支付进入 `Paid`,或由一次有效取消进入 `Cancelled`;两个结果不能同时成立。 +- 取消成功必须按原扣减通道回补库存;支付成功后不得回补。 +- 只有 `Paid` 可以发货,只有 `Shipped` 可以完成;扩展功能不得用新增订单状态覆盖这一履约主链。 + +#### 3.0.1 核心状态基线 + +流程图根据已确认需求定义状态语义和合法转换;数据库与接口只负责映射存储编码和对外表示,不得反向新增、删除或改写业务状态。 + +| 业务对象 | 核心状态 | 状态性质 | +|---|---|---| +| 账号 | 正常、禁用 | 持久化状态;决定能否登录和继续使用旧令牌 | +| 商品 | 草稿/未上架、已上架、已下架 | 持久化销售状态;只有已上架进入公开列表和搜索;删除是满足约束后的终止结果,不是继续保留的销售状态 | +| 购物车条目 | 可结算、不可结算 | 根据商品上下架、实时库存、数量和归属实时派生,不新增独立业务状态机 | +| 订单 | `PendingPayment`、`Paid`、`Shipped`、`Completed`、`Cancelled` | 持久化状态;合法转换以 3.6 为唯一流程基线 | +| 钱包与支付 | 余额、不可变流水、确定支付记录 | F10 不定义“支付中”等额外业务状态;支付成功以支付记录落库且订单进入 `Paid` 为准 | + +账号状态: + +```mermaid +stateDiagram-v2 + [*] --> Normal: 创建正常账号 + Normal --> Disabled: 管理员禁用并撤销旧令牌 + Disabled --> Normal: 管理员启用 + Normal --> Normal: 重复启用幂等返回 + Disabled --> Disabled: 重复禁用幂等返回 +``` + +商品销售状态: + +```mermaid +stateDiagram-v2 + state "草稿/未上架" as Draft + state "已上架" as OnSale + state "已下架" as OffSale + state "物理删除完成(仅无历史关联的终止结果)" as Deleted + + [*] --> Draft: 创建并保存 + Draft --> OnSale: 完整性校验通过并主动上架 + OnSale --> OffSale: 商家主动下架 + OffSale --> OnSale: 重新校验通过并上架 + Draft --> Deleted: 无历史关联且确认删除 + OffSale --> Deleted: 无历史关联且确认删除 + Deleted --> [*] +``` + +#### 3.0.2 核心模块直接出入口 + +下图只表达业务模块之间允许直接传递的公开事实,不表示可以跨模块访问内部仓储、DbContext 或数据表。 + +```mermaid +flowchart LR + M01["M01 Identity
账号、角色、地址归属"] -->|"认证主体与角色"| M03["M03 Cart
本人购物车"] + M01 -->|"买家身份与地址快照契约"| M04["M04 Ordering
订单与履约状态"] + M01 -->|"认证主体与角色"| M05["M05 Payment
钱包与支付记录"] + + M06U["M06-03 管理入口"] -->|"禁用/启用命令"| M01 + M06P["M06-01 商家入口"] -->|"分类与商品维护命令"| M02["M02 Catalog
商品、价格、库存、销售状态"] + M02 -->|"已上架商品与实时价格库存"| M03 + M02 -->|"下单重读与库存条件更新"| M04 + M03 -->|"本人选中条目与数量
不传最终金额"| M04 + M04 -->|"订单号、归属、应付金额
状态 PendingPayment"| M05 + M05 -->|"确定支付记录
条件推进 PendingPayment → Paid"| M04 + M04 -->|"本期平台经营范围内 Paid 订单与履约快照"| M06O["M06-02 商家履约入口"] + M06O -->|"条件推进 Paid → Shipped"| M04 + + M04 -. "事务提交后的订单事实" .-> EXT["X03/C03 等扩展入口"] + M05 -. "事务提交后的支付事实" .-> EXT +``` + +| 来源模块 | 直接入口数据或命令 | 目标模块 | 直接出口结果 | 边界约束 | +|---|---|---|---|---| +| M01 Identity | 已认证用户 ID、服务端角色、账号状态 | M03、M04、M05、M06 | 允许或拒绝当前操作 | 目标模块不能自行修改账号、角色或令牌状态 | +| M01 Address | 当前买家选择的地址 ID | M04 Ordering | 归属校验结果和地址快照数据 | M04 只能读取并保存快照,不能修改地址 | +| M02 Catalog | 已上架状态、实时价格、实时库存 | M03 Cart | 可加购状态、实时小计和失效原因 | M03 不占用库存,也不能决定最终订单金额 | +| M02 Catalog | 销售状态、实时价格和实时库存 | M04 Ordering | 重读、校验、条件扣减或原通道回补结果 | 购买数量来自 M03 选中条目;M04 不能绕过 Catalog 规则直接改库存 | +| M03 Cart | 本人选中条目 ID 与数量 | M04 Ordering | 下单成功后清理结果;失败时原状保留 | 购物车金额仅供预览,M04 必须重读商品事实并重新计价 | +| M04 Ordering | 本人订单号、归属、持久化应付金额、`PendingPayment` | M05 Payment | 支付准入或当前最终订单状态 | M05 不接受客户端传入最终金额 | +| M05 Payment | 幂等支付命令和确定支付事实 | M04 Ordering | `PendingPayment → Paid` 的唯一条件更新结果 | 扣款、记录和状态必须形成一个原子结果 | +| M04 Ordering | 本期平台统一经营范围内的 `Paid` 订单和必要履约快照 | M06-02 | `Paid → Shipped` 结果 | 本期不按店铺/商家拆单;商家不能修改金额、支付事实、地址或订单项快照 | +| M06-01 | 分类、商品、上下架维护命令 | M02 Catalog | 最新商品销售状态 | 后台入口不拥有第二份商品事实 | +| M06-03 | 买家/商家账号禁用或启用命令 | M01 Identity | 最新账号状态和令牌失效结果 | 不允许修改角色或管理员账号 | + +跨模块流程只能使用上表中的公开输入和确定输出。出现失败、状态竞争或依赖不可用时,调用方读取目标模块返回的最终结果,不得自行补写另一模块的数据。 + +### 3.1 注册、登录、退出与账号治理 + +> 覆盖:M01-01、M01-02、M06-03;F01、F02、F13 +> 主责:唐宇昊;公共认证能力协作:罗皓晨 + +```mermaid +flowchart TD + A["游客选择注册或登录"] --> B{"选择注册?"} + B -- "是" --> C["填写手机号、密码和确认密码"] + C --> D{"格式、密码强度和两次输入一致?"} + D -- "否" --> E["保留非敏感输入并提示字段错误"] + D -- "是" --> F{"手机号是否已注册?"} + F -- "是" --> G["拒绝重复注册,不泄露其他账号资料"] + F -- "否" --> H["固定买家角色,生成唯一用户名并哈希密码"] + H --> I["创建正常账号和默认头像"] + I --> J["展示用户名并由用户明确进入登录"] + B -- "否" --> K["输入手机号和密码"] + J --> K + K --> L{"凭据正确?"} + L -- "否" --> M["统一提示账号或密码错误"] + L -- "是" --> N{"账号状态正常?"} + N -- "否" --> O["拒绝登录并提示账号停用"] + N -- "是" --> P["M01 签发登录凭证并返回服务端确认的角色"] + P --> V["M01 直接出口:认证主体、角色和账号状态"] + V --> Q["M03/M04/M05/M06 按各自资源规则继续校验"] + Q --> R{"刷新、访问受保护资源或退出?"} + R -- "刷新/访问" --> S{"令牌有效且账号仍正常?"} + S -- "是" --> Q + S -- "否" --> T["清理失效登录态并引导重新登录"] + R -- "退出" --> U["仅使当前令牌失效并返回登录页"] +``` + +关键说明: + +- 公开注册只能创建买家账号,不能由客户端指定商家或管理员角色。 +- 注册成功只展示账号摘要并引导登录,不默认建立登录态。 +- 账号不存在和密码错误使用统一提示;账号禁用在凭据正确后单独判断。 +- 用户主动退出只撤销当前令牌;管理员禁用账号的全部旧令牌失效流程见 3.7。 +- 前端路由只改善体验,服务端仍按 JWT、Policy 和资源归属校验权限。 +- 令牌失效状态无法确认时,受保护请求必须失败关闭,不能因依赖异常继续放行。 + +### 3.2 个人资料与收货地址 + +> 覆盖:M01-03;F03 +> 主责:唐宇昊;下单协作:韦乾强 + +资料维护: + +```mermaid +flowchart TD + A["M01 入口:访问个人中心"] --> B{"当前身份?"} + B -- "游客" --> X["引导登录并保留安全返回目标"] + B -- "商家或管理员" --> Y["403:拒绝访问买家私人资源"] + B -- "买家" --> C["查看用户名、默认头像和掩码手机号"] + C --> D{"选择资料操作?"} + D -- "重置用户名" --> E{"本项目期内是否仍有一次机会?"} + E -- "否" --> F["拒绝修改并说明次数已用完"] + E -- "是" --> G["服务端重新生成全局唯一用户名"] + G --> H["保存并返回最新资料"] + D -- "修改手机号" --> I["重新验证当前密码"] + I --> I1{"当前密码正确?"} + I1 -- "否" --> K["保持原资料和当前登录态并提示原因"] + I1 -- "是" --> J{"新手机号格式正确且全局唯一?"} + J -- "否" --> K["保持原资料和当前登录态并提示原因"] + J -- "是" --> L["保存新手机号并撤销修改前全部令牌"] + L --> M["清理登录态并要求重新登录"] +``` + +地址维护: + +```mermaid +flowchart TD + A["M01 Address:已登录买家进入地址管理"] --> B["按当前买家查询本人地址"] + B --> C{"新增、编辑、设默认或删除?"} + C -- "新增" --> D["校验收件人、联系电话、地区和详细地址"] + C -- "编辑/设默认/删除" --> E{"地址是否属于当前买家?"} + E -- "否" --> X["返回不存在或无权限,不泄露归属"] + E -- "是" --> F{"具体操作?"} + F -- "编辑" --> D + F -- "设默认" --> G["原子切换,最终最多一个默认地址"] + F -- "删除普通地址" --> H["删除本人地址"] + F -- "删除默认地址" --> I["删除后保持无默认地址"] + I --> J["提示买家后续重新选择"] + D --> K{"字段是否合法?"} + K -- "否" --> L["保留输入并提示字段错误"] + K -- "是" --> M["保存并返回最新地址"] + G --> N["返回唯一默认地址结果"] + H --> O["刷新本人地址列表"] + B -. "后续下单选择任一本人地址" .-> P["M04 直接入口:重新校验地址归属并生成地址快照"] +``` + +关键说明: + +- 用户名不能由客户端任意指定,只能在限次规则内由服务端重新生成。 +- 手机号修改属于敏感操作,必须验证当前密码;成功后修改前签发的全部令牌失效。 +- 地址必须按买家隔离,不能查看或修改他人地址。 +- 删除默认地址后不自动指定其他地址;“最多一个默认地址”允许当前没有默认地址。 +- 订单保存收货信息快照,后续修改地址不改变历史订单。 + +### 3.3 商品维护、上架与购物端浏览 + +> 覆盖:M02-01、M02-02、M06-01;F04、F05、F06、F11 +> 主责:顾欣月 + +后台分类与商品生命周期: + +```mermaid +flowchart TD + A["M06-01 入口:商家通过 Policy 进入管理"] --> B{"维护分类还是商品?"} + B -- "分类" --> C["查询、新增、编辑、启用、停用或申请删除分类"] + C --> D{"申请删除且存在商品或历史引用?"} + D -- "是" --> E["拒绝删除并引导停用"] + D -- "否" --> F["保存维护结果或完成无引用分类删除"] + B -- "商品" --> G["创建或编辑名称、分类、价格、库存、图片和描述"] + G --> H{"字段、图片、分类和并发状态有效?"} + H -- "否" --> I["拒绝保存并保留表单内容"] + H -- "是" --> J["保存草稿或保持当前销售状态"] + J --> K{"主动上架、下架、删除或暂不变更状态?"} + K -- "上架" --> L{"必填信息完整且分类已启用?"} + L -- "否" --> M["拒绝上架并指出缺失项"] + L -- "是" --> N["M02 状态变为已上架"] + K -- "下架" --> O["状态变为已下架"] + K -- "删除" --> P{"当前是否已上架?"} + P -- "是" --> P1["先执行下架,状态变为已下架"] + P -- "否" --> P2{"是否存在历史订单关联?"} + P1 --> P2 + P2 -- "是" --> Q["拒绝破坏性删除并保持已下架"] + P2 -- "否" --> R["完成物理删除,进入终止结果"] + K -- "暂不变更状态" --> S["返回管理列表,保持当前销售状态"] +``` + +购物端列表、搜索与详情: + +```mermaid +flowchart TD + A["游客、买家、商家或管理员进入购物端"] --> B["提交分页、分类、关键词、价格、库存和排序条件
关键词去除首尾空白,F05 至少按商品名称模糊匹配"] + B --> C{"参数是否合法?"} + C -- "否" --> D["返回字段级错误并保留查询条件"] + C -- "是" --> E["服务端强制过滤为已上架商品"] + E --> F{"是否有匹配结果?"} + F -- "否" --> G["展示空结果并提供清空筛选"] + F -- "是" --> H["展示主图、名称、当前价格和库存摘要"] + H --> I["进入详情并展示图片、描述、分类、价格和库存"] + I --> J{"商品仍为已上架?"} + J -- "否" --> K["旧链接显示不可售或不存在,不提供购买入口"] + J -- "是" --> L{"当前角色?"} + L -- "游客" --> M["触发买家操作时引导登录并保留意图"] + L -- "商家或管理员" --> N["仅浏览公开效果,不显示买家操作"] + L -- "买家" --> O{"当前库存是否充足?"} + O -- "否" --> P["保留详情展示,标记售罄并禁用购买"] + O -- "是" --> Q["M02 输出商品事实,进入 M03 加购流程
购买继续复用 F07 购物车结算与 F08 下单主链"] +``` + +关键说明: + +- 新建或编辑商品不会自动上架;只有商家主动上架且完整性校验通过后,状态才进入“已上架”。 +- 公开列表和搜索只返回已上架商品;下架商品的旧链接只能显示不可售状态。 +- 已上架但库存为 0 的商品仍可展示详情,但必须标记售罄并禁用购买。 +- 商品下架不删除历史订单快照、购物车、收藏或浏览历史中的关联记录,但购买入口必须失效。 +- 有历史订单关联的商品不得进行破坏性删除,应使用下架表达停售。 +- 本期不引入多商家商品归属模型;后台以商家 Policy 控制入口,不在流程图中自行增加店铺或租户边界。 + +### 3.4 购物车结算与提交订单 + +> 覆盖:M03-01、M04-01;F07、F08 +> 购物车主责:朱惠惠;订单主责:韦乾强;商品协作:顾欣月 +> 直接入口:M01 提供买家与地址归属;M02 提供商品销售状态、实时价格和库存 +> 直接出口:成功生成 M04 `PendingPayment` 订单并进入 M05;失败时购物车、库存和订单均不产生部分结果 + +```mermaid +flowchart TD + ID["M01 直接输入:已认证买家"] --> A["M03:买家维护本人购物车"] + CAT["M02 直接输入:销售状态、实时价格和库存"] --> B + A --> B{"商品已上架且数量合法并不超过实时库存?"} + B -- "否" --> BX["拒绝加入或调大,返回失效原因和最大可购量"] + B -- "是" --> C["按买家+商品唯一条目新增或累加"] + C --> D["幂等键防止重复累加,服务端保存选中状态"] + D --> E["买家选择可用条目并请求结算预览"] + E --> F["服务端重读归属、销售状态、实时价格和库存并计算总额"] + F --> G{"全部条目可结算?"} + G -- "否" --> GX["整次结算失败,仅标记问题条目并保留全部购物车数据"] + G -- "是" --> H["展示服务端金额,买家选择本人地址并提交下单幂等键"] + ADDR["M01 直接输入:本人地址记录与归属"] --> J + H --> I{"该买家+幂等键已有成功订单?"} + I -- "是" --> IX["返回原订单号,不重复扣库存或清理购物车"] + I -- "否" --> J["再次校验身份、地址、购物车、商品、库存和正数总额"] + J --> K{"最终校验通过?"} + K -- "否" --> KX["拒绝提交并保留购物车条目"] + K -- "是" --> L["开启事务,逐项条件扣减库存"] + L --> M{"全部库存扣减成功?"} + M -- "否" --> R["整体回滚:库存、订单、待发布订单创建事实和购物车均恢复原状"] + M -- "是" --> N["写唯一订单、地址和商品快照、服务端总额"] + N --> O["记录待发布的订单创建事实"] + O --> P["删除本次已结算购物车条目"] + P --> Q["提交事务,订单状态为 PendingPayment"] + Q --> S["M04 直接输出:订单号、应付金额和 PendingPayment"] + S --> T["进入 M05 收银台"] + N -. "写入失败" .-> R + O -. "订单创建事实记录失败" .-> R + P -. "清理失败" .-> R + Q -. "提交失败" .-> R +``` + +关键说明: + +- 前端显示的价格和库存不能作为下单事实,提交时必须由服务端重新校验。 +- 商品价格变化只刷新服务端计价,不自动把条目标为失效;商品未上架、资源归属错误或库存不足才阻止结算。分类停用是否影响既有已上架商品购买,须由商品主责确认后再进入核心规则。 +- 购物车条目的“可结算/不可结算”是实时派生结果,提交瞬间必须再次校验。 +- 库存扣减、订单和快照、待发布订单创建事实、已结算购物车清理属于一个原子业务结果。 +- 重复提交同一幂等请求只能返回首次结果,不能重复扣库存或生成订单。 +- 事务提交后的消息发布失败由架构确定的可靠机制重试,不回滚已经提交的订单。 + +### 3.5 小金库充值与模拟支付 + +> 主责:张海洋;订单协作:韦乾强 +> 模块文档:[`zhy/M05-支付流程.md`](zhy/M05-支付流程.md) +> 当前成熟度:初稿,待主责自审及 Ordering 交叉评审 + +根文档只保留 F10 核心基线: + +- 直接入口:M01 提供正常买家身份;M04 提供本人订单号、归属、持久化应付金额、当前状态和支付截止时间。 +- 原子结果:钱包扣款、钱包流水、支付记录、首次处理结果、`PendingPayment → Paid` 和待发布支付成功事实同一事务提交。 +- 直接出口:M04 获得唯一 `Paid` 结果,M06-02 可查询待发货订单,M09 消费事务后的支付事实。 +- F10 不新增“支付中”订单状态;支付与主动/超时取消只能有一个条件更新胜出。 +- 详细充值、支付、查询、异常、回滚、流程派生接口映射和待评审项统一在模块文档维护。 + +### 3.6 订单取消、发货与完成 + +> 覆盖:M04-02、M04-03、M04-04、M06-02;F09、F12 +> 主责:韦乾强;支付协作:张海洋;定时任务实现协作:罗皓晨 +> 直接入口:M05 返回 `Paid`;M06-02 提交发货;买家或系统定时任务提交取消/完成触发 +> 直接出口:M04 返回唯一最终状态、状态时间线和必要快照;事务提交后的事实可供 X03/C03 消费 + +```mermaid +stateDiagram-v2 + [*] --> PendingPayment: F08 下单事务提交成功 + PendingPayment --> Paid: F10 本人钱包支付事务成功 + PendingPayment --> Cancelled: F09 本人主动取消事务成功 + PendingPayment --> Cancelled: C03 创建满30分钟且系统自动取消成功 + Paid --> Shipped: F12 平台运营商家发货事务成功 + Shipped --> Completed: F09 订单所属买家确认收货 + Shipped --> Completed: F09 发货满7天且系统自动完成 + Cancelled --> [*] + Completed --> [*] +``` + +订单列表、详情与操作入口: + +```mermaid +flowchart TD + ID["M01 直接输入:已认证买家"] --> A["M04:买家进入订单列表"] + A --> B["按本人、状态和分页查询,创建时间倒序"] + B --> C["查看订单摘要或进入详情"] + C --> D{"订单是否属于当前买家?"} + D -- "否" --> X["返回不存在或无权限,不泄露订单内容"] + D -- "是" --> E["展示地址和商品快照、金额、状态时间线及支付信息"] + E --> F{"当前状态?"} + F -- "PendingPayment" --> G["显示去支付和主动取消入口"] + F -- "Shipped" --> H["显示确认收货入口"] + H -. "符合售后规则" .-> AS2["X04:从 Shipped 订单项接入独立售后流程"] + F -- "Completed" --> I["显示评价入口"] + I -. "X01" .-> RV["从 Completed 订单项接入评价流程"] + I -. "符合售后期限" .-> AS3["X04:从 Completed 订单项接入独立售后流程"] + F -- "Paid" --> J["显示等待商家发货"] + J -. "符合售后规则" .-> AS1["X04:从 Paid 订单项接入独立售后流程"] + F -- "Cancelled" --> K["不显示支付、发货或完成入口"] +``` + +支付与取消竞争: + +```mermaid +flowchart TD + A["订单状态为 PendingPayment"] --> B{"触发来源?"} + B -- "买家支付" --> P["M05 按 3.5 执行支付事务"] + B -- "买家主动取消" --> C{"已登录买家且订单属于本人?"} + B -- "C03 系统超时检查" --> D{"创建满30分钟且仍为 PendingPayment?"} + C -- "否" --> X["拒绝操作"] + C -- "是" --> E["开启取消事务并条件推进 PendingPayment → Cancelled"] + D -- "否" --> Y["跳过本次任务"] + D -- "是" --> E + P --> Q{"M05 返回的支付事务是否成功?"} + Q -- "是" --> PAID["提交后最终状态为 Paid"] + Q -- "否" --> Z["读取并返回订单最终状态"] + E --> F{"状态条件更新成功?"} + F -- "否" --> Z + F -- "是" --> G["按订单项库存来源回补普通或秒杀库存"] + G --> H["记录取消时间和待发布订单取消事实"] + H --> I{"取消事务全部成功?"} + I -- "否" --> R["整体回滚;人工请求或系统定时任务可按策略重试"] + I -- "是" --> CANCELLED["提交后最终状态为 Cancelled"] +``` + +商家发货与订单完成: + +```mermaid +flowchart TD + ID["M01 直接输入:已认证且状态正常的商家"] --> A["M06-02:分页查询本期平台统一经营范围内订单并查看详情"] + ORD["M04 直接输入:Paid 订单与必要履约快照"] --> A + A --> B{"角色、授权范围和订单状态均允许发货?"} + B -- "否" --> X["拒绝发货,不允许修改金额、支付事实或快照"] + B -- "是且状态为 Paid" --> C["事务内条件推进 Paid → Shipped"] + C --> C1{"状态条件更新成功?"} + C1 -- "否" --> Y["返回订单当前状态,不重复发货"] + C1 -- "是" --> D["记录发货时间和待发布订单发货事实"] + D --> E{"事务提交成功?"} + E -- "否" --> Y2["整体回滚,保持原状态并允许安全重试"] + E -- "是" --> F["M04 直接输出:订单状态为 Shipped,买家可查看结果"] + F --> G{"完成触发来源?"} + G -- "买家确认" --> H{"买家已登录、订单属于本人且仍为 Shipped?"} + G -- "系统自动完成" --> I{"发货满7天且仍为 Shipped?"} + H -- "否" --> Z["拒绝操作或返回已有完成结果"] + I -- "否" --> W["跳过本次任务"] + H -- "是" --> J["条件推进 Shipped → Completed,记录买家确认方式"] + I -- "是" --> K["条件推进 Shipped → Completed,记录自动完成方式"] + J --> M{"状态条件更新成功?"} + K --> M + M -- "否" --> Z2["返回已有完成结果"] + M -- "是" --> L["记录完成时间、完成方式和待发布订单完成事实"] + L --> N{"完成事务提交成功?"} + N -- "否" --> V["整体回滚,保持 Shipped 并允许安全重试"] + N -- "是" --> O["M04 直接输出:唯一 Completed 结果"] +``` + +关键说明: + +- 买家列表和详情只返回本人订单;本期平台运营商家共享统一经营订单的履约范围,不按店铺或商家账号拆单。 +- 买家支付、主动取消和 C03 超时取消竞争 `PendingPayment`,数据库状态条件决定唯一胜出结果。 +- 取消、原库存通道回补和待发布订单取消事实处于同一事务,重复取消不能重复回补。 +- 商家只能条件推进 `Paid → Shipped`;买家确认与系统自动完成只能竞争 `Shipped → Completed`。 +- 正式自动完成期限为发货满 7 天;C03 的正式超时取消期限为订单创建满 30 分钟。 +- X01 评价和 X04 售后只能从已确认的订单状态接入,不得反向覆盖核心订单状态。 + +### 3.7 后台角色与操作边界 + +> 覆盖:M06-01、M06-02、M06-03;F11、F12、F13 +> 主责:顾欣月、韦乾强、唐宇昊 +> 直接入口:M01 返回认证主体、角色和账号状态 +> 直接出口:商品命令交给 M02,履约命令交给 M04,账号治理命令交给 M01 + +```mermaid +flowchart TD + A["访问后台入口"] --> B{"是否已认证?"} + B -- "否" --> X["要求登录,不返回后台数据"] + B -- "是" --> C{"服务端确认角色和账号状态"} + C -- "账号禁用" --> X1["拒绝后台访问并清理失效登录态"] + C -- "买家" --> Y["403:拒绝进入后台业务"] + C -- "商家" --> D["进入商家端"] + D --> E{"选择商品管理还是订单履约?"} + E -- "商品" --> F["通过商家 Policy 向 M02 提交分类和商品命令"] + E -- "订单" --> G["向 M04 查询可处理订单并按合法状态发货"] + C -- "管理员" --> H["进入用户管理"] + H --> I["分页筛选买家和商家账号,手机号默认掩码"] + I --> J{"目标账号和操作是否合法?"} + J -- "否" --> Z["拒绝管理员账号、角色修改或其他越权操作"] + J -- "是" --> K{"禁用还是启用?"} + K -- "禁用" --> L["M01 将账号状态改为禁用并撤销旧令牌"] + K -- "启用" --> M["M01 将账号状态恢复正常"] + L --> N["目标无法登录,禁用前令牌不能访问受保护资源"] + M --> O["禁用前令牌不恢复,目标必须重新登录"] +``` + +关键说明: + +- 后台只是按角色组织入口,账号、商品和订单事实仍分别归 M01、M02、M04。 +- 商家不能通过商品或订单后台修改买家账号、支付事实或订单金额。 +- 管理员账号治理不提供角色修改、提权或普通用户私人资料编辑。 +- 后台页面隐藏入口不能替代服务端 Policy 和资源归属校验。 +- 重复禁用或启用按当前状态幂等返回;令牌失效结果无法确认时,禁用不得返回虚假成功。 +- 本期不定义管理员创建商家或修改角色流程,商家账号继续由已确认的受控初始化方式提供。 + +### 3.8 核心模块直接出入口详图 + +本节单独展示模块交接,便于接口、数据库和联调评审。每条实线都是同步业务入口或确定结果;虚线是事务提交后的扩展出口。任何失败出口都必须返回调用方,不允许调用方越过目标模块直接改表。 + +#### 3.8.1 Identity、Catalog 向 Cart、Ordering 提供输入 + +```mermaid +flowchart LR + A["M01 Identity
认证主体、角色、账号状态"] -->|"允许买家操作"| B["M03 Cart"] + A -->|"允许买家下单"| C["M04 Ordering"] + D["M01 Address
地址归属与快照契约"] -->|"本人地址校验成功"| C + E["M02 Catalog
销售状态、实时价格、实时库存"] -->|"加购/改数量校验"| B + B -->|"本人选中条目ID与数量
不含最终金额"| C + E -->|"下单重读与库存条件扣减"| C + + A -->|"未认证/角色错误/账号禁用"| X["401、403 或登录失效结果"] + D -->|"不存在或不属于买家"| Y["M04 拒绝整次下单"] + E -->|"商品未上架或库存不足"| Z["M03 标记问题条目
M04 拒绝整次提交"] +``` + +#### 3.8.2 Cart、Ordering、Payment 的交易交接 + +```mermaid +flowchart LR + A["M03 Cart
本人选中条目"] -->|"选中条目与数量"| B["M04 Ordering
服务端重读并计价"] + B -->|"事务成功"| C["订单 PendingPayment
库存已扣、快照已保存、购物车已清理"] + B -->|"事务失败"| X["库存与购物车保持原结果
不产生部分订单"] + C -->|"订单号、归属、应付金额"| D["M05 Payment"] + D -->|"支付事务成功"| E["支付记录已落库
订单 Paid"] + D -->|"余额不足或状态竞争失败"| F["订单保持当前最终状态
钱包不产生部分扣款"] + E -->|"Paid 订单"| G["M06-02 待发货入口"] + C -->|"买家主动取消"| H["M04 取消事务"] + H -->|"取消成功"| I["订单 Cancelled
原库存通道已回补"] + H -->|"状态竞争或事务失败"| J["返回当前订单状态
库存不产生部分回补"] +``` + +#### 3.8.3 Ordering 与商家履约、买家完成的交接 + +```mermaid +flowchart LR + A["M04 Ordering
Paid 订单与履约快照"] -->|"本期平台统一经营范围内查询"| B["M06-02 商家履约"] + B -->|"合法发货命令"| C["M04 条件推进 Paid → Shipped"] + B -->|"越权或状态非法"| X["拒绝发货并返回当前状态"] + C -->|"状态竞争或事务失败"| X + C -->|"Shipped 详情"| D["订单所属买家"] + D -->|"主动确认收货"| E["M04 条件推进 Shipped → Completed"] + W["系统定时任务
发货满7天"] -->|"自动完成触发"| E + E -->|"只提交一次"| F["Completed、完成时间和完成方式"] + E -->|"状态竞争或事务失败"| Y["返回当前状态,不重复发货或完成"] + C -. "事务提交后的发货事实" .-> MSG["X03 消息扩展入口"] + F -. "事务提交后的完成事实" .-> MSG +``` + +#### 3.8.4 后台入口与业务事实所属模块 + +```mermaid +flowchart LR + A["M06 后台统一入口"] --> A1{"已认证且账号正常?"} + A1 -- "否" --> X["拒绝访问并清理失效登录态"] + A1 -- "是" --> B{"服务端角色?"} + B -- "商家商品管理" --> C["M02 Catalog
分类与商品事实"] + B -- "商家订单履约" --> D["M04 Ordering
订单状态与快照"] + B -- "管理员账号治理" --> E["M01 Identity
账号状态与令牌失效"] + C -->|"最新销售状态"| F["F04~F06 购物端"] + D -->|"Shipped/Completed"| G["F09 买家订单"] + E -->|"正常/禁用"| H["F02 登录与全部受保护入口"] +``` + +直接交接约束: + +- 调用方只传业务标识和必要命令,目标模块重新校验当前身份、归属和状态。 +- 成功出口必须是已经提交的确定业务结果;处理中页面、前端缓存和推送消息不能作为模块交接事实。 +- 失败出口必须说明是认证、授权、资源归属、业务状态还是依赖异常,调用方不得自行猜测成功。 +- 跨模块事务按照系统架构已确认的模块化单体边界协调;不得用跨模块内部仓储依赖替代公开应用接口。 + +## 四、核心流程追踪矩阵 + +| 教师编号 | 核心状态或确定结果 | 直接入口 → 直接出口 | 本文流程 | 主责人 | 当前成熟度 | +|---|---|---|---|---|---| +| F01 | 创建“正常”买家账号 | 游客注册 → F02 登录 | 3.1 | 唐宇昊 | 基线已校准,待主责确认 | +| F02 | 有效令牌 + 服务端角色;退出后当前令牌失效 | M01 → M03/M04/M05/M06 | 3.1、3.8.1 | 唐宇昊 | 基线已校准,待主责确认 | +| F03 | 本人资料与地址;敏感修改后令牌状态明确 | M01 Address → M04 地址快照 | 3.2、3.8.1 | 唐宇昊 | 基线已校准,待主责确认 | +| F04 | 只返回已上架商品的分页列表 | M02 → 购物端列表 | 3.3 | 顾欣月 | 基线已校准,待主责确认 | +| F05 | 安全的关键词/组合查询结果 | 查询条件 → M02 → F04 列表 | 3.3 | 顾欣月 | 基线已校准,待主责确认 | +| F06 | 公开详情、最新价格库存和明确可售状态 | F04 列表 → M02 详情 → M03 | 3.3、3.8.1 | 顾欣月 | 基线已校准,待主责确认 | +| F07 | 本人购物车;条目可结算状态实时派生 | M01/M02 → M03 → M04 | 3.4、3.8.1 | 朱惠惠 | 基线已校准,待 Cart/Ordering 评审 | +| F08 | 唯一 `PendingPayment` 订单、快照、扣减库存和清理结果 | M01/M02/M03 → M04 → M05 | 3.4、3.8.2 | 韦乾强 | 基线已校准,待 Cart/Catalog 评审 | +| F09 | 本人订单可查;合法到达 `Cancelled` 或 `Completed` | M04/M05/系统定时任务 → M04 | 3.6、3.8.2~3.8.3 | 韦乾强 | 基线已校准,待 Payment 评审 | +| F10 | 确定支付记录且订单进入 `Paid` | M04 → M05 → M04/M06-02 | [M05 支付流程](zhy/M05-支付流程.md)、3.8.2 | 张海洋 | 初稿,待主责自审及 Ordering 交叉评审;C08 接入语义待决 | +| F11 | 商品处于草稿/未上架、已上架、已下架,或满足约束后完成删除 | M06-01 → M02 → F04~F06 | 3.3、3.7、3.8.4 | 顾欣月 | 基线已校准,待主责确认 | +| F12 | 合法 `Paid → Shipped` 并记录发货事实 | M04 → M06-02 → M04 | 3.6、3.7、3.8.3 | 韦乾强 | 基线已校准,待主责确认 | +| F13 | 买家/商家账号“正常 ↔ 禁用”,旧令牌结果明确 | M06-03 → M01 → 全部受保护入口 | 3.1、3.7、3.8.4 | 唐宇昊 | 基线已校准,待主责确认 | + +## 五、选做与挑战流程登记 + +以下流程仍以主需求中的文字规则为准。每项必须从表中核心状态或确定结果接入,扩展失败不得破坏“不可变核心结果”。 + +| 编号 | 基础核心流程 | 直接扩展入口 → 出口 | 不可变核心结果 | 主责人 | 当前状态 | +|---|---|---|---|---|---| +| X01 | F09、F06 | `Completed` 订单项 → 评价记录 → F06 公开评价 | 订单保持 `Completed`;快照、商品状态、价格和库存不变;同一订单项最多一条评价 | 顾欣月 | 待细化 | +| X02 | F02、F06,展示衔接 F04 | 已登录买家查看详情 → 本人收藏/浏览记录 | 不修改商品事实;游客不产生个人记录;严格按买家隔离 | 唐宇昊 | 待细化 | +| X03 | F08、F09、F10、F12;X04 可追加来源 | 核心事务提交事件 → 消息落库/查询/已读/离线补查 | 消息失败不回滚核心事务,也不能反向修改订单或支付状态 | 罗皓晨 | 待细化 | +| X04 | F09、F10、F12 | 本人 `Paid/Shipped/Completed` 订单项 → 独立售后状态 → 幂等退款 | 订单核心状态和快照不被“已退款”覆盖;退款不超实付且不重复入账 | 张海洋 | 待细化 | +| C01 | F11 + F04/F06 → F08 → F10/F09/F12 | F11 商家创建/发布活动;F06 买家进入秒杀入口 → 独立库存条件扣减 → 汇入 `PendingPayment` | 后续复用核心支付和履约;取消只回补原秒杀库存;支付成功不得回补 | 朱惠惠 | 待细化;库存划拨口径待确认 | +| C03 | F08、F10、F09 | `PendingPayment` 创建满 30 分钟 → 系统定时任务复用取消流程 → `Cancelled` | 与支付只能一个胜出;取消和原库存通道回补原子且幂等 | 韦乾强 | 部分定义 | +| C04 | F04、F05、F06 | 替换 F05 查询实现 → 返回同口径 F04 列表 → F06 详情 | 只公开已上架商品;权限、筛选口径和下单重校验不变 | 顾欣月 | 待细化 | +| C06 | 经 X03 接入 F08/F09/F10/F12 | X03 消息成功落库 → 实时推送/重连 → X03 补查 | 推送失败不改变消息事实和核心事务;客户端不得仅凭推送改状态 | 罗皓晨 | 待细化 | +| C07 | F04、F06、F11,约束 F08 | F04/F06 数据库读取前 Cache-Aside;F11 提交后失效 | PostgreSQL 仍是事实源;Redis 故障只影响性能;F08 始终重读数据库 | 罗皓晨、顾欣月 | 待细化;TTL 上限待确认 | +| C08 | F10、F09;退款对账关联 X04 | F10 支付确认阶段 → 回调幂等/乱序 → 稳定结果与每日对账 | 不重复扣款;`Cancelled` 收到迟到成功不得变为 `Paid`,只登记差异 | 张海洋 | 待细化;与同步 F10 的替换边界待确认 | +| C10 | F01~F13 全部横切 | 统一入口 → 双实例分发/故障切换 → 同一业务结果 | API、鉴权、权限、状态机和数据库结果不变;实例切换不得重复写或越权 | 罗皓晨 | 待细化 | + +当前不得直接冻结的三项: + +1. C01 必须先确认秒杀库存从普通库存划拨或冻结的口径,避免两个库存通道共同超用总库存。 +2. C08 必须确认其替换 F10 的哪个支付确认步骤,不能让同步支付和异步回调同时成为最终支付事实。 +3. C07 必须在设计与验收前确定 TTL、主动失效和失败重试的最长旧值窗口。 + +## 六、维护与评审规则 + +1. 负责人先在主需求对应模块章节中确认业务语义、状态和异常边界。 +2. 先完成业务流程、状态和直接模块出入口,再由流程步骤派生接口能力;不得按 Axxx 清单拼接流程。 +3. 先确认所依赖的 F01~F13 核心流程,再选择扩展入口、出口和不可变核心结果。 +4. 跨模块流程由扩展主责人和所依赖的核心 F 负责人共同评审直接出入口。 +5. 扩展图只能增加独立能力,不得复制或改写整条核心主链;需要改变核心时先修订需求和核心流程。 +6. 流程评审通过后,同一任务同步主需求文字、核心/扩展流程图和追踪矩阵。 +7. 根据已确认流程同步接口设计和数据库设计;接口契约确认后再修改代码及调用方。 +8. 涉及事务、Worker、消息、缓存或部署的技术实现,再同步系统架构设计。 +9. 图中不得使用未确认的 Axxx、DBxxx、字段、状态编码或实现完成度。 +10. 每轮修改检查 Mermaid 语法、相对链接、UTF-8、术语和 `git diff --check`。 diff --git "a/docs/02-\350\256\276\350\256\241\346\226\207\346\241\243/\345\221\275\345\220\215\350\247\204\350\214\203.md" "b/docs/02-\350\256\276\350\256\241\346\226\207\346\241\243/\345\221\275\345\220\215\350\247\204\350\214\203.md" index 8a8ac04a0092570fe3ce430e014a347a9b05fc3b..051c625107edfb3404dcc4e7729c36166f7d38eb 100644 --- "a/docs/02-\350\256\276\350\256\241\346\226\207\346\241\243/\345\221\275\345\220\215\350\247\204\350\214\203.md" +++ "b/docs/02-\350\256\276\350\256\241\346\226\207\346\241\243/\345\221\275\345\220\215\350\247\204\350\214\203.md" @@ -101,8 +101,8 @@ - 图片和附件使用小写 `kebab-case`,例如 `order-checkout-flow.png`,不使用 `截图1.png`、`最终版2.png`。 - 文件名不得包含姓名、日期或版本,除非日报、周报、Migration、发布材料等规则明确要求。 - 接口并行设计阶段统一在 `docs/02-设计文档/interface/` 保存个人原稿,固定使用 `interface-<姓名拼音首字母>.md`,例如 `interface-tyh.md`;首字母必须全小写。 -- 数据库并行设计阶段仍在 `docs/02-设计文档/` 保存 `database-<姓名拼音首字母>.md`,例如 `database-lhc.md`,不另建个人文件夹。 -- 个人接口原稿用于贡献与交叉评审追踪,汇总后继续保留;`接口设计.md` 是实现、OpenAPI、联调和测试的唯一接口事实源,个人原稿不得覆盖总文档。个人数据库文件按《数据库设计》的汇总规则处理,最终数据库事实源仍为 `数据库设计.md`。 +- 数据库并行设计阶段统一在 `docs/02-设计文档/database/` 保存个人原稿,固定使用 `database-<姓名拼音首字母>.md`,例如 `database-lhc.md`;首字母必须全小写。 +- 个人接口和数据库原稿汇总后继续保留,但不得覆盖对应的 `接口设计.md` 和 `数据库设计.md` 主事实源。 ## 四、Vue 3、TypeScript、Vite、Pinia、Axios与UI diff --git "a/docs/02-\350\256\276\350\256\241\346\226\207\346\241\243/\346\216\245\345\217\243\350\256\276\350\256\241.md" "b/docs/02-\350\256\276\350\256\241\346\226\207\346\241\243/\346\216\245\345\217\243\350\256\276\350\256\241.md" index 0aa4eee14e76322335e2fa604dc0365f3e45ea09..3e52661b586e3d0bb4043d6f3910bdf1bfadb97d 100644 --- "a/docs/02-\350\256\276\350\256\241\346\226\207\346\241\243/\346\216\245\345\217\243\350\256\276\350\256\241.md" +++ "b/docs/02-\350\256\276\350\256\241\346\226\207\346\241\243/\346\216\245\345\217\243\350\256\276\350\256\241.md" @@ -7190,7 +7190,7 @@ RefundDetailResponse { - 模块 / Tag:Messaging - 需求编号:X03-FR03、X03-FR10、X03-FR11 - 负责人:罗皓晨 -- 关联数据表:待 `database-lhc.md` 确认 +- 关联数据表:待 `docs/02-设计文档/database/database-lhc.md` 确认 - 当前状态:待交叉评审 - 用途:按创建时间倒序分页查询当前用户自己的消息。 - 方法与路径:`GET /api/messages` @@ -7291,7 +7291,7 @@ RefundDetailResponse { - 模块 / Tag:Messaging - 需求编号:X03-FR04、X03-FR11 - 负责人:罗皓晨 -- 关联数据表:待 `database-lhc.md` 确认 +- 关联数据表:待 `docs/02-设计文档/database/database-lhc.md` 确认 - 当前状态:待交叉评审 - 用途:查询当前用户拥有的一条完整站内消息。 - 方法与路径:`GET /api/messages/{messageId}` @@ -7370,7 +7370,7 @@ RefundDetailResponse { - 模块 / Tag:Messaging - 需求编号:X03-FR05、C06-FR05 - 负责人:罗皓晨 -- 关联数据表:待 `database-lhc.md` 确认 +- 关联数据表:待 `docs/02-设计文档/database/database-lhc.md` 确认 - 当前状态:待交叉评审 - 用途:为消息入口角标、首次连接和断线重连补偿提供当前未读总数。 - 方法与路径:`GET /api/messages/unread-count` @@ -7432,7 +7432,7 @@ RefundDetailResponse { - 模块 / Tag:Messaging - 需求编号:X03-FR06 - 负责人:罗皓晨 -- 关联数据表:待 `database-lhc.md` 确认 +- 关联数据表:待 `docs/02-设计文档/database/database-lhc.md` 确认 - 当前状态:待交叉评审 - 用途:幂等地记录当前用户一条消息的首次已读时间。 - 方法与路径:`POST /api/messages/{messageId}/read` @@ -7499,7 +7499,7 @@ RefundDetailResponse { - 模块 / Tag:Messaging - 需求编号:X03-FR07 - 负责人:罗皓晨 -- 关联数据表:待 `database-lhc.md` 确认 +- 关联数据表:待 `docs/02-设计文档/database/database-lhc.md` 确认 - 当前状态:待交叉评审 - 用途:将操作开始时当前用户已经存在的未读消息批量标记为已读。 - 方法与路径:`POST /api/messages/read-all` diff --git "a/docs/02-\350\256\276\350\256\241\346\226\207\346\241\243/\346\225\260\346\215\256\345\272\223\350\256\276\350\256\241.md" "b/docs/02-\350\256\276\350\256\241\346\226\207\346\241\243/\346\225\260\346\215\256\345\272\223\350\256\276\350\256\241.md" index 83909d5722f29d0c2bd01fd543033a9b27c73a4a..f63d913f3de15bdaa5ac3fd14e8e3d877536d8e5 100644 --- "a/docs/02-\350\256\276\350\256\241\346\226\207\346\241\243/\346\225\260\346\215\256\345\272\223\350\256\276\350\256\241.md" +++ "b/docs/02-\350\256\276\350\256\241\346\226\207\346\241\243/\346\225\260\346\215\256\345\272\223\350\256\276\350\256\241.md" @@ -6,66 +6,60 @@ ## 修订记录 | 版本 | 日期 | 修改人 | 修改说明 | -|------|------|--------|----------| -| v0.1 | 2026-07-24 | 罗皓晨 | 增加 DBxxx 表编号、六人区间、模块归属和统一表设计模板 | +|---|---|---|---| +| v0.1 | 2026-07-24 | 罗皓晨 | 明确 DBxxx 分工、个人原稿、单表模板、汇总和冻结规则 | ## 一、设计说明 -- 数据库:PostgreSQL,通过 EF Core 10 与 Npgsql 访问;精确版本以系统架构和依赖锁定结果为准。 -- 编码:统一使用 UTF-8。 -- Schema:默认使用 `public`,未经架构评审不按模块拆分数据库 Schema。 -- 命名:遵循《命名规范》第六章;表名使用复数 `snake_case`,主键使用 `id`,时间点使用 `_at`。 -- PostgreSQL 是业务事实来源;Redis、RabbitMQ、缓存和进程内存不得保存无法恢复的唯一业务事实。 -- 每个模块负责人只设计本人模块拥有的数据,不得通过直接修改其他模块表代替公开接口、Application 契约或集成事件。 +- 数据库使用 PostgreSQL,通过 EF Core 10 与 Npgsql 访问。 +- PostgreSQL 是业务事实来源;Redis、RabbitMQ、对象存储和进程内存不登记为业务表。 +- [《命名规范》](命名规范.md)第六章是表、字段、约束、索引和 Migration 命名的唯一事实源,本文件不重复命名规则。 +- [《接口设计》](接口设计.md)是 Axxx、字段和状态输入来源;接口未确认时,关联表必须标记“待接口确认”。 +- `数据库设计.md` 是 EF Core 实体、映射、Migration、初始化和测试的唯一数据库设计事实源。 +- `database/database-<姓名拼音首字母>.md` 是个人贡献原稿,汇总后继续保留,但不能覆盖主文档。 +- 当前尚未汇总完整表定义,文档成熟度为 **模板/占位,未冻结**。 -## 二、表编号、分工与编写要求 +## 二、DBxxx 分工与个人原稿 -### 2.1 DBxxx 编号与六人分配 +### 2.1 编号分配 -数据库表使用 `DB` 加三位数字作为文档追踪编号。编号不进入 PostgreSQL 真实表名、EF Core 实体名、DbSet、约束名或 Migration 名。 +DBxxx 只用于文档追踪和分工,不进入真实表名、实体、DbSet、约束、索引或 Migration 名。 -| 负责人 | 负责模块 | 数据表编号范围 | -|---|---|---| -| 唐宇昊 | Identity、Engagement | `DB001`~`DB020` | -| 顾欣月 | Catalog、Review | `DB021`~`DB040` | -| 朱惠惠 | Cart、Seckill | `DB041`~`DB060` | -| 韦乾强 | Ordering | `DB061`~`DB080` | -| 张海洋 | Payment、AfterSales | `DB081`~`DB100` | -| 罗皓晨 | Messaging、可靠事件公共表 | `DB101`~`DB120` | +| 负责人 | 负责模块 | DBxxx 范围 | 个人原稿 | +|---|---|---|---| +| 唐宇昊 | Identity、Engagement | `DB001`~`DB020` | `database/database-tyh.md` | +| 顾欣月 | Catalog、Review | `DB021`~`DB040` | `database/database-gxy.md` | +| 朱惠惠 | Cart、Seckill | `DB041`~`DB060` | `database/database-zhh.md` | +| 韦乾强 | Ordering | `DB061`~`DB080` | `database/database-wqq.md` | +| 张海洋 | Payment、AfterSales | `DB081`~`DB100` | `database/database-zhy.md` | +| 罗皓晨 | Messaging、可靠事件公共表 | `DB101`~`DB120` | `database/database-lhc.md` | -编号规则: +规则: -1. 一张 PostgreSQL 持久化表占用一个 DBxxx 编号;Redis Key、RabbitMQ 资源、对象存储 Bucket、视图展示项和 C10 部署资源不占用表编号。 -2. 每名成员只能在本人区间内新增表。表合入 `dev` 后编号保持稳定,表重命名但数据职责不变时保留编号。 -3. 表拆分时原表保留原编号,新表使用新编号;废弃表保留编号并标记“已废弃”,不得重新分配。 -4. 不得为了占满 20 个编号提前创建无业务依据的表;超出本人区间时由全组评审后重新分配。 -5. 跨模块业务事实由事实所属模块登记。调用方可以记录关联编号,但不得建立同义表或直接修改所属模块内部数据。 -6. 每个已登记表必须补齐字段、主键、外键、唯一约束、Check 约束、索引、状态含义和关联接口;只有表名没有完整定义时仍属于“部分定义”,不得直接生成 Migration。 +1. 一张 PostgreSQL 持久化表占一个 DBxxx;不得为了占满区间拆表。 +2. 每人只使用本人区间,只设计本人模块拥有的数据。 +3. 编号进入主文档后不得复用;拆表使用新编号,废弃表保留原编号并标记。 +4. 跨模块业务事实只由事实所有者登记,其他模块只能保存稳定引用或必要快照。 -### 2.2 个人数据库文件与汇总要求 +### 2.2 编写与汇总 -六名成员分别在 `docs/02-设计文档/` 下创建以下文件,不创建个人文件夹: +1. 每人只修改本人原稿,先登记表清单,再按第三章补齐完整定义。 +2. 个人原稿阶段不同时修改主文档,避免六人冲突。 +3. 六份原稿分别交叉评审并合入 `dev` 后,由罗皓晨在独立整合分支汇总本文件。 +4. 首次汇总后,个人原稿继续保留;后续变更必须在同一任务中同步个人原稿和主文档。 +5. 分支、提交、PR 和评审流程统一遵循[《Git 团队协作流程》](Git团队协作流程.md),本文件不重复规定。 -| 负责人 | 个人数据库文件 | 数据表编号范围 | -|---|---|---| -| 唐宇昊 | `database-tyh.md` | `DB001`~`DB020` | -| 顾欣月 | `database-gxy.md` | `DB021`~`DB040` | -| 朱惠惠 | `database-zhh.md` | `DB041`~`DB060` | -| 韦乾强 | `database-wqq.md` | `DB061`~`DB080` | -| 张海洋 | `database-zhy.md` | `DB081`~`DB100` | -| 罗皓晨 | `database-lhc.md` | `DB101`~`DB120` | +## 三、个人原稿内容 -每个个人数据库文件必须: +### 3.1 表登记清单 -1. 只使用本人 DBxxx 编号区间,只设计本人负责模块拥有的数据。 -2. 先给出表登记清单,再按 2.3 节模板逐张补齐字段、约束、索引、关系、删除行为和状态规则。 -3. 每张表列出关联 Axxx;接口尚未确认时标记“待接口确认”,不得自行编造接口编号。 -4. 个人文件是协作阶段材料,不是长期事实源。全部文件通过交叉评审后,由罗皓晨汇总到本文件并统一 ER 图、表清单和完整表定义。 -5. 汇总完成并确认无遗漏后,在同一文档任务中删除六份个人数据库文件;历史贡献通过 Git 记录保留,避免长期维护两套数据库事实。 +每份个人原稿先登记本人实际需要的表,不要求占满编号: -### 2.3 单张表详细定义模板 +| DBxxx | 真实表名 | 表用途 | 关联需求 | 关联接口 | 状态 | +|---|---|---|---|---|---| +| DBxxx | `table_name` | 说明唯一业务事实 | Mxx / Fxx / Xxx / Cxx | Axxx / 待接口确认 | 待评审 | -每名成员在本人 `database-<姓名拼音首字母>.md` 中按以下格式补齐每张表: +### 3.2 单表详细定义 ```markdown #### DBxxx 中文表名(real_table_name) @@ -73,10 +67,11 @@ - 负责人: - 所属模块: - 表用途: -- 关联接口:Axxx +- 关联需求: +- 关联接口: - 当前状态:待评审 -| 字段名 | PostgreSQL 类型 | 允许空 | 默认值 | 说明 | +| 字段名 | PostgreSQL 类型 | 允许空 | 默认值 | 说明与校验 | |---|---|---:|---|---| 约束: @@ -86,28 +81,59 @@ 索引: -| 索引名 | 字段 | 是否唯一 | 服务场景 | +| 索引名 | 字段与顺序 | 是否唯一 | 服务的接口或查询 | |---|---|---:|---| 关系与删除行为: -状态值与转换规则: +状态值与转换: + +并发、幂等与事务: + +敏感数据与脱敏: + +验证场景: ``` -表设计要求: +只有表名或字段列表不算完整定义。字段类型、空值、默认值、主外键、唯一/Check 约束、索引用途、删除行为和状态转换均必须明确。 + +## 四、主文档汇总 + +### 4.1 统一表清单 + +| DBxxx | 真实表名 | 所属模块 | 负责人 | 表用途 | 关联需求/接口 | 状态 | +|---|---|---|---|---|---|---| +| 待汇总 | 待汇总 | 待汇总 | 待汇总 | 六份个人原稿尚未完成 | 待汇总 | 模板/占位 | + +### 4.2 跨模块关系 + +跨模块关系由双方评审,不能由引用方单方面决定对方表结构: + +| 引用方 | 事实所有者 | 引用内容 | 引用方式 | 快照要求 | 状态 | +|---|---|---|---|---|---| +| Cart、Engagement、Review | Identity、Catalog | 用户 ID、商品 ID | 稳定 ID | 无 | 待确认 | +| Ordering | Identity、Catalog | 买家、商品、地址、成交信息 | 稳定 ID + 订单快照 | 必须 | 待确认 | +| Payment、AfterSales | Ordering | 订单、订单项、实付和状态 | 应用契约 + 稳定 ID | 按金额事实确认 | 待确认 | +| Messaging | Ordering、Payment、AfterSales | 接收人和业务目标 | 集成事件 + 稳定 ID | 消息展示摘要 | 待确认 | + +跨模块物理外键如需建立,必须由双方确认删除行为;禁止跨模块级联删除,也不得借外键直接读写其他模块内部表。 + +### 4.3 ER 图 + +六份原稿通过评审后,由罗皓晨生成全局 ER 图。ER 图覆盖已确认的主键、主要外键和关系基数,但不替代字段、约束、索引和状态定义。 -- 表名使用复数 `snake_case`;主键使用 `id`;外键列使用 `<单数实体>_id`。 -- 布尔字段使用 `is_` 或 `has_`;时间点使用 `_at`;金额使用 `_amount`;状态值使用稳定 `lower_snake_case`。 -- 字段必须写明 PostgreSQL 类型、空值、默认值和业务含义,不使用 `TINYINT`、`DATETIME`、`utf8mb4` 等 MySQL 专属定义。 -- 索引必须写明服务的真实查询,不为所有字段机械建索引。 -- 接口中的字段和状态必须能追踪到相应 DBxxx 设计,但公开 API 不得暴露内部表结构或允许跨模块直接改表。 +当前状态:**待汇总**。 -## 三、ER 图 +## 五、冻结与 Migration -各负责人完成 `database-*.md` 并通过交叉评审后,由罗皓晨在此汇总全局 ER 图。ER 图必须覆盖已确认表关系,但不得代替字段、约束和索引定义。 +主文档达到以下条件后才能冻结: -## 四、初始化脚本 +- 六份个人原稿均完成自审和交叉评审。 +- 统一表清单不再包含“待汇总”占位。 +- 每张表的字段、约束、索引、关系、状态和关联接口完整。 +- DBxxx、表名、约束名和索引名无重复。 +- 跨模块引用、订单快照和数据所有权已经双方确认。 +- 全局 ER 图和表创建依赖顺序完整。 +- [《接口设计》](接口设计.md)第五章中会影响表结构的阻塞项已解决,或相关表继续标记为“部分定义”。 -- Migration、初始化和种子数据的最终位置以实际后端结构为准,未建立后端工程前不预建空目录。 -- 演示数据不少于 30 个商品、3 个分类;不得使用真实个人敏感信息。 -- Migration 只能在对应 DBxxx 表结构标记为“已确认”且相关接口契约完成评审后创建。 +只有在主文档中标记为“已确认”的表才能创建 EF Core 实体和 Migration。初始化与 Seed 必须遵守已确认约束及教师演示数据要求,不得使用真实个人敏感信息。 diff --git a/eshop-project-rules-upload/AGENTS.md b/eshop-project-rules-upload/AGENTS.md index 861b2a874fa6fa4bbcc8cf5b6d765d53ffaa8907..eeb06bb5d008d702b1d70dea270a1c1e14d53ff9 100644 --- a/eshop-project-rules-upload/AGENTS.md +++ b/eshop-project-rules-upload/AGENTS.md @@ -74,6 +74,8 @@ ## 四、按任务类型读取文件 +本节编号用于资料分类,不代表设计先后。新增功能或改变业务行为时,设计顺序固定为:教师要求与已确认需求 → 业务流程、状态、异常和模块出入口 → 接口、数据库与架构落地 → 代码与测试。现有接口、表或实现只能用于校验可实施性和发现偏离,不能反向拼接或覆盖已确认的业务流程。 + ### 1. 需求、范围与验收 涉及功能范围、角色、权限、业务规则、模块归属或验收结论时,读取: @@ -90,6 +92,7 @@ 涉及目录结构、依赖方向、公共组件、认证授权、事件、缓存、对象存储、可观测性或部署边界时,读取: - `docs/02-设计文档/系统架构设计.md` 中与任务有关的第 4、5 章和第 6~12、14、15 章对应小节; +- 涉及业务动作、状态或跨模块交接时,读取 `docs/02-设计文档/process/` 中的目标流程; - 相关项目文件、入口文件、依赖清单和配置文件; - 当前能力涉及的需求与验收章节。 @@ -100,6 +103,7 @@ 涉及表、字段、索引、关系、状态、事务、Migration 或演示数据时,读取: - `docs/02-设计文档/数据库设计.md`; +- `docs/02-设计文档/process/` 中已经确认的目标业务流程、状态和模块交接; - 对应需求与接口章节; - 现有实体、映射、DbContext、Migration、初始化或种子数据文件; - 相关测试。 @@ -108,16 +112,21 @@ `数据库设计.md` 当前仍可能包含字段不完整的模板内容和需要按 PostgreSQL/Npgsql 复核的示例。必须以目标表的完整设计及实际实体、映射和 Migration 交叉确认,不能把表标题当作可实施定义。 +六份个人数据库原稿保存在 `docs/02-设计文档/database/database-<姓名拼音首字母>.md`,仅用于贡献和交叉评审追踪。`docs/02-设计文档/数据库设计.md` 是实体、映射、Migration、初始化和测试的唯一数据库设计事实源;未在主文档中标记为“已确认”的表不得创建 Migration。 + ### 4. Web API、DTO 与模块间协作 涉及接口、请求响应、错误码、分页、鉴权或模块间调用时,读取: +- `docs/02-设计文档/process/` 中目标模块已经确认的业务动作、状态、异常和直接出入口; - `docs/02-设计文档/接口设计.md`; - 对应需求、数据库设计和验收标准; - 现有 Controller/Endpoint、DTO、应用服务、领域逻辑和测试; - OpenAPI/Swagger 契约文件(存在时)。 -必须遵守“接口文档先行”:模块间接口需要变化时,先确认并更新接口契约,再修改实现和调用方。不得通过跨模块 DbContext、内部仓储或直接改表代替公开接口。 +接口必须由已确认业务流程中的动作、输入输出、状态和异常结果派生。不得按 Axxx 清单拼接流程,也不得用现有接口缺口反向修改已确认业务语义;发生冲突时先记录接口设计缺口,只有需求变化时才重新评审流程。 + +必须遵守“接口文档先行于代码”:模块间接口需要变化时,在业务流程确认后先更新并确认接口契约,再修改实现和调用方。这里的“先行”只针对代码和调用方,不表示接口先于需求或业务流程。不得通过跨模块 DbContext、内部仓储或直接改表代替公开接口。 读取接口设计时,必须同时定位第一章相关通用约定、第二章目标 Axxx 清单和第三章同编号详细定义;缺少请求字段、响应、错误、鉴权或业务规则时先记录并补齐契约,不得凭清单名称猜测实现。 diff --git a/eshop-project-rules-upload/document-routing.reference.md b/eshop-project-rules-upload/document-routing.reference.md index 849739969e262fe3078ef6e2667bca0fe05491c5..9dc41e29e1ff9a7b3693952776ebe0e8bbb042b0 100644 --- a/eshop-project-rules-upload/document-routing.reference.md +++ b/eshop-project-rules-upload/document-routing.reference.md @@ -76,11 +76,12 @@ | 任务类型 | 最小文档范围 | 需要扩展时 | |---|---|---| | 项目理解 | README、需求 2.4/8/9、架构 1/3/5/14/15 | 再读目标模块七节需求和架构 7.x | -| 新功能或行为变化 | 教师对应编号、需求目标模块七节、需求 5/9、相关设计、命名相关章节 | 跨模块时加入提供方契约和调用方 | -| API/DTO | 需求目标模块、接口 1.x 相关约定、接口清单与对应 Axxx、命名 2/7/17/19 | 鉴权读接口 1.6,列表读 1.11,幂等读 1.12 | +| 新功能或行为变化 | 教师对应编号、需求目标模块七节、需求 5/9、相关业务流程、相关设计、命名相关章节 | 跨模块时加入提供方契约和调用方 | +| 业务流程/流程图 | 需求目标模块七节、需求 5/8/9、业务流程设计目标章节 | 先确认业务动作、状态、异常和模块出入口;完成后再映射架构 7.x、接口 Axxx 和数据库 DBxxx | +| API/DTO | 需求目标模块、业务流程目标章节、接口 1.x 相关约定、接口清单与对应 Axxx、命名 2/7/17/19 | 先从流程提取接口能力;鉴权读接口 1.6,列表读 1.11,幂等读 1.12 | | 数据库/Migration | 需求目标模块、需求 5、数据库对应表、命名 2/6/17/19、实际实体/Migration | 并发事务再读架构 7.x 和接口 1.12 | -| 前端页面 | 需求目标模块、需求 7、架构 6、接口对应 Axxx、命名 2/4/7/17/19 | 多客户端再读架构 6.4 和接口 1.15 | -| 后端业务 | 需求目标模块、架构 4/5/7、接口对应 Axxx、数据库相关 DBxxx、命名 2/5/6/7/17/19 | 安全读架构 8,错误读架构 9 | +| 前端页面 | 需求目标模块、需求 7、业务流程目标章节、架构 6、接口对应 Axxx、命名 2/4/7/17/19 | 多客户端再读架构 6.4 和接口 1.15 | +| 后端业务 | 需求目标模块、业务流程目标章节、架构 4/5/7、接口对应 Axxx、数据库相关 DBxxx、命名 2/5/6/7/17/19 | 安全读架构 8,错误读架构 9 | | 缺陷诊断 | 预期行为来源、实际调用链、现有测试、日志/响应/只读数据 | 契约或设计冲突时再读对应设计章节 | | 文档维护 | 目标文档、直接上游事实源、直接下游消费者 | 完成度表述再读实现、测试与 Git 证据 | | 测试/验收 | 教师验收/评分、需求编号、测试计划/报告、实际实现与命令 | 挑战读需求 4、架构 7.x 和原始脚本 | @@ -130,7 +131,23 @@ | 十四、六人纵向架构职责 | 主责、联调对象和 M00 边界 | | 十五、分阶段实施 | 当前阶段是否允许引入某项能力 | -### 6.3 `docs/02-设计文档/命名规范.md` +### 6.3 `docs/02-设计文档/process/` + +本目录集中维护复杂业务流程图,避免在总需求正文中堆叠同一套详细图示: + +- 修改流程前先读 `docs/02-设计文档/process/README.md`,确认负责人、补充位置、模板、成熟度和检查清单。 +- `业务流程设计.md`:只维护全局核心基线、公共状态、跨模块交接、追踪矩阵和扩展登记。 +- `<负责人缩写>/<模块编号>-<模块名称>流程.md`:由负责人维护单个模块的主流程、状态、异常、模块出入口、由流程派生的接口映射和待评审项;根文档只链接,不重复保存细节。 +- `一、文档定位与事实来源`:需求、流程、架构、接口和数据库的职责边界。 +- `二、绘图与维护约定`:图类型、核心 F 扩展规则、状态和跨模块评审要求。 +- `三、F01~F13 核心业务流程`:商城核心闭环、核心状态、模块直接出入口,以及注册登录、资料地址、商品、购物车下单、支付、订单履约和后台角色流程。 +- `四、核心流程追踪矩阵`:F01~F13 的核心状态、直接入口出口、流程章节、主责人和成熟度。 +- `五、选做与挑战流程登记`:X01~X04 和已选 C 项的基础 F、扩展入口、不可变核心结果和状态。 +- `六、维护与评审规则`:主需求、流程图和下游设计的同步顺序。 + +业务语义仍以主需求为准;流程目录把需求转换为可评审的业务动作、状态、异常和模块交接。核心流程已经完成基线校准但仍待各主责人交叉评审;X/C 扩展必须从核心状态和直接模块出口接入。流程确认后,再派生 API、数据库和架构技术时序;Axxx、HTTP 状态、DTO、DBxxx、Worker、缓存和消息名不得用来拼接或反向覆盖业务流程。接口文档仍是实现阶段的唯一 API 契约,但它先行于代码,不先行于需求和业务流程。 + +### 6.4 `docs/02-设计文档/命名规范.md` 新增或重命名时,先读 `一、目标、优先级与 AI 执行规则`、`二、标准业务词汇` 和 `十九、提交前命名检查清单`,再按资产选择: @@ -155,7 +172,7 @@ 不要求每次全文读取 658 行。只读取公共三节与目标资产章节,并搜索现有同义名称。 -### 6.4 `docs/02-设计文档/接口设计.md` +### 6.5 `docs/02-设计文档/接口设计.md` 先按接口特征选择第一章: @@ -183,25 +200,26 @@ 只有接口清单、没有详细 Axxx 时标记为 `部分定义`;字段、失败响应和业务规则未确认前不得直接编码。当前六份个人原稿已保存在 `docs/02-设计文档/interface/`,主接口文档保留 107 个不重复 Axxx 追踪编号,其中 103 个为有效 HTTP 契约;A229、A230、A418、A431 均为已取消历史编号。整体仍为“部分定义,未冻结”:需继续完成数据库反查、真实 OpenAPI、跨模块公开契约和交叉评审。每次任务开始时重新检查,不永久假设此状态。 -### 6.5 `docs/02-设计文档/数据库设计.md` +### 6.6 `docs/02-设计文档/数据库设计.md` -读取设计说明、编号分配、个人文件规则、ER 图和初始化脚本。协作阶段读取目标负责人的 `docs/02-设计文档/database-<姓名拼音首字母>.md`;汇总完成后读取本文件中的统一表清单和完整定义,再核对实际实体、映射、DbContext、Migration、约束、索引与 Seed。 +读取设计说明、DBxxx 分工、个人原稿规则、单表模板、统一表清单、跨模块关系、ER 图和冻结条件。并行设计阶段读取目标负责人的 `docs/02-设计文档/database/database-<姓名拼音首字母>.md`;汇总完成后以主文档中的统一表清单和完整定义为事实源,再核对实际实体、映射、DbContext、Migration、约束、索引与 Seed。 -当前审计中六份 `database-*.md` 尚未创建,主数据库文档只有 PostgreSQL 公共规则、编号分配和表模板,尚无完整表定义。因此: +当前已建立 `docs/02-设计文档/database/` 原稿目录,但六份个人原稿尚未创建,主文档仍为“模板/占位,未冻结”。因此: - 不能把标题当作完整表定义。 - 不能从需求直接猜字段、类型或状态码。 - 表设计不完整时先补齐并评审,再实现 Migration。 +- 个人原稿汇总后继续保留,但不能覆盖主文档。 - 数据库文档与真实 Migration 冲突时明确记录偏离。 -### 6.6 `docs/03-测试文档/` +### 6.7 `docs/03-测试文档/` - `测试计划.md`:读取范围、类型、环境、用例编号、缺陷流程和进度。 - `测试报告.md`:读取实际轮次、统计、缺陷、典型分析和结论。 当前两份文件仍包含大量空白模板字段。模板只能规定记录格式,不能证明已执行、已通过或达到覆盖率。真实结论必须来自测试项目、命令、环境、原始输出、截图、响应、查询或平台记录。 -### 6.7 过程与交付文档 +### 6.8 过程与交付文档 - Git:`README.md` Git 章节和完整 `Git团队协作流程.md`。 - 日报:`reports/daily/README.md`、本人当天 Git 和验证证据。 @@ -235,11 +253,12 @@ 1. 教师对应验收编号。 2. 需求 2.4、目标模块完整七节、需求 5/8/9。 -3. 架构 4/5 和对应 7.x。 -4. 命名公共三节与目标资产章节。 -5. 接口通用相关小节、Axxx 清单与详细定义。 -6. 数据库目标表及实际实体/Migration。 -7. 目标前后端代码和现有测试。 +3. 业务流程设计中的目标流程;缺失时先登记并补充业务图。 +4. 架构 4/5 和对应 7.x。 +5. 命名公共三节与目标资产章节。 +6. 根据流程动作和模块出入口核对接口通用小节、Axxx 清单与详细定义。 +7. 根据流程中的业务事实和状态核对数据库目标表及实际实体/Migration。 +8. 目标前后端代码和现有测试。 ### 修复一个缺陷 @@ -282,6 +301,7 @@ ```powershell rg -n "^### M04-02 " docs/01-需求文档/需求规格说明书.md rg -n "F12|M06-02" docs/00-项目要求 docs/01-需求文档 +rg -n "F08|M04-01" docs/02-设计文档/process/业务流程设计.md rg -n "^### 7\\.8 " docs/02-设计文档/系统架构设计.md rg -n "A201~A300|Cart_AddCartItem" docs/02-设计文档/接口设计.md rg -n "cart_item|CartItem" docs backend frontend diff --git a/eshop-project-rules-upload/eshop-align-docs.SKILL.md b/eshop-project-rules-upload/eshop-align-docs.SKILL.md index e627e43c0ea1ca7bfb10f1bd8a76f0b14fb97b8f..9d83f5bed1875652624e9b04647e9f085b2eee0c 100644 --- a/eshop-project-rules-upload/eshop-align-docs.SKILL.md +++ b/eshop-project-rules-upload/eshop-align-docs.SKILL.md @@ -29,10 +29,11 @@ description: 维护 E-Shop 教师要求、需求、架构、数据库、接口 | 目标文档 | 上游事实源 | 必查下游 | |---|---|---| | README/项目范围 | 教师项目要求、需求 2.2/2.4/8/9、架构 1/3/15 | 实际目录、入口、依赖、部署和可运行命令 | -| 需求规格 | 教师项目要求、验收/评分编号、用户确认 | 架构、API、数据库、实现与测试追踪 | -| 系统架构 | 需求目标模块、当前交付边界、真实项目/依赖/配置 | 各模块实现、部署和测试策略 | -| 数据库设计 | 需求业务规则/状态、接口字段、实际实体和 Migration | 查询调用方、Seed、测试与兼容性 | -| 接口设计 | 需求角色/流程、数据库、架构安全与错误约定 | OpenAPI、Endpoint、DTO、客户端和契约测试 | +| 需求规格 | 教师项目要求、验收/评分编号、用户确认 | 业务流程、架构、API、数据库、实现与测试追踪 | +| 业务流程设计 | 已确认需求的角色、主流程、状态、异常和模块边界 | 架构技术时序、接口、数据库、页面和流程测试 | +| 系统架构 | 需求目标模块、已确认业务流程、当前交付边界、真实项目/依赖/配置 | 各模块实现、部署和测试策略 | +| 数据库设计 | 已确认流程中的业务事实/状态、接口字段、实际实体和 Migration | 查询调用方、Seed、测试与兼容性 | +| 接口设计 | 已确认流程中的动作、输入输出、状态和异常,数据库与架构约束 | OpenAPI、Endpoint、DTO、客户端和契约测试 | | 测试计划/报告 | 验收标准、实际测试入口、环境、命令和原始结果 | 缺陷闭环、完成度和发布判断 | | 日报/周报 | 对应 README、成员真实 Git、工作区和验证证据 | 汇总、计划和风险,不冒用他人成果 | | 会议纪要 | 模板和真实参会、决策、负责人、截止时间 | 后续任务、需求确认和未决项 | @@ -40,19 +41,30 @@ description: 维护 E-Shop 教师要求、需求、架构、数据库、接口 接口清单没有对应 Axxx 详情、数据库章节只有表名、测试计划或报告仍为空白模板时,必须保留为“部分/模板/缺失”,不能为了文档看起来完整而虚构字段、统计或结论。 +复杂业务流程图集中维护在 `docs/02-设计文档/process/`。`业务流程设计.md` 只保留全局核心基线、公共状态、跨模块交接和追踪索引;各负责人按 `process/README.md` 在本人目录中以“一模块一文档”维护细节。主需求保留功能规则、文字步骤与流程链接,不重复嵌入同一张详细图;需求文字与流程图冲突时先修正业务语义,再同步图示。核心流程必须标明业务状态、直接模块入口和确定出口;X/C 扩展必须绑定基础 F、接入状态和不可变核心结果,不能另起一套主链路。 + +设计顺序固定为“已确认需求 → 业务流程 → 接口/数据库/架构落地 → 实现与测试”。业务图先使用业务动作确定状态和结果,再建立“流程步骤 → Axxx/DBxxx/技术时序”映射。不得把接口清单拼成流程,也不得把 HTTP 状态码、DTO、字段或事件名当作业务节点。“接口文档先行”只表示已派生的接口契约必须先于代码和调用方修改完成确认。 + ## 维护接口汇总 -- `docs/02-设计文档/接口设计.md` 是实现、OpenAPI、联调和测试的唯一接口事实源。 +- `docs/02-设计文档/接口设计.md` 是实现、OpenAPI、联调和测试的唯一接口契约,但其业务能力必须由已确认流程派生。 - 六份 `docs/02-设计文档/interface/interface-<姓名拼音首字母>.md` 作为个人贡献原稿长期保留,用于自审和交叉评审,但不能覆盖总文档。 - 负责人修改个人原稿时,同一任务必须同步总文档中的统一清单、同编号详细定义、需求追踪状态和未决项;不得只改个人文件。 - 汇总时检查 Axxx、`operationId` 和“HTTP 方法 + 路径”全局唯一,并把缺少字段、状态机、鉴权、DBxxx 或跨模块契约的接口标为“部分定义”或“待交叉评审”,不得为了凑齐数量改成“已确认”。 +## 维护数据库汇总 + +- `docs/02-设计文档/数据库设计.md` 是实体、映射、Migration、初始化和测试的唯一数据库设计事实源。 +- 六份 `docs/02-设计文档/database/database-<姓名拼音首字母>.md` 作为个人贡献原稿保留;并行编写阶段只改个人原稿,统一汇总后再同步主文档。 +- 汇总时检查 DBxxx、表名、约束名、索引名、数据所有权和跨模块关系;缺少字段、约束、索引、状态或评审的表不得标记为“已确认”。 + ## 建立一致性追踪 逐项核对: ```text -F/X/C/N/D 编号 → 负责人 → 需求与边界 → 数据设计 → API 契约 +F/X/C/N/D 编号 → 负责人 → 需求与边界 → 业务流程/状态/模块交接 +→ 数据设计与 API 契约 → 实际实现 → 权限与状态 → 测试场景 → 验证证据 → 当前状态 ``` diff --git a/eshop-project-rules-upload/eshop-deliver-feature.SKILL.md b/eshop-project-rules-upload/eshop-deliver-feature.SKILL.md index fdc9e01d809717d6d7cbee663bb866a283371b16..e67d0d622829e7531a110a31caa00e28729302d4 100644 --- a/eshop-project-rules-upload/eshop-deliver-feature.SKILL.md +++ b/eshop-project-rules-upload/eshop-deliver-feature.SKILL.md @@ -16,15 +16,17 @@ description: 按业务模块纵向交付 E-Shop 新功能或预期行为变更 1. 按 `$eshop-project-workflow` 的 `references/document-routing.md` 建立最小事实包,从教师基线和需求规格确认需求编号、负责人、角色、业务规则和验收条件。 2. 需求编号、功能名称、负责人或验收项相互冲突时停止实施并请求确认,不自行合并、重编号或替换负责人。 3. 写明本次包含项、明确排除项、依赖模块和受影响用户流程。 -4. 检查相关实现是否真实存在;不存在时先说明脚手架或契约缺口,不虚构代码结构。 -5. M00 或公共脚手架缺失时将其记录为前置依赖;除非当前任务明确属于 M00,不由单个业务功能任务顺手搭建全仓或代写公共负责人工作。 -6. 区分计划、已实现、已验证和缺失状态。 +4. 确认 `docs/02-设计文档/process/` 中目标流程已覆盖角色、状态、异常和模块出入口;缺失时先补流程,不从现有接口或代码反推预期业务。 +5. 检查相关实现是否真实存在;不存在时先说明脚手架或契约缺口,不虚构代码结构。 +6. M00 或公共脚手架缺失时将其记录为前置依赖;除非当前任务明确属于 M00,不由单个业务功能任务顺手搭建全仓或代写公共负责人工作。 +7. 区分计划、已实现、已验证和缺失状态。 ## 读取最小事实包 | 层面 | 必读章节与资产 | |---|---| | 范围 | 教师对应编号;需求 2.4、目标模块完整七节、需求 5/8/9;挑战任务追加需求 4 | +| 流程 | `process/README.md`、全局核心基线和目标负责人模块流程;确认状态、异常、直接输入输出和扩展接入点 | | 架构 | 架构 4/5,以及目标能力对应的 6、7.x、8、9、14、15 章 | | 命名 | 命名规范 1/2/19,再读取代码、API、数据库、事件、配置或测试对应资产章节 | | 契约 | 接口第一章相关约定、第二章目标 Axxx 清单、第三章同编号详情、实际 OpenAPI 和调用方 | @@ -32,7 +34,7 @@ description: 按业务模块纵向交付 E-Shop 新功能或预期行为变更 | 质量 | 对应验收编号、测试计划、真实测试入口、现有测试与原始结果 | - 只按稳定编号和标题定位,不依赖行号,也不默认加载其他成员的全部模块。 -- 接口只有清单没有 Axxx 详情时先补齐并确认契约;数据库只有表名没有字段、约束和索引时先补齐设计。 +- 先以需求和流程确定业务动作、状态、异常与模块交接,再派生接口能力和数据事实;接口只有清单没有 Axxx 详情时补齐契约,数据库只有表名没有字段、约束和索引时补齐设计。 - 文档与实现不一致时记录 `实现偏离` 和兼容影响,不静默采用更方便的一方。 - 纵向任务只覆盖用户确认的模块和链路;用户只要求其中一层时,明确其余层尚未交付。 @@ -41,6 +43,7 @@ description: 按业务模块纵向交付 E-Shop 新功能或预期行为变更 | 层面 | 必查内容 | |---|---| | 需求 | 对应 F/X/C/M 编号、角色、权限、主流程、异常和验收条件 | +| 流程 | 参与者、业务动作、判断分支、状态转换、模块直接出入口、失败和回归结果 | | 数据 | `数据库设计.md`、实体、映射、约束、索引、Migration、Seed 和历史兼容性 | | 契约 | `接口设计.md`、OpenAPI、DTO、错误码、分页、鉴权和调用方 | | 后端 | API/Endpoint、Application、Domain、Infrastructure、事务、事件和后台任务 | @@ -52,12 +55,14 @@ description: 按业务模块纵向交付 E-Shop 新功能或预期行为变更 ## 按安全顺序实施 1. 先固定需求与验收边界。 -2. 需要改变模块间接口时先更新接口设计或 OpenAPI 契约,再改实现与调用方。 -3. 需要持久化变更时同步实体、映射、Migration、约束、兼容性、Seed 和测试。 -4. 后端实现服务端参数校验、Policy、资源归属、事务、一致性、幂等和错误处理。 -5. 前端实现真实 API 调用、类型、角色入口和加载、空数据、成功、失败、无权限反馈。 -6. 通过公开 API、应用接口或集成事件协作,不跨模块直接使用内部 DbContext、仓储或表。 -7. 只为已经确认的共同需求建设公共能力;单模块逻辑留在本模块。 +2. 先确认业务流程、状态、异常和模块直接出入口;流程图使用业务动作,不使用 Axxx、HTTP 状态或 DTO 拼接流程。 +3. 从已确认流程派生所需接口能力、数据事实和技术时序;发现现有契约冲突时先修正设计缺口,不反向覆盖流程。 +4. 需要改变模块间接口时先更新接口设计或 OpenAPI 契约,再改实现与调用方。 +5. 需要持久化变更时同步实体、映射、Migration、约束、兼容性、Seed 和测试。 +6. 后端实现服务端参数校验、Policy、资源归属、事务、一致性、幂等和错误处理。 +7. 前端实现真实 API 调用、类型、角色入口和加载、空数据、成功、失败、无权限反馈。 +8. 通过公开 API、应用接口或集成事件协作,不跨模块直接使用内部 DbContext、仓储或表。 +9. 只为已经确认的共同需求建设公共能力;单模块逻辑留在本模块。 简单 CRUD 保持简单。只有架构文档已确认的复杂规则才使用 DDD、CQRS、Outbox、缓存或消息等机制。 @@ -71,7 +76,7 @@ description: 按业务模块纵向交付 E-Shop 新功能或预期行为变更 ## 交付结果 -按“需求 → 数据 → 契约 → 后端 → 前端 → 测试 → 文档”列出实际覆盖情况,并明确: +按“需求 → 流程 → 数据/契约 → 后端 → 前端 → 测试 → 文档”列出实际覆盖情况,并明确: - 已完成和已验证的纵向链路; - 未完成、未验证或由其他负责人承担的链路; diff --git a/eshop-project-rules-upload/eshop-project-workflow.SKILL.md b/eshop-project-rules-upload/eshop-project-workflow.SKILL.md index fbc5411d8d541d5e6a4a46cf49593f1a3a0cbe4b..b3f98a177d5aaadd7cb23d0b17d3e9861083771d 100644 --- a/eshop-project-rules-upload/eshop-project-workflow.SKILL.md +++ b/eshop-project-rules-upload/eshop-project-workflow.SKILL.md @@ -29,7 +29,9 @@ description: 作为 E-Shop 仓库所有任务的项目级总入口,统一完 3. 将关键文档标记为 `完整定义`、`部分定义`、`模板/占位`、`实现偏离` 或 `缺失`。 4. 接口只有清单没有 Axxx 详情、数据库只有表名没有字段约束、测试文件只有模板时,先作为缺口报告,不把它们当作可实施契约或通过证据。 5. 同一事实冲突时,按教师基线、用户当前确认、真实实现与验证证据、已确认设计、模板与计划的顺序判断。 -6. 接口任务以 `docs/02-设计文档/接口设计.md` 为唯一实施契约;`docs/02-设计文档/interface/` 中的个人原稿只用于贡献追踪,修改后必须同步总文档。 +6. 新增功能或改变业务行为时,先由需求确认角色、规则和验收,再在 `docs/02-设计文档/process/` 确认业务流程、状态、异常和模块出入口;接口、数据库和架构从流程派生,不能按现有 Axxx 或 DBxxx 反向拼接流程。 +7. 业务流程确认后,接口任务以 `docs/02-设计文档/接口设计.md` 为唯一实施契约;“接口先行”只表示先于代码和调用方修改。`docs/02-设计文档/interface/` 中的个人原稿只用于贡献追踪,修改后必须同步总文档。 +8. 数据库任务以 `docs/02-设计文档/数据库设计.md` 为唯一实施契约;`docs/02-设计文档/database/` 中的个人原稿用于并行设计和评审,未确认表不得生成 Migration。 ## 选择专项 Skill