# CLAUDE.md — ERP项目 Claude Code 主指令文件

> 本文件是 Claude Code 的"操作手册"。Claude Code 启动时会自动读取此文件。

---

## 🎯 项目概述

- **项目名称**: 【人工填写：公司 + 项目名，例如"XX 公司 ERP 管理系统"】
- **项目简述**: 【人工填写：一句话描述项目目标，例如"面向中小制造企业的全流程 ERP，涵盖采购/库存/生产/销售/财务"】
- **目标用户**: 【人工填写：谁会用，例如"企业内部管理人员（采购员、仓管员、生产主管、销售员、财务人员、管理层）"】
- **部署方式**: 【人工填写：私有化部署 / 云部署 / Docker 容器化 等】

---

## 🔄 编码开发流程（两阶段 + 统一功能循环）

编码阶段入口：`/erp-workflow:coding-start`。本插件保留**后端模块阶段**与**前端整体阶段**两段，但两段共用**同一套功能循环 skill**（`feature-spec → feature-tdd → feature-review`），由 `phase` 参数区分。

### 阶段路由（coding-start 内，只做分发）

`coding-start` 每次入口按"先后端、再前端"检查并派发到 `phase-driver`：

1. 扫 `docs/08 § 二` 各后端模块 `里程碑:` 字段 + `git tag -l 'milestone/<id>'`：有未打里程碑模块 → 派发 `phase-driver`（phase=backend），结束。
2. 后端全部打里程碑 → 读 `docs/08 § 三` `整体里程碑:` + `git tag -l 'milestone/frontend-phase'`：未完成 → 派发 `phase-driver`（phase=frontend），结束。
3. 后端 + 前端都完成 → 输出"所有阶段已完成"。

### 统一功能循环（两阶段共用）

**阶段驱动（外）**：`phase-driver`（phase=backend 走后端模块；phase=frontend 走前端整体阶段——自带 prototype/ 门禁 + 从 prototype/docs01/docs05 推导 FE 清单写入 docs/08 § 三）→ feature 循环 → `milestone`（本地 merge 进默认分支 + 打 `milestone/<id>` 或 `milestone/frontend-phase` tag）→ 自动回调 `coding-start` 路由下一阶段（无人工介入）。

**功能循环（内，每个 REQ-XXX-NNN 或 FE-NN 一遍）**：`feature-spec` → `feature-tdd` → `feature-review`。
- phase=backend：单元是 REQ，分支 `module-<id>`，产出 controller/service/repository/DTO/migration；
- phase=frontend：单元是 FE，分支 `frontend-phase`，产出 `frontend/` 下组件/路由/API client（以 prototype 为页面权威）；
- `feature-review` verdict=approve → 勾选 docs/08 § 二（后端 REQ）/ § 三（前端 FE）对应子项，继续下一单元；
- 本阶段单元全部完成 → 调用 `milestone` 打里程碑 tag + 回调 `coding-start`。

### 里程碑前守门

- `milestone` 在打 tag 前内置测试闸门（phase 由分支推断：后端 `scripts/test.sh`；前端 vitest + Playwright，命令取自 docs/04 § 零）；红色不得跳过。
- 测试 / 验证统一派发到 Agent 子会话执行，主会话只接收结构化结论。

---

## ✅ 阶段完成判定规则

`docs/08-模块任务管理.md` 分三段：
- `§ 一`：计划阶段三段（①②③）进度勾选
- `§ 二`：后端编码模块元数据表（每个模块一行 bullet，记录依赖 / 路径 / 里程碑 tag / REQ 功能子项；行序即 REQ 开发顺序，是 phase-driver 的排序权威）
- `§ 三`：前端整体阶段（`整体里程碑:` 字段 + FE 功能清单，由 phase-driver(phase=frontend) 推导填入）

**阶段完成判定**统一以 `里程碑:` 字段（§二 模块 / §三 整体）+ 本地 `git tag -l 'milestone/<id>'` 判定；子项勾选只作可视化进度，不参与完成判定。

### 后端模块格式

每个后端模块在 docs/08 § 二 中长这样：

