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

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

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

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

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

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

### 验收
- [x] 缺项目归属卡片可在消息台直接补项目并继续执行。
- [x] 不新增 `resolve-project` 接口。
- [x] 不直连 `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/`。

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

---

## 统一守则（每期都要过）

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

## 回填记录（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，且 PMFlow 本地路由层 指挥链改为隔离 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`