5.4 KiB
5.4 KiB
阶段 ③ 详细设计（Detailed Design）
定义：把架构落到可实现的粒度——每个接口的签名与契约、数据结构与迁移、视图状态机、异常处理、边界条件。详细设计完成后，实现者不需要再做任何设计决策，只需照做。 输入：① 规格 + ② 架构（模块边界、owner、契约归属）。 输出：详细设计文档（接口/数据/状态机/异常/边界）+ 可落地的契约声明（类型定义、表结构草案）。 进入下一阶段（④ UI Spec / ⑤ 实现）：接口契约与数据契约已定案，边界与异常已覆盖。
1. 要求（Requirements）
1.1 进入条件
- 架构已定案（无阻塞性未决决策）。
- 规格的
BR-*/E-*/AC-*全部可映射到具体接口/数据/状态。
1.2 完成条件（DoD）
- 每个公开接口（HTTP/SSE端点、函数、模型工具及业务事件）有签名、入参校验规则、返回与错误语义
- 每个数据结构（表/文件/状态对象）有字段、类型、可空性、owner；变更走追加式迁移且有守卫
- 每个有状态视图/流程有状态机（状态全集 + 合法转换 + 每个状态的禁用手势）
- 规格中每条
E-*都能落到具体错误码 + 处理路径（重试/降级/回滚） - 边界条件显式列出：空输入、上限、并发、超时、权限缺失、版本不兼容
- 所有契约与规格 id 可双向追溯（实现点 ↔ BR/E/AC）
2. 规则（Rules）
| 编号 | 规则 |
|---|---|
| R-3.1 | 契约先行且单一：接口与数据契约在详细设计中定案，实现只落契约不发明契约；跨进程契约只放共享层一处（G-1）。 |
| R-3.2 | 入参显式校验：每个对外接口（HTTP、文件上传、SQL数据卡参数、模型请求和服务命令）的入参都有校验（类型/枚举/边界），禁止裸用；"无入参"是唯一例外。通用校验器不得被滥用成"非空字符串检查"。 |
| R-3.3 | 状态机完备：状态全集含加载/空/错误/提交中等"非 happy path"状态；每个状态定义允许的动作与禁用手势。折叠状态机（如把 Loading 与 Submitting 合并成一个布尔）会丢失关键行为，禁止。 |
| R-3.4 | 异常必有归属：每条失败路径有明确处理语义（重试上限、降级、回滚、幂等）与错误码；静默失败是设计缺陷。 |
| R-3.5 | 迁移只追加：持久化结构变更只能追加带守卫的迁移（版本号递增 + 幂等守卫），禁止修改历史迁移；迁移只跑一次。 |
| R-3.6 | 边界显式：空输入、数量上限、并发/竞态、超时、凭据缺失、旧版本兼容等边界条件写成条目，不得留给实现时"顺手处理"。 |
| R-3.7 | 单实现点：一条规则/一个行为只有一个实现点（继承规格 R-1.3）；发现需要多处实现，回到规格拆分。 |
| R-3.8 | 详细设计可评审：设计文档要能被实现者之外的人评审出"漏了 X 状态/缺了 Y 错误码"，否则说明粒度还不够。 |
3. 输出规范
3.1 详细设计文档结构
1. 范围与本设计覆盖的规格 id BR-xx / E-xx / AC-xx 清单（双向追溯表）
2. 接口设计 每个接口：签名 / 入参校验规则 / 返回 / 错误语义 / owner
3. 数据设计 表/文件/对象：字段、类型、可空性、owner、迁移草案（只追加）
4. 状态机与流程 有状态视图/流程的状态机表（状态 × 转换 × 动作 × 守卫）
5. 异常与错误码 错误码表：码 / 触发条件 / 用户可见消息 / 处理路径（重试/降级/回滚/幂等）
6. 边界条件清单 空输入 / 上限 / 并发 / 超时 / 权限 / 版本兼容
7. 测试映射 每个 AC-xx 对应的测试点（单测/集成/E2E 层级建议）
8. 未决项 遗留问题（owner + needed-by），或已解决的决策记录
3.2 契约声明（可落地的部分）
- 类型定义：新增共享业务契约优先位于
backend/contracts/，由FastAPI请求/响应模型引用；前端同步以已验证的生成物或契约测试为准。当前不存在完整OpenAPI生成流水线，建设前标为待实现。不要顺手重排旧API的所有请求模型。 - 数据结构草案：DDL/迁移骨架，标注幂等守卫。
- 状态机表：Markdown 表格即可，复杂流程可配 sequence 图（见 02-architecture.md §3.2）。
3.3 交付物清单
- 详细设计文档入
docs/v2/或相应业务目录，注明草案/定案和所覆盖需求编号。 - 契约草案（类型/迁移/错误码表）
- 测试映射表（为 ⑥ 验证做准备）
4. 轻量路径（小改动）
- 单接口小改：契约 + 边界 + 测试映射合并为设计文档中的 2-3 小节。
- 触碰共享契约、迁移、状态机、模型工具与数据出口：必须完整走详细设计。
5. 相关文档
- 输入：阶段 ① 01-requirement.md、阶段 ② 02-architecture.md
- UI 相关设计拆到：阶段 ④ 04-ui-spec.md
- 实现时按此设计编码：阶段 ⑤ 05-implementation.md
变更：XB-1.0 / 2026-09-28，按兴邦 Next.js + FastAPI 项目事实适配；稳定规则编号保留。