ai-customer-service/docs/REMEDIATION_TASK_BOARD_2026-05-06.md

# ai-customer-service 整改任务板（基于 2026-05-06 最新 review）

> 生成时间：2026-05-06  
> 代码基线：`ee3a31e`  
> 目标：把本轮 review 结论转成可执行整改任务，而不是停留在结论层。  
> 当前总状态：**代码级门禁通过；sub2api 单平台主链通过但带风险；newapi 平台能力未通过；真实预生产 / 生产放行门禁未通过。**

---

## 0. 使用规则

- 状态仅允许：`未开始 / 进行中 / 已完成 / 已阻塞`
- 每项必须包含：责任角色、交付物、完成判据、验证方式、阻塞依赖
- 任何“已完成”必须附文件证据或命令证据
- 任务按四段拆分：`设计 / 实现 / 验证 / 放行证据`
- 未完成设计段，不得直接跳实现
- 未完成验证段，不得更新为“可放行”
- 未完成放行证据段，不得对外给出“预生产通过 / 可灰度 / 可上线”口径

---

## 1. 当前阶段门控结论

### 1.1 代码级门禁
- 结论：**PARTIAL / 不稳定**
- 依据：`go build ./...`、`go vet ./...` 当前通过；但本轮再次实测 `go test ./... -count=1` 失败，失败用例为 `test/e2e/sub2api_callback_flow_test.go:186`，实际 `event[0].type = reply.generated`，预期 `message.received`，并伴随 `sql: database is closed`

### 1.2 sub2api 单平台主链
- 结论：**PASS WITH RISKS / E2E 当前不稳定**
- 已验证链路：webhook → dialog → outbox → callback worker
- 仍有风险：严格事务外盒不成立、并发 claim 缺失、callback_target 语义未落地、E2E 已再次复现顺序异常与 `sql: database is closed`

### 1.3 newapi 平台能力
- 结论：**FAIL**
- 直接证据：
  - `internal/platformadapter/newapi_adapter.go:20-21` 仍直接返回 `501 not implemented`
  - `internal/app/app.go:129-130` 仍允许注册 `newapi` adapter
  - `internal/app/app.go:186-187` 仍允许启动 `newapi` callback worker

### 1.4 真实预生产 / 生产放行
- 结论：**FAIL**
- 依据：`test/QA_GATE_STATUS.md`、`prd/PRODUCTION_CHECKLIST.md` 仍明确：代码级通过，但真实共享预生产 Gate B 与生产 Gate C 未闭环

---

## 2. 整改总览（按 gap taxonomy）

| Gap Type | 当前问题 | 优先级 | 默认责任角色 |
|---|---|---|---|
| design_gap | 平台启用状态与真实可用能力未统一建模 | P1 | TechLead |
| implementation_gap | newapi 入口未实现但可装配；callback_target 运行时未消费 | P1 | Engineer |
| test_gap | newapi 无对等正向链路测试；sub2api callback 稳定性回归不足 | P1 | QA / Engineer |
| evidence_gap | 真实共享预生产 / 灰度环境证据未闭环 | P0 | QA / DevOps |
| call_chain_gap | newapi 对外看似支持，真实入口未接通 | P1 | TechLead / Engineer |
| contract_gap | event.CallbackTarget 字段语义与 worker 实际行为不一致 | P1 | TechLead |

---

## 3. 设计段任务（先收口设计与口径）

| ID | 优先级 | 任务 | 责任角色 | 交付物 | 完成判据 | 验证方式 | 依赖 | 状态 |
|---|---|---|---|---|---|---|---|---|
| D-01 | P1 | 收口平台能力矩阵，明确 `sub2api`/`newapi` 的真实支持级别 | TechLead | 平台能力设计说明 | 明确区分：已生产可用 / 占位未实现 / 禁止启用 | 设计文档包含平台能力表、入口/出口/测试覆盖状态 | 无 | 未开始 |
| D-02 | P1 | 定义“平台启用”与“平台真实可用”统一门控规则 | TechLead | 装配门控设计 | 明确哪些条件满足后才允许注册 adapter / 启动 worker | 文档中给出代码落点与判定规则 | D-01 | 未开始 |
| D-03 | P1 | 定义 `callback_target` 的正式契约：删除伪能力或落地多目标路由 | TechLead | 契约设计说明 | 不能再存在“模型字段存在但运行时完全不消费”的状态 | 文档中明确 event model、worker 路由、回调配置关系 | 无 | 未开始 |
| D-04 | P1 | 设计 outbox 并发 claim / 多实例投递策略 | TechLead | 并发与重试设计 | 至少明确单实例约束，或设计 `claim/skip locked` 方案 | 设计文档中有状态流转与失败恢复说明 | 无 | 未开始 |
| D-05 | P0 | 更新项目对外发布口径：只允许宣称“sub2api 代码级可用”，禁止宣称“多平台已完成 / 生产可上线” | PM | 更新后的发布/状态文档口径 | 相关文档不再出现失真口径 | 复核文档章节与结论语句 | 无 | 未开始 |

---

## 4. 实现段任务（把设计缺口落到代码）

