ai-customer-service/docs/REMEDIATION_PLAN_2026-05-11.md

# ai-customer-service 生产上线修复方案与技术任务拆解

> 生成日期：2026-05-11  
> 基线 commit：`67922c5` (HEAD)  
> 技术负责人：TechLead  
> 对应 Review 报告：`docs/CODE_REVIEW_REPORT_SYSTEMATIC_2026-05-11.md`

---

## 1. 设计范围

### 1.1 本次覆盖

| Review 报告项 | 优先级 | 本次是否覆盖 |
|---|---|---|
| P0-1 Dirty worktree 收口 | P0 | ✅ 覆盖 |
| P0-2 Makefile test 目标缺少 `-p 1` | P0 | ✅ 覆盖 |
| P1-1 ticket_handler.List 覆盖率 0% | P1 | ✅ 覆盖 |
| P1-2 newapi_adapter.BuildIngressAck 覆盖率 0% | P1 | ✅ 覆盖 |
| P1-3 Authz header 伪造风险未文档化 | P1 | ✅ 覆盖 |
| P1-4 RateLimiter GC 压力 | P1 | ✅ 覆盖 |
| P1-5 IPv6 地址在 rate limit key 中被错误截断 | P1 | ✅ 覆盖 |
| P2-1 配置解析失败静默回退 | P2 | ✅ 覆盖 |
| P2-2 callback worker 无连接池限制 | P2 | ✅ 覆盖 |
| P2-3 缺少 SQLite/内存测试回退 | P2 | ✅ 覆盖 |
| P2-4 worker 缺少优雅关闭等待 | P2 | ✅ 覆盖 |

### 1.2 明确不做

- **不引入 pgx 替换 lib/pq**：review 报告建议项，但当前无功能缺口，不属于阻塞问题。
- **不实现 newapi 完整 ingress 逻辑**：旧 remediation board（D-01/I-01）已覆盖该设计缺口，本次仅补充 `BuildIngressAck` 的单元测试（与 review P1-2 对应），不改变 newapi 仍为 501 占位的事实。
- **不引入 testcontainers-go**：P2-3 仅做 skip 回退与文档标注，不做完整容器化测试基础设施。
- **不改写 outbox 并发 claim / transactional outbox**：属于旧 remediation board（I-04/I-05）范围，本次不做。

### 1.3 与 review 报告对应关系

| 本方案章节 | Review 报告章节 | 问题编号 |
|---|---|---|
| 3.1 P0 修复 | 5. P0 — 阻塞级 | P0-1, P0-2 |
| 3.2 P1 修复 | 5. P1 — 必须修复 | P1-1 ~ P1-5 |
| 3.3 P2 修复 | 5. P2 — 建议修复 | P2-1 ~ P2-4 |

---

## 2. 修复方案总览

| 问题 | 技术方案概述 |
|---|---|
| **P0-1 Dirty worktree** | 分 2 批 commit：① 文档文件（8 modified + 4 untracked docs）② 代码文件（3 modified internal）。commit 后打 tag `v0.9.1-pre`。 |
| **P0-2 Makefile test** | `Makefile:2` 改为 `go test ./... -count=1 -p 1`，与 README/CI 保持一致。 |
| **P1-1 ticket_handler.List 0%** | 在 `ticket_handler_test.go` 补充 `List` 的成功与错误分支单元测试，使用现有 `mockTicketService` + `memory.TicketStore`。 |
| **P1-2 newapi_adapter.BuildIngressAck 0%** | 新建 `internal/platformadapter/newapi_adapter_test.go`，覆盖 `BuildIngressAck(meta=nil)` 与 `meta!=nil` 两个分支。 |
| **P1-3 Authz 伪造风险** | 新建 `docs/SECURITY_BOUNDARY.md`，明确 `RequireRoles` 的信任边界；在 `authz.go` 函数注释中标注“依赖上游网关完成真实身份验证”。 |
| **P1-4 RateLimiter GC 压力** | `limits.go:67-73` 将 `var valid []time.Time` 新分配改为原地双指针过滤，复用 `sw.tokens` 底层数组。 |
| **P1-5 IPv6 截断** | `limits.go:110-114` 将手动 `lastIndexByte(addr, ':')` 替换为 `net.SplitHostPort`，正确提取 IPv6 host；补充 IPv6 单元测试。 |
| **P2-1 配置静默回退** | `config.go` 新增 `mustGetEnvInt` / `mustGetEnvBool`（解析失败返回 error）；在 `Load()` 生产模式下对关键数值型配置启用严格解析。 |
| **P2-2 worker 连接池** | `app.go:172` 将裸 `&http.Client{Timeout: ...}` 替换为显式配置 `Transport.MaxIdleConns` / `MaxIdleConnsPerHost` 的 client。 |
| **P2-3 测试回退** | `test/e2e/*_test.go` 与 `test/integration/*_test.go` 在 `TestMain` 或每个 `Test*` 开头增加 PostgreSQL 连通性检测，不通则 `t.Skip`。 |
| **P2-4 worker 优雅关闭** | `app.go` 在 startWorker 中引入 `sync.WaitGroup`：`wg.Add(1)` + goroutine `defer wg.Done()`；closer 中 `cancel()` 后执行 `wg.Wait()`（带 5s 超时兜底）。 |

