95 lines
5.4 KiB
Markdown
95 lines
5.4 KiB
Markdown
# 第 3 轮工作计划（轻量合并版）：审批意见（note）贯穿批准流程
|
||
|
||
更新日期：2026-08-01
|
||
|
||
## 1. 本轮目标
|
||
|
||
让审批人在批准/驳回时填写意见（note），意见随批准记录（approvals）与审批历史事件（history_event）落库，双后端（文件 + 共享 database）一致，并贯通网关与前端展示；矩阵 P3「外部副作用二次确认」剩余项的首个子项（审批意见）完成。
|
||
|
||
## 2. 背景和当前状态
|
||
|
||
- 当前已完成：P3 双人职责分离、角色策略、token 摘要、grant/event 同事务（第 1 轮前）；证据链统一强校验（第 1 轮，425 passed）；契约漂移门禁（第 2 轮，431 passed）。`history_event` 已支持 `note` 参数，但 `decide` 批准路径未透传意见。
|
||
- 当前缺口：`ApprovalStore.decide` / `DatabaseApprovalStore.decide` 的 approvals 记录只有 `{**approver, approvedAt}`，无 note；网关 `ConfirmRequest` 无 note 字段；前端审批历史不展示意见。
|
||
- 本轮为什么现在做：矩阵 P3 剩余验收「审批意见/委托/转派/批量审批」的首项，延续审批域；纯本地可验证。
|
||
- Workspace preflight：第 2 轮收口（431 passed / ruff 干净）；共享脏工作区、无提交。
|
||
- 方向分析：Q1 推荐选项 B（审批能力扩展-意见首切片），目标续跑轮授权执行。
|
||
|
||
## 3. 本轮工作方向
|
||
|
||
```text
|
||
decide 无 note 透传
|
||
-> ApprovalBackend/ApprovalStore/DatabaseApprovalStore.decide 增加 note 参数（approvals + history 落库）
|
||
-> harness.take_confirmation 透传 note；网关 ConfirmRequest.note
|
||
-> 前端 GovConsole 审批历史展示 note；api/types.ts 契约
|
||
-> 黄金测试（文件+DB 双后端 note 落库、历史事件带 note、API 透传）
|
||
-> 矩阵 P3 行注记「审批意见已完成」；CHANGELOG
|
||
```
|
||
|
||
## 4. 已确认决策
|
||
|
||
任务重量：
|
||
- 档位：轻型（单模块域：approval_store/approval_db_store/harness/gateway + 前端类型 + 测试）。
|
||
- 规模依据：改动集中在双后端 `decide` 签名（向后兼容默认 None）、harness 透传、网关字段、前端类型；风险 LOW（impact 分析：decide/take_confirmation 无直接索引调用者）。
|
||
- 选择原因：延续审批域、本地可验证、向后兼容。
|
||
|
||
P0/P1 决策（按 Q1 推荐采纳）：
|
||
- 决策 1（P0）：本轮切片 = 审批意见 note 贯穿批准流程（选项 B 首项）。
|
||
- 决策 2（P1）：不新建分支、不提交、不推送（沿用共享脏工作区约束）。
|
||
- 决策 3（P1）：验证深度 = 双后端聚焦测试 + 全量黄金回归。
|
||
|
||
默认假设：
|
||
- 假设 1：note 为可选字符串，批准与驳回均可携带；驳回路径也落库到历史事件。
|
||
- 假设 2：note 不进入 paramsHash（params 不变），只进 approvals/history，避免改变既有审批语义。
|
||
- 假设 3：前端展示为「审批历史」新增列/描述，不强制弹窗输入（保留向后兼容）。
|
||
|
||
未决但不阻塞：委托/转派/批量审批、文件→DB 存量迁移、WORM 归档（后续轮）；MySQL 实机故障注入（外部环境）。
|
||
|
||
## 5. 范围
|
||
|
||
In scope:
|
||
- `server/agent_core/approval_store.py`：`ApprovalBackend.decide` 与 `ApprovalStore.decide` 增加 `note: str | None = None`；approvals 记录 `{"note": note}` 当 note 非空；驳回/批准 history_event 透传 note。
|
||
- `server/agent_core/approval_db_store.py`：`DatabaseApprovalStore.decide` 同样处理（payload 存 note）。
|
||
- `server/agent_core/harness.py`：`take_confirmation` 增加 `note` 参数透传。
|
||
- `server/gateway/app.py`：`ConfirmRequest` 增加 `note` 字段；confirm 端点透传。
|
||
- `apps/web/src/api/types.ts`：`ApprovalDecision` 增加 `note?: string`。
|
||
- `apps/web/src/gov/GovConsole.tsx`：审批历史展示 note（若已有 history 渲染处）。
|
||
- `tests/golden/test_approval_store.py`、`test_approval_database_store.py`、`test_harness_p3.py`：新增 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_approval_store.py tests/golden/test_approval_database_store.py tests/golden/test_harness_p3.py -p no:cacheprovider` 全部通过。
|
||
- 全量：`python -m pytest tests/golden -q -p no:cacheprovider`（固定 .venv 运行时）≥ 431。
|
||
- ruff 改动文件干净；git diff --check 无空白错误。
|
||
|
||
## 7. 验证方式
|
||
|
||
- 双后端 note 落库断言（文件+DB）；API 透传断言；前端类型引用编译。
|
||
- 全量黄金套件回归。
|
||
|
||
## 8. 关键风险
|
||
|
||
| 风险 | 影响 | 控制方式 |
|
||
|---|---|---|
|
||
| decide 签名变更破坏调用方 | 回归 | 默认 None 向后兼容；聚焦 + 全量回归 |
|
||
| DB 后端 payload 存储字段漂移 | note 丢 | payload 为整条 record JSON，新增 key 自然往返 |
|
||
| 前端类型不匹配 | 编译失败 | 同步 types.ts + GovConsole 渲染 |
|
||
|
||
## 9. 停止条件
|
||
|
||
- 全量黄金测试非本轮相关回归无法快速定位时暂停。
|
||
- 任何提交/推送/合并/清理操作停下等待授权。
|
||
|
||
## 10. 本轮完成定义
|
||
|
||
- 实现、测试、文档完成；聚焦与全量通过；矩阵/CHANGELOG 回写；不提交。
|
||
- 收口：报告主要结论、关键洞察、需要特别留意的地方。
|
||
|
||
## 11. 下一步
|
||
|
||
轻量合并版：主 agent 实现 + 验证 + 收口报告。
|