| ID | 优先级 | 任务 | 责任角色 | 交付物 | 完成判据 | 验证方式 | 依赖 | 状态 |
|---|---|---|---|---|---|---|---|---|
| I-01 | P1 | 处理 newapi 假接通：二选一——禁用装配，或补完整 ingress 实现 | Engineer | 代码修改 + 测试 | 不能再出现“入口未实现但仍可注册/启动 worker” | `go test ./... -count=1`；读取关键文件确认分支收口 | D-01, D-02 | 未开始 |
| I-02 | P1 | 让 worker 与平台能力门控一致，不允许未实现平台独立启动 callback worker | Engineer | 代码修改 + 测试 | worker 启动条件与平台真实能力一致 | 读取 `internal/app/app.go` 关键分支；相关测试通过 | D-02 | 未开始 |
| I-03 | P1 | 处理 `callback_target` 契约漂移：删除字段伪能力或在 worker 中真正消费 | Engineer | 代码修改 + 测试 | 数据模型与运行时行为一致 | 读取 builder / event / worker；定向测试通过 | D-03 | 未开始 |
| I-04 | P1 | 补 outbox 并发 claim 机制或显式限制单实例语义并固化到代码/文档 | Engineer | 代码或明确限制说明 | 不再处于“默认可多实例、实际会重复投递”的灰区 | 代码/文档与测试或注释证据一致 | D-04 | 未开始 |
| I-05 | P2 | 评估并落地更严格 transactional outbox 方案，或明确记录当前非强一致边界 | TechLead / Engineer | 设计决策记录 + 代码/文档 | 团队对一致性边界有明确基线 | 决策文档 + 相关代码/文档证据 | D-04 | 未开始 |

---

## 5. 验证段任务（不是“改完就算完成”）

| ID | 优先级 | 任务 | 责任角色 | 交付物 | 完成判据 | 验证方式 | 依赖 | 状态 |
|---|---|---|---|---|---|---|---|---|
| V-01 | P1 | 为 newapi 增加对等验证：若实现则补 integration/e2e；若禁用则补门控测试 | QA / Engineer | 测试代码 + 验证记录 | newapi 状态与测试口径一致，不再空缺 | `go test ./test/integration ./test/e2e -count=1` 或对应定向用例 | I-01, I-02 | 未开始 |
| V-02 | P1 | 对 sub2api callback 链路做多轮稳定性复跑，专查事件顺序和 DB 关闭时机脆弱性 | QA | 稳定性复跑记录 | 至少形成重复执行证据，并记录是否复现 `reply.generated`/`message.processing` 顺序异常与 `database is closed` 类问题 | 定向多轮 `go test` 记录 | 无 | 未开始 |
| V-03 | P1 | 对 outbox 并发 / 重试 / dead-letter 行为补定向验证 | QA / Engineer | 测试与验证报告 | claim/重试/死信路径与设计一致 | 定向测试命令 + 输出 | I-03, I-04 | 未开始 |
| V-04 | P1 | 回收旧 review 漂移：更新/替代 `CODE_REVIEW_REPORT.md` 等过期结论 | QA / PM | 新旧报告差异说明 | 不再让过期 P0/P1 结论继续作为现状依据 | 文档 diff + QA 复核 | D-05 | 未开始 |

---

## 6. 放行证据段任务（真实环境，不是仓库内自嗨）

| ID | 优先级 | 任务 | 责任角色 | 交付物 | 完成判据 | 验证方式 | 依赖 | 状态 |
|---|---|---|---|---|---|---|---|---|
| E-01 | P0 | 在共享预生产环境复跑 Gate B 并留痕 | QA / DevOps | 预生产验证记录 | 启动、DB、migration、webhook、ticket、audit、ready 全链路留痕 | 复跑脚本与记录文件 | 无 | 未开始 |
| E-02 | P0 | 在共享预生产 / 灰度环境完成监控接线与回滚演练留痕 | DevOps / QA | 监控与回滚证据 | 不再只有本地/容器化演练记录 | 真实环境演练记录、告警/仪表盘证据 | E-01 | 未开始 |
| E-03 | P1 | 形成“平台能力 + 环境门禁”统一放行页 | XL / PM / QA | 放行基线文档 | 明确平台支持边界、代码级门禁、预生产门禁、生产门禁 | 文档校验无失真口径 | D-05, E-01, E-02 | 未开始 |

---

## 7. 最短闭环执行顺序

### 7.1 当前最短关键路径
1. V-02 先定位并修复 `sub2api` callback E2E 不稳定失败，恢复 `go test ./...` 稳定通过能力
2. D-01 收口平台能力矩阵
3. D-02 收口平台启用 / worker 启动门控
4. I-01 处理 newapi 假接通
5. I-02 同步 worker 启动逻辑
6. V-01 补 newapi 对等验证
7. E-01 共享预生产 Gate B 留痕
8. E-02 共享预生产 / 灰度环境运行证据留痕
9. E-03 更新统一放行页

### 7.2 原则
- 若目标是先消除“能力口径失真”，优先做 D-01/D-02/I-01/I-02/V-01
- 若目标是先冲放行证据，仍不能跳过平台能力收口；否则会带着失真口径进入预生产

---

## 8. 明确禁止的错误结论

在以下任务完成前，禁止出现这些说法：

- “多平台接入已经完成”
- “newapi 已支持，只差联调”
- “当前整体生产可上线”
- “预生产 / 灰度已通过”
- “callback_target 已支持多目标回调”
- “平台回调 outbox 已具备多实例生产级可靠性”

---

## 9. 当前最小可接受对外口径

1. 代码级门禁：通过
2. sub2api 单平台主链：通过，但带重要风险
3. newapi：未通过，不应按已接入汇报
4. 真实预生产 Gate B：未通过
5. 生产灰度 Gate C：未通过

---

## 10. 任务板维护要求

- 每完成一项，必须同步：状态、证据、对应文档
- 任何“已完成”若无命令输出或文件证据，视为无效
- 若验证失败，必须把失败现象写回对应任务，不允许口头跳过
- 小龙负责最终事实校准，不接受“看起来差不多”