# erp-workflow（lite）

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

把"从零到 N 个后端模块上线 + 前端整体阶段"的整个流程固化成 **11 个 skill + 2 个 agent + 22 份模板 + 3 个脚本**，让 CC 在 schema 演化用 Flyway migration、需求可追溯、纯本地 git 的前提下推进编码。后端按模块循环依次打里程碑 tag，所有后端模块打里程碑后进入前端整体阶段（以项目根 `prototype/` 静态 HTML mockup 为页面权威）。两阶段共用同一套功能循环 skill，由 `phase` 参数区分。

## 这个插件做什么

```
┌────────────────────────────────────────────────────────┐
│  erp-workflow-lite                                       │
│                                                          │
│  计划（/plan-start，一次性，2 个审阅断点）               │
│    ① lite-init      初始化 + REQ 卡片      ⏸ 审阅 REQ    │
│    ② lite-design    脚手架 + docs/03       ⏸ 审阅 schema │
│    ③ lite-build-db  V1+apply + docs/05/08                │
│                                                          │
│  编码（/coding-start，统一功能循环）                     │
│    后端模块循环  ┐                                       │
│    前端整体阶段  ┘→ phase-driver                         │
│        feature-spec → feature-tdd → feature-review       │
│        全 approve → milestone（test→报告→merge+tag）     │
└────────────────────────────────────────────────────────┘
```

## 首次使用

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

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

   - **第一段（首次运行）**：执行 `lite-init`（依赖检查 / git init / 初始化 docs + CLAUDE.md / 引导填技术栈 + 需求索引 / 生成 REQ 卡片骨架）后**停下**，等你审阅并补全 `docs/01-需求清单/<module>/REQ-*.md`（第一个人工关口：业务范围）
   - **第二段（REQ 审阅完重新运行）**：执行 `lite-design`（生成 docs/04 架构规范 / scripts / .env.local / 从 REQ 正向设计 `docs/03-数据库设计文档.md`）后再次**停下**，等你审阅 docs/03 的表 / 字段 / 索引 / 外键（第二个人工关口：database schema）
   - **第三段（docs/03 审阅完重新运行）**：执行 `lite-build-db`（解析 docs/03 → 生成 V1 migration → DROP+CREATE 本地 schema 并 apply → 生成 docs/05 API 契约 + 追加 docs/08 § 二 模块清单），Plan 完成后**停下**

   每次运行都会自动接上次停下的地方继续。Plan 完成后**不会自动进入编码**，需要你手动运行 `/erp-workflow:coding-start`。

3. **Coding 阶段入口**（后端模块循环 → 前端整体阶段）：
   ```
   /erp-workflow:coding-start
   ```
   Plan 全部完成后由你显式触发。`coding-start` 是阶段分发权威——每次入口都重新扫描 docs/08 § 二/§ 三 里程碑字段 + 本地 git tag，按当前进度决定派发：

   **路由规则（coding-start 真值表，只做分发）**：

   | `backend_done` | `frontend_done` | coding-start 派发 |
   |---|---|---|
   | `false` | 任意 | `phase-driver(phase=backend)`（写后端） |
   | `true` | `false` | `phase-driver(phase=frontend)`（写前端） |
   | `true` | `true` | 打印"所有阶段已完成"，停下 |

   docs/08 里程碑字段与 `git tag -l` 不一致 → 停下报错（绝不静默假设完成状态）。

   **后端阶段（phase-driver phase=backend）**：
   - 切到 `module-<id>` 分支，对每个未完成 REQ：`feature-spec → feature-tdd → feature-review`
   - 全 approve → `milestone`（内置测试闸门 + 完成报告 + 本地 merge + 打 `milestone/<id>` tag）→ 自动回 `coding-start` 再次路由

   **前端阶段（phase-driver phase=frontend，自带前置门禁）**：
   - prototype/ 门禁（≥ 1 个 *.html，缺失则 AskUserQuestion 提示用户补齐 → 停下）
   - 准备 FE 清单（无审阅断点）：§ 三 占位则 AI 扫 prototype + docs/01 + docs/05 推导写入；§ 三 已有则加载
   - 切 `frontend-phase` 分支，对每个未完成 FE：`feature-spec → feature-tdd → feature-review`（`fe-code-reviewer` agent 做 7 维 review）
   - 全 approve → `milestone`（内置测试闸门 vitest + Playwright + 完成报告 + merge + tag）→ 自动回 `coding-start` → 全部完成

4. **中途恢复**：任何时候运行对应入口命令——根据 Plan § 一 checkbox、§ 二 各后端模块里程碑 tag、§ 三 前端整体里程碑 tag 跳到当前该做的事。

## 目录结构

