ai-customer-service/docs/RECTIFICATION_REVIEW_REPORT_V2.md

ai-customer-service 整改版审查报告 v2

角色框架：小龙 / PM / TechLead / QA / DevOps
审查目标：从“可跑通”提升到“生产可控、可灰度、可追责、不可默默降级”

---

0. 阶段门控结论

当前结论：REQUEST_CHANGES
是否可直接按“生产已具备上线条件”放行：否

当前真实状态

• 代码主链：已基本打通
• 关键测试：已实跑通过
• 生产落地控制：仍有明显缺口
• 团队流程一致性：存在文档漂移与门禁失真

本轮阻塞上线的核心原因

1. 默认允许 memory store 启动，存在生产级降级失控
2. readiness 不能证明“生产依赖已就绪”
3. QA / 上线文档与真实代码状态存在漂移
4. 环境变量与部署文档口径不一致，存在实施误配风险
5. 后台操作鉴权与运维级控制尚未形成完整闭环

---

1. 本次复核依据与已验证证据

1.1 已实际读取的关键实现

重点核查：

• internal/app/app.go
• internal/config/config.go
• internal/http/router.go
• internal/http/handlers/webhook_handler.go
• internal/http/handlers/webhook_security.go
• internal/http/handlers/health_handler.go
• internal/http/handlers/session_handler.go
• internal/http/handlers/ticket_handler.go
• internal/service/dialog/service.go
• internal/service/handoff/service.go
• internal/store/postgres/*
• internal/store/memory/*
• db/migration/0001_init.up.sql

文档对照：

• prd/PRODUCTION_CHECKLIST.md
• test/QA_GATE_STATUS.md

1.2 已实际执行的验证

已通过 ASCII symlink 规避中文路径工具限制后执行：

go test -count=1 ./...
go test -count=1 ./test/e2e -run 'TestFullTicketFlow_E2E|TestSecurity_.*' -v
go test -count=1 ./test/integration -run 'TestHealthCheck_.*|TestDialogService_.*|TestTicketAssignResolve.*|TestSessionHandler.*' -v

实测结论

• 全仓测试通过
• 工单 E2E 主链通过
• Webhook 安全 E2E 通过
• Health/readiness 集成测试通过
• Session / Dialog / Ticket 关键集成测试通过

---

2. 审查后的总判断

2.1 已落实部分

A. 功能主链已存在

• webhook 收消息
• dialog 识别意图
• handoff 创建 ticket
• ticket assign / resolve / close / get
• stats / feedback / manual handoff 基本能力已落地

B. 基础安全入口已存在

• webhook HMAC
• timestamp 窗口校验
• dedup 幂等
• body limit
• rate limit

C. Postgres 持久化路径已接通

• AI_CS_POSTGRES_ENABLED=true 时走 postgres store
• migration 启动执行
• session / ticket / audit / dedup 均有 PG 实现

2.2 当前不能判定“生产可放心上线”的核心原因

A. 降级失控

生产默认可退化为 memory store，且服务仍能成功启动并 ready。

B. readiness 语义过宽

只能证明“进程能收请求”，不能证明“生产依赖与安全前置条件已满足”。

C. 文档与代码状态漂移

团队已有“测试失败/允许上线”等结论与当前代码真实状态不一致。

D. 部署契约未收敛

文档写的环境变量名与代码真实读取项不完全一致。

E. 后台操作的真实性边界不足

ticket / session 相关后台接口仍偏内网占位实现，缺少真正的操作鉴权闭环。

---

3. 角色化整改方案

3.1 小龙（CEO / 统筹者）整改责任

核心问题

当前团队最大问题不是“没人干活”，而是：

• 修了代码但没同步门禁文档
• 跑通了链路但仍以“允许上线”模糊放行
• 角色产出没有被强制做事实校准

小龙必须承担的整改动作

XL-P0-1：建立“代码事实高于报告”的门禁

今后任何“已完成 / 可上线 / 已通过”的结论，必须满足：

1. 有实际文件证据
2. 有实际命令输出
3. 有当前版本时间点的校准
4. 有至少一次小龙抽样自验

XL-P0-2：重写阶段状态口径

把当前项目阶段结论统一收敛成三层：

• 代码主链状态
• 预生产验证状态
• 生产上线状态

禁止再用单句“允许上线”覆盖全部层次。

XL-P1-1：强制角色交付模板

后续 PM / TechLead / QA / DevOps 输出必须固定带：

• 结论
• 证据
• 阻塞项
• 下一阶段条件
• 责任人
• 时间要求

XL-P1-2：增加“实施漂移复核点”

每次关键修复后，小龙必须做 3 件事：

1. 复跑最小必要测试
2. 复核关键配置契约
3. 更新门禁文档状态

小龙验收标准

• 所有“完成/通过”结论都有命令或文件证据
• 文档状态与当前代码状态一致
• 不再使用“允许上线”作为模糊总括结论
• 每个整改项都有明确责任角色和验收人

3.2 PM（产品经理）整改责任

当前 PM 问题

不是没有文档，而是文档覆盖面和交付口径不够硬：

• 上线检查项有，但和代码契约未完全对齐
• 对“Phase1 可上线”表述偏乐观
• 对“dev fallback 与 prod 要求差异”没有明确写成产品/交付边界
• 对“上线前必须真实环境验证”的门槛定义不够强

PM 必须承担的整改动作

PM-P0-1：修正文档中的上线口径

将现有文档中的“允许上线”改成分层表述：

• 代码级门禁通过
• 仓库内测试门禁通过
• 真实环境门禁未闭环
• 仅允许进入预生产/灰度准备

PM-P0-2：补“运行模式约束”

在 PRD / checklist / status 中明确写入：

• memory mode 仅用于开发 / 测试
• prod 环境不允许无持久化运行
• 若缺少 DB / secret / 关键依赖，系统应 fail-fast，不得 silent degrade

PM-P1-1：补齐“上线运营口径与观察指标”

新增明确观察项：

• 工单创建量是否异常偏低/偏高
• handoff 比率是否异常
• audit 写入是否持续
• dedup 是否稳定
• readiness 是否真实反映依赖状态
• 实例重启后数据是否仍在

PM-P1-2：统一环境变量文档契约

所有面向部署的文档，必须统一写成代码真实读取的变量名，例如：

• AI_CS_POSTGRES_ENABLED
• AI_CS_POSTGRES_DSN
• AI_CS_POSTGRES_MIGRATION_DIR
• AI_CS_WEBHOOK_SECRET
• AI_CS_WEBHOOK_MAX_SKEW_SECONDS

禁止再用泛化口径替代真实配置契约。

PM 验收标准

• 文档中不再出现“仅凭仓库内测试即可认定生产可上线”的表述
• 文档中的环境变量名与 config.go 完全一致
• 明确区分 dev/test 与 prod 运行要求
• 上线观察指标、失败判定线、回滚触发条件都已写清

3.3 TechLead（技术经理）整改责任

当前 TechLead 问题

TechLead 已把主链做起来，但没有把“生产默认安全”做成系统约束。

必须整改的技术项

TL-P0-1：禁止生产默认退化到 memory store

目标：

• 生产模式下，不允许 Postgres.Enabled=false 仍正常启动

建议实现方向：

1. 增加运行模式，例如：
   • AI_CS_RUNTIME_MODE=dev|test|prod
2. 在 prod 模式下强制校验：
   • AI_CS_POSTGRES_ENABLED=true
   • AI_CS_POSTGRES_DSN 非空
   • migration dir 可用
3. 不满足则 app.New() 直接返回错误

验收标准

• prod 下未启用 Postgres 时服务启动失败
• 错误信息明确说明缺失项
• 有对应测试覆盖

TL-P0-2：收紧 readiness 语义

当前 probe.SetReady(true) 太早，必须改。

建议：

• 启动完成后不直接 ready
• ready 的条件至少包含：
  • DB 已连接
  • migration 已成功
  • 关键配置已完整
  • 运行模式合法
  • 如启用 webhook auth，则 secret 已配置

可选策略：

• health 保持诊断信息
• ready 专门作为流量门禁

验收标准

• 缺 DB / 缺 secret / 缺关键配置时 ready=DOWN
• ready 不再仅因为进程启动成功就返回 UP
• 有集成测试覆盖关键失败场景

TL-P0-3：统一配置契约与部署文档

TechLead 要输出一份代码视角的配置契约基线，作为 PM / DevOps / QA 的唯一来源。

至少包括：

• 变量名
• 默认值
• 是否允许默认值出现在 prod
• 是否阻断启动
• 对应组件
• 风险等级

示例字段：

• AI_CS_POSTGRES_ENABLED
• AI_CS_POSTGRES_DSN
• AI_CS_POSTGRES_MIGRATION_DIR
• AI_CS_WEBHOOK_SECRET
• AI_CS_MAX_BODY_BYTES

验收标准

• 有单独配置契约表
• 与 config.go 实际实现一致
• 明确哪些默认值仅限 dev/test

TL-P1-1：补后台接口鉴权设计

当前：

• actor_id 主要来自 query param
• 更接近内部占位实现，而不是正式后台控制面接口

需明确：

• 是仅内网可调
• 还是后台服务调用
• 还是运营台使用
• 对应认证方式是什么

至少补设计：

• 内部 token / service auth / gateway auth
• 操作审计字段真实性
• actor 来源不可伪造

验收标准

• ticket/session 后台接口有明确 auth 模式
• actor_id 不再只是前端随便传
• 权限边界写入设计文档

TL-P1-2：补多实例与恢复场景验证设计

需要明确验证：

• dedup 在多实例下是否稳定
• ticket / session / audit 在重启后是否一致
• migration 重复执行是否幂等
• 故障恢复后 ready 恢复逻辑是否正确

3.4 QA（质量经理）整改责任

当前 QA 问题

QA 不是没工作，而是结论闭环不够硬：

• 文档中存在过时结论
• “允许上线”没有严格区分代码门禁与生产门禁
• 没把“memory fallback 风险”上升为真正阻断项

QA 必须承担的整改动作

QA-P0-1：重做上线门禁文档

重写 QA_GATE_STATUS，按以下结构：

1. 当前代码事实
2. 实测命令
3. 通过项
4. 未通过项
5. 文档漂移项
6. 生产阻断项
7. 下一阶段建议结论

必须明确区分：

• 仓库内验证通过
• 真实环境未验证
• 生产阻断未解除

QA-P0-2：把“降级失控”列为 Critical

以下情形必须判定为 Critical：

• prod 可在 memory mode 启动
• ready 不能区分关键依赖缺失
• 部署文档与配置契约不一致
• 文档已允许上线，但真实环境门禁未验证

QA-P1-1：建立“文档漂移检测”检查项

今后每次 QA 审查必须加一栏：

• 代码状态 vs status 文档是否一致
• 测试状态 vs 报告状态是否一致
• 配置项 vs checklist 是否一致

QA-P1-2：增加真实环境前置门禁

上线前 QA 必须强制检查：

• 使用真实环境变量启动一次
• ready / health 返回符合预期
• Postgres migration 执行成功
• webhook 签名真实联调成功
• audit / ticket 实际入库成功

QA 验收标准

• QA 报告明确区分代码门禁 / 生产门禁
• 文档漂移项被单独列出
• memory fallback 风险被列为 Critical 直到修复
• 不再用“允许上线”掩盖真实环境未验证

3.5 DevOps（运维 / SRE）整改责任

当前 DevOps 问题

仓库中有上线清单，但还不是实际运维闭环。

DevOps 必须承担的整改动作

DO-P0-1：形成真实部署基线

需要明确：

• 启动命令
• 必填环境变量
• secret 注入方式
• Postgres 连通性检查
• migration 执行方式
• readiness / liveness 探针路径
• 灰度方式
• 回滚方式

DO-P0-2：把“关键配置缺失即启动失败”纳入部署标准

即使代码修完，部署侧也要加保护：

• 若 prod 缺少 AI_CS_POSTGRES_DSN / AI_CS_WEBHOOK_SECRET
• CI/CD 或启动脚本应直接 fail

DO-P1-1：补监控与告警

最少补这些：

• 5xx rate
• webhook reject rate
• handoff rate
• ticket create rate
• audit write error
• DB connect / migration error
• ready down duration

DO-P1-2：补 runbook

必须有：

• 启动失败排查
• migration 失败回滚
• DB 不可用处理
• webhook auth 失败联调
• 实例重启后数据一致性检查

DevOps 验收标准

• 有真实部署基线文档
• prod 关键配置缺失时不会“假成功启动”
• 有最小监控告警集
• 有回滚与故障 runbook

---

4. P0 / P1 / P2 总整治清单

P0：上线前必须完成

1. 禁止 prod 退化为 memory mode
2. 收紧 readiness，改成真实依赖门禁
3. 修正文档：状态、测试、环境变量口径统一
4. QA 重做门禁结论，撤销过宽“允许上线”表述
5. 建立部署侧关键配置 fail-fast 机制

P1：灰度前应完成

1. 后台操作接口鉴权边界明确
2. 真实环境 DB / migration / webhook 联调
3. 监控告警最小闭环
4. 文档漂移检测纳入 QA 常规项
5. runbook 与回滚路径补齐

P2：全量上线后持续补

1. 更完整威胁建模
2. 多实例一致性与恢复测试
3. store/app 层覆盖率继续补齐
4. 敏感字段脱敏、审计治理、保留策略完善
5. 更细粒度容量与可观测性建设

---

5. 整改后阶段门禁定义

Gate A：代码级通过

满足：

• 主链测试通过
• 安全测试通过
• prod 不允许 memory fallback
• readiness 逻辑收紧
• 配置契约与代码一致

Gate B：预生产通过

满足：

• 真实 Postgres 联通
• migration 成功
• webhook 签名联调成功
• audit / ticket 入库成功
• ready / live 行为符合预期
• 最小监控已接通

Gate C：生产灰度通过

满足：

• 5% 灰度稳定
• handoff / ticket / audit 指标正常
• 无异常 5xx / reject 激增
• 回滚演练已通过

---

6. 最终整改版结论

ai-customer-service 当前应被定义为：
“代码主链可用，适合进入生产整改与预生产验证阶段；但尚不应被标记为生产可直接放心上线。”

更准确地说：

• 不是没做成
• 也不是 demo 空壳
• 但现在离生产级放心放量，还差最后一层关键控制：禁止隐式降级、收紧 readiness、统一配置契约、修正文档漂移、补部署门禁。