---
name: db-design-gen
description: A3 DB 设计 + REQ 回填——基于 docs/01-需求清单/<module>/REQ-*.md 正向设计 docs/03-数据库设计文档.md（业务实体 → 表 + 字段 + 索引 + 外键 + 业务注记），并把回填值写入 REQ 卡片的「依赖表: TBD(A3 自动补)」与模块头的「涉及表: TBD(A3 自动补)」占位。生成完毕停下等人工审阅。
user-invocable: false
allowed-tools: Read Write Edit Grep Glob Bash(cat *)
---

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

# db-design-gen

## 前置条件

- A1 `scope-lock` 已完成：`docs/01-需求清单/<module>/_module.md` + `docs/01-需求清单/<module>/REQ-*.md` 已生成，含 `TBD(A3 自动补)` 占位。
- A2 `skeleton-gen` 已完成：`docs/04-技术规范.md § 一+` 命名规范已生成（本 skill 推导表/字段命名时严格遵循）。

## 执行步骤

### 步骤 0：打印当前位置流程图

用 `Bash` 执行 `cat` 命令向用户展示当前位置流程图（stdout 即 ASCII 框图）：

```bash
cat "${CLAUDE_PLUGIN_ROOT}/skills/plan/db-design-gen/banners/flow.txt"
```

### A. 读取设计输入

读：

- `docs/04-技术规范.md`
- `docs/01-需求清单/index.md` 模块索引
- `docs/01-需求清单/*/REQ-*.md` 所有 REQ 卡片

### B. 推导 schema

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

1. 严格套用 `docs/04` 的命名规范
2. **主键**：模板内置 `iIncrement` 为主键。REQ 明确要求复合主键 / UUID / 业务主键时按 REQ；其他主键变更需同步改 docs-03-header / docs-03-table 两份模板
3. **外键**：依据 REQ 中的引用关系（如「订单引用客户」），明确列出 `ON DELETE` / `ON UPDATE` 策略；不能确定时默认 `RESTRICT`
4. **索引**：根据 REQ 的查询模式推导业务索引；外键列默认建索引；标准列里 `sBrandsId` / `sSubsidiaryId` 这类多租户隔离列，按业务查询模式建组合索引
5. **业务注记**：对每张表用一两句话说明业务用途、关键约束、与其他表的关系

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

### C. 渲染 docs/03

1. 读取 `${CLAUDE_SKILL_DIR}/templates/docs-03-header-template.md`，填充 `schema_name`（从 `.env.local` 读 `DB_SCHEMA`，无则填 `【人工填写：DB_SCHEMA】`）、`er_overview`（纯文本 ER 概览）。
2. 渲染「表清单」：对每张表：读取并填充 `${CLAUDE_SKILL_DIR}/templates/docs-03-table-template.md`。
3. 写入 `docs/03-数据库设计文档.md`。

完成后，用 `Edit` 在 `docs/08-模块任务管理.md` 中勾选：
- `  - [ ] docs/03-数据库设计文档.md 已生成`

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

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

完成后，用 `Edit` 在 `docs/08-模块任务管理.md` 中勾选：
- `  - [ ] docs/01 各 REQ 卡片"依赖表" + 模块头"涉及表" 已回填`

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

1. 完成后，用 `Edit` 在 `docs/08-模块任务管理.md` 中勾选 A3 顶层（A3 两个子项已在 C / D 步骤分别勾选）：
   - `- [ ] A3 DB 设计 + REQ 回填 — db-design-gen`

2. 打印停下横幅并**停下**：

   ```
   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
    [db-design-gen] ✅ A3 DB 设计完成

    产出：
      ✓ docs/03-数据库设计文档.md
      ✓ docs/01-需求清单/<module>/REQ-*.md 依赖表已回填 + _module.md 涉及表已回填

    ⏸ 现在请你审阅 docs/03。
       重点关注：
         - 业务实体覆盖是否完整
         - 字段类型 / 长度 / 是否可空 / 默认值是否合理
         - 索引是否覆盖主要查询模式
         - 外键 ON DELETE / ON UPDATE 策略是否符合业务
         - 字段「业务含义」列含 `【人工填写：需用户审阅】` 标注的位置需逐一确认

    审阅完成后，再运行：
      /erp-workflow:plan-start

   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
   ```

   **停止**，不调用任何下游 skill。

## 参考

- `${CLAUDE_SKILL_DIR}/templates/docs-03-header-template.md`
- `${CLAUDE_SKILL_DIR}/templates/docs-03-table-template.md`
- `docs/04-技术规范.md` § 一+（命名规范输入）
- `docs/01-需求清单/<module>/_module.md`（模块头：回填 `涉及表`）
- `docs/01-需求清单/<module>/REQ-*.md`（REQ 输入 + 回填 `依赖表`）