---

## 3. 任务拆解表

> 粒度约束：每个任务 2-5 分钟，必须有具体文件路径和函数名。

### 3.1 P0 — 阻塞级

| 任务 ID | 文件路径 | 函数/位置 | 预期变更 | 估计耗时 |
|---|---|---|---|---|
| **P0-1a** | 全仓库 | `git status` | 确认 dirty 文件清单，按 "docs" / "code" 分组 | 2 min |
| **P0-1b** | 全仓库 | `git commit` | 批次 1：提交 12 个 docs 文件（modified + untracked）；消息 `docs: sync review reports, runbooks, and checklists` | 3 min |
| **P0-1c** | 全仓库 | `git commit` | 批次 2：提交 3 个 internal/ 文件；消息 `fix: platform event store and builder drift` | 3 min |
| **P0-1d** | 全仓库 | `git tag` | 打 tag `v0.9.1-pre`；推送 tag | 2 min |
| **P0-2a** | `Makefile:2` | `test` target | 将 `go test ./...` 改为 `go test ./... -count=1 -p 1` | 2 min |

### 3.2 P1 — 必须修复

| 任务 ID | 文件路径 | 函数/位置 | 预期变更 | 估计耗时 |
|---|---|---|---|---|
| **P1-1a** | `internal/http/handlers/ticket_handler_test.go` | `TestTicketHandlerList_Success` | 新增测试：向 `mockTicketService.tickets` Create 2 条 ticket，调用 `h.List`，断言返回 200 且 `items` 数组长度为 2 | 3 min |
| **P1-1b** | `internal/http/handlers/ticket_handler_test.go` | `TestTicketHandlerList_ServiceError` | 新增测试：注入一个返回 error 的 `TicketService` mock（或改 `ListOpen` 返回 `errors.New("db down")`），断言返回 500 且 error code 为 `CS_SYS_5002` | 3 min |
| **P1-2a** | `internal/platformadapter/newapi_adapter_test.go` | `TestNewAPIAdapter_BuildIngressAck_NilMeta` | 新建文件与测试：`adapter.BuildIngressAck(nil, nil)` 断言返回 `map[string]any{"accepted":false,"platform":"newapi"}` | 3 min |
| **P1-2b** | `internal/platformadapter/newapi_adapter_test.go` | `TestNewAPIAdapter_BuildIngressAck_WithMeta` | 同上文件：传入 `&PlatformInboundMeta{EventID:"evt-1"}`，断言返回包含 `event_id:"evt-1"` | 2 min |
| **P1-3a** | `docs/SECURITY_BOUNDARY.md` | — | 新建文档：明确标注 `internal/http/middleware/authz.go:RequireRoles` 仅做 RBAC 白名单校验，不验证 header 真实性；生产部署必须前置 API Gateway / JWT 验证 | 3 min |
| **P1-3b** | `internal/http/middleware/authz.go:42` | `RequireRoles` | 在函数注释头增加 `// SECURITY: This middleware trusts the upstream gateway to authenticate the actor headers.` | 2 min |
| **P1-4a** | `internal/platform/httpx/limits.go:67-73` | `RateLimiter.Allow` | 将 `var valid []time.Time` + `append` 循环改为原地双指针过滤：`n := 0; for _, t := range sw.tokens { if t.After(cutoff) { sw.tokens[n] = t; n++ } }; sw.tokens = sw.tokens[:n]` | 3 min |
| **P1-4b** | `internal/platform/httpx/limits_test.go` | 现有测试 | 运行 `go test -race ./internal/platform/httpx/...`，确认零 DATA RACE | 2 min |
| **P1-5a** | `internal/platform/httpx/limits.go:98-115` | `rateLimitKey` | 导入 `net`；将 `lastIndexByte(addr, ':')` 截断逻辑替换为 `host, _, err := net.SplitHostPort(addr)`，err==nil 则返回 host，否则返回原值 | 3 min |
| **P1-5b** | `internal/platform/httpx/limits.go:117-124` | `lastIndexByte` | 删除 `lastIndexByte` 函数（若已无其他引用） | 2 min |
| **P1-5c** | `internal/platform/httpx/limits_test.go` | `TestRateLimitKey_IPv6` | 新增测试：`rateLimitKey` 对 `req.RemoteAddr = "[::1]:8080"` 应返回 `"::1"`；对 `"[2001:db8::1]:8080"` 应返回 `"2001:db8::1"` | 3 min |

