新增 quick-field：字段微改快速通道（加列+界面呈现，不重跑 coding）

保 schema SSoT 不缩水（V_n ALTER + docs/03 同步 + validate-ddl fail-closed），代码主会话直改 + grep 清单/轻量编译自检；台账 req-ledger 重基线但绝不作废 req-done/milestone tag——Router 视一切已完成，不冷起栈、不跑测试门/行为门。未过行为验收的字段登记 docs/08 §四待验清单，攒批人工勾销。硬护栏：仅追加式 ADD COLUMN（可空/带 DEFAULT）+ 既有链路多带一个字段，超界回落 /add-req；步骤 0 要求台账干净（防全量重基线吞掉其他待处理增量）；禁手动灌库（源库 Flyway 托管，绕 history 会重复 apply 报错）。同步：plugin.json 注册（9→10 skill）、README 目录树/入口表、add-req 顶部分流提示。 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

新增 quick-field：字段微改快速通道（加列+界面呈现，不重跑 coding）
保 schema SSoT 不缩水（V_n ALTER + docs/03 同步 + validate-ddl fail-closed），代码主会话直改 + grep 清单/轻量编译自检；台账 req-ledger 重基线但绝不作废 req-done/milestone tag——Router 视一切已完成，不冷起栈、不跑测试门/行为门。未过行为验收的字段登记 docs/08 §四待验清单，攒批人工勾销。硬护栏：仅追加式 ADD COLUMN（可空/带 DEFAULT）+ 既有链路多带一个字段，超界回落 /add-req；步骤 0 要求台账干净（防全量重基线吞掉其他待处理增量）；禁手动灌库（源库 Flyway 托管，绕 history 会重复 apply 报错）。同步：plugin.json 注册（9→10 skill）、README 目录树/入口表、add-req 顶部分流提示。 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
yanghl
1 parent 56c4d891
Showing 4 changed files with 165 additions and 6 deletions
.claude-plugin/plugin.json
README.md
skills/plan/add-req/SKILL.md
skills/plan/quick-field/SKILL.md
 {
   "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"
   ]
 }
@@ -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 个）
@@ -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。
 `<root>` = 项目根（含 `docs/`、`config-vars.yaml`、`sql/`、`.git`）。`${CLAUDE_PLUGIN_ROOT}` = 插件根。
+---
+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 会登记待验条目，攒批后人工或随下次正规需求一并验收。
+
+`<root>` = 项目根（含 `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/<id>` 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 <root> status --porcelain` 必须为空——本 skill 末尾整体提交，脏树会混入无关改动。不干净 → 停下提示先处理。
+4. **台账干净（关键）**：
+   ```
+   node ${CLAUDE_PLUGIN_ROOT}/lib/req-ledger.mjs scan <root>
+   ```
+   - `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<n+1>__add_<table>_<column>.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<n+1>`、`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 <root>
+```
+
+复核输出：`changed` **仅含**本次目标 REQ 卡、`new`/`removed` 为空（步骤 0 已保证，此处防中途意外）。确认后：
+
+```
+node ${CLAUDE_PLUGIN_ROOT}/lib/req-ledger.mjs commit <root>
+```
+
+**本 skill 全程绝不执行任何 `git tag -d`**——req-done / milestone 全部保留，Router 视一切已完成，coding.mjs 不会因本次微改重跑任何模块。这正是 quick-field 与 add-req 的本质区别。
+
+## 步骤 6：待验登记
+
+`Read` `docs/08-模块任务管理.md`：末尾若无 `## 四、quick-field 待验字段` 小节则追加创建，然后登记一行：
+
+```
+- [ ] <YYYY-MM-DD> <table>.<column>（<REQ-id>；<展示/录入>）——未过测试门/行为门，待人工点验或随下次正规需求批量验收
+```
+
+（该小节位于 §三 之后，`req-ledger` 的 FE 行解析在下一个 `##` 处截断，不影响台账哈希。）验收完成后由人工勾选。
+
+## 步骤 7：git 提交 + 完成横幅
+
+1. 在**当前分支（默认分支）**提交全部产物：
+   ```
+   git -C <root> add sql/migrations docs/01-需求清单 docs/03-数据库设计文档.md docs/05-API接口契约.md docs/08-模块任务管理.md backend frontend .req-ledger.json
+   git -C <root> commit -m "feat(quick-field): <table>.<column> 增列 + 界面呈现（V<n+1> + docs 同步 + 台账重基线，不重跑 coding）"
+   ```
+2. `git -C <root> status --porcelain` 复核干净，有残留则排查补提交。
+3. 打印横幅并**停下**：
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ [quick-field] ✅ 字段微改完成（未重跑 coding）
+
+   新列：<table>.<column>（<类型>，V<n+1>）
+   呈现：<页面/组件 + 列表列/详情项/表单项>
+   文档：docs/03 已同步（validate-ddl 通过）<；docs/05 已增行 或 —>
+   自检：grep 清单 <N>/<N> 通过<；编译/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 永不改）