朱子纯 / erp-workflow-plugin

SKILL.md 4.99 KB

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 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 框图）：

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