5.4 KiB

Raw Blame History

第 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. 本轮工作方向

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 实现 + 验证 + 收口报告。

5.4 KiB Raw Blame History Unescape Escape