---
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` 或人工方案）：改列类型、字段带联动校验、需要新查询接口、需要迁移回填存量数据、新页面。**纯前端小交互**（不涉 schema）→ 走姊妹通道 `/erp-workflow:quick-ui`。

## 步骤 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 / quick-ui）` 小节则追加创建，然后登记一行：

```
- [ ] <YYYY-MM-DD> <table>.<column>（<REQ-id>；quick-field <展示/录入>）——未过测试门/行为门，待人工点验或随下次正规需求批量验收
```

（该小节位于 §三 之后，`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 永不改）