---

name: db-design-gen description: A3 DB 设计 + REQ 回填——基于 docs/01-需求清单//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. 渲染「表清单」：每行 - \` — <一句话用途>`。
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 输入 + 回填 依赖表）