name: db-init description: A4 DB 初始化——LLM 解析 docs/03-数据库设计文档.md → 生成 sql/migrations/V1__initial_schema.sql（DDL only，Flyway 初始 migration）→ 用 lib/validate-ddl.mjs 全量校验 DDL ↔ docs/03 一致性 → 验证 MySQL 连接 → 调 scripts/setup-test-db.mjs 复用三层防护并 DROP+CREATE 空库 → 用 lib/apply-ddl.mjs apply V1。 user-invocable: false
allowed-tools: Read Write Edit Glob Skill Bash(node *) Bash(mysql *)
所有输出必须使用中文。
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 在后。
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 不动）：- 解析 stderr 差异清单，修正 V1.sql
- 重跑
validate-ddl.mjs - 退出 0 → 进入 B；退出 1 且本轮 < 3 → 回步骤 1；本轮 ≥ 3 仍失败 → 停下，打印最终残留差异 + 已尝试的 3 轮修正摘要，让用户介入
-
2→ 用法错（docs/03 / V1 路径找不到），打印路径并停下
完成后（V1 写入并通过 validate-ddl.mjs 校验），勾选：
- [ ] sql/migrations/V1__initial_schema.sql 已生成- [ ] DDL 与 docs/03 全量一致
B. 数据库环境检查
用 Glob 确认 .env.local 存在（不存在 → 提示重跑 A2 skeleton-gen 并停下）。用 Read 逐行解析 KEY=VALUE（跳过空行 / # 注释，不做 shell-source / 变量展开），校验 DB_HOST / DB_PORT / DB_USER / DB_PASSWORD / DB_SCHEMA 5 项均非空——任一缺失 → 打印缺失字段并停下。
用解析出的值跑连通性自检：
mysql -h<DB_HOST> -P<DB_PORT> -u<DB_USER> -p<DB_PASSWORD> -e "SELECT 1;"
成功 → 进入步骤 C；失败 → 打印具体错误（认证 / 主机不可达 / 端口拒接）并停下。
勾选：- [ ] .env.local 凭据已验证（mysql -e "SELECT 1" OK）
C. 自动导入 MySQL
C.1 DROP+CREATE 空库
node scripts/setup-test-db.mjs
C.2 把 V1 灌入已清空的 schema
调 ${CLAUDE_PLUGIN_ROOT}/lib/apply-ddl.mjs：它用纯 JS 解析 .env.local（不 shell-source，消除注入），再经 mysql2 把 DDL 灌入 schema。
node "${CLAUDE_PLUGIN_ROOT}/lib/apply-ddl.mjs" .env.local sql/migrations/V1__initial_schema.sql
退出码与处理：
-
0→ 成功，进入步骤 D -
1→ 失败：打印 stderr 并停下 -
2→ 用法错（路径找不到），打印路径并停下
勾选：- [ ] setup-test-db.mjs 防护通过 + DROP+CREATE + apply V1 已执行
D. 勾选 docs/08 进度 + 进入 A5
-
勾选（A4 子项 + A4 顶层；DDL ↔ docs/03 5 维一致已由 A.3 校验过，V1 文件自此未变）：
- [ ] DDL ↔ docs/03 apply 后 5 维一致（validate-ddl.mjs）- [ ] A4 DB 初始化 — db-init
立即调用
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 安全解析 .env.local + mysql2 灌入 DDL，不 shell-source） -
docs/03-数据库设计文档.md（DDL 翻译输入，SSoT） -
.env.local（DB 凭据） - 产物：
sql/migrations/V1__initial_schema.sql（由 Flyway 在 Spring Boot 启动时验证 / apply）