---

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

执行步骤

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

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

读取 docs/03-数据库设计文档.md，按字段 / 索引 / 外键 / 业务注记严格翻译为：

• 每张表一段 CREATE TABLE
• 字段顺序与 docs/03 表格行序一致；Nullable 列直接映射 NOT NULL / NULL；默认 列映射 DEFAULT <value>；列尾用 COMMENT '<业务含义>' 写注释
• 索引
• 外键：在所有表创建完成后统一追加

要求：

• 严禁臆造 docs/03 中没有的表 / 字段 / 索引 / 外键
• 严禁省略 docs/03 中已有的列、注释或约束
• 字符集统一 utf8mb4 + utf8mb4_unicode_ci，引擎统一 InnoDB，除非 docs/03 业务注记明确要求其他设置

A.2 落盘 V1 文件

用 Write 写 sql/migrations/V1__initial_schema.sql（Write 会自动创建缺失的父目录 sql/migrations/），内容 = 头部注释 + DDL 主体：

1. 头部注释（6 行 SQL 注释）：

   • -- 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.

2. DDL 主体：A.1 推导出的所有 CREATE TABLE → CREATE INDEX → ALTER TABLE ... ADD CONSTRAINT ... FOREIGN KEY，按此顺序拼接。

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 不动）：
  1. 解析 stderr 差异清单，修正 V1.sql
  2. 重跑 validate-ddl.mjs
  3. 退出 0 → 进入 B；退出 1 且本轮 < 3 → 回步骤 1；本轮 ≥ 3 仍失败 → 停下，打印最终残留差异 + 已尝试的 3 轮修正摘要，让用户介入
• 2 → 用法错（docs/03 / V1 路径找不到），打印路径并停下

完成后（V1 写入并通过 validate-ddl.mjs 校验），用 Edit 在 docs/08-模块任务管理.md 中勾选：

• - [ ] sql/migrations/V1__initial_schema.sql 已生成
• - [ ] DDL 与 docs/03 全量一致

B. 数据库环境检查

B.1 检查 .env.local 凭据

用 Glob 检查 .env.local 是否存在；不存在 → 提示用户重新运行 A2 skeleton-gen 重建并停下。

用 Read 读取 .env.local，逐行解析 KEY=VALUE（跳过空行 / # 注释，不做 shell-source / 变量展开），校验 5 个必填字段 DB_HOST、DB_PORT、DB_USER、DB_PASSWORD、DB_SCHEMA 均存在且非空。

任一缺失 → 打印缺失字段名并停下，提示用户编辑 .env.local 后重跑。

B.2 验证 MySQL 连接

用 B.1 解析出的字段值（不要 shell-source .env.local）拼出 mysql 客户端调用，做一次连通性自检。把 <DB_HOST> 等占位替换为读到的实际值：

mysql -h<DB_HOST> -P<DB_PORT> -u<DB_USER> -p<DB_PASSWORD> -e "SELECT 1;"

• 成功 → 进入步骤 C
• 失败 → 打印具体错误（认证 / 主机不可达 / 端口拒接等），提示检查 .env.local，停下。

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

• - [ ] .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 → 成功，进入 C.3
• 1 → 失败：若错误提示 mysql2 not found，先在目标项目执行 npm i mysql2 再重跑；其余错误打印 stderr 并停下
• 2 → 用法错（路径找不到），打印路径并停下

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

• - [ ] setup-test-db.mjs 防护通过 + DROP+CREATE + apply V1 已执行

C.3 自检：docs/03 ↔ V1 表集合一致

再跑一次 validate-ddl.mjs，确认刚 apply 的 V1__initial_schema.sql 与 docs/03 的表/列/类型/索引/外键 5 维仍然一致（参数顺序：docs/03 在前，V1.sql 在后）：

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

退出码 0 → 进入步骤 D；1 → 打印 stderr 5 维 diff 并停下；2 → 路径错，打印路径并停下。

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

1. 完成后，用 Edit 在 docs/08-模块任务管理.md 中勾选（A4 子项 + A4 顶层）：

   • - [ ] DDL ↔ docs/03 apply 后 5 维一致（validate-ddl.mjs）
   • - [ ] A4 DB 初始化 — db-init

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

参考

• ${CLAUDE_PLUGIN_ROOT}/lib/validate-ddl.mjs（A.3 / C.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）