# 阶段 ③ 详细设计（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 项目事实适配；稳定规则编号保留。