diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index d400862..97620e6 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "erp-workflow", - "description": "ERP 项目全流程框架：阶段 A 计划（plan-start 入口 + A0~A5 共 6 个 skill + 增量需求入口 add-req + B 阶段瘦入口 coding-start = 9 个 skill；plan-start 终结闸 4 项前移硬校验；add-req 经 req-ledger 哈希台账识别后续新增/变更需求只跑增量） + 阶段 B 编码（单个静默 Workflow 脚本 coding.mjs，子代理自动跑后端+前端功能循环、测试闸门、本地里程碑 tag）。", + "description": "ERP 项目全流程框架：阶段 A 计划（plan-start 入口 + A0~A5 共 6 个 skill + 增量需求入口 add-req + 字段微改快速通道 quick-field + B 阶段瘦入口 coding-start = 10 个 skill；plan-start 终结闸 4 项前移硬校验；add-req 经 req-ledger 哈希台账识别后续新增/变更需求只跑增量；quick-field 对「加列 + 界面呈现」保 SSoT 跳流程、不重跑 coding） + 阶段 B 编码（单个静默 Workflow 脚本 coding.mjs，子代理自动跑后端+前端功能循环、测试闸门、本地里程碑 tag）。", "version": "0.3.0", "skills": [ "./skills/plan/plan-start", @@ -11,6 +11,7 @@ "./skills/plan/db-init", "./skills/plan/downstream-gen", "./skills/plan/add-req", + "./skills/plan/quick-field", "./skills/coding/coding-start" ] } diff --git a/README.md b/README.md index 741e3fb..db6ecab 100644 --- a/README.md +++ b/README.md @@ -119,7 +119,7 @@ Claude Code 插件：ERP / 后端管理系统全流程开发框架。 ``` erp-workflow-plugin/ ├── .claude-plugin/ -│ └── plugin.json # 插件清单，显式列出 9 个 skill 路径 +│ └── plugin.json # 插件清单，显式列出 10 个 skill 路径 ├── README.md # 本文档 ├── workflows/ │ └── coding.mjs # 阶段 B：整个编码阶段编排为单个静默 Workflow @@ -132,7 +132,7 @@ erp-workflow-plugin/ ├── agents/ │ └── code-reviewer.md # 统一 reviewer（coding.mjs review stage 调用，phase 选维度集） └── skills/ # 按阶段分组（slug 不变，由 SKILL.md frontmatter name 决定） - ├── plan/ # 阶段 A：8 个 skill（入口 + A0~A5 + 增量入口） + ├── plan/ # 阶段 A：9 个 skill（入口 + A0~A5 + 增量入口 + 微改通道） │ ├── plan-start/ # A 阶段入口 + Plan 终结硬闸 │ ├── project-init/ # A0 │ ├── scope-lock/ # A1 @@ -140,20 +140,22 @@ erp-workflow-plugin/ │ ├── db-design-gen/ # A3 │ ├── db-init/ # A4 │ ├── downstream-gen/ # A5（含前端 FE 清单推导，原 A6 已并入） - │ └── add-req/ # 增量需求入口（Plan 完结后追加/修改需求，经 req-ledger 哈希台账只跑增量） + │ ├── add-req/ # 增量需求入口（Plan 完结后追加/修改需求，经 req-ledger 哈希台账只跑增量） + │ └── quick-field/ # 字段微改快速通道（加列 + 界面呈现：保 SSoT 跳流程，不作废 tag、不重跑 coding） └── coding/ # 阶段 B：1 个 skill（瘦入口） └── coding-start/ # 启动 workflows/coding.mjs ``` -## Skill 清单（9 个） +## Skill 清单（10 个） -### 入口（3 个） +### 入口（4 个） | Skill | 作用 | 谁调用 | |---|---|---| | `plan-start` | **A 阶段入口 + Plan 终结硬闸**。读 docs/08 § 一 找第一个未勾 A 子项 → 派发对应 A skill；A 全部完成时校验 4 项前移闸门（REQ 真实数据、`config-vars.yaml` 全部配置（含 DB 凭据 / 密钥）全锁、docs/04 § 零 命令齐、docs/05+02 已评审），全过才提示运行 `/erp-workflow:coding-start`，否则指出缺口不放行 | **用户手动** `/erp-workflow:plan-start` | | `coding-start` | **B 阶段瘦入口**（`allowed-tools: Read Glob Workflow Bash(git ...)`）。校验 Plan 完成态（docs/08 § 一 全勾）+ 取得 projectRoot（git 就绪由 coding.mjs runBranchSetup 在运行时把守）→ 读 docs/08 § 二/§ 三 + `git tag -l 'milestone/*'` 概述阶段进度（Workflow Router 再用 `req-done/*` 判定功能级 resume）→ 若有 `docs/superpowers/RESUME.md` 则读末尾条目复盘上次 halt 原因/待跑模块 → 调用 `Workflow({scriptPath:"${CLAUDE_PLUGIN_ROOT}/workflows/coding.mjs", args:{projectRoot}})` 启动整个编码阶段 → 告知"已在后台启动" | **用户手动** `/erp-workflow:coding-start` | | `add-req` | **增量需求入口**（Plan 完结后追加 / 修改需求时用）。`node lib/req-ledger.mjs scan` 用内容哈希台账（`.req-ledger.json`）识别 docs/01 REQ 卡片 + docs/08 §三 FE 行的**新增 / 变更**；只对增量做 **A3-delta**（写新 `V_n` migration + 同步 docs/03，**绝不改 V1**）+ **A5-delta**（补 docs/05 端点 / docs/02 顺序 / docs/08 模块行 / FE 行），并 `git tag -d` 作废**变更**单元已有的 `req-done/*`（及所属 `milestone/*`，复位 docs/08 里程碑字段），使 coding.mjs Router 只重跑增量。首跑无台账则先建基线。 | **用户手动** `/erp-workflow:add-req` | +| `quick-field` | **字段微改快速通道**（已完成需求追加纯展示/录入字段时替代 add-req 全流程）。保 schema SSoT 不缩水（`V_n` ALTER + docs/03 同步 + validate-ddl fail-closed），后端/前端代码由主会话直改（grep 清单 + 轻量编译/lint 自检），台账 `req-ledger commit` 重基线但**绝不作废任何 req-done/milestone tag**——Router 视一切已完成，不重跑 coding.mjs（不冷起栈、不跑测试门/行为门）。代价是字段未过行为验收：登记到 docs/08 §四 待验清单，攒批人工验收。仅限追加式 ADD COLUMN（可空/带 DEFAULT）+ 既有链路多带一个字段；超界即停下回落 `/add-req`。 | **用户手动** `/erp-workflow:quick-field` | ### Plan 阶段 A skill（A0~A5，共 6 个） diff --git a/skills/plan/add-req/SKILL.md b/skills/plan/add-req/SKILL.md index b691acc..ae91521 100644 --- a/skills/plan/add-req/SKILL.md +++ b/skills/plan/add-req/SKILL.md @@ -12,6 +12,8 @@ allowed-tools: Read Write Edit Grep Glob AskUserQuestion Bash(node *) Bash(git * 用于**初始 Plan（A0~A5）已完结**之后，往项目里**追加新需求**或**修改已有需求**。不重跑整条 Plan，只处理增量；产出与 A1/A3/A5 完全一致，交由 `coding.mjs` Router 增量编码。 > 用法约定：先**人工**在 `docs/01-需求清单/` 里把新 REQ 卡片写好（真实业务内容，同 A1 填法）或修改已有卡片，再运行 `/erp-workflow:add-req`。本 skill 负责「识别 + 下游生成 + 作废过期完成标记」，不替你写业务需求本身。 +> +> **微改分流**：若只是给已有表**追加一个纯展示/录入字段**（ADD COLUMN + 界面呈现，不改业务逻辑/端点），走 `/erp-workflow:quick-field` 更快——保 schema SSoT 但不作废 tag、不重跑 coding.mjs。语义变更 / 新端点 / 类型变更仍走本 skill。 `` = 项目根（含 `docs/`、`config-vars.yaml`、`sql/`、`.git`）。`${CLAUDE_PLUGIN_ROOT}` = 插件根。 diff --git a/skills/plan/quick-field/SKILL.md b/skills/plan/quick-field/SKILL.md new file mode 100644 index 0000000..0db778c --- /dev/null +++ b/skills/plan/quick-field/SKILL.md @@ -0,0 +1,154 @@ +--- +name: quick-field +description: 字段级微改快速通道——给已有表追加展示/录入字段（ADD COLUMN + 界面呈现）时替代 add-req 全流程。保 schema SSoT（V_n migration + docs/03 同步 + validate-ddl），代码由主会话直改（不起 coding.mjs、不冷起栈、不跑测试门/行为门），台账 req-ledger 重基线但绝不作废 req-done/milestone tag，Router 视一切已完成不重跑。超出「纯追加字段」边界即停下回落 /add-req。 +user-invocable: true +allowed-tools: Read Write Edit Grep Glob AskUserQuestion Bash(node *) Bash(git *) Bash(ls *) +--- + +**所有输出必须使用中文。** + +# quick-field — 字段级微改快速通道 + +用于**初始 Plan（A0~A5）已完结、相关模块已编码完成**之后的最小改动形态：「数据库加一列 + 界面展示/录入出来」。与 `/erp-workflow:add-req` 的分工： + +| | add-req（正规通道） | quick-field（本 skill） | +|---|---|---| +| 适用 | 新需求 / 需求语义变更 | 已有需求追加纯展示/录入字段 | +| schema | V_n + docs/03 + validate-ddl | **相同（不缩水）** | +| 代码 | 作废 tag → coding.mjs 全流程重跑 | 主会话直改，语法/grep 自检 | +| 验收 | 测试门 + Preview + 行为门 | **跳过**，登记待验（docs/08 §四） | +| tag | 删 req-done/milestone 逼 Router 重跑 | **绝不删任何 tag** | + +> 速度来自跳过 coding.mjs 的门（冷起栈 / 测试门 / 截图门 / 行为门），代价是**该字段未过行为验收**——步骤 7 会登记待验条目，攒批后人工或随下次正规需求一并验收。 + +`` = 项目根（含 `docs/`、`config-vars.yaml`、`sql/`、`backend/`、`frontend/`、`.git`）。`${CLAUDE_PLUGIN_ROOT}` = 插件根。 + +## 适用边界（硬门，任一不满足即停下回落 add-req） + +1. **仅追加式 ADD COLUMN**：不改类型 / 不重命名 / 不删列 / 不加索引约束外键（`validate-ddl.mjs` 对 `MODIFY/CHANGE/DROP/RENAME` 本就硬拒，天然护栏）。 +2. **列可空或带 DEFAULT**：存量数据无需迁移回填。 +3. **不改业务逻辑**：不新增端点、不改已有端点语义/校验规则/权限——只是既有查询/详情/表单的响应与提交里**多带一个字段**。 +4. **前端仅展示/录入**：列表列、详情项、表单项；不新增页面/路由/交互流程。 +5. **字段归属某个已完成的 REQ**（有 `req-done/` tag 或所属模块已打 milestone）。尚未编码的 REQ 直接改它的卡片走正常流程即可，轮不到本 skill。 + +超界示例（一律停下，打印原因 + 建议走 `/erp-workflow:add-req` 或人工方案）：改列类型、字段带联动校验、需要新查询接口、需要迁移回填存量数据、新页面。 + +## 步骤 0：前置检查（全过才继续） + +1. **Plan 已完结**：`Read` `docs/08-模块任务管理.md § 一`，存在任一 `- [ ]` 未勾 → 停下提示先跑 `/erp-workflow:plan-start`。 +2. **coding.mjs 未在运行**：向用户确认当前没有 Coding Workflow 在后台跑（并行 lane 会占用 migration 版本段，撞 V_n 编号）。在跑 → 停下等它结束。 +3. **工作树干净**：`git -C status --porcelain` 必须为空——本 skill 末尾整体提交，脏树会混入无关改动。不干净 → 停下提示先处理。 +4. **台账干净（关键）**： + ``` + node ${CLAUDE_PLUGIN_ROOT}/lib/req-ledger.mjs scan + ``` + - `ledgerExists: false` → 停下提示先跑一次 `/erp-workflow:add-req` 建基线。 + - `new[]` / `changed[]` / `removed[]` 须**全空**（`changed` 仅含本次目标 REQ 卡一项时放行——用户可能已先在卡片上手写了字段说明）。存在其他待处理增量 → **停下**：步骤 6 的 `req-ledger commit` 是全量重基线，会把这些增量悄悄吞进基线、导致 add-req 永远检测不到它们。提示先跑 `/erp-workflow:add-req` 清账再来。 + +## 步骤 1：收集改动意图 + +从用户输入（或 `AskUserQuestion`）明确： + +- **目标表**（docs/03 已有的表）与**字段业务含义**； +- **列名**：按 CLAUDE.md Schema 演化规约的匈牙利前缀（`i/s/t/b/d`）+ snake_case 拟定，向用户确认； +- **类型 / 可空 / DEFAULT**（必须满足边界 2）； +- **前端呈现**：列表列 / 详情项 / 表单项（可多选），出现在哪个页面； +- **归属 REQ 卡**：`Grep` `docs/01-需求清单/` 中 `依赖表:` 含目标表的卡片定位；多卡命中或零命中 → `AskUserQuestion` 让用户指定。 + +随后对照上方适用边界逐条判定，**任一超界立即停下**（打印命中的边界条目），不做任何写操作。 + +## 步骤 2：schema SSoT（与 add-req A3-delta 完全一致，不缩水） + +1. **写增量 migration**：`ls sql/migrations/V*.sql` 取最大版本 `n`，新建 `sql/migrations/V__add__.sql`，内容 `ALTER TABLE ... ADD COLUMN ...`（命名规范 / 默认值翻译规则同 CLAUDE.md Schema 演化规约）。**绝不改 V1 或任何已存在 V_n。** +2. **同步 docs/03**：目标表小节增列行，保持 docs/03 为 schema SSoT。 +3. **校验（fail-closed）**： + ``` + node ${CLAUDE_PLUGIN_ROOT}/lib/validate-ddl.mjs docs/03-数据库设计文档.md sql/migrations/V*.sql + ``` + 退出码非 0 → 按 stderr diff 就地修正 docs/03 或 V_n，重跑直到 0。**绝不带分叉进入步骤 3。** + +> **绝不手动 apply 到数据库**（包括 `lib/apply-ddl.mjs`）：源库是 Flyway 托管态（有 `flyway_schema_history`），手动灌 V_n 不写历史行，后端下次启动 Flyway 会重复 apply 报错。新列由后端下次启动时 Flyway 自动 apply——用户本来就要起后端看界面，无需额外动作。 + +## 步骤 3：文档轻同步 + +1. **docs/05**：若该 REQ 的端点小节列有字段明细（响应/请求体字段表），对应增一行；docs/05 只写到端点粒度则跳过。 +2. **REQ 卡回填**：在目标卡片的字段/业务说明处补一句该字段（保持卡片与实现一致；若步骤 0 放行时用户已手写，核对即可）。 +3. **不动** docs/02（顺序无变化）、docs/08 §二/§三（无新 REQ / 无新 FE 行——**绝不**新增 FE 行，否则台账多出一个 new 单元、Router 会把它当未完成功能重跑前端）。 + +## 步骤 4：代码直改 + 轻量自检 + +**后端**（`Grep` 表名 / 实体名在 `backend/` 定位，遵循 docs/04-技术规范.md 分层约定）： + +- 实体 / DTO / mapper（或等价 ORM 映射、SQL 列清单）追加字段；既有查询 `SELECT` 若显式列列名则补列；表单提交链路（录入场景）补透传。 +- **不写新端点、不写新 service 方法**——只在既有链路上多带一个字段（越界即停，回落 add-req）。 + +**前端**（`Grep` 页面 / 组件在 `frontend/` 定位，组件选型对齐 docs/04 § 零 `frontend.ui_lib`）： + +- 按步骤 1 的呈现要求追加列表列 / 详情项 / 表单项；文案 / 样式对齐同页面既有字段。 + +**轻量自检（必做，不搭测试 harness）**： + +1. **grep 清单**：新列名（snake）与实体字段名（camel）在以下位置逐一 `Grep` 确认出现——`sql/migrations/V`、`docs/03`、后端实体/DTO/mapper、前端组件；录入场景额外确认提交链路（表单字段 → 请求体）。缺一处即补。 +2. **语法/编译门（若命令轻量）**：docs/04 § 零 有后端编译或前端 lint/类型检查命令（如 `gradle compileJava`、`vue-tsc`、lint script）则各跑一次，红了就修；**不跑**全量测试 / e2e / 冷起栈。 + +## 步骤 5：台账重基线（绝不作废 tag） + +仅当步骤 3 改动了 `docs/01` 卡片（通常会）： + +``` +node ${CLAUDE_PLUGIN_ROOT}/lib/req-ledger.mjs scan +``` + +复核输出：`changed` **仅含**本次目标 REQ 卡、`new`/`removed` 为空（步骤 0 已保证，此处防中途意外）。确认后： + +``` +node ${CLAUDE_PLUGIN_ROOT}/lib/req-ledger.mjs commit +``` + +**本 skill 全程绝不执行任何 `git tag -d`**——req-done / milestone 全部保留，Router 视一切已完成，coding.mjs 不会因本次微改重跑任何模块。这正是 quick-field 与 add-req 的本质区别。 + +## 步骤 6：待验登记 + +`Read` `docs/08-模块任务管理.md`：末尾若无 `## 四、quick-field 待验字段` 小节则追加创建，然后登记一行： + +``` +- [ ]
.（；<展示/录入>）——未过测试门/行为门，待人工点验或随下次正规需求批量验收 +``` + +（该小节位于 §三 之后，`req-ledger` 的 FE 行解析在下一个 `##` 处截断，不影响台账哈希。）验收完成后由人工勾选。 + +## 步骤 7：git 提交 + 完成横幅 + +1. 在**当前分支（默认分支）**提交全部产物： + ``` + git -C add sql/migrations docs/01-需求清单 docs/03-数据库设计文档.md docs/05-API接口契约.md docs/08-模块任务管理.md backend frontend .req-ledger.json + git -C commit -m "feat(quick-field):
. 增列 + 界面呈现（V + docs 同步 + 台账重基线，不重跑 coding）" + ``` +2. `git -C status --porcelain` 复核干净，有残留则排查补提交。 +3. 打印横幅并**停下**： + +``` +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + [quick-field] ✅ 字段微改完成（未重跑 coding） + + 新列：
.（<类型>，V） + 呈现：<页面/组件 + 列表列/详情项/表单项> + 文档：docs/03 已同步（validate-ddl 通过）<；docs/05 已增行 或 —> + 自检：grep 清单 / 通过<；编译/lint 通过 或 —> + 台账：已重基线；req-done/milestone tag 全部保留 + 待验：docs/08 §四 已登记（未过测试门/行为门） + + 新列将在后端下次启动时由 Flyway 自动 apply。起栈后请人工 + 看一眼界面；攒批待验条目可随下次正规需求一并验收后勾销。 + [ERP-HALT] 字段微改完成，已停下。 +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ +``` + +## 参考 + +- `${CLAUDE_PLUGIN_ROOT}/skills/plan/add-req/SKILL.md`（正规增量通道；超界回落目标） +- `${CLAUDE_PLUGIN_ROOT}/lib/req-ledger.mjs`（台账 scan/commit；本 skill 只重基线、不作废 tag） +- `${CLAUDE_PLUGIN_ROOT}/lib/validate-ddl.mjs`（DDL↔docs/03 一致性，MODIFY/DROP 硬拒） +- `docs/03-数据库设计文档.md` + `sql/migrations/V*.sql`（schema SSoT，追加 V_n） +- `docs/04-技术规范.md`（分层落盘 / 组件库 / 编译 lint 命令） +- `CLAUDE.md` Schema 演化规约（匈牙利前缀、默认值翻译、V1 永不改）