SKILL.md 7.45 KB

Edit Raw Blame History



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 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 推导表/字段命名时严格遵循）。


执行步骤


步骤 A0：确认 ERP schema 约定（一次性）

在正向设计 schema 之前，先确认本项目的 3 项数据库约定。默认值即现 ERP 约定，用户可逐项覆盖。结果写入 docs/04 + CLAUDE.md，本 skill 后续步骤（B/C）严格引用确认后的值，不再字面写死。


先用 Grep 检查 docs/04-技术规范.md 是否已含 ## 四、数据库 schema 约定 节。已存在则视为本约定已确认，跳过本步骤直接读取该节作为 PK_CONVENTION / TENANT_COLS / COL_PREFIX_RULE 的值，进入步骤 A。


用 AskUserQuestion 一次性提出以下 3 个问题（每题给「沿用默认」与「自定义」两类选项；选自定义时追问具体值）：


主键约定（PK_CONVENTION）


默认（沿用 ERP）：iIncrement int 整数主键（自增方式由实现决定：DB AUTO_INCREMENT 或应用/触发器分配），另设 sId varchar(100) 业务 ID 对外暴露。
自定义：用户给出主键列名 / 类型 / 生成策略（如复合主键 / UUID / 业务主键）。


租户隔离列（TENANT_COLS）


默认（沿用 ERP）：sBrandsId varchar(100)（品牌 ID，多租户隔离）+ sSubsidiaryId varchar(100)（子公司 ID，组织层级隔离），默认值均为 1111111111。
自定义：用户给出租户列名 / 类型 / 默认值，或声明本项目不做多租户隔离（此时 TENANT_COLS = 「无」）。


列命名前缀规则（COL_PREFIX_RULE）


默认（沿用 ERP）：匈牙利前缀——i = int、s = varchar、t = datetime。
自定义：用户给出自己的前缀/命名规则，或声明不使用前缀（此时 COL_PREFIX_RULE = 「无前缀，列名直接用业务语义」）。


得到三项确认值后：


写入 docs/04-技术规范.md：用 Grep 确认无 ## 四、数据库 schema 约定 节后，用 Edit 在文末追加该节，列出 PK_CONVENTION / TENANT_COLS / COL_PREFIX_RULE 三项的确认值（每项含列名/类型/默认值/生成策略的完整描述）。

写入 CLAUDE.md：用 Edit 在「Schema 演化规约」节末尾追加一条「数据库 schema 约定（A3 确认）」小节，简述三项约定，并注明「详见 docs/04 § 四」。


后续步骤 B/C 用到 {{PK_CONVENTION}} / {{TENANT_COLS}} / {{COL_PREFIX_RULE}} 处，一律引用此处确认后的值。


A. 读取设计输入

读：


docs/04-技术规范.md

docs/01-需求清单/index.md 模块索引

docs/01-需求清单/*/REQ-*.md 所有 REQ 卡片


B. 推导 schema

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


严格套用 docs/04 的命名规范 + 步骤 A0 确认的 COL_PREFIX_RULE 列命名前缀规则

主键：套用步骤 A0 确认的 PK_CONVENTION。REQ 明确要求与确认约定不同的主键（复合主键 / UUID / 业务主键）时按 REQ，并在该表业务注记里注明偏离原因

外键：依据 REQ 中的引用关系（如「订单引用客户」），明确列出 ON DELETE / ON UPDATE 策略；不能确定时默认 RESTRICT


索引：根据 REQ 的查询模式推导业务索引；外键列默认建索引；步骤 A0 确认的 TENANT_COLS 租户隔离列（若非「无」），按业务查询模式建组合索引

业务注记：对每张表用一两句话说明业务用途、关键约束、与其他表的关系


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


C. 渲染 docs/03


读取 ${CLAUDE_SKILL_DIR}/templates/docs-03-header-template.md，填充 schema_name（从 .env.local 读 DB_SCHEMA，无则填 【人工填写：DB_SCHEMA】）、er_overview（纯文本 ER 概览），以及步骤 A0 确认的 {{PK_CONVENTION}} / {{TENANT_COLS}} / {{COL_PREFIX_RULE}}。
渲染「表清单」：对每张表：读取并填充 ${CLAUDE_SKILL_DIR}/templates/docs-03-table-template.md，其中标准列区块用步骤 A0 确认的 {{PK_CONVENTION}} / {{TENANT_COLS}} 展开（TENANT_COLS = 「无」时不输出租户列行）。
写入 docs/03-数据库设计文档.md。


完成后，用 Edit 在 docs/08-模块任务管理.md 中勾选：


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


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


列出 docs/01-需求清单/*/_module.md（模块头）和 docs/01-需求清单/*/REQ-*.md（REQ 卡片）。
在这些文件中搜索 TBD(A3 自动补) 的并回填。 不动 TBD(A5 自动补)

打印回填统计：A3 回填 <M> 处模块"涉及表" + <N> 处 REQ"依赖表"。


完成后，用 Edit 在 docs/08-模块任务管理.md 中勾选：


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


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


完成后，用 Edit 在 docs/08-模块任务管理.md 中勾选 A3 顶层（A3 两个子项已在 C / D 步骤分别勾选）：


- [ ] A3 DB 设计 + REQ 回填 — db-design-gen


打印停下横幅并停下：

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