# erp-workflow

Claude Code 插件：ERP / 后端管理系统全流程开发框架。

把"从零到 N 个模块上线"的整个流程固化成 **19 个 skill + 2 个 hook + 38 份模板**，让 CC 在 schema 演化用 Flyway migration、需求可追溯、人工审核可控的前提下推进编码。

## 这个插件做什么

```
📋 阶段 A：规划（一次性，入口 /erp-workflow:erp-plan-start）
   初始化项目 → 锁范围（REQ 卡片生成）
                        ↓
              ⏸ 审阅 REQ 卡片 → 重跑 /erp-plan-start 继续
                        ↓
   生骨架 → 初始化 DB（V1 migration + seed）→ 生 DB 设计 → 生下游文档
                                                         ↓
                                     用户显式 /erp-workflow:erp-coding-start

🔁 阶段 B：编码（按模块循环，入口 /erp-workflow:erp-coding-start）
   功能循环：Brainstorm → Plan → TDD → Verify → Review
   模块循环：本地测试闸门 → 写模块报告 → 建 GitLab MR → ⏸ 用户 Approve+Merge → 下次 coding-start 自动扫 MR merged → 下一模块

⚙️ 后台守门：占位符未填 / 红旗触发 / 跨模块改动未记录
```

## 安装

### 方式 1：本地测试（开发期）

```bash
claude --plugin-dir /path/to/erp-workflow-plugin
```

### 方式 2：从 marketplace 安装（发布后）

```
/plugin install erp-workflow@<your-marketplace>
```

