---
name: db-design-gen
description: A3 DB 设计 + REQ 回填——基于 docs/01 REQ 卡片正向设计 docs/03 并回填 REQ 卡片与模块头的 TBD 占位。
user-invocable: false
allowed-tools: Read Write Edit Grep Glob
---

**所有输出必须使用中文。**

# db-design-gen

每步骤完成后用 `Edit` 在 `docs/08-模块任务管理.md` § 一 勾选对应子项。

## 执行步骤

### A. 读取设计输入

读：

- `docs/04-技术规范.md`
- `docs/06-实现策略.md`（A2 人工填写的实现策略；若含影响数据模型的关键决策 / 对默认约定的偏离，步骤 B 据此调整）
- `docs/01-需求清单/index.md` 模块索引
- `docs/01-需求清单/*/*.md` 所有 REQ 卡片（跳过文件名为 `_module.md` 的模块头；卡片文件名 == req_id）

### B. 推导 schema

基于步骤 A 读到的 REQ + 命名规范，**正向推导**业务实体 → 表 + 字段 + 索引 + 语义引用关系。要求：

1. 严格套用 `docs/04` 命名规范 + 匈牙利列前缀（`i`=int / `s`=varchar / `t`=datetime）
2. **主键**：标准列 `iIncrement` int 主键。REQ 明确要求不同主键（复合主键 / UUID / 业务主键）时按 REQ，并在该表业务注记里注明偏离原因
3. **语义引用关系**：依据 REQ 中的引用关系（如「订单引用客户」），列出 `from→to`（如 `sCustomerId → 客户表.sId`）；仅语义、不建 FK 约束、不写 `ON DELETE` / `ON UPDATE`，应用层维护一致性
4. **索引**：根据 REQ 的查询模式推导业务索引；语义引用列默认建索引；租户隔离列 `sBrandsId` / `sSubsidiaryId`（标准列）按业务查询模式建组合索引。
   - 索引 bullet 的 `(类别)` 槽位**统一用 ASCII**：唯一索引写 `UNIQUE`、普通/组合索引写 `INDEX`（与 DDL 侧 `UNIQUE KEY` / `KEY` 对齐，validate-ddl 据此比对 UNIQUE\|INDEX 类别）；主键不在 `### 索引` 重复列（由标准列 `iIncrement` 治理）。
5. **业务注记**：对每张表用一两句话说明业务用途、关键约束、与其他表的关系

> 若 `docs/06-实现策略.md` 载有影响数据模型的关键决策 / 对默认约定的偏离（如软删除标志、乐观锁版本列、特殊主键策略、多租户隔离方式等），**优先遵循**，并在对应表「业务注记」注明依据。

如果某 REQ 表述模糊以致无法推断关键 schema 细节（如：枚举值范围 / 字段长度上限 / 必填性），先按合理默认推导并在该字段「业务含义」列加 `【人工填写：需用户审阅】` 标注，待步骤 E 用户审阅时调整；**不打断本次推导**。

### C. 渲染 docs/03

1. 读取 `${CLAUDE_SKILL_DIR}/templates/docs-03-header-template.md`，填充 `schema_name`（从 `config-vars.yaml` 读 `database.schema`，无则填 `【人工填写：database.schema】`）、`er_overview`（纯文本 ER 概览）。「项目标准列约定」是固定 7 列（主表）/ 8 列（从表，额外含 `sParentId`），无占位、原样保留。
2. 渲染「表清单」：对每张表读取并填充 `${CLAUDE_SKILL_DIR}/templates/docs-03-table-template.md`——标准列已内置原样输出，只需填业务字段（`{{#each columns}}`）/ 索引 / 引用关系 / 业务注记。标准列按表位区分：**主表**（docs/03 表清单第一张表）输出 7 行标准列（`iIncrement` / `sId` / `sBrandsId` / `sSubsidiaryId` / `tCreateDate` / `iOrder` / `sMemo`）；**从表**（第二张起的其余表）输出 8 行，额外加入 `sParentId`（varchar(50) NOT NULL，业务父级ID）且**位置紧随 `sId` 之后**。其中 `sId` / `sBrandsId` / `sSubsidiaryId` / `sParentId` 均为 varchar(50) NOT NULL；`sBrandsId` / `sSubsidiaryId` 默认 `1111111111`；`tCreateDate` 默认当前时间；`iOrder`（int NOT NULL，排序号）默认为数据行条数+1，由应用在 insert 时算 count+1 赋值（非 SQL 默认）；`sMemo`（LONGTEXT，可空）备注。这些列的『当前时间 → CURRENT_TIMESTAMP』『1111111111 → DEFAULT '1111111111'』『iOrder 不写 SQL 默认』等 DDL 默认值翻译由下游 A.1 db-init 处理，docs/03 只记录业务语义。
3. 写入 `docs/03-数据库设计文档.md`。

勾选：`  - [ ] docs/03-数据库设计文档.md 已生成`

### D. 回填模块头 + REQ 卡片的 TBD 字段

1. 列出 `docs/01-需求清单/*/*.md`：`_module.md`（模块头）和其余 .md（REQ 卡片，文件名 == req_id）。
2. 在这些文件中搜索 `TBD(A3 自动补)` 的并回填。 不动 `TBD(A5 自动补)`
3. 打印回填统计：`A3 回填 <M> 处模块"涉及表" + <N> 处 REQ"依赖表"`。

勾选：`  - [ ] docs/01 各 REQ 卡片"依赖表" + 模块头"涉及表" 已回填`

### E. 勾选 A3 顶层 + 停下等人工审阅

1. 勾选 A3 顶层（A3 两个子项已在 C / D 步骤分别勾选）：`- [ ] A3 DB 设计 + REQ 回填 — db-design-gen`

2. 打印停下横幅并**停下**，不调用任何下游 skill：

   ```
   [db-design-gen] ✅ A3 DB 设计完成
   产出：docs/03-数据库设计文档.md + REQ 卡片依赖表/模块头涉及表已回填
   ⏸ 请审阅 docs/03（业务实体覆盖、字段类型/默认值、索引、语义引用关系、`【人工填写：需用户审阅】` 标注）。
   审阅完成后运行：/erp-workflow:plan-start
   ```

## 参考

- `${CLAUDE_SKILL_DIR}/templates/docs-03-header-template.md`
- `${CLAUDE_SKILL_DIR}/templates/docs-03-table-template.md`
- `docs/04-技术规范.md` § 一+（命名规范输入）
- `docs/06-实现策略.md`（A2 人工填写；影响 schema 的关键决策 / 偏离来源）
- `docs/01-需求清单/<module>/_module.md`（模块头：回填 `涉及表`）
- `docs/01-需求清单/<module>/<req_id>.md`（REQ 输入 + 回填 `依赖表`）