```markdown
- module_0 系统管理
  - 依赖: —
  - 路径: backend/module/sys/
  - 里程碑: —
  - 功能:
    - [ ] REQ-SYS-001 用户登录
    - [ ] REQ-SYS-002 用户注册
```

- `里程碑:` 字段由 `milestone` 在打里程碑 tag 时从 `—` 改为 `milestone/<module_id>`。
- 每个 `REQ-*` 子项由 `feature-review` 在 verdict=approve 时自动勾选为 `[x]`。

### 状态语义

| `里程碑:` 字段 | `git tag -l` | 含义 | 你（Claude Code）的行为 |
|---|---|---|---|
| `—` | tag 不存在 | 该阶段未开始 / 进行中（未打里程碑） | ✅ 开始 / 继续该阶段开发 |
| `milestone/<id>` | tag 存在 | 阶段**已完成** | 🟢 进入下一未完成模块；全部完成 → 输出完成信息 |

### 模块完成报告

由 `milestone` skill 产出，模板由 milestone skill 持有。CC 不手写模块报告，仅填模板。

---

## 🏷️ 占位符统一约定

项目文档里有 **2 种填写占位** + **1 种提示占位**：

| 格式 | 谁填 | 使用阶段 | 说明 |
|------|-----|---------|------|
| `【人工填写：<简短说明>】` | 人 | 仅计划阶段文档 | 密钥 / 账密 / 包名 / 命名约定 / 小版本号等人工才能决定的值；编码阶段 plan/spec 禁止出现，查不到真值时用 `AskUserQuestion` 问用户 |
| `TBD(<责任人>)` | CC 自动 | 计划或编码 | 后缀附带责任方（如 `TBD(design 自动补)` / `TBD(build-db 自动补)`）；由对应 skill 就地补填 |

**HTML 注释 `<!-- ... -->`**：提示占位，是**插件内部大纲模板**里给 LLM 的**填空提示 / 章节引导**，指引 LLM 按结构填实际内容。skill 生成时会**剥除**这些注释，最终产物里注释不会保留。

---

## 📐 编码行为约束

### 你必须做的 ✅

1. **严格遵循** `docs/04-技术规范.md`——命名 / 编码 / 统一响应 / 异常处理 / 数据访问 / 配置与安全 / 环境配置（含 .env.local 字段说明）等项目专属技术规约全部在此
2. **每个后端接口** 必须先在 `docs/05-API接口契约.md` 定义，再编码实现
3. **每个功能可追溯到 `REQ-XXX-NNN`**——commit tag + 代码注释（如 `// REQ-SYS-001: 用户登录`）+ plan/spec 文件名均用此 tag
4. **遇到跨模块改动**（动到非当前模块的代码）——按 § 🟡 软规则 **S2** 执行（允许改，但必须留痕）
5. **遇到技术栈外组件引入**（`docs/04 § 零` 技术栈表外的框架 / 中间件 / 关键库），按 § 🟡 软规则 **S1** 执行（允许引入，但必须先 AskUserQuestion）

### 你禁止做的 🚫

1. **主会话直接 `mysql -e` 跑业务 DDL**（只读查询 / 临时本地调试除外）——业务 schema 必须走 `sql/migrations/V_n__*.sql`，详见下方 Schema 演化规约
2. **手动 Edit `docs/08 § 二` 的 `里程碑:` 字段**，必须由 `milestone` 自动回写

### Schema 演化规约（Flyway migration）

1. **文件命名**：`sql/migrations/V<n>__<snake_case_desc>.sql`，例：`V5__add_user_email_unique_index.sql`
2. **版本号分配**：建文件前 `ls sql/migrations/V*.sql` 查当前最大 n，新文件 `n_max + 1`
3. **Apply 方式**：Spring Boot 启动 / 测试启动时 Flyway 自动 apply（项目必须在 `pom.xml` 声明 `flyway-core` + `flyway-mysql` 依赖）。`scripts/setup-test-db.sh` 只负责清空库，不做 apply
4. **已合并的 migration 永不修改**：发现错了写一个补救 migration（如 `V7__fix_V5_index_name.sql`），旧 `V_n.sql` 不动
5. **临时调试 DDL**：临时在本地试字段/索引可手动 `mysql -e`，但不写 migration；下次 `setup-test-db.sh` 会 drop+create 清掉
6. **计划 ③ 生成的 V1**：`V1__initial_schema.sql` 是计划阶段由 `build-db` 从 `docs/03-数据库设计文档.md`（design 正向设计的 schema SSoT）翻译生成的初始版本；后续 V2/V3/... 由编码阶段每个 REQ 按需写入，**同时**反向同步更新 docs/03 对应表小节以保持 SSoT 一致

