291 lines
12 KiB
Markdown
291 lines
12 KiB
Markdown
# ai-customer-service 最新审查报告（2026-05-06）
|
||
|
||
> 审查时间：2026-05-06
|
||
> 代码基线：`ee3a31e77c00d47802e7b3a54057467b3a713400`
|
||
> 审查方式：小龙主审 + 双视角 QA 复核 + 现有门禁文档对照
|
||
> 目标：给出当前代码与放行状态的真实结论，回收过期结论，并把问题转成可执行整改基线。
|
||
> 配套任务板：`docs/REMEDIATION_TASK_BOARD_2026-05-06.md`
|
||
|
||
---
|
||
|
||
## 0. 阶段门控结论
|
||
|
||
### 总结论
|
||
- **代码级门禁：PARTIAL / 不稳定**
|
||
- **sub2api 单平台主链：PASS WITH RISKS**
|
||
- **newapi 平台能力：FAIL**
|
||
- **真实共享预生产 Gate B：FAIL**
|
||
- **生产灰度 Gate C：FAIL**
|
||
|
||
### 是否可进入下一阶段
|
||
- **是否可按“整体生产可上线”口径放行：否**
|
||
- **是否可按“多平台能力已完成”口径汇报：否**
|
||
- **是否可按“sub2api 单平台代码级链路已可用”口径汇报：是，但必须同时声明关键风险与未完成门禁**
|
||
|
||
### 当前最小可接受口径
|
||
1. 代码级门禁已通过
|
||
2. sub2api 的 webhook → outbox → callback worker 主链已接通
|
||
3. newapi 当前未通过，不应按已接入汇报
|
||
4. 真实共享预生产 / 灰度环境证据未闭环，因此不能按生产可上线口径放行
|
||
|
||
---
|
||
|
||
## 1. 审查输入与证据来源
|
||
|
||
### 1.1 已读取的关键代码
|
||
- `cmd/ai-customer-service/main.go`
|
||
- `internal/app/app.go`
|
||
- `internal/http/router.go`
|
||
- `internal/http/handlers/platform_webhook_handler.go`
|
||
- `internal/http/handlers/platform_webhook_security.go`
|
||
- `internal/platformadapter/sub2api_adapter.go`
|
||
- `internal/platformadapter/newapi_adapter.go`
|
||
- `internal/service/platformevents/builder.go`
|
||
- `internal/service/platformdelivery/worker.go`
|
||
- `internal/store/postgres/platform_event_store.go`
|
||
|
||
### 1.2 已读取的关键文档
|
||
- `docs/CODE_REVIEW_REPORT.md`
|
||
- `docs/RECTIFICATION_REVIEW_REPORT_V2.md`
|
||
- `docs/REVIEW_REPORT_2026-05-04.md`
|
||
- `docs/P0_P1_P2_RECTIFICATION_EXECUTION_BOARD.md`
|
||
- `docs/PRODUCTION_LAUNCH.md`
|
||
- `test/QA_GATE_STATUS.md`
|
||
- `prd/PRODUCTION_CHECKLIST.md`
|
||
|
||
### 1.3 已采纳的实测依据
|
||
- 本轮主审曾捕获两次 `go test ./...` 失败信号：
|
||
- `test/e2e/sub2api_callback_flow_test.go:186`
|
||
- 一次实际 `event[0].type = message.processing`，预期 `message.received`
|
||
- 本轮复核再次实际 `event[0].type = reply.generated`，预期 `message.received`
|
||
- 两次都伴随 `platform callback event delivery failed` 与 `sql: database is closed`
|
||
- 曾有并行 QA 复核在当时现态仓库上复跑 `go test ./... -count=1`：通过
|
||
- 但本轮再次实测 `go test ./... -count=1`：失败
|
||
- 因此当前最真实口径应为：`go build ./...`、`go vet ./...` 通过；`go test ./...` 存在不稳定失败，代码级门禁不能再写成稳定 PASS
|
||
|
||
### 1.4 证据解释原则
|
||
- `go build ./...`、`go vet ./...` 当前可支持通过结论
|
||
- `go test ./...` 当前不能稳定支持通过口径，应视为不稳定失败状态
|
||
- 真实失败信号不能被抹掉，应作为当前事实与稳定性风险保留
|
||
- 不以历史报告或角色自报覆盖当前代码与命令事实
|
||
|
||
---
|
||
|
||
## 2. 当前真实状态
|
||
|
||
### 2.1 已成立的事实
|
||
1. `sub2api` 主链路已真实接通，不是只有定义没有调用
|
||
2. `newapi` 不是“待联调”，而是“入口未实现但装配可开”的未通过状态
|
||
3. 代码级门禁与本地/仓库内验证不能等同于真实预生产或生产放行
|
||
4. 当前最主要的阻塞，不再是早期报告中的旧 P0，而是：
|
||
- 平台能力口径失真
|
||
- callback / outbox 一致性与扩展性边界未收口
|
||
- 真实环境放行证据未闭环
|
||
|
||
### 2.2 已不应继续沿用的旧结论
|
||
以下表述对当前代码已不再成立，不应继续作为“当前事实”引用：
|
||
1. `RateLimiter` 存在 P0 并发写问题
|
||
2. ticket resolve/close 不区分不存在与状态冲突
|
||
3. 后台接口“完全无鉴权”
|
||
4. prod 默认仍可 fallback 到 memory
|
||
5. readiness 相关生产约束仍未收紧
|
||
|
||
说明：
|
||
- 这些项在旧报告中曾成立或部分成立，但已与当前代码和现有门禁文档不一致
|
||
- 继续引用会造成报告漂移
|
||
|
||
### 2.3 仍然成立的高层判断
|
||
1. 当前项目还不是完整 PRD 意义上的完整 AI 客服系统
|
||
2. 当前不能按“整体生产可上线”口径放行
|
||
3. 文档漂移仍是风险，只是漂移重心已经从早期代码 P0 转向旧报告口径过期
|
||
|
||
---
|
||
|
||
## 3. 关键调用链路核查
|
||
|
||
### 3.1 sub2api 主链路核查
|
||
|
||
#### 结论
|
||
- **PASS WITH RISKS**
|
||
|
||
#### 四层核查
|
||
1. 定义
|
||
- `PlatformAdapter` 接口存在
|
||
- `Sub2APIAdapter` 已实现
|
||
- `Worker`、`PlatformEventStore`、event builder 均存在
|
||
2. 装配
|
||
- `internal/app/app.go` 会在配置开启时注册 `sub2api` adapter
|
||
- 在 `platformEvents != nil` 且配置满足时启动 `sub2api` worker
|
||
3. 调用
|
||
- `router` → `PlatformWebhookHandler`
|
||
- `PlatformWebhookHandler` → `registry.Resolve(platform)` → adapter `ParseInbound`
|
||
- `dialog.Process` 后进入 `BuildInboundEvents`
|
||
- `InsertPendingBatch` 写入 outbox
|
||
- worker `RunOnce` / `deliver` 发起 callback
|
||
4. 入口
|
||
- `/api/v1/customer-service/platforms/sub2api/webhook`
|
||
|
||
#### 结论解释
|
||
- 这条链路是实链路，不是“有结构、没接线”
|
||
- 但它仍然带有一致性、并发和稳定性风险，不能直接放大为“平台回调系统已生产级完成”
|
||
|
||
### 3.2 newapi 主链路核查
|
||
|
||
#### 结论
|
||
- **FAIL**
|
||
|
||
#### 直接证据
|
||
1. `internal/platformadapter/newapi_adapter.go:20-21`
|
||
- `ParseInbound` 直接返回 `501 not implemented`
|
||
2. `internal/app/app.go:129-130`
|
||
- 当 `cfg.PlatformAdapters.NewAPI.Enabled` 时，仍会注册 `newapi` adapter
|
||
3. `internal/app/app.go:186-187`
|
||
- `startWorker("newapi", cfg.PlatformAdapters.NewAPI)` 仍可能启动 `newapi` callback worker
|
||
|
||
#### 结论解释
|
||
- 当前状态不是“newapi 已接通但未验证”，而是“配置上看似支持，真实入口未实现”
|
||
- 这是典型 `call_chain_gap + implementation_gap`
|
||
|
||
---
|
||
|
||
## 4. 自动化与验证结果结论
|
||
|
||
| 检查项 | 结论 | 说明 |
|
||
|---|---|---|
|
||
| 代码级门禁 | PARTIAL / 不稳定 | `go build ./...`、`go vet ./...` 当前通过；`go test ./... -count=1` 本轮再次失败于 `test/e2e/sub2api_callback_flow_test.go:186` |
|
||
| sub2api 主链存在性 | PASS | 入口、调用、outbox、worker 四层均可追踪 |
|
||
| newapi 平台能力 | FAIL | 入口未实现但装配仍可打开 |
|
||
| callback worker 基本投递能力 | PASS | 成功/失败/重试/死信路径存在 |
|
||
| callback_target 契约一致性 | FAIL | 字段存在，但 worker 不消费该字段 |
|
||
| outbox 并发投递安全性 | PARTIAL | `ListDue` 无 claim / `skip locked`，多实例下有重复投递窗口 |
|
||
| outbox 强一致性 | PARTIAL | 非严格 transactional outbox |
|
||
| 真实共享预生产 Gate B | FAIL | 当前仍缺真实共享预生产复跑与留痕 |
|
||
| 生产灰度 Gate C | FAIL | 当前仍缺真实监控接线、灰度稳定性与回滚证据 |
|
||
|
||
---
|
||
|
||
## 5. 问题清单
|
||
|
||
### Critical
|
||
|
||
#### C-01 真实共享预生产 / 生产放行证据未闭环
|
||
- 影响：不能按“生产可上线”口径放行
|
||
- 证据：
|
||
- `test/QA_GATE_STATUS.md`
|
||
- `prd/PRODUCTION_CHECKLIST.md`
|
||
- 当前状态：代码级通过，但真实共享预生产 Gate B 和生产 Gate C 仍未通过
|
||
- 建议：继续按 Gate B / Gate C 在真实共享环境复跑并留痕
|
||
|
||
### Important
|
||
|
||
#### I-01 newapi 平台入口未实现但仍可装配/启动 worker
|
||
- 影响：对外口径容易失真，误报为“平台已支持”
|
||
- 证据：
|
||
- `internal/platformadapter/newapi_adapter.go:20-21`
|
||
- `internal/app/app.go:129-130`
|
||
- `internal/app/app.go:186-187`
|
||
- 建议：二选一收口
|
||
1. 禁止未实现平台被注册/启动 worker
|
||
2. 补完整 newapi ingress 实现与对等测试
|
||
|
||
#### I-02 平台启用状态与真实可用能力未统一建模
|
||
- 影响：未完成平台也可能启动 callback worker，形成半接通状态
|
||
- 证据：`internal/app/app.go:158-187`
|
||
- 建议：把 adapter 注册条件、worker 启动条件、入口可用条件收成同一门控
|
||
|
||
#### I-03 `callback_target` 契约与运行时行为不一致
|
||
- 影响：数据模型表达了能力，运行时并未支持，后续易造成静默错投或错误认知
|
||
- 证据：
|
||
- event builder 写入 `callback_target`
|
||
- `worker.go` 实际只使用 `Worker.CallbackURL`
|
||
- 建议：删除伪能力，或真正按 event target 路由
|
||
|
||
#### I-04 outbox 多实例并发投递风险未收口
|
||
- 影响：水平扩展时可能重复投递
|
||
- 证据：`internal/store/postgres/platform_event_store.go:78-86` 的 `ListDue` 仅查询，不做 claim / 锁定
|
||
- 建议：补 claim 机制、`FOR UPDATE SKIP LOCKED` 或显式限定单实例运行边界
|
||
|
||
#### I-05 严格事务外盒未成立
|
||
- 影响：业务主写成功但 outbox 写失败时，一致性不可保证
|
||
- 证据：业务处理与 `InsertPendingBatch` 不在同一事务中
|
||
- 建议：后续评估 transactional outbox 或明确记录一致性边界
|
||
|
||
#### I-06 sub2api callback E2E 已再次复现失败，说明链路存在现实不稳定性
|
||
- 影响：当前 `go test ./...` 不能稳定通过，代码级门禁不能再按稳定 PASS 对外汇报
|
||
- 证据：本轮复核再次在 `test/e2e/sub2api_callback_flow_test.go:186` 失败，实际出现 `reply.generated` 先于 `message.received`，并伴随 `sql: database is closed`
|
||
- 建议：先把该问题提升为当前优先闭环项，做定向稳定性定位与修复，再恢复代码级门禁口径
|
||
|
||
### Minor
|
||
|
||
#### M-01 旧 review 文档存在显著漂移
|
||
- 影响：继续引用会误导后续判断
|
||
- 典型文档：
|
||
- `docs/CODE_REVIEW_REPORT.md`
|
||
- `docs/PRODUCTION_EXECUTION_PLAN.md`
|
||
- 建议：以后续新报告和任务板为准，逐步回收旧结论
|
||
|
||
---
|
||
|
||
## 6. Gap Taxonomy Summary
|
||
|
||
| Gap Type | 具体表现 | 主责任方向 |
|
||
|---|---|---|
|
||
| design_gap | 平台启用 / 平台可用性门控未统一；多实例投递策略未正式定义 | TechLead |
|
||
| implementation_gap | newapi 入口未实现；callback_target 运行时未消费 | Engineer |
|
||
| test_gap | newapi 缺对等测试；sub2api callback E2E 已复现不稳定失败，需优先定位与修复 | QA / Engineer |
|
||
| evidence_gap | 真实共享预生产 / 灰度环境证据未闭环 | QA / DevOps |
|
||
| call_chain_gap | newapi 看似支持但入口未接通 | TechLead / Engineer |
|
||
| contract_gap | callback_target 字段与 worker 真实行为不一致 | TechLead |
|
||
|
||
---
|
||
|
||
## 7. 与旧报告的关系
|
||
|
||
### 7.1 可以继续保留的主结论
|
||
- 当前不能按“整体生产可上线”口径放行
|
||
- 代码级通过不等于预生产和生产放行通过
|
||
- 文档漂移仍需持续治理
|
||
|
||
### 7.2 必须回收的过期口径
|
||
- 旧版把若干已修复问题继续当作当前 P0
|
||
- 旧版把“无鉴权 / prod fallback / readiness 过宽”继续描述为当前代码事实
|
||
- 旧版若暗示“修完早期两个 P0 即可灰度”，现阶段已不再成立
|
||
|
||
### 7.3 新基线文件
|
||
后续应以以下文件作为当前基线：
|
||
- `docs/REVIEW_REPORT_2026-05-06.md`
|
||
- `docs/REMEDIATION_TASK_BOARD_2026-05-06.md`
|
||
- `test/QA_GATE_STATUS.md`
|
||
- `prd/PRODUCTION_CHECKLIST.md`
|
||
|
||
---
|
||
|
||
## 8. 后续执行建议
|
||
|
||
### 最短闭环顺序
|
||
1. 先定位并修复 `sub2api` callback E2E 不稳定失败，恢复 `go test ./...` 稳定通过能力
|
||
2. 收口平台能力矩阵
|
||
3. 收口平台启用 / worker 启动统一门控
|
||
4. 处理 newapi 假接通
|
||
5. 补 newapi 对等验证
|
||
6. 在共享预生产环境复跑 Gate B 并留痕
|
||
7. 在共享预生产 / 灰度环境补监控接线与回滚证据
|
||
|
||
### 对应任务板
|
||
- 详见：`docs/REMEDIATION_TASK_BOARD_2026-05-06.md`
|
||
|
||
---
|
||
|
||
## 9. 最终判定
|
||
|
||
**当前项目应被定义为：**
|
||
|
||
> **`go build ./...` 与 `go vet ./...` 当前通过，但 `go test ./...` 已再次实测失败，说明代码级门禁并不稳定；sub2api 单平台回调主链已可用，但仍带重要一致性/并发/稳定性风险；newapi 当前未通过；真实共享预生产与生产放行门禁未闭环，因此不能按“整体生产可上线”或“多平台已完成”口径汇报。**
|
||
|
||
正式门控结论：
|
||
- **代码级门禁：部分通过 / 当前不稳定**
|
||
- **sub2api 单平台主链：通过，但带重要风险且 E2E 当前不稳定**
|
||
- **newapi 平台能力：未通过**
|
||
- **真实共享预生产门禁：未通过**
|
||
- **生产放行门禁：未通过**
|