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

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

---

## 🎯 项目概述

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

---

## 🔄 B 阶段开发流程

B 阶段由 `/erp-workflow:coding-start` 启动 `workflows/coding.mjs`：按模块循环跑 spec → plan → tdd → verify → review（同构 `featureLoop`），后端每模块一个里程碑 tag，前端整体一个里程碑 tag。里程碑字段与子项清单记录在 `docs/08 § 二`（后端）/ `§ 三`（前端）；阶段完成判定以 `里程碑:` / `整体里程碑:` 字段 + 本地 `git tag -l 'milestone/<id>'` 为准，子项勾选只作可视化进度。详细路由 / testGate / 中断行为见 `README.md` 与 `workflows/coding.mjs`。

---

## 🏷️ 占位符统一约定

项目文档里两种人工填写占位：
- `【人工填写：<简短说明>】` — 仅 A 阶段文档；B 阶段 plan/spec 禁止出现，查不到真值时用 `AskUserQuestion` 问用户。
- `TBD(<责任人>)` — 由对应 skill / `coding.mjs` stage 自动就地补填（如 `TBD(A3 自动补)`）；模块完成报告 § ⑦ 检查 `TBD(CC 补)` 残留。

---

## 📐 编码行为约束

### 你必须做的 ✅

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

### 你禁止做的 🚫

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

### 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.mjs` 只负责清空库，不做 apply
4. **已合并的 migration 永不修改**：发现错了写一个补救 migration（如 `V7__fix_V5_index_name.sql`），旧 `V_n.sql`
5. **临时调试 DDL**：临时在本地试字段/索引可手动 `mysql -e`，但不写 migration；下次 `setup-test-db.mjs` 会 drop+create 清掉
6. **A4 生成的 V1**：`V1__initial_schema.sql` 是 A 阶段由 `db-init` 从 `docs/03-数据库设计文档.md`（A3 正向设计的 schema SSoT）翻译生成的初始版本；后续 V2/V3/... 由 B 阶段每个 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 的 Brainstorm → Plan → TDD → Verify → AI 自审）默认 **静默编程**，但触发以下任何一条必须**立刻停下、记录原因、等人决策**，不得自行绕过：

| # | 中断 | 例子 |
| - | --- | --- |
| 1 | **测试反复失败** | 同一测试同一功能内连续 **10 次**修复失败 |
| 2 | **要改密钥 / 账密 / 包名** | 密钥 / 账密 在 `.env.local`、包名 / 命名空间 / 端口等在 `config-vars.yaml` 里由人工标注必须填的字段（规则见 `docs/07-环境配置.md`） |
| 3 | **外部接口不可达** | 第三方 API 无法连接、证书失效等环境问题，并无法自行解决 |

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

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

1. `coding.mjs` 子代理在当前功能的 plan 文件里追加一节 `## 🚩 Blocker`（记录原因 / 阻塞点），并 throw 进入 HALT 终止态
2. 整阶段 fail-fast：halt 后停止后续所有模块/功能的静默执行
3. Workflow 返回结构化诊断（halt 原因 + blocker 文件路径），等人修复后重跑 `/erp-workflow:coding-start` 从断点续跑

---

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

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

| # | 软规则 | 允许动作 | 强制后续 |
| - | ----- | ------- | ------- |
| S1 | **技术栈外组件引入** | 用 `AskUserQuestion` 给用户三选一：接受引入 / 换方案 / 拒绝 | ① **接受** → 同会话直接在 `docs/04 § 零` 追加一行 → 继续流程 ② **换方案 / 拒绝** → 视为常规歧义澄清，继续 Q&A 收敛 ③ 不写 Blocker、不中断流程 |
| S2 | **跨模块改动** | **默认不改**，仅为当前模块实现所必需时允许修改 | `coding.mjs` 的 cross-module stage 在模块循环内记录改动并补「原因 / 影响评估」，「跨模块改动」节完整贴入《模块完成报告》 |