---

name: db-init description: A4 DB 初始化——LLM 解析 docs/03-数据库设计文档.md → 生成 sql/migrations/V1__initial_schema.sql（DDL only，Flyway 初始 migration）→ 用 lib/validate-ddl.mjs 做 5 维校验（表/列/类型/索引/外键）DDL ↔ docs/03 一致性 → 连库前置预检（mysql2 模块 + mysql 客户端）→ 校验 config-vars.yaml DB 凭据 5 项非空 → 调 scripts/setup-test-db.mjs DROP+CREATE 空库（连不上即失败）→ 用 lib/apply-ddl.mjs apply V1。 user-invocable: false

allowed-tools: Read Write Edit Skill Bash(node *) Bash(npm i mysql2) Bash(npm install mysql2)

所有输出必须使用中文。

db-init

每步骤完成后用 Edit 在 docs/08-模块任务管理.md § 一 勾选对应子项。

执行步骤

A. DDL 生成（不依赖数据库连接）

A.1 读 docs/03 并翻译为 DDL

读取 docs/03-数据库设计文档.md，对每张表生成一段 CREATE TABLE（字段顺序/可空/默认/列注释严格对齐 docs/03 行序），随后按顺序追加 CREATE INDEX 与统一追加的 ALTER TABLE ... ADD CONSTRAINT ... FOREIGN KEY。严禁臆造或省略 docs/03 中的任何表/字段/索引/外键/约束。字符集 utf8mb4 + utf8mb4_unicode_ci、引擎 InnoDB，除非 docs/03 业务注记另有说明。

A.2 落盘 V1 文件

用 Write 写 sql/migrations/V1__initial_schema.sql（Write 自动创建父目录）。文件开头是以下 6 行注释，其后接 A.1 的 DDL 主体（CREATE TABLE → CREATE INDEX → ALTER TABLE ... ADD FOREIGN KEY）：

-- Flyway migration V1 — initial schema for <project_name>   -- 从 CLAUDE.md § 🎯 项目概述 读
-- Generated: <YYYY-MM-DDTHH:MM:SSZ>                          -- UTC ISO 8601
-- Source: 由 A4 db-init 从 docs/03-数据库设计文档.md 翻译生成（schema SSoT 是 docs/03）
-- This is the FIRST migration; subsequent schema changes must be written as new files sql/migrations/V2__<desc>.sql, V3__... etc.
-- Apply: Flyway runs this automatically at Spring Boot startup.
-- Do not hand-edit this file after it is committed; write a new migration instead.

A.3 校验 V1 ↔ docs/03 5 维一致性 + 自主修正

调 ${CLAUDE_PLUGIN_ROOT}/lib/validate-ddl.mjs 做跨平台、纯 Node 的 5 维校验（表集合 / 列名 / 列类型 / 索引 / 外键）。注意参数顺序：docs/03 在前，V1.sql 在后。

机检边界（勿误解）：5 维 = 表集合 / 列名 / 列类型 / 索引（名 + UNIQUE|INDEX 类别 + 列）/ 外键（列 → 表(列) + ON DELETE）；表体内联与独立 CREATE INDEX / ALTER TABLE ... ADD FOREIGN KEY 两种形态都识别。A.1 要求的「字段顺序 / 可空 / 默认 / 列注释对齐」不在机检范围内——这几项靠 A.1 翻译时忠实对齐 docs/03（docs/03 已在 A3 人工审阅过），validate-ddl 不会代为兜底，勿因校验通过就认定它们也一致。

node "${CLAUDE_PLUGIN_ROOT}/lib/validate-ddl.mjs" \
  docs/03-数据库设计文档.md \
  sql/migrations/V1__initial_schema.sql

退出码与处理：

• 0 → 通过，进入步骤 B
• 1 → 存在差异（5 维 diff 明细打印到 stderr）。进入自主修正循环（最多 3 轮，docs/03 是 SSoT 不动）：
  1. 解析 stderr 差异清单，修正 V1.sql
  2. 重跑 validate-ddl.mjs
  3. 退出 0 → 进入 B；退出 1 且本轮 < 3 → 回步骤 1；本轮 ≥ 3 仍失败 → 停下，打印最终残留差异 + 已尝试的 3 轮修正摘要，让用户介入
• 2 → 用法错（docs/03 / V1 路径找不到），打印路径并停下

