---
name: design
description: 计划第 2 段——生成架构文档（docs/04 § 一+，含前端 Design Tokens + 环境配置）+ 工具脚本 + .env.local + sql/migrations/，然后从 REQ 正向设计 docs/03 并回填 REQ 依赖表，停下等人工审阅 docs/03。
user-invocable: false
allowed-tools: Read Write Edit Glob Grep Skill AskUserQuestion Bash(mkdir *) Bash(cp *) Bash(cat *) Bash(bash *)
---

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

# design

## 执行步骤

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

用 `Bash` 执行以下命令（文件不存在时静默忽略，不报错）：

```bash
cat "${CLAUDE_PLUGIN_ROOT}/skills/crosscut/plan-start/banners/flow.txt" 2>/dev/null || true
```

打印横幅：`▶ 计划阶段 ② — design`。

### A. 读取锁定的输入

用 `Read` 读取：
- `docs/04-技术规范.md` § 零 技术栈表
- `docs/01-需求清单/index.md` 需求索引
- `docs/01-需求清单/` 下所有 REQ 卡片（`docs/01-需求清单/*/REQ-*.md`）

后续所有内容都基于它们推导。

### B. 生成 docs/04 § 一+（保留 § 零 不覆盖）

docs/04 已由 init 写入 § 零。本步骤追加 § 一 ~ 五。

docs/04 承担三类内容（不再生成独立的前端规范文件或环境配置文件）：
- § 一~三：后端/前端/共同编码规范
- § 四：前端 Design Tokens + 交互约定
- § 五：环境配置

操作：
1. 读取 `docs/04-技术规范.md`（现有 § 零 完整内容）。
2. 读取 `${CLAUDE_SKILL_DIR}/templates/docs-04-skeleton-template.md`。
3. 基于技术栈，按大纲生成 § 一 ~ 五 的项目专属内容，剥掉 HTML 注释（注释是给 LLM 的提示，不应出现在最终文档里）。
4. 拼接原有内容和新生成内容，写回 `docs/04-技术规范.md`。

完成后，用 `Edit` 在 `docs/08-模块任务管理.md` 中勾选：
- `  - [ ] 架构文档已生成（docs/04 § 一+ ｜ scripts/*.sh ｜ .env.local ｜ sql/migrations/）`（步骤 C 完成后一并勾选）

### C. 生成工具脚本 + 目录结构

#### C.1 复制固定文件

```bash
mkdir -p scripts sql/migrations src/styles
cp "${CLAUDE_SKILL_DIR}/templates/env-local-template" .env.local
cp "${CLAUDE_SKILL_DIR}/templates/scripts-setup-test-db-template.sh" scripts/setup-test-db.sh
```

注意：本阶段不生成 `src/styles/tokens.css`（前端 token 骨架由前端阶段处理）。

#### C.2 渲染 scripts/test.sh

读取 `${CLAUDE_SKILL_DIR}/templates/scripts-test-template.sh`，基于步骤 A 的技术栈（docs/04 § 零）为以下 7 个命令槽推断命令后写到 `scripts/test.sh`（纯后端项目可把前端 / E2E 槽填 `echo` 占位）：

- `{{backend_build}}` / `{{backend_lint}}` / `{{backend_test}}` — 后端各 stage 命令
- `{{frontend_build}}` / `{{frontend_lint}}` / `{{frontend_test}}` — 前端各 stage 命令
- `{{e2e_cmd}}` — E2E（无 E2E 工具则填 `echo "[test.sh] e2e 略"`）

> 推断规则：根据 `docs/04 § 零`。
> - 「后端*」存在 → 据后端技术栈推 backend 三槽（build / lint / test 命令）
> - 「前端*」存在 → 据前端技术栈推 frontend 三槽
> - 缺席 stack → 三槽全填 `:`（语法合法即可）
> - `{{e2e_cmd}}` 通常仅前端，按上述前端规则或填 `echo "[test.sh] e2e 略"`
>
> 表结构异常（列名变更 / 无中文前缀）时停下，用 `AskUserQuestion` 让用户显式确认每 stack 命令。

#### C.3 赋权

```bash
bash -c "chmod +x scripts/*.sh"
```

完成后，用 `Edit` 在 `docs/08-模块任务管理.md` 中勾选：
- `  - [ ] 架构文档已生成（docs/04 § 一+ ｜ scripts/*.sh ｜ .env.local ｜ sql/migrations/）`

### D. 追加 .gitignore 忽略项

调用脚本完成合并：

```bash
bash "${CLAUDE_SKILL_DIR}/scripts/merge-gitignore.sh" "${CLAUDE_SKILL_DIR}/templates/gitignore-append-template"
```

### E. 推导 schema + 渲染 docs/03

基于步骤 A 读到的 REQ + docs/04 § 一命名规范，**正向推导**业务实体 → 表 + 字段 + 索引 + 外键。要求：