---

## 🗂️ Git 提交规范

每次提交必须遵循以下格式：

```
<type>(<scope>): <subject>
```

- `scope`: 模块名，如 `user` / `inventory` / `order`
- `subject`: 简短描述；业务类（feat / fix / test）必须带 `REQ-XXX-NNN` 后缀

`type` 含义：

| type | 看到它意味着 |
|-----|-------------|
| `feat` | **新能力上线**——用户多了一个功能、接口、页面或业务规则 |
| `fix` | **修 bug**——原来行为错了，这次改对 |
| `refactor` | **重构**——外部行为不变，只改代码结构 / 命名 / 抽象 |
| `docs` | **文档改动**——只动 Markdown / 代码注释，不动实现 |
| `style` | **格式调整**——空白 / 缩进 / import 顺序，逻辑 0 变化 |
| `test` | **只动测试代码**——补用例 / 修 fixture，不碰实现 |
| `chore` | **流程维护**——构建 / 依赖 / 工具 / 证据档案 / 里程碑元数据等非业务动作 |

---

## 🚩 中断机制

功能循环（每个功能 REQ-XXX 的 feature-spec → feature-tdd → feature-review）默认 **静默编程**，但触发以下任何一条必须**立刻停下、记录原因、等人决策**，不得自行绕过：

| # | 中断 | 例子 |
| - | --- | --- |
| 1 | **测试反复失败** | 同一测试同一功能内连续 **10 次**修复失败 |
| 2 | **要改密钥 / 账密 / 包名** | 涉及 .env.local / docs/04 §零环境 中的密钥/账密字段 |
| 3 | **外部接口不可达** | 第三方 API 无法连接、证书失效等环境问题，并无法自行解决 |

> 其余需要人类判断的场景一律走普通 `AskUserQuestion` Q&A，不中断、不写 Blocker 文件。

**触发中断时的固定动作：**

1. 在当前功能的 spec 文件里追加一节 `## 🚩 Blocker`（报告格式由 `interrupt-check` 的 `interrupt-block-template.md` 持有）
2. 停止后续所有功能的静默执行
3. 在主会话输出一句话摘要 + 指向 blocker 文件的路径，等人回复

---

## 🟡 软规则（允许继续，但有强制后续动作）

以下情况 **不触发中断**，CC 可自行继续推进，但必须在约定位置留痕，模块完成时统一审计。

| # | 软规则 | 允许动作 | 强制后续 |
| - | ----- | ------- | ------- |
| S1 | **技术栈外组件引入** | 用 `AskUserQuestion` 给用户三选一：接受引入 / 换方案 / 拒绝 | ① **接受** → 同会话直接在 `docs/04 § 零` 追加一行 → 继续流程 ② **换方案 / 拒绝** → 视为常规歧义澄清，继续 Q&A 收敛 ③ 不写 Blocker、不中断流程 |
| S2 | **跨模块改动** | **默认不改**，仅为当前模块实现所必需时允许修改 | 在该模块 `milestone` 完成报告的「⑤ 偏离与取舍」节如实记录改了哪个非当前模块的文件 + 原因（本插件无自动留痕 hook，靠报告人工记录） |

---

## 🧭 通用工作准则（General Principles）

### 1. Think Before Coding

**Don't assume. Don't hide confusion. Surface tradeoffs.**

Before implementing:
- State your assumptions explicitly. If uncertain, ask.
- If multiple interpretations exist, present them - don't pick silently.
- If a simpler approach exists, say so. Push back when warranted.
- If something is unclear, stop. Name what's confusing. Ask.

### 2. Simplicity First

**Minimum code that solves the problem. Nothing speculative.**