详见官方文档 [Discover and install plugins](https://code.claude.com/docs/en/discover-plugins)。

## 首次使用

1. **进入空项目目录并启动 Claude Code**：
   ```bash
   mkdir my-erp && cd my-erp
   claude --plugin-dir /path/to/erp-workflow-plugin
   ```

2. **Plan 阶段入口**（一次性规划）：
   ```
   /erp-workflow:erp-plan-start
   ```
   Plan 阶段**两段式**执行，中间有一个 REQ 审阅断点：

   - **第一段（首次运行）**：跑 **A0 → A1**（创建骨架 / 锁技术栈 / 填需求 / 生成 REQ 卡片）后**停下**，等你审阅 `docs/01-需求清单/*.md` 里的 REQ 卡片（这是 Plan 阶段最关键的人工关口）
   - **第二段（审阅完重跑同一命令）**：继续 **A2 → A5**（生骨架 / 初始化 DB / 生设计 / 生下游文档），Plan 完成后再次**停下**

   每次运行都会自动接上次停下的地方继续；中途可以随时关闭 CC，下次跑同样的命令就能恢复。Plan 完成后**不会自动进入编码**，需要你手动运行 `/erp-workflow:erp-coding-start`。

3. **Coding 阶段入口**（模块循环）：
   ```
   /erp-workflow:erp-coding-start
   ```
   Plan 全部完成后由你显式触发。**按 `docs/02 § 二` REQ 开发顺序清单**扫描决定当前模块：
   对每个 REQ 所属模块查 `docs/08` 的 `MR:` 字段 + `glab mr view state`：
   - `state == merged` → 模块已完成，跳过
   - `MR: —` / opened / closed / 查不到 → 该模块是当前模块

   之后 `git checkout main` + `git pull --ff-only` 同步远程 main（保证下次 module 分支切出时 base 新鲜），再派发到 `erp-module-start`。

   **`docs/08 § 二` 每模块是 bullet（`- module_id ...`，无 checkbox）**——完成信号由 MR merged state 判定。原来的"翻勾 `[x]`"动作已从结构上消除，彻底消灭 Codex adversarial review Finding 1 的"用户抢跑 coding-start 跳过未合并模块"的 ordering bug。

4. **中途恢复**：任何时候跑对应入口命令——根据 Plan § 一 checkbox 和 § 二 各模块 MR state 跳到当前该做的事。

## 目录结构

```
erp-workflow-plugin/
├── .claude-plugin/
│   └── plugin.json              # 插件清单，声明 skills 三个子目录
├── README.md                    # 本文档
├── hooks/
│   ├── hooks.json               # hook 注册表（2 个 hook）
│   └── scripts/*.sh             # 2 个 hook 脚本
└── skills/
    ├── plan/                    # 阶段 A：6 个一次性规划 skill
    ├── coding/                  # 阶段 B：9 个模块/功能循环 skill
    └── crosscut/                # 横切：2 个入口 + 1 红旗 + 1 留痕 skill
```

插件加载时按 `plugin.json` 的 `skills: ["./skills/plan", "./skills/coding", "./skills/crosscut"]` 扫描。skill 名称不含子目录前缀（如 `/erp-workflow:erp-scope-lock`）。

## Hook 清单（2 个，全部在 hooks/hooks.json 注册）

| Hook | 脚本 | 事件 | 触发条件 | 作用 |
|---|---|---|---|---|
| 拒绝 no-verify | `deny-no-verify.sh` | PreToolUse / Bash | CC 尝试 `git push --no-verify` | 硬拦截，强制 `.githooks/pre-push` 生效 |
| 跨模块改动留痕 | `log-cross-module.sh` | PostToolUse / Edit \| Write | 当前处于 `module-*` 分支 且 编辑目标路径落在 `docs/08 § 二` 中**非当前模块**的 path 范围内（无论目标模块 MR 是否已 merged） | 把改动追加为 `TBD(CC 补)` 存根到 `<current_module>-cross-module.md`；通过 `additionalContext` 软提示 CC 调 `erp-cross-module-log` skill **自主推断**补「原因 / 影响评估」两列。即时性由 CC 自己决定；**最迟在 `erp-module-report` § ⑦ 硬闸门处**（TBD 未清空会阻断模块完成报告），保证模块完成前所有 TBD 必被 CC 填实 |

**流程使用情况**：2 个 hook 全部在 hooks.json 注册、被 CC 自动触发。

## Skill 清单（19 个）

### Plan 阶段（6 个，`skills/plan/`）

| # | Skill | 作用 | 流程中谁调用 |
|---|---|---|---|
| A0 | `erp-project-init` | • 依赖检查（`mysql` / `mysqldump` 在 PATH，缺失则尝试自动安装）<br>• 空目录初始化：`cp` 模板创建 CLAUDE.md / docs/01/README.md / docs/08<br>• `git init` | `erp-plan-start` |
| A1 | `erp-scope-lock` | • 引导填项目概述 / 技术栈 / 需求索引<br>• 生成 REQ 卡片（`schema_refs=TBD(A4 自动补)`、`api_refs=TBD(A5 自动补)`）<br>• **停下**等人工审阅 REQ 卡片，审阅完毕用 `/erp-plan-start` 恢复续进 A2 | A0 |
| A2 | `erp-skeleton-gen` | • 生成架构文档：docs/04 § 一+ / docs/06 / docs/07 / docs/09<br>• 生成工具脚本：scripts/*.sh、.githooks/pre-push、.env.local<br>• 创建 `sql/migrations/` 空目录（Flyway 准备）<br>• 合并 .gitignore（逐行判重） | `erp-plan-start` |
| A3 | `erp-db-init` | • 验证 MySQL 连接<br>• 导出 schema 为 `sql/migrations/V1__initial_schema.sql`（DDL only）<br>• 导出数据为 `sql/seed-data.sql`（INSERT only） | A2 |
| A4 | `erp-db-design-gen` | • 生成 `docs/03-数据库设计文档.md`<br>• 回填 REQ 卡片依赖表（`TBD(A4 自动补)` → 实际表名）<br>• schema 一致性检查 | A3 |
| A5 | `erp-downstream-gen` | • 一次性生成 docs/02 / docs/05 / docs/06 § 五 / docs/10<br>• 回填 REQ 卡片依赖接口（`TBD(A5 自动补)` → 实际 endpoint）<br>• 追加模块清单到 docs/08 § 二<br>• 最终占位符扫描（TBD 自动补 + `【人工填写：】` QA 循环）<br>• 打印 Plan 完成横幅并**停下**（不自动进 B） | A4 |

### Coding 阶段（9 个，`skills/coding/`）

**触发与顺序**（`erp-coding-start` 是唯一由用户手动触发的入口，下面所有 skill 都由 skill 链自动调用）：

```
/erp-workflow:erp-coding-start          ← 用户每次手动触发
        │
        │  扫 docs/02 REQ 序 + docs/08 MR 字段 + glab mr view state 判当前模块：
        │  - 所有模块都 merged → 打印"所有模块已完成"
        │  - 找到第一个非 merged 模块 → 派发
        │  派发前 git checkout main + git pull --ff-only（同步远程 base）
        │
        └─→ erp-module-start（幂等可重入，切 module-<id> 分支）
                  │
                  │ 对每个未完成 REQ，按序串链：
                  │ erp-feature-brainstorm → -plan → -tdd → -verify → -review
                  │
                  │ review approve              → 回 erp-module-start（推进下一 REQ）
                  │ review request-changes (<5) → fix commit → 回 erp-feature-verify 重跑
                  │ review request-changes (=5) → 停下（升级给人）
                  │
                  │ 模块全部 REQ approve →
                  │   erp-local-test-gate（commit test-gate.md）
                  │   → erp-module-report（commit 模块报告 + cross-module log）
                  │   → erp-mr-create（worktree clean 校验 → push 代码+evidence → 建 MR
                  │       → 追 MR URL 到报告 + commit → 写 MR iid 到 docs/08 + commit
                  │       → 再 push；docs/08 无 checkbox）
                  │
                  └─ ⏸ 停下等人工 Approve + Merge
                     （人工合并后再跑 coding-start，扫到 state=merged 自动跳过
                      → pull main → 推进下一模块）
```

| Skill | 做什么 | 谁触发它 |
|---|---|---|
| `erp-module-start` | 定位当前模块（docs/02 REQ 序）+ 切/建 `module-<id>` 分支 + 扫 `docs/superpowers/reviews/*.md` 的 `verdict=approve` 算已完成 REQ + 推进第一个未完成 REQ 的功能循环。全部完成 → `erp-local-test-gate`。**幂等可重入**（中途断开再跑自动跳过已 approve 的 REQ） | `erp-coding-start` 派发；`erp-feature-review` approve 后回调 |
| `erp-feature-brainstorm` | 功能循环步骤 1：交互 brainstorm → 生成 `docs/superpowers/specs/*.md` | `erp-module-start` 推进 REQ 时调用 |
| `erp-feature-plan` | 功能循环步骤 2：spec → 任务级 plan（含文件路径 + 完整代码），输出 `docs/superpowers/plans/*.md` | `erp-feature-brainstorm` 链式调用 |
| `erp-feature-tdd` | 功能循环步骤 3：红绿循环（写失败测试 → 实现 → 子会话验证通过 → commit 到 `module-<id>` 分支） | `erp-feature-plan` 链式调用 |
| `erp-feature-verify` | 功能循环步骤 4：全测试套件派子会话跑一次，用模板渲染 evidence | `erp-feature-tdd` 链式调用；`erp-feature-review` 在 request-changes 修复后重跑 |
| `erp-feature-review` | 功能循环步骤 5：AI 自审，写 `docs/superpowers/reviews/*.md`。approve → 回 `erp-module-start`；request-changes → 逐项 Edit + fix commit → 回 `erp-feature-verify` 重跑（最多 5 轮，第 5 轮仍 request-changes 则停下） | `erp-feature-verify` 链式调用 |
| `erp-local-test-gate` | MR 前硬闸门：子会话跑 `scripts/test.sh`（脚本内部 drop+create 空库、Flyway apply `sql/migrations/V*.sql`、再跑测试）；通过 → 写 `<module_id>-test-gate.md` 并 `git add + commit`（evidence 进 module 分支）；失败停下 | `erp-module-start` 在本模块所有 REQ approve 后调用 |
| `erp-module-report` | 红旗检查 → 生成 12 节模块完成报告 `docs/superpowers/module-reports/<date>-<module_id>.md` → `git add + commit`（报告 + cross-module log 进 module 分支，erp-mr-create 的 worktree clean 前置条件依赖此步） | `erp-local-test-gate` 链式调用 |
| `erp-mr-create` | 红旗检查 → 验证当前分支 = `module-<id>` + `git status --porcelain` worktree 干净 → `git push` 推代码和所有 evidence → `glab mr create`（模块报告嵌入 MR 描述）→ 追 MR URL 到报告 + commit → 回写 `MR: —` → `MR: !<iid>` 到 docs/08 + commit → 再次 push；**停下等人工 Approve+Merge**。docs/08 § 二是模块元数据 bullet（无 checkbox），完成由 MR state 判定 | `erp-module-report` 链式调用 |

### Crosscut（4 个，`skills/crosscut/`）

| Skill | 作用 | 流程中谁调用 |
|---|---|---|
| `erp-plan-start` | **A 阶段入口**。读 docs/08 § 一 找第一个未勾 A 子项 → 派发对应 A skill；A 全部完成时提示运行 coding-start | **用户手动**运行 `/erp-workflow:erp-plan-start` |
| `erp-coding-start` | **B 阶段入口**。先验证 Plan 已完成；**按 `docs/02 § 二` REQ 序扫**，对每个 REQ 所属模块查 `MR: 字段 + glab mr view state`：`merged` 跳过；`—`/opened/closed/查不到 选为当前模块。派发前 `git checkout main + git pull --ff-only` 同步远程 base，然后调 `erp-module-start` | **用户手动**运行 `/erp-workflow:erp-coding-start` |
| `erp-red-flag-check` | 检查 CLAUDE.md 的 6 项红旗清单；命中则追加 Blocker 到计划文件并停下 | 功能循环各步骤和生成重要制品前自动调用 |
| `erp-cross-module-log` | 给 `log-cross-module.sh` 追加的跨模块改动存根补「原因 / 影响评估」 | 用户看到 hook 提示后调用；`erp-module-start` 初始化日志文件时也会用其模板 |

## Templates 清单（38 份）

| 所属 Skill | 模板文件 | 用途 |
|---|---|---|
| erp-project-init | `CLAUDE-template.md` | 项目根的 CLAUDE.md（4 条通用准则 + ERP 专属约定） |
| erp-project-init | `docs-01-readme-template.md` | 需求清单索引骨架，等用户填模块表 |
| erp-project-init | `docs-08-initial-template.md` | 工作流进度文件骨架（Plan A0~A5 checkbox） |
| erp-scope-lock | `req-card-template.md` | 单张 REQ-XXX-NNN 卡片字段结构 |
| erp-scope-lock | `docs-01-module-template.md` | 单模块 `<code>-<name>.md` 外壳 |
| erp-skeleton-gen | `docs-04-skeleton-template.md` | docs/04 § 一+ 编码规范大纲（HTML 注释引导 LLM） |
| erp-skeleton-gen | `docs-06-static-template.md` | docs/06 § 一~四 UI 模式大纲 |
| erp-skeleton-gen | `docs-07-env-template.md` | docs/07 环境配置大纲 |
| erp-skeleton-gen | `docs-09-structure-template.md` | docs/09 目录结构大纲 |
| erp-skeleton-gen | `scripts-setup-test-db-template.sh` | 运行时 drop + create 空库脚本（0 槽位）；schema apply 交给 Flyway |
| erp-skeleton-gen | `githooks-pre-push-template.sh` | pre-push → 调 scripts/test.sh（0 槽位） |
| erp-skeleton-gen | `env-local-template` | 6 字段凭据模板（DB_* + JWT_SECRET） |
| erp-skeleton-gen | `gitignore-append-template` | 插件推荐忽略项（`.env.local`、`.tmp/`、构建产物等） |
| erp-db-init | `migration-v1-header-template.sql` | V1 initial migration 文件头部注释 |
| erp-db-init | `seed-data-sql-template.sql` | seed-data.sql 文件头部注释 |
| erp-db-design-gen | `docs-03-header-template.md` | docs/03 数据库设计头部 |
| erp-db-design-gen | `docs-03-table-template.md` | docs/03 单表小节模板 |
| erp-downstream-gen | `docs-02-template.md` | docs/02 开发计划 |
| erp-downstream-gen | `docs-05-header-template.md` | docs/05 API 契约头部 |
| erp-downstream-gen | `docs-05-endpoint-template.md` | docs/05 单接口小节 |
| erp-downstream-gen | `docs-06-module-pagelist-template.md` | docs/06 § 五 单模块页面清单 |
| erp-downstream-gen | `docs-08-module-row-template.md` | docs/08 § 二 单模块 bullet 行 |
| erp-downstream-gen | `docs-10-header-template.md` | docs/10 验收清单头部 |
| erp-downstream-gen | `docs-10-module-template.md` | docs/10 单模块验收项 |
| erp-module-start | `module-start-banner-template.md` | 模块启动横幅 |
| erp-module-start | `cross-module-log-template.md` | cross-module 日志头（副本） |
| erp-feature-brainstorm | `feature-spec-template.md` | 功能 spec 结构 |
| erp-feature-plan | `feature-plan-template.md` | 功能 plan 结构 |
| erp-feature-tdd | `commit-message-template.md` | TDD 每步 commit 信息 |
| erp-feature-verify | `feature-verify-evidence-template.md` | 验证证据渲染模板 |
| erp-feature-review | `feature-review-template.md` | 自审报告结构 |
| erp-local-test-gate | `test-gate-result-template.md` | 闸门结果渲染 |
| erp-module-report | `module-report-template.md` | 12 节模块报告 |
| erp-mr-create | `mr-title-template.md` | MR 标题模板 |
| erp-mr-create | `mr-description-template.md` | MR 描述模板（嵌入模块报告） |
| erp-red-flag-check | `red-flag-block-template.md` | Blocker 节追加模板 |
| erp-cross-module-log | `cross-module-log-template.md` | cross-module 日志头（主本） |
| erp-cross-module-log | `cross-module-log-row-template.md` | 单条改动行模板 |

**流程使用情况**：所有模板都被对应 skill 的 `SKILL.md` 引用，没有孤儿模板。

## 前置依赖

- **MySQL 8.x** 实例已建好（CC 不跑 DDL；schema 由人工初始化）
- **`mysql` / `mysqldump` 命令行**：`erp-db-init` (A3) 验证连接 + 导出 V1 initial migration + 导出 seed-data.sql；`scripts/setup-test-db.sh` 在测试闸门前后 drop+create 空库
- **Spring Boot + Flyway**（**必需**）：pom.xml 声明 `flyway-core` + `flyway-mysql`；Spring 启动时自动 apply `sql/migrations/V*.sql`。本插件生成的 `setup-test-db.sh` 只清库，schema 必须由 Flyway 应用
- **GitLab + glab CLI**：`erp-mr-create` 用 `glab mr create`；`erp-coding-start` 用 `glab mr view` 判 MR 状态
- **本地能跑 `mvn test` / `pnpm test`**：测试闸门 `scripts/test.sh` 由 `erp-skeleton-gen` 生成

## 设计原则

参见 `erp-project-init/templates/CLAUDE-template.md` 末尾的「🧭 通用工作准则」4 条：① Think Before Coding ② Simplicity First ③ Surgical Changes ④ Goal-Driven Execution。

最关键的 1 条："**所有测试与验证派发到全新子会话执行，主会话只接收结构化结论**"——避免主会话被测试输出污染，并让测试结果作为独立证据存档。