---
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 Skill AskUserQuestion
---

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

# 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：打印当前位置流程图

向用户展示当前在 A 阶段流程中的位置（A-only，`▶` 标在 A3）：

```
┌──────────────────────────────────────────────────────┐
│ 📋 阶段 A：规划（一次性）                               │
│                                                       │
│   A0 初始化项目 → A1 锁范围（REQ 卡片）                 │
│                          ↓                            │
│     ⏸ 等你审阅 REQ，重新运行 /plan-start 继续      │
│                          ↓                            │
│   A2 生成骨架 → ▶ A3 生成 DB 设计 → A4 初始化 DB → A5 生成下游文档│
│                          ↓                            │
│     ⏸ 等你审阅 docs/03，重新运行 /plan-start 继续  │
└──────────────────────────────────────────────────────┘
```

### A. 读取设计输入

用 `Read` / `Glob` 读取：

- `docs/04-技术规范.md` § 一+ 命名规范（表名 / 字段名 / 索引名 / 外键名约定，及主键 / 时间戳 / 软删等审计列约定）
- `docs/01-需求清单/index.md` 模块索引（模块代码 ↔ 中文名）
- `docs/01-需求清单/*/REQ-*.md` 所有 REQ 卡片，提取 `req_id` / `goal` / `输入`（主表+从表的字段清单）/ `输出`（主表+从表的字段清单）/ `跨字段规则` / `边界` / `验收`

### B. LLM 推导 schema

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

1. **表名 / 列名 / 索引名 / 外键名** 严格套用 `docs/04 § 一+` 的命名规范
2. **审计列**：除明确不需要的辅助表外，每张业务表至少含 `created_at` / `updated_at`；如 `docs/04 § 一+` 约定了 `created_by` / `updated_by` / 软删 `deleted_at`，一并补全
3. **主键**：默认 `id BIGINT UNSIGNED PRIMARY KEY AUTO_INCREMENT`，除非 REQ 明确要求复合主键 / UUID / 业务主键
4. **外键**：依据 REQ 中的引用关系（如「订单引用客户」），明确列出 `ON DELETE` / `ON UPDATE` 策略；不能确定时默认 `RESTRICT`
5. **索引**：根据 REQ 的查询模式（如"按时间范围查"、"按状态筛选"）推导业务索引；外键列默认建索引
6. **业务注记**：对每张表用一两句话说明业务用途、关键约束、与其他表的关系

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

### C. 渲染 docs/03

1. 用 `Read` 读取 `${CLAUDE_SKILL_DIR}/templates/docs-03-header-template.md`，填充 `schema_name`（从 `.env.local` 读 `DB_SCHEMA`，无则填 `【人工填写：DB_SCHEMA】`）、`er_overview`（基于步骤 B 表关系生成的纯文本 ER 概览）。
2. 渲染「表清单」：每行 `- \`<table_name>\` — <一句话用途>`。
3. 对每张表：用 `Read` 读取 `${CLAUDE_SKILL_DIR}/templates/docs-03-table-template.md`，填充字段 / 索引 / 外键 / 业务注记。
4. 用 `Write` 写入 `docs/03-数据库设计文档.md`。

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

1. 用 `Glob` 列出 `docs/01-需求清单/*/_module.md`（模块头）和 `docs/01-需求清单/*/REQ-*.md`（REQ 卡片）。
2. 用 `Grep` 在这些文件中搜索 `TBD(A3 自动补)` 的**行号**（不读全文）。两种行命中：
   - `涉及表: TBD(A3 自动补)` → 模块级（仅在 `_module.md`，每文件一次）
   - `依赖表: TBD(A3 自动补)` → REQ 级（仅在 `REQ-*.md`，每文件一次）
3. 对每个命中行按类型回填：
   - **模块级 `涉及表`**（`_module.md`）：用 `Read` 取该文件 `module_code` + `module_name`，聚合步骤 B 中所有归属该模块的表（多表用 `, ` 分隔）；`Edit` 替换为 `涉及表: <table1>, <table2>, ...`
   - **REQ 级 `依赖表`**（`REQ-*.md`）：从文件名直接得 `req_id`（`REQ-USR-001.md` → `REQ-USR-001`）；根据步骤 B 推导结果定位该 REQ 关联的表；`Edit` 替换为 `依赖表: <table1>, <table2>`
   - **不动** `TBD(A5 自动补)` 的两种行（`依赖接口` REQ 级 / `依赖模块` 模块级）—— 由 A5 `downstream-gen` 生成 docs/05 + 完成模块 DAG 后回填
4. 用 `Grep` 再次扫 `TBD(A3 自动补)` 应 0 命中；仍有残留则打印残留位置清单并停下。
5. 打印回填统计：`A3 回填 <M> 处模块涉及表 + <N> 处 REQ schema_refs`。

### E. 勾选 docs/08 自动项 + 停下等人工审阅

1. 用 `Edit` 在 `docs/08-模块任务管理.md` 勾选 2 个自动项（**不勾**第 3 个人工闸门，由用户审阅后自己勾）：
   - `  - [ ] docs/03-数据库设计文档.md 已生成` → `[x]`
   - `  - [ ] docs/01 各 REQ 卡片"涉及数据表"已回填` → `[x]`
   - `  - [ ] 用户已审阅 docs/03 表结构` 保持 `[ ]`（人工勾）
   - `- [ ] A3 DB 设计 + REQ 回填 — db-design-gen` 保持 `[ ]`（最后一个子项勾后再勾父项）

2. 输出 `db-design-gen: docs/03 已生成 + N 处 REQ 已回填依赖表`。

3. 打印停下横幅并**停下**（**不调** `Skill(db-init)`，A4 由用户审阅后手动恢复）：

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

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

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

    审阅完成后，到 docs/08 § 一 把 A3 的「用户已审阅 docs/03 表结构」
    手动勾上（`[ ]` → `[x]`），然后再勾父项 `- [ ] A3 DB 设计 + REQ 回填`，
    再运行：
      /erp-workflow:plan-start

    （入口会读取 docs/08 进度，自动派发到 A4 db-init）
   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
   ```

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

## 不变量

- 本 skill **不连接任何数据库**，纯文档驱动；MySQL 连接验证 / DDL apply 由 A4 `db-init` 负责
- REQ 卡片的 `依赖接口` 字段不在此处填充，留给 A5 `downstream-gen` 在生成 docs/05 后按 `TBD(A5 自动补)` 回填
- DB 设计与 REQ 卡片同等重要，必须留出人工审阅闸门，避免 LLM 推导的表结构未经把关就被 A4 翻译成 DDL 并 apply 到 MySQL

## 参考

- `${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 输入 + 回填 `依赖表`）