### 3.3 P2 — 建议修复

| 任务 ID | 文件路径 | 函数/位置 | 预期变更 | 估计耗时 |
|---|---|---|---|---|
| **P2-1a** | `internal/config/config.go:201-255` | `getEnvInt` / `getEnvBool` | 新增 `mustGetEnvInt(key string) (int, error)` 与 `mustGetEnvBool(key string) (bool, error)`：解析失败时返回 `fmt.Errorf` 而非静默 fallback | 3 min |
| **P2-1b** | `internal/config/config.go:66-148` | `Load()` | 生产模式下，对 `AI_CS_WEBHOOK_MAX_SKEW_SECONDS` 等关键数值配置若环境变量存在但解析失败，返回 error（可选：仅替换最危险的 2-3 个字段以控制范围） | 4 min |
| **P2-2a** | `internal/app/app.go:172` | `startWorker` 内 client 创建 | 将 `&http.Client{Timeout: ...}` 替换为 `&http.Client{Timeout: ..., Transport: &http.Transport{MaxIdleConns: 100, MaxIdleConnsPerHost: 10}}` | 3 min |
| **P2-3a** | `test/e2e/*_test.go` | `TestMain` 或首个 Test | 增加 `pgCheck()`：尝试 `sql.Open("postgres", dsn).Ping()`，失败则 `t.Skip("PostgreSQL not available")` | 3 min |
| **P2-3b** | `test/integration/*_test.go` | `TestMain` 或首个 Test | 同上增加 skip 逻辑 | 3 min |
| **P2-4a** | `internal/app/app.go:158-188` | `startWorker` 闭包 | 在 `New` 函数内声明 `var workerWg sync.WaitGroup`；`startWorker` 中 `workerWg.Add(1)`；goroutine 内 `defer workerWg.Done()`；`worker.Start(workerCtx)` | 3 min |
| **P2-4b** | `internal/app/app.go:164-167` | worker closer | 将 closer 改为：`cancel(); done := make(chan struct{}); go func() { workerWg.Wait(); close(done) }(); select { case <-done: return nil; case <-time.After(5 * time.Second): return fmt.Errorf("worker %s shutdown timeout", platform) }` | 4 min |
| **P2-4c** | `internal/app/app.go` | `import` | 确认新增 `sync` 和 `time`（time 通常已有）导入 | 2 min |

---

## 4. 风险与保护

### 4.1 风险清单

| 风险 ID | 来源任务 | 风险描述 | 等级 |
|---|---|---|---|
| R-01 | P0-1b/c | 批量 commit 可能将未评审代码带入基线 | 🟡 中 |
| R-02 | P1-4a | 限流器原地过滤改动若索引越界，可能 panic 核心路径 | 🔴 高 |
| R-03 | P1-5a | `net.SplitHostPort` 对 IPv6 兼容但可能改变 IPv4 行为（实际不会，但需验证） | 🟡 中 |
| R-04 | P2-1b | 严格配置解析可能破坏现有开发/测试环境（如 `AI_CS_MAX_BODY_BYTES=1MB` 拼写错误导致启动失败） | 🟡 中 |
| R-05 | P2-4a/b | `sync.WaitGroup` 使用不当可能导致 `Shutdown` 死锁或 panic（如 `wg.Add` 在 goroutine 启动后调用） | 🔴 高 |
| R-06 | 全量 | 任何代码改动引入 race condition | 🟡 中 |

### 4.2 降级策略