- No features beyond what was asked.
- No abstractions for single-use code.
- No "flexibility" or "configurability" that wasn't requested.
- No error handling for impossible scenarios.
- If you write 200 lines and it could be 50, rewrite it.

Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.

### 3. Surgical Changes

**Touch only what you must. Clean up only your own mess.**

When editing existing code:
- Don't "improve" adjacent code, comments, or formatting.
- Don't refactor things that aren't broken.
- Match existing style, even if you'd do it differently.
- If you notice unrelated dead code, mention it - don't delete it.

When your changes create orphans:
- Remove imports/variables/functions that YOUR changes made unused.
- Don't remove pre-existing dead code unless asked.

The test: Every changed line should trace directly to the user's request.

### 4. Goal-Driven Execution

**Define success criteria. Loop until verified.**

Transform tasks into verifiable goals:
- "Add validation" → "Write tests for invalid inputs, then make them pass"
- "Fix the bug" → "Write a test that reproduces it, then make it pass"
- "Refactor X" → "Ensure tests pass before and after"

For multi-step tasks, state a brief plan:
```
1. [Step] → verify: [check]
2. [Step] → verify: [check]
3. [Step] → verify: [check]
```

Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.

---

## 🗺️ Skill 索引（erp-workflow，共 11 个）

### 入口

| Skill | 描述 |
|-------|------|
| `plan-start` | 计划阶段入口——扫 docs/08 § 一找第一个未完成计划段（①②③）并派发 |
| `coding-start` | 编码阶段入口 + 阶段分发器——先后端（docs/08 § 二）后前端（§ 三），派发 phase-driver(phase=backend/frontend)；都完成则输出全部完成 |

### 计划阶段

| Skill | 描述 |
|-------|------|
| `init` | 计划 ①——项目初始化 + 范围锁定（模板复制、依赖检查、git init、项目概述+技术栈+需求索引、REQ 卡片生成，停下等人工审阅） |
| `design` | 计划 ②——脚手架 + 数据库设计（docs/04 § 一+、scripts、.env.local、docs/03 DB 设计，停下等人工审阅） |
| `build-db` | 计划 ③——DB 初始化 + 下游文档（V1 migration apply、docs/05 API 契约、docs/08 § 二模块清单，计划阶段结束） |

### 编码阶段

| Skill | 描述 |
|-------|------|
| `phase-driver` | 阶段驱动（phase 参数区分）——backend：加载当前模块 REQ 清单逐个派发；frontend：prototype/ 门禁 + 推导 FE 清单写 docs/08 § 三后逐个派发 |
| `feature-spec` | 功能规格（两阶段共用）——为 REQ（后端）/ FE（前端）生成"规格 + 任务级计划"合并文档 |
| `feature-tdd` | TDD 实现（两阶段共用）——按 plan 测试先行再实现，Agent 子会话跑测试；路径护栏按 phase 区分 |
| `feature-review` | 验证 + AI 自审（两阶段共用）——子会话跑测试 + reviewer agent（后端 superpower / 前端 fe-code-reviewer），approve 勾选进度回 phase-driver |
| `milestone` | 里程碑（phase 由分支推断）——内置测试闸门（Agent 子会话），green 则本地 merge + 打 tag，生成完成报告 |

### 守门

| Skill | 描述 |
|-------|------|
| `interrupt-check` | 中断检查——触发中断条件时由功能循环 skill 调用，追加 Blocker 节并停止执行 |

### 文档套件（5 文档）

| 文档 | 职责 |
|------|------|
| `docs/01-需求清单/` | REQ 卡片目录（模块子目录 + index.md） |
| `docs/03-数据库设计文档.md` | 表/字段/索引/外键 SSoT（design 生成，编码阶段同步更新） |
| `docs/04-技术规范.md` | 技术栈总览（§ 零）+ 架构规范 + 前端 Design Tokens / 交互约定 + 环境变量说明（含 .env.local 密钥字段）——已把原 UI 规范与环境配置并入此文件 |
| `docs/05-API接口契约.md` | 所有后端接口契约（build-db 生成，feature-spec 按需追加） |
| `docs/08-模块任务管理.md` | 全流程进度跟踪（§ 一计划 / § 二后端模块 / § 三前端整体） |