```
erp-workflow-plugin/
├── .claude-plugin/
│   └── plugin.json                  # 插件清单，声明 skills 三个子目录
├── README.md                        # 本文档
├── agents/
│   ├── superpower-code-reviewer.md  # 后端 code-reviewer agent（feature-review 后端阶段调用）
│   └── fe-code-reviewer.md          # 前端专用 reviewer（feature-review 前端阶段调用，7 维 review）
└── skills/
    ├── plan/                        # 计划阶段：3 个一次性规划 skill
    │   ├── lite-init/
    │   ├── lite-design/
    │   └── lite-build-db/
    ├── coding/                      # 编码阶段：5 个 skill（两阶段共用统一功能循环）
    │   ├── phase-driver/
    │   ├── feature-spec/
    │   ├── feature-tdd/
    │   ├── feature-review/
    │   └── milestone/
    └── crosscut/                    # 横切：3 个 skill（2 个入口 + 1 个中断守门）
        ├── plan-start/
        ├── coding-start/
        └── interrupt-check/
```

## Hook 清单

lite 版本**无 Hook**——跨模块改动留痕已移除。跨模块改动须在 `milestone` 完成报告的「偏离与取舍」节人工记录。

## Skill 清单（11 个）

### 入口（`skills/crosscut/`）

| Skill | 作用 | 流程中谁调用 |
|---|---|---|
| `plan-start` | **A 阶段入口**。读取 docs/08 § 一找第一个未勾计划段（①②③）→ 派发对应 plan skill；全部完成时提示运行 coding-start | **用户手动**运行 `/erp-workflow:plan-start` |
| `coding-start` | **B 阶段入口 + 阶段分发器（只做分发）**。① 校验 Plan 已完成（docs/08 § 一 ①②③ 全勾）② 后端完成性检查（§ 二 + git tag）③ 前端完成性检查（§ 三 + tag）④ 真值表派发到 phase-driver | **用户手动**运行 `/erp-workflow:coding-start`；`milestone` 每阶段完成后自动回调 |
| `interrupt-check` | 检查 CLAUDE.md 的 3 项中断清单；触发则追加 Blocker 到 spec 文件并停下 | `feature-tdd`（同一测试 >10 次失败）/ `milestone`（环境失败横幅 ③）按需调用 |

### 计划阶段（`skills/plan/`）

| Skill | 作用 | 流程中谁调用 |
|---|---|---|
| `lite-init` | 计划 ①：依赖检查 / git init / 创建 CLAUDE.md + docs/01/index.md + docs/04 § 零 + docs/08；引导填项目概述 / 技术栈 / 需求索引；按模块生成 REQ 卡片骨架；**停下**等人工审阅 REQ | `plan-start` |
| `lite-design` | 计划 ②：生成 docs/04 架构规范大纲 + scripts（test.sh / setup-test-db.sh）+ .env.local + .gitignore 合并；从 docs/01 REQ 正向设计 `docs/03-数据库设计文档.md`（schema SSoT）；**停下**等人工审阅 docs/03 | `plan-start` |
| `lite-build-db` | 计划 ③：解析 docs/03 → `sql/migrations/V1__initial_schema.sql`（5 维度校验 DDL ↔ docs/03）→ DROP+CREATE 本地 schema 并 apply V1；生成 docs/05 API 契约 + 回填 REQ 依赖接口；追加模块清单到 docs/08 § 二；打印 Plan 完成横幅并**停下** | `plan-start` |

### 编码阶段（`skills/coding/`）

| Skill | 作用 | 流程中谁调用 |
|---|---|---|
| `phase-driver` | 阶段驱动（`phase` 参数区分）。**backend**：切 `module-<id>` 分支，扫 docs/08 § 二 计算未完成 REQ，推进第一个未完成 REQ；本模块全 approve → `milestone`。**frontend**：prototype/ 门禁 → FE 清单准备（§ 三 占位则推导写入，§ 三 已有则加载）→ 切 `frontend-phase` 分支，推进未完成 FE；全 approve → `milestone`。**幂等可重入** | `coding-start` 派发；`feature-review` approve 后回调 |
| `feature-spec` | 功能规格（两阶段共用）：为 REQ（后端）/ FE（前端）生成"规格 + 任务级计划"合并文档（`docs/superpowers/specs/*.md`）；路径护栏按 phase 区分 | `phase-driver` 推进单元时调用 |
| `feature-tdd` | TDD 实现（两阶段共用）：按 spec/plan 写失败测试 → 实现 → Agent 子会话验证通过 → commit（后端：controller/service/repository/DTO/migration；前端：`frontend/` 下组件/路由/API client） | `feature-spec` 链式调用 |
| `feature-review` | 验证 + AI 自审（两阶段共用）：子会话跑全量测试 → 委托 reviewer agent（后端：`superpower-code-reviewer`；前端：`fe-code-reviewer`）。approve → 勾选 docs/08 对应子项 + 回 `phase-driver`；request-changes → fix → 重跑（最多 5 轮，第 5 轮仍 request-changes 则停下） | `feature-tdd` 链式调用 |
| `milestone` | 里程碑（phase 由当前分支推断）：内置测试闸门（Agent 子会话：后端 `scripts/test.sh`；前端 vitest + Playwright）→ 6 节完成报告 → 本地 `git merge --no-ff` 进默认分支 → 回写 docs/08 `里程碑:` 字段 → `git tag -a milestone/<id>` → **自动回调 coding-start**（无人工介入）。完成由本地 `git tag -l` 判定 | `phase-driver`（本阶段全部单元 approve 后）|

