SKILL.md 5.87 KB

Edit Raw Blame History



name: db-init
description: A4 DB 初始化——LLM 解析 docs/03-数据库设计文档.md → 生成 sql/migrations/V1__initial_schema.sql（DDL only，Flyway 初始 migration）→ 全量校验 DDL ↔ docs/03 一致性 → 验证 MySQL 连接 → 调 scripts/setup-test-db.sh 复用三层防护并 DROP+CREATE 空库 → apply V1。
user-invocable: false


allowed-tools: Read Write Edit Glob Skill Bash(mkdir *) Bash(mysql *) Bash(set *) Bash(. .env.local) Bash(grep *) Bash(bash *) Bash(./scripts/setup-test-db.sh) Bash(cat *)

所有输出必须使用中文。


db-init


执行步骤


步骤 0：打印当前位置流程图

用 Bash 执行 cat 命令向用户展示当前位置流程图（stdout 即 ASCII 框图）：
cat "${CLAUDE_PLUGIN_ROOT}/skills/db-init/banners/flow.txt"


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 文件

Bash: mkdir -p sql/migrations。

用 Write 写 sql/migrations/V1__initial_schema.sql，内容 = 头部注释 + DDL 主体：


头部注释（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.


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


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

调 ${CLAUDE_SKILL_DIR}/scripts/validate.sh 做脚本化的校验：
bash "${CLAUDE_SKILL_DIR}/scripts/validate.sh" \
  sql/migrations/V1__initial_schema.sql \
  docs/03-数据库设计文档.md


退出码与处理：


0 → 通过，进入步骤 B

1 → 自主修正循环（最多 3 轮，docs/03 是 SSoT 不动）：


解析 stderr 差异清单，修正 V1.sql
重跑 validate.sh
退出 0 → 进入 B；退出 1 且本轮 < 3 → 回步骤 1；本轮 ≥ 3 仍失败 → 停下，打印最终残留差异 + 已尝试的 3 轮修正摘要，让用户介入


2 → 用法错（V1 / docs 路径找不到），打印路径并停下


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


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


B. 数据库环境检查


B.1 检查 .env.local 凭据

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

用 Bash 加载并校验 5 个必填字段非空：
set -a; . .env.local; set +a
for v in DB_HOST DB_PORT DB_USER DB_PASSWORD DB_SCHEMA; do
  eval val=\${$v:-}
  [ -z "$val" ] && echo "MISSING: $v"
done


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


B.2 验证 MySQL 连接
set -a; . .env.local; set +a
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 空库
./scripts/setup-test-db.sh


C.2 把 V1 灌入已清空的 schema
set -a; . .env.local; set +a
mysql -h"$DB_HOST" -P"$DB_PORT" -u"$DB_USER" -p"$DB_PASSWORD" "$DB_SCHEMA" \
  < sql/migrations/V1__initial_schema.sql


非零退出 → 报错停下，打印 mysql stderr。

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


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


C.3 自检 SHOW TABLES
set -a; . .env.local; set +a
ACTUAL=$(mysql -N -B -h"$DB_HOST" -P"$DB_PORT" -u"$DB_USER" -p"$DB_PASSWORD" \
  -e "SHOW TABLES;" "$DB_SCHEMA" | wc -l | tr -d ' ')
EXPECTED=$(grep -c '^## `' docs/03-数据库设计文档.md)
[ "$ACTUAL" = "$EXPECTED" ] || { echo "MISMATCH: actual=$ACTUAL expected=$EXPECTED"; exit 1; }


行数不一致 → 报错停下；一致 → 进入步骤 D。


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


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


- [ ] SHOW TABLES 行数 == docs/03 表数量
- [ ] A4 DB 初始化 — db-init


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


参考


${CLAUDE_SKILL_DIR}/scripts/validate.sh（A.3 表名 + 每表列名集合校验脚本）

docs/03-数据库设计文档.md（DDL 翻译输入，SSoT）

.env.local（DB 凭据）
产物：sql/migrations/V1__initial_schema.sql（由 Flyway 在 Spring Boot 启动时验证 / apply）