82 lines
5.4 KiB
Markdown
82 lines
5.4 KiB
Markdown
# 阶段 ③ 详细设计（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 详细设计文档结构
|
||
|
||
```text
|
||
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](02-architecture.md) §3.2）。
|
||
|
||
### 3.3 交付物清单
|
||
- 详细设计文档入 `docs/v2/` 或相应业务目录，注明草案/定案和所覆盖需求编号。
|
||
- 契约草案（类型/迁移/错误码表）
|
||
- 测试映射表（为 ⑥ 验证做准备）
|
||
|
||
---
|
||
|
||
## 4. 轻量路径（小改动）
|
||
|
||
- 单接口小改：契约 + 边界 + 测试映射合并为设计文档中的 2-3 小节。
|
||
- 触碰共享契约、迁移、状态机、模型工具与数据出口：必须完整走详细设计。
|
||
|
||
---
|
||
|
||
## 5. 相关文档
|
||
|
||
- 输入：阶段 ① [01-requirement.md](01-requirement.md)、阶段 ② [02-architecture.md](02-architecture.md)
|
||
- UI 相关设计拆到：阶段 ④ [04-ui-spec.md](04-ui-spec.md)
|
||
- 实现时按此设计编码：阶段 ⑤ [05-implementation.md](05-implementation.md)
|
||
|
||
变更：XB-1.0 / 2026-09-28，按兴邦 Next.js + FastAPI 项目事实适配；稳定规则编号保留。
|