## Agent 清单（2 个）

| Agent | 用途 | 谁调用 |
|---|---|---|
| `superpower-code-reviewer` | 对后端 REQ diff 做 AI 自审，产出 `must_fix[]` / `nice_to_have[]` / `gaps` | `feature-review`（phase=backend）：`Agent(subagent_type=superpower-code-reviewer)` |
| `fe-code-reviewer` | 对前端 FE-NN diff 做 7 维 AI 自审：prototype 一致性 / Design Tokens / 无障碍 / 响应式 / 业务校验前端复刻 / API 一致性 / 状态机覆盖 | `feature-review`（phase=frontend）：`Agent(subagent_type=fe-code-reviewer)` |

## Banners 清单（2 份）

流程图抽到独立 `.txt` 文件，SKILL.md 步骤 0 用 `bash cat` 输出——保证 ASCII 边框对齐不被 LLM 复读破坏。

| 所属 Skill | Banner 文件 | 用途 |
|---|---|---|
| `plan-start` | `banners/flow-lite.txt` | 整体流程图（▶ 标在 plan-start 分发横幅前） |
| `coding-start` | `banners/flow-lite.txt` | 整体流程图（▶ 标在 coding-start 分发横幅前） |

## Templates 清单（22 份模板文件，21 个不同名——`commit-message-template.md` 由 feature-tdd / feature-review 各持一份）

| 所属 Skill | 模板文件 | 用途 |
|---|---|---|
| `lite-init` | `CLAUDE-template.md` | 项目根的 CLAUDE.md（4 条通用准则 + ERP 专属约定 + skill 索引） |
| `lite-init` | `docs-01-index-template.md` | 需求清单索引骨架 |
| `lite-init` | `docs-08-initial-template.md` | 工作流进度文件骨架（Plan ①②③ checkbox） |
| `lite-init` | `docs-04-stack-template.md` | docs/04 § 零 默认技术栈总览（零槽位，cp 即可） |
| `lite-init` | `req-card-template.md` | 单张 REQ-XXX-NNN 卡片骨架（6 个 `{{...}}` 占位符由 CC 替换） |
| `lite-init` | `_module-template.md` | 模块子目录的 `_module.md` 模块头 |
| `lite-design` | `docs-04-skeleton-template.md` | docs/04 § 一+ 编码规范大纲 |
| `lite-design` | `docs-03-header-template.md` | docs/03 数据库设计头部 |
| `lite-design` | `docs-03-table-template.md` | docs/03 单表小节模板 |
| `lite-design` | `scripts-setup-test-db-template.sh` | drop + create 空库脚本（0 槽位） |
| `lite-design` | `scripts-test-template.sh` | test.sh 骨架（多个命令槽位，由 lite-design 按技术栈推断填充） |
| `lite-design` | `env-local-template` | 6 字段凭据模板（DB_* + JWT_SECRET） |
| `lite-design` | `gitignore-append-template` | 插件推荐忽略项（`.env.local`、`.tmp/`、构建产物等） |
| `lite-build-db` | `docs-05-header-template.md` | docs/05 API 契约头部 |
| `lite-build-db` | `docs-05-endpoint-template.md` | docs/05 单接口小节 |
| `lite-build-db` | `docs-08-module-row-template.md` | docs/08 § 二 单模块 bullet 行 |
| `feature-spec` | `feature-spec-plan-template.md` | 功能规格 + 任务级计划合并文档 |
| `feature-review` | `feature-review-template.md` | 自审报告结构 |
| `feature-review` | `commit-message-template.md` | review fix commit 信息 |
| `feature-tdd` | `commit-message-template.md` | TDD 每步 commit 信息 |
| `milestone` | `milestone-report-template.md` | 完成报告模板（6 节） |
| `interrupt-check` | `interrupt-block-template.md` | Blocker 节追加模板 |

**Scripts 清单（2 份）**：

| 所属 Skill | 脚本文件 | 用途 |
|---|---|---|
| `lite-init` | `scripts/render.sh` | 渲染单个 `_module.md` 或 `REQ-*.md`（替换 6 个占位符） |
| `lite-design` | `scripts/merge-gitignore.sh` | 合并 .gitignore（逐行判重） |

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

## 前置依赖

- **MySQL 8.x** 实例已就绪（推荐本地 / `*.local` host；`lite-build-db` 的安全守护要求 host 在白名单且 schema 名含 `test`/`dev`/`local`，避免误删生产库）
- **`mysql` 命令行**：`lite-build-db` 验证连接 + 自动 `DROP+CREATE` schema 后 apply V1；`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 应用
- **本地 git 仓库**（纯本地，**无需远程 / push / GitLab**）：`lite-init` 执行 `git init`；编码阶段每模块由 `milestone` 本地 `git merge --no-ff` 进默认分支并 `git tag -a milestone/<id>`，完成信号由 `git tag -l` 判定
- **本地可运行 `mvn test` / `pnpm test`**：测试闸门 `scripts/test.sh` 由 `lite-design` 生成

## 设计原则

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

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