| 风险 ID | 降级策略 |
|---|---|
| R-01 | commit 前执行 `git diff --cached` 复核；docs 与代码分开 commit，一旦有问题可单独 revert。 |
| R-02 | ① 改前通读 `limits_test.go` 确保有覆盖；② 改后必跑 `go test -race ./internal/platform/httpx/...`；③ 若发现异常，立即回滚到 `var valid []time.Time` 方案。 |
| R-03 | 在 `limits_test.go` 中保留原有 IPv4 用例并追加 IPv6 用例；若 CI 失败，回滚到字符串处理但修复 IPv6 专用分支。 |
| R-04 | P2-1b 仅对生产模式 (`cfg.Runtime.Env == "production"`) 生效；开发/测试环境保持静默回退。若生产启动失败，工程师可立即切回旧 `getEnvInt`。 |
| R-05 | ① `wg.Add(1)` 必须紧接在 `go func()` 之前（同一线程）；② closer 中 `wg.Wait()` 必须带 `time.After` 超时；③ 改后运行 `go test ./internal/app/...` 并手动发送 SIGTERM 验证无死锁。 |
| R-06 | 全量代码任务完成后统一执行 `go test -race ./internal/... -count=1 -p 1`；任何 race 报告阻塞合并。 |

---

## 5. QA 交接与实施约束

### 5.1 编码后漂移检查点（QA 可验证）

| 检查点 ID | 验证命令 / 步骤 | 通过标准 |
|---|---|---|
| CP-01 | `cd /home/long/project/ai-customer-service && git status --short` | 零 modified / 零 untracked（或仅有本次计划外的新 review 报告） |
| CP-02 | `make test` | 等价于 `go test ./... -count=1 -p 1`，零失败（postgres/e2e/integration skip 属于预期行为） |
| CP-03 | `go test -race ./internal/... -count=1 -p 1` | 24/24 pass，零 DATA RACE |
| CP-04 | `go test ./internal/http/handlers/... -coverprofile=/tmp/handlers.out && go tool cover -func=/tmp/handlers.out \| grep ticket_handler.go` | `List` 函数覆盖率 > 0% |
| CP-05 | `go test ./internal/platformadapter/... -coverprofile=/tmp/pa.out && go tool cover -func=/tmp/pa.out \| grep newapi_adapter.go` | `BuildIngressAck` 覆盖率 > 0% |
| CP-06 | `go test ./internal/platform/httpx/...` | 全部通过，包括新增 IPv6 用例 |
| CP-07 | `ls docs/SECURITY_BOUNDARY.md && head -n 20 docs/SECURITY_BOUNDARY.md` | 文件存在，且首段包含 "RequireRoles" 和 "upstream gateway" 关键词 |
| CP-08 | `grep -n "sync.WaitGroup\|workerWg" internal/app/app.go` | 至少出现 `workerWg.Add(1)`、`defer workerWg.Done()`、`workerWg.Wait()` 三处 |
| CP-09 | `grep -n "MaxIdleConns" internal/app/app.go` | 出现 `MaxIdleConns` 与 `MaxIdleConnsPerHost` |
| CP-10 | `go vet ./...` | 零警告 |

### 5.2 必查真实调用链路

| 链路 | 验证方式 |
|---|---|
| **RateLimiter 核心路径** | `TestRateLimiter_WithRateLimit` 必须实际触发 `Allow` 并通过；QA 可单步确认 `rateLimitKey` 返回预期值。 |
| **Authz 信任边界** | QA 手动阅读 `docs/SECURITY_BOUNDARY.md` 与 `authz.go` 注释，确认两者口径一致。 |
| **Worker Graceful Shutdown** | QA 本地启动服务后发送 SIGTERM（`kill -TERM <pid>`），观察日志确认 worker 在 5s 内完成退出，无 `shutdown timeout` error。 |
| **Config 严格模式** | QA 设置 `AI_CS_RUNTIME_ENV=production` + `AI_CS_WEBHOOK_MAX_SKEW_SECONDS=not_a_number`，启动服务应报错并退出。 |

---

## 6. Engineer 实施说明

### 6.1 文件级落点