1. 严格套用 `docs/04 § 一` 的命名规范（匈牙利前缀 `i` int / `s` varchar / `t` datetime 等）
2. **主键**：模板内置 `iIncrement` 为主键。REQ 明确要求复合主键 / UUID / 业务主键时按 REQ；其他主键变更需同步改 docs-03-header / docs-03-table 两份模板
3. **外键**：依据 REQ 中的引用关系（如「订单引用客户」），明确列出 `ON DELETE` / `ON UPDATE` 策略；不能确定时默认 `RESTRICT`
4. **索引**：根据 REQ 的查询模式推导业务索引；外键列默认建索引；标准列里 `sBrandsId` / `sSubsidiaryId` 这类多租户隔离列，按业务查询模式建组合索引
5. **业务注记**：对每张表用一两句话说明业务用途、关键约束、与其他表的关系

如果某 REQ 表述模糊以致无法推断关键 schema 细节（如：枚举值范围 / 字段长度上限 / 必填性），先按合理默认推导并在该字段「业务含义」列加 `【人工填写：需用户审阅】` 标注，不打断本次推导。

渲染 docs/03：
1. 读取 `${CLAUDE_SKILL_DIR}/templates/docs-03-header-template.md`，填充 `schema_name`（从 `.env.local` 读 `DB_SCHEMA`，无则填 `【人工填写：DB_SCHEMA】`）、`er_overview`（纯文本 ER 概览）。
2. 渲染「表清单」：对每张表，读取并填充 `${CLAUDE_SKILL_DIR}/templates/docs-03-table-template.md`。
3. 写入 `docs/03-数据库设计文档.md`。

完成后，用 `Edit` 在 `docs/08-模块任务管理.md` 中勾选：
- `  - [ ] docs/03 数据库设计已生成（REQ → 表/字段/索引/外键，回填 REQ 依赖表）`

### F. 回填模块头 + REQ 卡片的 TBD 字段

1. 列出 `docs/01-需求清单/*/_module.md`（模块头）和 `docs/01-需求清单/*/REQ-*.md`（REQ 卡片）。
2. 在这些文件中搜索 `TBD(design 自动补)` 并回填为实际表名。**不动** `TBD(build-db 自动补)`。
   - `_module.md` 的 `涉及表` 字段：填入该模块涉及的所有表名（逗号分隔）
   - `REQ-*.md` 的 `依赖表` 字段：填入该 REQ 操作的表名（逗号分隔）
3. 打印回填统计：`design 回填 <M> 处模块"涉及表" + <N> 处 REQ"依赖表"`。

### G. 勾选 § 一 ② 顶层 + 停下等人工审阅

1. 完成后，用 `Edit` 在 `docs/08-模块任务管理.md` 中勾选 ② 顶层：
   - `- [ ] 计划 ② 脚手架 + 数据库设计 — design`

2. 打印停下横幅并**停下**：

   ```
   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
    [design] ✅ 计划 ② 完成

    产出：
      ✓ docs/04-技术规范.md（§ 一+ ｜ § 四 Design Tokens ｜ § 五 环境配置）
      ✓ scripts/setup-test-db.sh + scripts/test.sh（已赋权）
      ✓ .env.local（含占位符，凭据请自填）
      ✓ sql/migrations/（目录已建）
      ✓ .gitignore（已追加忽略项）
      ✓ docs/03-数据库设计文档.md
      ✓ docs/01 各 REQ 卡片"依赖表" + 模块头"涉及表" 已回填

    ⏸ 现在请你审阅 docs/03。
       重点关注：
         - 业务实体覆盖是否完整
         - 字段类型 / 长度 / 是否可空 / 默认值是否合理
         - 索引是否覆盖主要查询模式
         - 外键 ON DELETE / ON UPDATE 策略是否符合业务
         - 字段「业务含义」列含 `【人工填写：需用户审阅】` 标注的位置需逐一确认
         - .env.local 中的凭据占位符请直接编辑文件填写（凭据不进会话）

    审阅完成后，再运行：
      /erp-workflow:plan-start

   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
   ```

   **停止**，不调用任何下游 skill。

## 参考

- `docs/04-技术规范.md` § 零（技术栈输入）
- `docs/01-需求清单/index.md`（模块索引输入）
- `docs/01-需求清单/<module>/_module.md`（模块头：回填 `涉及表`）
- `docs/01-需求清单/<module>/REQ-*.md`（REQ 输入 + 回填 `依赖表`）
- `${CLAUDE_SKILL_DIR}/templates/docs-04-skeleton-template.md`（大纲：§ 一~三 编码规范 + § 四 Design Tokens + § 五 环境配置）
- `${CLAUDE_SKILL_DIR}/templates/docs-03-header-template.md`
- `${CLAUDE_SKILL_DIR}/templates/docs-03-table-template.md`
- `${CLAUDE_SKILL_DIR}/templates/scripts-test-template.sh`（推断命令填充槽位；缺席 stack 填 `:`）
- `${CLAUDE_SKILL_DIR}/templates/scripts-setup-test-db-template.sh`（0 槽位）
- `${CLAUDE_SKILL_DIR}/templates/env-local-template`（0 槽位）
- `${CLAUDE_SKILL_DIR}/templates/gitignore-append-template`（0 槽位）
- `${CLAUDE_SKILL_DIR}/scripts/merge-gitignore.sh`（.gitignore 逐行判重合并脚本）