---
name: erp-db-design-gen
description: A4 DB 设计生成 + REQ 回填——用 mysql CLI 反查 schema 生成 docs/03-数据库设计文档.md；然后用 Grep 在 docs/01-需求清单/*.md 定位 TBD(A4 自动补) 替换为实际表/字段引用。
user-invocable: false
allowed-tools: Read Write Edit Grep Glob Skill Bash(mysql *) Bash(set *) Bash(. .env.local)
---

**所有输出必须使用中文。**

# erp-db-design-gen

## 前置条件

- `erp-db-init` 已完成：`.env.local` 凭据已填，`sql/migrations/V1__initial_schema.sql` 和 `sql/seed-data.sql` 都已生成。
- `erp-scope-lock` 已完成：`docs/01-需求清单/<module>-*.md` REQ 卡片存在，含 `TBD(A4 自动补)` 占位。

## 执行步骤

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

向用户展示当前在 A 阶段流程中的位置（A-only，`▶` 标在 A4）：

```
┌──────────────────────────────────────────────────────┐
│ 📋 阶段 A：规划（一次性）                               │
│                                                       │
│   A0 初始化项目 → A1 锁范围（REQ 卡片）                 │
│                          ↓                            │
│     ⏸ 等你审阅 REQ，重新运行 /erp-plan-start 继续      │
│                          ↓                            │
│   A2 生成骨架 → A3 初始化 DB → ▶ A4 生成 DB 设计 → A5 生成下游文档│
│                                  ↓                    │
│                    规划阶段到此结束                     │
└──────────────────────────────────────────────────────┘
```

### A. 查询实时 schema

用 `Bash` 加载 `.env.local` 后查询（用 `set -a; . ...; set +a` 替代 `source`，避免密码中的 shell 特殊字符被展开）：

```bash
set -a; . .env.local; set +a
MYSQL_CMD="mysql -h${DB_HOST} -P${DB_PORT} -u${DB_USER} -p${DB_PASSWORD} -N -B"

# 表列表 + 注释
$MYSQL_CMD -e "SELECT table_name, table_comment FROM information_schema.tables WHERE table_schema='${DB_SCHEMA}' AND table_type='BASE TABLE' ORDER BY table_name;"

# 字段详情
$MYSQL_CMD -e "SELECT table_name, column_name, column_type, is_nullable, column_default, column_comment FROM information_schema.columns WHERE table_schema='${DB_SCHEMA}' ORDER BY table_name, ordinal_position;"

# 外键
$MYSQL_CMD -e "SELECT table_name, column_name, referenced_table_name, referenced_column_name FROM information_schema.key_column_usage WHERE table_schema='${DB_SCHEMA}' AND referenced_table_name IS NOT NULL;"

# 索引
$MYSQL_CMD -e "SELECT table_name, index_name, GROUP_CONCAT(column_name ORDER BY seq_in_index) AS cols, non_unique FROM information_schema.statistics WHERE table_schema='${DB_SCHEMA}' GROUP BY table_name, index_name, non_unique;"
```

在内存中将结果解析为结构化列表，**只保留表名、字段名与关键元信息，不把查询结果完整写入会话上下文**。

### B. 生成 docs/03

1. 用 `Read` 读取 `${CLAUDE_SKILL_DIR}/templates/docs-03-header-template.md`，填充 `schema_name`、`er_overview`、`tables[]`。
2. 对每张表，用 `Read` 读取 `${CLAUDE_SKILL_DIR}/templates/docs-03-table-template.md`，填充并追加。
3. 每个字段的业务含义：
   - 如果 `column_comment` 非空，直接用
   - 否则从 A1 生成的 REQ 卡片上下文推断
4. 用 `Write` 写入 `docs/03-数据库设计文档.md`。

### C. 回填 REQ 卡片的 TBD 字段

1. 用 `Glob` 列出 `docs/01-需求清单/*.md`（排除 `README.md`）。
2. 用 `Grep` 在这些文件中搜索 `TBD(A4 自动补)` 的**行号**（不读全文）。
3. 对每个命中的 REQ：
   - 用 `Read` 仅读取该 REQ 卡片所在的片段（REQ 标题行前后 20 行）
   - 根据 `goal` / `input` / `output` 推断引用的表
   - 用 `Edit`：`依赖表: TBD(A4 自动补)` → `依赖表: <table1>, <table2>`（具体表名）
   - **不动** `依赖接口: TBD(A5 自动补)`——那行由 A5 `erp-downstream-gen` 生成 docs/05 后回填
4. 打印回填统计：`A4 回填 N 处 schema_refs`。

### D. 一致性检查

1. 用 `Grep` 在 `docs/01-需求清单/*.md` 搜索 `依赖表:`，抽取所有表名。
2. 用 `Grep` 在 `docs/03-数据库设计文档.md` 搜索表标题（每张表一行 `### table_name`）。
3. 比对：
   - REQ 提到但 docs/03 没有的表 → 报错停下（schema 与需求不一致；请确认是 REQ 理解错误还是需要新增 migration）
   - docs/03 有但没 REQ 引用 → 警告但不停下（可能是未使用表）
4. 用 `Grep` 在 `docs/01-需求清单/*.md` 中搜索 `TBD(A4 自动补)`：应 0 命中（A4 已把所有 schema_refs 回填完）；若仍有，打印残留 REQ 清单并停下。

### E. 勾选 docs/08 进度 + 进入 A5

用 `Edit` 在 `docs/08-模块任务管理.md` 勾选 4 个 checkbox（A4 的 3 个子项 + A4 父项）：
- `  - [ ] docs/03 数据库设计已生成` → `[x]`
- `  - [ ] REQ 卡片依赖表已回填` → `[x]`
- `  - [ ] schema 一致性检查通过` → `[x]`
- `- [ ] A4 DB 设计 + REQ 回填 — erp-db-design-gen` → `[x]`

输出 `db-design-gen: 完成（<T> 张表, <R> 个 REQ 已回填依赖表；依赖接口留给 A5）`。

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

## 不变量

- REQ 卡片的 `依赖接口` 字段不在此处填充，留给 A5 的 `erp-downstream-gen` 先生成 docs/05 API 契约后按 `TBD(A5 自动补)` 回填。

## 参考

- `${CLAUDE_SKILL_DIR}/templates/docs-03-header-template.md`
- `${CLAUDE_SKILL_DIR}/templates/docs-03-table-template.md`
- `.env.local`（DB 凭据）
- `docs/01-需求清单/*.md`（回填目标）