# 第 4 轮工作计划（轻量合并版）：批量审批（confirm-batch）

更新日期：2026-08-01

## 1. 本轮目标

新增批量审批能力：一条请求处理多条待审批确认卡（同一批准/驳回决定 + 每条可带意见），复用现有 P2/P3 单条 confirm 的完整语义（证据校验、双人分离、执行/驳回、审计），前端门禁管理台待审批列表支持多选批量操作；矩阵 P3「外部副作用二次确认」剩余项之一完成。

## 2. 背景和当前状态

- 当前已完成：单条 confirm 链路完整（P2 一次放行、P3 双人、证据链强校验、审批意见 note 落库）；GovConsole 有 PendingView（单条批准/驳回）+ ApprovalHistoryView。
- 当前缺口：待审批列表只能逐条操作；无批量入口；后端无聚合批量端点。
- 本轮为什么现在做：矩阵 P3 剩余「批量审批」；本地可完整验证（双后端单条语义已被第 3 轮覆盖，批量是编排层）。
- Workspace preflight：第 3 轮收口（435 passed）；服务 8003/5173 正常；共享脏工作区、无提交。
- 方向分析：Q1 推荐选项 A（批量审批），目标续跑轮授权执行。

## 3. 本轮工作方向

```text
单条 confirm
-> POST /api/actions/confirm-batch { confirmIds, approve, note? }（逐条走 execute_confirmed，聚合结果）
-> 前端 PendingView 多选 + 批量按钮（复用 postConfirm 语义）
-> 黄金测试：批量批准 P2 多条、批量含 P3 需二次确认、批量驳回、逐条隔离失败
-> 矩阵 P3 注记「批量审批已完成」；CHANGELOG
```

## 4. 已确认决策

任务重量：
- 档位：轻型（单域：gateway 端点 + GovConsole 前端 + 黄金测试）。
- 规模依据：核心是编排层（循环复用现有语义），不新增双后端状态机；风险 LOW。
- 选择原因：最小且独立的 P0 剩余项，可完整本地验证。

P0/P1 决策（按 Q1 推荐采纳）：
- 决策 1（P0）：本轮切片 = 批量审批（选项 A）。
- 决策 2（P1）：不新建分支、不提交、不推送。
- 决策 3（P1）：验证深度 = 聚焦批量端点测试 + 全量黄金回归。

默认假设：
- 假设 1：批量 = 同一 approve 决定应用于多条 confirmId；note 为公共意见（逐条落库）。
- 假设 2：逐条执行并聚合；单条失败不阻断其余（逐条隔离），响应含每条结果与失败原因。
- 假设 3：P3 首次批准（needsSecondConfirm）在批量结果中标记 secondConfirmRequired，不视为失败。
- 假设 4：批量仅限当前用户可审批的作用域（复用 allowed 谓词，天然隔离）。

未决但不阻塞：委托/转派审批、文件→DB 存量迁移、WORM 归档（后续轮）。

## 5. 范围

In scope:
- `server/gateway/app.py`：`ConfirmBatchRequest`（confirmIds: list[str]、approve: bool、note?: str）+ `POST /api/actions/confirm-batch`，逐条调用 `execute_confirmed`，聚合 `{results: [{confirmId, ok, message, secondConfirmRequired}]}`。
- `apps/web/src/api/client.ts`：`postConfirmBatch(sessionId, confirmIds, approve, note?)`。
- `apps/web/src/gov/GovConsole.tsx`：PendingView 多选（Checkbox）+ 批量批准/驳回按钮。
- `tests/golden/test_gov_api.py` 或新增 `test_confirm_batch.py`：批量 P2 通过、批量含 P3 二次确认、批量驳回、单条失败隔离、note 落库。
- 文档：`docs/architecture/harness.md`、`docs/product/plan-completion-matrix.md`（P3 注记）、`docs/CHANGELOG.md`。

Out of scope:
- 委托/转派、文件→DB 迁移、WORM、MySQL 实机故障注入。
- 提交/推送/合并/清理用户改动。

## 6. 成功标准

- 聚焦：`python -m pytest -q tests/golden/test_confirm_batch.py tests/golden/test_gov_api.py -p no:cacheprovider` 通过。
- 全量：`python -m pytest tests/golden -q -p no:cacheprovider`（固定 .venv）≥ 435。
- ruff 干净；前端 tsc 通过；git diff --check 无空白错误。

## 7. 验证方式

- 批量端点 API 测试（TestClient + install_test_auth）；前端 tsc；全量黄金回归。

## 8. 关键风险

| 风险 | 影响 | 控制方式 |
|---|---|---|
| 批量逐条执行中断言耦合 | 部分失败语义不清 | 每条独立 try/except，聚合结果含 ok/message |
| P3 二次确认在批量中误判失败 | 语义错误 | secondConfirmRequired 单独标记 |
| 前端多选交互回归 | 编译/交互问题 | tsc + 复用既有 decide 逻辑 |

## 9. 停止条件

- 全量黄金测试非本轮相关回归无法快速定位时暂停。
- 任何提交/推送/合并/清理操作停下等待授权。

## 10. 本轮完成定义

- 实现、测试、文档完成；聚焦与全量通过；矩阵/CHANGELOG 回写；不提交。
- 收口：报告主要结论、关键洞察、需要特别留意的地方。

## 11. 下一步

轻量合并版：主 agent 实现 + 验证 + 收口报告。