93 lines
4.7 KiB
Markdown
93 lines
4.7 KiB
Markdown
# 第 12 轮工作计划（轻量合并版）：审批转派（transfer）
|
||
|
||
更新日期：2026-08-01
|
||
|
||
## 1. 本轮目标
|
||
|
||
新增审批转派：当前可审批者可将待确认项转派给指定用户（`transfer`），转派后仅目标用户可审批；双后端（文件/DB）支持并记录 TRANSFERRED 历史事件；矩阵 P3「外部副作用二次确认」剩余项之一（转派审批）完成。
|
||
|
||
## 2. 背景和当前状态
|
||
|
||
- 当前已完成：审批委托（delegation，第 10 轮）、审批意见、批量审批；`ApprovalBackend` 协议含 stage/decide/pending_record/consume_grant 等。
|
||
- 当前缺口：无转派能力——待确认项只能 owner/delegate 操作，无法移交给他人；`ApprovalBackend` 无 transfer 方法。
|
||
- 本轮为什么现在做：矩阵 P3 剩余「委托/转派审批」的转派部分；纯本地可验证。
|
||
- Workspace preflight：第 11 轮收口（474 passed）；服务 8003/5173 正常；共享脏工作区、无提交。
|
||
- 方向分析：Q1 推荐（审批转派），目标续跑轮授权执行。
|
||
|
||
## 3. 本轮工作方向
|
||
|
||
```text
|
||
待确认项只能 owner/delegate 操作
|
||
-> ApprovalBackend.transfer(confirm_id, to_user_id, allowed, now_epoch)（文件+DB）
|
||
-> harness.transfer_confirmation(confirm_id, to_user_id)：当前可审批者转移，转派后仅目标可审批
|
||
-> 历史事件 TRANSFERRED；网关 POST /api/actions/transfer
|
||
-> 黄金测试：owner 可转派、非 owner 拒绝、转派后目标可审批原 owner 不能、双后端持久化
|
||
-> 矩阵 P3 注记「转派已完成」；CHANGELOG
|
||
```
|
||
|
||
## 4. 已确认决策
|
||
|
||
任务重量：
|
||
- 档位：轻型（ApprovalBackend + 双后端 + harness + 网关 + 测试）。
|
||
- 规模依据：新增一个 transfer 方法（文件/DB 各一）+ harness 封装 + 端点；沿用 decide 的 CAS/事务模式；风险 LOW。
|
||
- 选择原因：P3 剩余项中委托之后的自然增量。
|
||
|
||
P0/P1 决策（按 Q1 推荐采纳）：
|
||
- 决策 1（P0）：本轮切片 = 审批转派（transfer）。
|
||
- 决策 2（P1）：不新建分支、不提交、不推送。
|
||
- 决策 3（P1）：验证深度 = 聚焦转派测试 + 全量黄金回归。
|
||
|
||
默认假设：
|
||
- 假设 1：转派仅 P2 单重审批（P3 需双人分离，转派改变 owner 会破坏 SOD 语义，故 P3 拒绝转派）。
|
||
- 假设 2：转派后 `ownerUserId = 目标用户`（原 owner/delegate 不再可审批）；历史事件 status=TRANSFERRED 记录 from/to。
|
||
- 假设 3：仅当前可审批者（owner 或被委托人）可发起转派；角色策略仍校验。
|
||
- 假设 4：`transfer` 返回新 pending 或 None（失败）；DB 后端沿用 CAS 重试。
|
||
|
||
未决但不阻塞：批量转派、委托撤销、转派审计 UI 展示（后续轮）。
|
||
|
||
## 5. 范围
|
||
|
||
In scope:
|
||
- `server/agent_core/approval_store.py`：`ApprovalBackend.transfer()` 协议 + `ApprovalStore.transfer()`（文件）。
|
||
- `server/agent_core/approval_db_store.py`：`DatabaseApprovalStore.transfer()`（DB，CAS）。
|
||
- `server/agent_core/harness.py`：`transfer_confirmation(confirm_id, to_user_id)`（校验当前身份可审批 + P2 判定）。
|
||
- `server/gateway/app.py`：`TransferRequest` + `POST /api/actions/transfer`。
|
||
- `tests/golden/test_approval_transfer.py`（新）：owner 转派、非 owner 拒绝、P3 拒绝、转派后目标可批原 owner 不能、DB 持久化。
|
||
- 文档：`docs/architecture/harness.md`、`docs/product/plan-completion-matrix.md`（P3 注记）、`docs/CHANGELOG.md`。
|
||
|
||
Out of scope:
|
||
- 批量转派、委托撤销、转派 UI 展示、MySQL 实机故障注入。
|
||
- 提交/推送/合并/清理用户改动。
|
||
|
||
## 6. 成功标准
|
||
|
||
- 聚焦：`python -m pytest -q tests/golden/test_approval_transfer.py tests/golden/test_approval_store.py tests/golden/test_harness_p3.py -p no:cacheprovider` 通过。
|
||
- 全量：`python -m pytest tests/golden -q -p no:cacheprovider`（固定 .venv）≥ 474。
|
||
- ruff 干净；git diff --check 无空白错误。
|
||
|
||
## 7. 验证方式
|
||
|
||
- 转派单测（owner/非 owner/P3/转派后作用域/DB）；全量回归。
|
||
|
||
## 8. 关键风险
|
||
|
||
| 风险 | 影响 | 控制方式 |
|
||
|---|---|---|
|
||
| 转派破坏 P3 SOD | 安全回归 | P3 显式拒绝转派 |
|
||
| 转派后作用域不清 | 越权/锁死 | 转派后 owner=目标；测试锁定 |
|
||
| DB CAS 不一致 | 竞态 | 沿用 decide 的 CAS 重试模式 |
|
||
|
||
## 9. 停止条件
|
||
|
||
- 全量黄金测试非本轮相关回归无法快速定位时暂停。
|
||
- 任何提交/推送/合并/清理操作停下等待授权。
|
||
|
||
## 10. 本轮完成定义
|
||
|
||
- 实现、测试、文档完成；聚焦与全量通过；矩阵/CHANGELOG 回写；不提交。
|
||
- 收口：报告主要结论、关键洞察、需要特别留意的地方。
|
||
|
||
## 11. 下一步
|
||
|
||
轻量合并版：主 agent 实现 + 验证 + 收口报告。
|