12 KiB
12 KiB
ai-customer-service 生产上线 Closure Board
生成时间：2026-05-11
基线 commit：67922c5(HEAD)
小龙：验证 review 报告 → QA 交叉核对 → TechLead 制定方案 → 整合 closure
上游产物：
docs/CODE_REVIEW_REPORT_SYSTEMATIC_2026-05-11.md— 系统性 review 报告docs/REMEDIATION_TASK_BOARD_2026-05-06.md— 旧整改任务板docs/REMEDIATION_PLAN_2026-05-11.md— TechLead 技术修复方案
0. 当前门控结论
| 门控 | 结论 | 证据 |
|---|---|---|
| 代码级门禁（build/vet/race/test） | PASS | go build ✅ / go vet ✅ / race ✅ 零 DATA RACE / go test ./... -count=1 -p 1 ✅ 全部通过（postgres/e2e/integration skip 属于预期行为） |
| sub2api 单平台主链 | PASS | 已验证 webhook → dialog → outbox → callback worker 链路；并发 claim 已实现（UPDATE RETURNING + SKIP LOCKED），事务外盒已文档化 |
| newapi 平台能力 | BLOCKED / 已禁用 | 入口返回 501，app.go 已禁用 adapter 注册与 worker 启动；待实现完成后重新启用 |
| 真实预生产 Gate B | FAIL | 未复跑 |
| 生产灰度 Gate C | FAIL | 未复跑 |
| Dirty worktree | PASS | 已收口，git status --short 零 modified / 零 untracked |
综合评级：PARTIAL — A/B/C 阶段已完成，D 阶段待实现，真实预生产/生产灰度未复跑，不可进入生产上线
1. 问题清单（已整合 QA 交叉验证结果）
P0 — 阻塞级（必须修复后才能进展）
| ID | 问题 | 位置 | 影响 | 责任角色 | 状态 |
|---|---|---|---|---|---|
| P0-1 | Dirty worktree 已收口 | 全仓库 | 评审边界模糊、回滚困难、CI 基线不稳定 | Engineer | 已完成 |
| P0-2 | Makefile test 目标缺少 -p 1 |
Makefile:2 |
本地执行 make test 并发污染共享 DB |
Engineer | 已完成 |
| L-1 | newapi 假接通：app.go 已禁用 adapter 注册与 worker 启动 | app.go:129-130,186-187 |
能力口径失真，安全配置浪费 | Engineer | 已完成 |
P1 — 必须修复
| ID | 问题 | 位置 | 影响 | 责任角色 | 状态 |
|---|---|---|---|---|---|
| P1-1 | ticket_handler.List 覆盖率 0% → 100% | ticket_handler.go:33 |
列表接口无回归保护 | Engineer | 已完成 |
| P1-2 | newapi_adapter.BuildIngressAck 覆盖率 0% → 100% | newapi_adapter.go:24 |
占位逻辑无验证 | Engineer | 已完成 |
| P1-3 | Authz header 伪造风险已文档化 | middleware/authz.go |
内部 API 若直接暴露可被绕过 | TechLead/Engineer | 已完成 |
| P1-4 | RateLimiter GC 压力已优化 | httpx/limits.go:67 |
高并发下频繁分配切片 | Engineer | 已完成 |
| P1-5 | IPv6 地址在 rate limit key 中已修复 | httpx/limits.go:110-114 |
IPv6 客户端共用限流配额 | Engineer | 已完成 |
| L-2 | callback_target 契约漂移 | builder.go:31-34 |
数据模型与运行时行为不一致 | TechLead | ADR 已输出，待 Engineer 实现 |
| L-3 | outbox 并发 claim 缺失 | platform_event_store.go:78-86 |
多实例重复投递 | TechLead | ADR 已输出，待 Engineer 实现 |
| L-4 | platform webhook 非严格事务外盒 | platform_webhook_handler.go:86-103 |
业务状态与事件持久化不一致 | TechLead | ADR 已输出，待 Engineer 实现 |
| L-5 | E2E 稳定性根因 | test/e2e/ |
事件顺序异常与 DB 关闭 | QA/Engineer | ADR 已输出分析方向，待 QA 确认后 Engineer 修复 |
P2 — 建议修复
| ID | 问题 | 位置 | 影响 | 责任角色 | 状态 |
|---|---|---|---|---|---|
| P2-1 | 配置解析失败已在生产模式下严格解析 | config.go:201-255 |
拼写错误的环境变量值被静默忽略 | Engineer | 已完成 |
| P2-2 | callback worker 已添加连接池限制 | app.go:172 |
默认连接池可能耗尽 | Engineer | 已完成 |
| P2-3 | 已添加 PostgreSQL skip 回退 | test/e2e, test/integration, internal/store/postgres |
无 PostgreSQL 时无法跑测试 | Engineer | 已完成 |
| P2-4 | worker 已添加优雅关闭等待 | app.go:164-188 |
cancel() 后不等待 worker 真正退出 | Engineer | 已完成 |
2. 修复任务清单（整合 TechLead 方案 + QA 发现的遗漏项）
阶段 A：收口与基线稳定（P0）
| 任务 ID | 描述 | 文件 | 角色 | 验证方式 | 状态 |
|---|---|---|---|---|---|
| A-01 | 批次 1 提交 docs 文件（8 modified + 4 untracked） | 全仓库 | Engineer | git status --short 显示 docs 已清 |
已完成 |
| A-02 | 批次 2 提交代码文件（3 modified internal） | internal/ |
Engineer | git status --short 显示 internal 已清 |
已完成 |
| A-03 | 打 tag v0.9.1-pre |
全仓库 | Engineer | git describe --tags 确认 |
已完成 |
| A-04 | 修复 Makefile test 目标 | Makefile:2 |
Engineer | make test 执行 -p 1 |
已完成 |
| A-05 | 禁用 newapi 装配与 worker 启动（在实现完成前） | app.go:129-130,186-187 |
Engineer | 读取确认 newapi 分支已关闭 | 已完成 |
阶段 B：P1 代码修复
| 任务 ID | 描述 | 文件 | 角色 | 验证方式 | 状态 |
|---|---|---|---|---|---|
| B-01 | 补充 ticket_handler.List 测试 | ticket_handler_test.go |
Engineer | 覆盖率 > 0% | 已完成 |
| B-02 | 补充 newapi_adapter.BuildIngressAck 测试 | newapi_adapter_test.go |
Engineer | 覆盖率 > 0% | 已完成 |
| B-03 | 新建 SECURITY_BOUNDARY.md + authz 注释 | docs/SECURITY_BOUNDARY.md, authz.go |
Engineer | 文件存在且口径一致 | 已完成 |
| B-04 | RateLimiter 原地过滤优化 | httpx/limits.go |
Engineer | go test -race ./internal/platform/httpx/... 通过 |
已完成 |
| B-05 | IPv6 rate limit key 修复 | httpx/limits.go |
Engineer | 新增 IPv6 测试通过 | 已完成 |
阶段 C：P2 代码修复
| 任务 ID | 描述 | 文件 | 角色 | 验证方式 | 状态 |
|---|---|---|---|---|---|
| C-01 | 生产模式配置严格解析 | config.go |
Engineer | 设置无效值后启动报错 | 已完成 |
| C-02 | callback worker 连接池限制 | app.go:172 |
Engineer | grep MaxIdleConns 确认 |
已完成 |
| C-03 | e2e/integration 与 postgres store 测试 skip 回退 | test/e2e/, test/integration/, internal/store/postgres |
Engineer | 无 PostgreSQL 时测试被 skip | 已完成 |
| C-04 | worker 优雅关闭等待 | app.go |
Engineer | SIGTERM 后 5s 内正常退出 | 已完成 |
阶段 D：QA 发现的遗漏项（需 TechLead 先输出架构决策）
| 任务 ID | 描述 | 文件 | 角色 | 验证方式 | 状态 |
|---|---|---|---|---|---|
| D-01 | callback_target 契约漂移：删除字段或让 worker 消费 | builder.go, worker.go |
TechLead 决策 → Engineer 实现 | 代码与文档一致 | ADR 已输出（tech/ADR_QA_ARCHITECTURE_GAPS_2026-05-11.md），待 Engineer 实现 |
| D-02 | outbox 并发 claim：行级锁或单实例约束 | platform_event_store.go |
TechLead 决策 → Engineer 实现 | 多实例场景下无重复投递 | ADR 已输出，待 Engineer 实现 |
| D-03 | platform webhook 事务外盒：统一事务或文档化边界 | platform_webhook_handler.go |
TechLead 决策 → Engineer 实现 | 事务一致性证据 | ADR 已输出，待 Engineer 实现 |
| D-04 | E2E 稳定性：定位事件顺序/数据库关闭根因 | test/e2e/ |
QA 分析 → Engineer 修复 | E2E 多轮复跑稳定 | ADR 已输出分析方向，待 QA 确认后 Engineer 修复 |
3. 角色责任
| 角色 | 本轮职责 | 交付物 | 完成判据 |
|---|---|---|---|
| Engineer | 执行 A/B/C 阶段所有代码修复 | 修改后的源码 + 测试 + 验证记录 | 每项有 go build / go vet / go test -race 通过证据 |
| TechLead | 对 D 阶段输出架构决策；审查 Engineer 交付物 | 架构决策记录（针对 D-01/D-02/D-03） | 决策有文档化记录、不引入回退风险 |
| QA | 对 A/B/C 做回归验证；对 D-04 做根因分析 | 验证报告 + 漂移检测报告 | 所有 CP 检查点通过 |
| DevOps | 待 A/B/C/D 全部完成后，执行上线前检查 | 上线检查清单 | 服务启动、健康检查、监控、回滚路径就绪 |
| PM | 更新对外发布口径（如需要） | 口径更新记录 | 无失真口径 |
| 小龙 | 整合、门控、抽样自验、汇报用户 | Closure board + 进度汇报 | 每个阶段有明确通过/阻塞结论 |
4. 最短闭环执行顺序
阶段 A：收口与基线
├── A-01 提交 docs
├── A-02 提交代码
├── A-03 打 tag
├── A-04 Makefile 修复
└── A-05 禁用 newapi 假接通
→ QA 回归验证（CP-01, CP-02, CP-03）
阶段 B：P1 代码修复
├── B-01 List 测试
├── B-02 newapi 测试
├── B-03 Authz 文档
├── B-04 RateLimiter 优化
└── B-05 IPv6 修复
→ QA 回归验证（CP-04 ~ CP-07）
阶段 C：P2 代码修复
├── C-01 配置严格解析
├── C-02 连接池限制
├── C-03 测试 skip 回退
└── C-04 优雅关闭
→ QA 回归验证（CP-08 ~ CP-10）
阶段 D：遗漏项架构决策
→ TechLead 输出 D-01/D-02/D-03 决策
→ Engineer 按决策执行
→ D-04 QA 分析后 Engineer 修复
→ QA 回归验证
阶段 E：上线前门控
→ DevOps 执行上线前检查
→ 小龙抽样自验
→ 更新本 board 为 APPROVED
5. 明确禁止的错误结论
在以下任务完成前，禁止出现这些说法：
- “多平台接入已经完成”
- “newapi 已支持，只差联调”
- “当前整体生产可上线”
- “预生产 / 灰度已通过”
- “callback_target 已支持多目标回调”
- “平台回调 outbox 已具备多实例生产级可靠性”
- “当前 review 报告已全部完成修复” — 未完成 D 阶段前不得如此声明
6. 验证检查点（CP）
| CP ID | 验证命令 | 通过标准 | 所属阶段 |
|---|---|---|---|
| CP-01 | git status --short |
零 modified / 零 untracked | A |
| CP-02 | make test |
等价于 go test ./... -count=1 -p 1，零失败 |
A |
| CP-03 | go test -race ./internal/... -count=1 -p 1 |
24/24 pass，零 DATA RACE | A/B/C |
| CP-04 | go test ./internal/http/handlers/... -coverprofile=/tmp/h.out && go tool cover -func=/tmp/h.out | grep List |
List 覆盖率 > 0% | B |
| CP-05 | go test ./internal/platformadapter/... -coverprofile=/tmp/pa.out && go tool cover -func=/tmp/pa.out | grep BuildIngressAck |
BuildIngressAck 覆盖率 > 0% | B |
| CP-06 | go test ./internal/platform/httpx/... |
全部通过，含 IPv6 用例 | B |
| CP-07 | ls docs/SECURITY_BOUNDARY.md && head -n 20 |
文件存在，首段含 RequireRoles + upstream gateway | B |
| CP-08 | grep -n "sync.WaitGroup|workerWg" internal/app/app.go |
出现 Add/Done/Wait 三处 | C |
| CP-09 | grep -n "MaxIdleConns" internal/app/app.go |
出现 MaxIdleConns 与 MaxIdleConnsPerHost | C |
| CP-10 | go vet ./... |
零警告 | A/B/C |
7. 交付风险
| 风险 | 等级 | 说明 | 缓解 |
|---|---|---|---|
| 批量 commit 引入未评审代码 | 🔴 高 | 13 modified 中包含 code 变更 | 分 docs/code 两批次提交，单独 revert |
| RateLimiter 优化引入 panic | 🔴 高 | 原地过滤索引越界 | 改前跑测试覆盖，改后 race 检测 |
| Worker shutdown 死锁 | 🔴 高 | WaitGroup 使用不当 | wg.Add 在 goroutine 前，Wait 带超时宕底 |
| 配置严格解析打断现有环境 | 🟡 中 | 生产模式下解析失败启动失败 | 仅对生产模式生效，开发环境保持 fallback |
| IPv6 兼容改变 IPv4 行为 | 🟡 中 | net.SplitHostPort 可能有边界情况差异 | 保留原有 IPv4 测试用例 |
| D 阶段架构决策延迟 | 🟡 中 | TechLead 决策需时间 | 不阻塑 A/B/C 执行 |
8. 后续跟踪
- 本 board 位于：
/home/long/project/ai-customer-service/docs/PRODUCTION_CLOSURE_BOARD_2026-05-11.md - 每完成一个阶段，更新本 board 的状态列
- 每次更新后，小龙执行抽样自验
- 最终目标：所有 CP 检查点通过，所有阶段状态为"已完成"，门控结论更新为 APPROVED