PMFlow/docs/INBOX_INLINE_OPS_3_PHASE_CHECKLIST.md

Inbox 消息台内联操作（三期执行清单）

目标：用户在消息台完成待处理动作，尽量不跳转；实现过程中不绕开现有 AI PMO 状态机闭环。

Phase 1（先落地，最小闭环）

范围

• 前端内联处理 missing_project_scope 卡片。
• 后端只做字段投影增强，不新增执行链路接口。

后端 Checklist

• GET /ai-pmo/work-items 增加可直接渲染字段：
  • latest_policy_gate_code
  • approval_requirement（至少含 required/reason/message）
• 字段来源明确为“最近一条 decision_records 投影”，禁止前端猜文案。
• 保持现有 POST /ai-pmo/work-items/{id}/decision 语义不变。

前端 Checklist

• 消息台卡片识别条件：
  • state=waiting_manual
  • latest_policy_gate_code=missing_project_scope
• 内联面板显示“项目下拉 + 确认关联”。
• 项目下拉数据源使用 GET /projects?status=active。
• 点击确认后调用：
  • POST /ai-pmo/work-items/{id}/decision
  • body: { action: "approve", project_id }
• 成功后刷新消息台并显示 followup 回执文案。

验收

• 缺项目归属卡片可在消息台直接补项目并继续执行。
• 不新增 resolve-project 接口。
• 不直连 TypedExecutor。

---

Phase 2（扩展内联动作，不破坏闭环）

范围

• 支持更多 waiting_manual 场景统一内联处理。
• 负载预警改为复用现有 workload 接口。

后端 Checklist

• GET /ai-pmo/work-items 继续补充前端所需稳定字段（如 intent、execution_result 关键子字段）。
• 若需负责人相关动作，先定义 owner 写入目标（task/registry/work_item），再补接口，不先拍脑袋加 assign-owner。

前端 Checklist

• 通用 waiting_manual 面板（非 missing_project_scope）支持：
  • 继续执行
  • 标记失效
  • 查看详情
• 负载预警卡片实现方式：
  • 预览建议：POST /workloads/ai-optimize
  • 应用建议：POST /workloads/ai-optimize/apply
• 禁止依赖不存在接口：GET /workloads/suggestions。

验收

• 负载预警可在消息台触发建议预览与应用。
• 所有动作仍通过既有审计/回执链路。

---

Phase 3（信号源治理与增强）

范围

• 信号源相关内联治理动作补齐（编辑/删除/确认信息）。
• 明确通用信号源 API 边界后再接入消息台按钮。

后端 Checklist

• 先梳理“通用信号源 CRUD”真实接口归属（当前 /signal-sources 为食谱 webhook，不可直接复用）。
• 若缺通用接口，按规范新增并补测试。
• 补充操作审计（operation logs）与幂等约束。

前端 Checklist

• 基于真实通用接口接入：
  • 编辑信号源
  • 删除信号源（确认弹窗）
• 不在 InboxPage 内直接写 fetch，统一走 frontend/src/api/。

验收

• 消息台信号源治理动作可用，且接口与模型一致。
• 审计可追踪，状态可回放。

---

统一守则（每期都要过）

• 不新增绕开 ai_pmo 闭环的执行入口。
• 不做“前端猜测字符串”分支判断，优先消费稳定结构字段。
• 变更后跑通：
  • npm run build
  • tsc --noEmit
  • 相关后端测试（新增接口时必须补测）

回填记录（2026-03-12）

• Phase 1 状态：已完成并通过验证。
• 后端验证：
  • ../venv/bin/python -m pytest -q tests/test_ai_pmo_work_item_decision_api.py → 3 passed
  • ../venv/bin/python -m py_compile app/api/ai_pmo.py → 通过
• 前端验证：
  • npm run build → 通过
  • npx tsc --noEmit → 通过
• 热修（2026-03-12 同日）：
  • POST /ai-pmo/work-items/{id}/decision 在 waiting_manual + project_id 场景改为“快速返回 + 后台续跑”，避免消息台按钮长期卡在“处理中...”
  • POST /ai-pmo/work-items/{id}/decision 在上述场景会先把目标 work item 状态置为 executing（前端即时从“待处理”转为“处理中”）
  • 前端 decideWorkItem 增加 15s 超时保护，超时会回到可交互状态并提示错误
  • 口水话（短 query，如“怎么样了/在吗/辛苦了”）在后端列表接口过滤，不再下发到消息台前端（数据仍保留在后端记录）
  • 修复信号源续跑事务穿透：signal_source_registries 重复键分支改为 savepoint，且 OpenClaw 指挥链改为隔离 Session，避免 rollback 回滚外层新建 signal，彻底消除 ai_orchestration_runs.signal_id 外键报错
  • 修复“续跑后仍停在待人工确认”：signal_source.onboard 在 pending_manual/signal_source_pending_manual 且已具备 project_id+signal_id 时强制落 succeeded，并记录 manual_gate_resolved=true
• Phase 2/3：未开始，保持待办。

本清单对应文件范围（执行时参考）

• frontend/src/pages/InboxPage.tsx
• frontend/src/components/inbox/
• frontend/src/lib/inbox.ts
• frontend/src/types/inbox.ts
• frontend/src/api/aiPmo.ts
• frontend/src/api/projects.ts
• frontend/src/api/workloads.ts
• backend/app/api/ai_pmo.py