| 目标文件 | 落点行号 | 改动性质 |
|---|---|---|
| `Makefile` | 第 2 行 | 替换 |
| `internal/http/handlers/ticket_handler_test.go` | 文件末尾 | 追加 2 个 Test 函数 |
| `internal/platformadapter/newapi_adapter_test.go` | 新建 | 2 个 Test 函数 |
| `docs/SECURITY_BOUNDARY.md` | 新建 | Markdown 文档 |
| `internal/http/middleware/authz.go` | 第 42 行上方 | 添加注释块 |
| `internal/platform/httpx/limits.go` | 第 67-73 行 | 替换为原地过滤 |
| `internal/platform/httpx/limits.go` | 第 98-124 行 | 替换 `rateLimitKey` + 删除 `lastIndexByte` |
| `internal/platform/httpx/limits_test.go` | 文件末尾 | 追加 IPv6 Test 函数 |
| `internal/config/config.go` | 第 201-255 行之后 | 追加 `mustGetEnvInt` / `mustGetEnvBool` |
| `internal/config/config.go` | 第 66-148 行 | 条件性替换部分 `getEnvInt` 调用 |
| `internal/app/app.go` | 第 158-188 行 | 重构 startWorker 闭包 |
| `internal/app/app.go` | 第 172 行 | 替换 http.Client 创建 |
| `test/e2e/*_test.go` | 首个 Test 或 TestMain | 追加 skip 逻辑 |
| `test/integration/*_test.go` | 首个 Test 或 TestMain | 追加 skip 逻辑 |

### 6.2 最小验证项（Engineer 每完成一个 P1/P2 任务必须自测）

1. `go build ./...` 零错误。
2. `go vet ./...` 零警告。
3. 涉及改动的包：`go test -race ./<changed_pkg>/...` 通过。
4. 若修改了 exported 函数签名，确认调用方编译通过。

---

## 7. 阶段门控结论

### 7.1 当前状态

- **设计完整性**：本方案已覆盖 review 报告全部 P0/P1/P2 项，任务粒度 <= 5 分钟，文件路径与函数名已精确锁定。
- **风险可控性**：P1-4/P2-4 有较高风险，但已设计明确的降级策略（超时兜底 + race 检测 + 回滚路径）。
- **与旧 remediation board 兼容性**：
  - 本次 P1-2（newapi_adapter 测试）与旧 board 的 I-01（newapi 假接通）正交：本次仅补测试覆盖，不改变 newapi 仍为 501 占位的事实。
  - 本次不涉及旧 board 的 D-01/D-02/D-03/D-04（平台能力矩阵、callback_target 契约、outbox 并发 claim），这些仍按旧 board 排期执行。

### 7.2 结论

**✅ 可进入 Engineer 实现。**

前提条件：Engineer 必须严格按照本方案第 3 章的任务拆解顺序执行，禁止自行扩大范围（如顺带重写 newapi adapter 或引入 pgx）。

---

## 8. 下游执行约束摘要

### 8.1 Engineer 禁止偏离

- **禁止**在修复 P1-2 时顺带实现 newapi 完整 ingress 逻辑（仍保持 501 占位）。
- **禁止**改动 `lib/pq` 为 `pgx`。
- **禁止**修改任何不属于本方案列出的文件，除非发现编译阻断。
- **禁止**跳过 `go test -race` 自测。
- P0-1 必须分 2 批 commit（docs / code），禁止一次性混提交。

### 8.2 QA 必查链路

- `make test` 行为与 `-p 1` 一致性。
- `go test -race ./internal/... -count=1 -p 1` 零 race。
- ticket_handler.List 与 newapi_adapter.BuildIngressAck 的覆盖率从 0% 提升到 > 0%。
- `docs/SECURITY_BOUNDARY.md` 与 `authz.go` 注释口径一致。
- IPv6 rate limit key 的正确性（通过单元测试）。
- Worker graceful shutdown 的 SIGTERM 手动验证。

### 8.3 XL（TechLead / 负责人）必补门控

- P0-1 commit 后复核 `git log --oneline -5` 与 `git status`，确认 worktree 已清。
- P0-1d 打 tag 后，XL 必须亲自确认 tag 存在：`git describe --tags`。
- 全量任务完成后，XL 执行一次 `go test ./... -count=1 -p 1` 并留存输出截图/文本作为最终证据。
- 旧 remediation board 中与本方案无冲突的项（D-01 ~ I-05）继续保留，不得因本次方案而关闭或删除。

---

## 自检清单（返回时显式列出打勾状态）

- [x] 架构设计覆盖 review 报告所有 P0/P1 项
- [x] 每个任务 < 5分钟，有明确文件路径
- [x] 风险评估完整
- [x] 降级策略已设计
- [x] 实施漂移检测点已定义
- [x] 已明确标记是否可进入 Engineer 实现
- [x] 已给出 Engineer / QA / XL 的下游执行约束摘要