niuniu/ai-customer-service
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
9319583ee333f8b280452c4ccca284f358f8a2bd
ai-customer-service/docs/REVIEW_REPORT_2026-05-06.md

12 KiB
Raw Blame History

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 平台能力：未通过
  • 真实共享预生产门禁：未通过
  • 生产放行门禁：未通过
Reference in New Issue View Git Blame Copy Permalink