---
name: detailed-design
type: procedure
when: '详细设计, 接口设计, 数据库设计, DDL设计, 类设计, 详细方案, detailed design'
scope:
  - backend
  - frontend
products:
  - '*'
id: ka-procedure-详细设计流程
asset_kind: procedure
lifecycle_status: active
authority: supporting
owner_mechanism_id: mc-architecture-design
routes:
  - code_change
primary_triggers:
  - 详细设计流程
secondary_triggers: []
negative_triggers: []
priority: P1
specificity: 5
consumes:
  - mc-architecture-design
emits:
  - database_design
  - api_specification
  - openapi_spec
  - traceability_matrix
required_evidence:
  - execution_evidence
version: 1.1.0
last_reviewed: '2026-06-01'
stages: ["详细设计"]
---

## 适用场景
从架构设计产出实现锚点（数据结构、接口定义、状态机）、DDL 和映射矩阵。适用于编码前的设计阶段。

详细设计的正式必需产出不是固定的 `04-详细设计文档.md` 单文件。默认产出为：

- `docs/architecture/02-数据库设计文档.md`：承载 `DD-T*`、表字段、索引、审计、租户、安全和生命周期。
- `docs/architecture/03-API接口规格文档.md`：承载 `DD-A*`、端点、字段、错误、副作用和验收场景。
- `docs/api/openapi.yaml`：API 路径、操作和 schema 权威资产。
- SQL/migration 文件：数据库物理结构权威资产。

`docs/architecture/04-详细设计文档.md` 仅作为复杂模块或旧项目迁移的可选补充；如果数据库设计和 API 规格已完整承载详细设计，门禁不得强制要求该文件。

## 步骤
1. 确认架构设计已冻结，并在详细设计中引用 `ARCH-*`。
2. 产出数据库详细设计，声明 `DD-T*`，并同步 SQL/migration 权威资产。
3. 产出 API 详细设计，声明 `DD-A*`，并同步 `docs/api/openapi.yaml`。
4. 维护追踪矩阵，把 `REQ/PROTO/ARCH/DD` 关系写入 `docs/traceability/01-需求原型设计实现追踪矩阵.md`。
5. 进入切片规划前，确保后续切片能引用 `DD-*` 或 `ARCH-*` 并生成 `SLICE-*` 与 `AC-*`。

## 检查点
- [ ] DDL 命名/注释/审计字段/主键完备
- [ ] DDL 有兼容窗口和回滚策略
- [ ] 数据库设计声明 `DD-T*` 并引用 `ARCH-*`
- [ ] API 规格声明 `DD-A*` 并引用 `ARCH-*`
- [ ] OpenAPI 与 API 文档路径和字段一致
- [ ] SQL/migration 权威资产存在
- [ ] 页面映射/字段变更/菜单权限/状态机可追溯到 UI 交互设计
- [ ] 新增/修改菜单的角色授权和权限标识已文档化
- [ ] 实现锚点可供任务拆解直接消费

## 注意事项
- 禁止先写说明文字再补实现锚点（锚点优先）
- 禁止只写 `04-详细设计文档.md` 而缺少数据库设计、API 规格、OpenAPI 或 SQL/migration 权威资产
- DDL 必须指定关联策略和审计策略