完成后（V1 写入并通过 validate-ddl.mjs 校验），勾选：

• - [ ] sql/migrations/V1__initial_schema.sql 已生成
• - [ ] DDL ↔ docs/03 5 维一致（validate-ddl.mjs）

B. 数据库环境检查（连库前置——必须在步骤 C 的任何 DROP 之前完成）

B.1 工具链预检

A4 连库用到两样东西：apply-ddl.mjs 依赖 mysql2 模块、setup-test-db.mjs 依赖 mysql 客户端。两者都在 C 阶段才被调用，而 C.1 第一步就是 DROP DATABASE——所以必须在此先探测、缺则补齐，避免"删到一半才发现缺工具"。

1. mysql2 驱动（apply-ddl.mjs 从 config-vars.yaml 所在目录解析 mysql2，而非插件目录；按 A4 既定调用 apply-ddl.mjs config-vars.yaml …、cwd = 项目根，该目录即项目根，故下面按 cwd 解析的 node -e 探测对此调用具代表性）： bash node -e "import('mysql2/promise').then(()=>process.exit(0),()=>process.exit(1))"
   • 退出 0 → 已就绪。
   • 退出非 0 → 在项目根执行 npm i mysql2（首次会生成 / 更新根 package.json + node_modules；.gitignore 已忽略 node_modules），再重跑上面一行确认；仍失败 → 打印 stderr 并停下。
2. mysql 客户端： bash node -e "process.exit(require('node:child_process').spawnSync('mysql',['--version']).status===0?0:1)"
   • 退出非 0 → 打印「未找到 mysql 客户端，请安装并加入 PATH 后重跑 /plan-start」并停下（不进入 C）。

B.2 凭据校验

用 Read 读 config-vars.yaml 的 database: 段（文件缺失 → 提示重跑 A1 scope-lock 并停下），校验 host / port / user / password / schema 5 项均非空且非 【人工填写 占位——任一缺失 → 打印缺失字段并停下。

连通性无需在此单独探测：步骤 C.1 的 setup-test-db.mjs 会用同一份凭据连同一个 MySQL 跑 DROP+CREATE，连不上即报错（认证 / 主机不可达 / 端口拒接）；且 DROP DATABASE IF EXISTS 在连不上时不破坏任何东西，由 C.1 失败即可。

勾选：- [ ] config-vars.yaml DB 凭据 5 项非空校验通过

C. 自动导入 MySQL

C.1 DROP+CREATE 空库

node scripts/setup-test-db.mjs

C.2 把 V1 灌入已清空的 schema

调 ${CLAUDE_PLUGIN_ROOT}/lib/apply-ddl.mjs：它用纯 JS 解析 config-vars.yaml 的 database: 段（不 shell-source，消除注入），再经 mysql2 把 DDL 灌入 schema。

node "${CLAUDE_PLUGIN_ROOT}/lib/apply-ddl.mjs" config-vars.yaml sql/migrations/V1__initial_schema.sql

退出码与处理：

• 0 → 成功，进入步骤 D
• 1 → 失败：打印 stderr 并停下
• 2 → 用法错（路径找不到），打印路径并停下

勾选：- [ ] setup-test-db.mjs DROP+CREATE + apply V1 已执行

D. 勾选 docs/08 进度 + 进入 A5

1. 勾选 A4 顶层（5 维一致已由 A.3 的 validate-ddl.mjs 校验过，apply 不改 V1，无需复校）：

   • - [ ] A4 DB 初始化 — db-init

2. 立即调用 Skill(downstream-gen) 进入 A5，不等用户手动输入。

参考

• ${CLAUDE_PLUGIN_ROOT}/lib/validate-ddl.mjs（A.3 docs/03 ↔ V1.sql 5 维一致性校验，跨平台纯 Node）
• ${CLAUDE_PLUGIN_ROOT}/lib/apply-ddl.mjs（C.2 安全解析 config-vars.yaml 的 database: 段 + mysql2 灌入 DDL，不 shell-source）
• ${CLAUDE_PLUGIN_ROOT}/lib/yaml-config.mjs（apply-ddl 依赖的极简 YAML 读取）
• docs/03-数据库设计文档.md（DDL 翻译输入，SSoT）
• config-vars.yaml（DB 凭据，A1 产出）
• 产物：sql/migrations/V1__initial_schema.sql（由 Flyway 在 Spring Boot 启动时验证 / apply）