朱子纯 / erp-workflow-plugin

SKILL.md 10.6 KB

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 永不改）