sub2api-cn-relay-manager/TASKS.md

sub2api-cn-relay-manager 修复任务清单

基于 Review 报告生成 目标: 系统化跟踪 BLOCKER/HIGH/MEDIUM 问题解决

---

📋 任务总览

• BLOCKER: 4 项 | 预计 16h
• HIGH: 5 项 | 预计 20h
• MEDIUM: 4 项 | 预计 12h
• 总计: 13 项 | 预计 48h

---

🚨 BLOCKER 任务（必须完成）

[ ] B-01 HTTP Server 添加超时配置

优先级: P0
状态: 待处理
负责人: 待分配
开始日期: 待确定
预计工时: 4h
阻塞: 是

描述: HTTP Server 未配置 ReadTimeout、WriteTimeout、IdleTimeout

文件修改:

• internal/app/app.go
• internal/app/app_test.go

验收标准:

• 添加 ReadTimeout: 30s
• 添加 WriteTimeout: 30s
• 添加 IdleTimeout: 120s
• 添加 MaxHeaderBytes: 1MB
• 集成测试通过

---

[ ] B-02 日志结构化改造

优先级: P0
状态: 待处理
负责人: 待分配
开始日期: 待确定
预计工时: 6h
阻塞: 是

描述: 使用标准库 log 输出非结构化日志

文件修改:

• internal/log/log.go (新建)
• cmd/server/main.go
• cmd/cli/main.go
• internal/routing/logwriter.go

验收标准:

• 创建 slog 封装包
• 支持 LOG_LEVEL 环境变量
• 所有日志输出 JSON 格式
• 替换所有 log.Printf/log.Fatalf

---

[ ] B-03 日志轮转配置

优先级: P0
状态: 待处理
负责人: 待分配
开始日期: 待确定
预计工时: 4h
阻塞: 是

描述: 容器环境下日志无限增长

文件修改:

• internal/log/log.go
• go.mod

依赖:

• gopkg.in/natefinch/lumberjack.v2

验收标准:

• 单日志文件 100MB 限制
• 保留 3 个历史日志
• 历史日志自动压缩
• 7 天自动清理

---

[ ] B-04 CI/CD 工作流配置

优先级: P0
状态: 待处理
负责人: 待分配
开始日期: 待确定
预计工时: 4h
阻塞: 是

描述: 缺少 GitHub Actions 自动化测试和发布

文件新建:

• .github/workflows/ci.yml
• .github/workflows/release.yml

验收标准:

• CI 触发测试、覆盖率检查
• CI 触发格式化检查
• Release 构建多平台二进制
• Release 推送 Docker 镜像

---

🔴 HIGH 任务（建议完成）

[ ] H-01 补充 testutil 测试

优先级: P1
状态: 待处理
负责人: 待分配
预计工时: 3h

文件新建:

• internal/testutil/sqlite_test.go

验收标准:

• TestNewTestDB 覆盖率 100%
• TestNewTestDBWithMigrations 覆盖率 100%

---

[ ] H-02 补充 migrations 测试

优先级: P1
状态: 待处理
负责人: 待分配
预计工时: 4h

文件新建:

• internal/store/migrations/migrations_test.go

验收标准:

• TestMigrationScripts 验证关键表
• TestMigrationIdempotency 验证幂等性

---

[ ] H-03 日志 flush 错误监控

优先级: P1
状态: 待处理
负责人: 待分配
预计工时: 3h

文件修改:

• internal/routing/logwriter.go

验收标准:

• 添加 flush 错误计数
• 添加 Prometheus 指标暴露
• 超过阈值告警

---

[ ] H-04 Prometheus 指标暴露

优先级: P1
状态: 待处理
负责人: 待分配
预计工时: 6h

文件新建:

• internal/metrics/metrics.go

文件修改:

• internal/app/http_api.go
• go.mod

依赖:

• github.com/prometheus/client_golang/prometheus

验收标准:

• HTTP 请求指标（总量、延迟）
• 业务指标（导入、对账）
• /metrics 端点可访问

---

[ ] H-05 移除 Dockerfile 默认值

优先级: P1
状态: 待处理
负责人: 待分配
预计工时: 1h

文件修改:

• Dockerfile

文件新建:

• scripts/docker-entrypoint.sh

验收标准:

• 移除 SUB2API_CRM_ADMIN_TOKEN 默认值
• 添加启动时强制检查
• 缺少必需变量时优雅退出

---

🟡 MEDIUM 任务（可选完成）

[ ] M-01 测试代码 panic 替换

优先级: P2
状态: 待处理
负责人: 待分配
预计工时: 2h

文件修改:

• internal/store/sqlite/packs_repo_test.go:208
• internal/store/sqlite/providers_repo_test.go:316

修改内容:

// panic("unexpected QueryRowContext")
// ->
t.Fatalf("unexpected QueryRowContext")

---

[ ] M-02 错误信息字符串匹配优化

优先级: P2
状态: 待处理
负责人: 待分配
预计工时: 3h

文件新建:

• internal/errors/errors.go

修改目标:

• 多处测试使用 strings.Contains(err.Error(), ...)
• 改为使用 errors.Is()

---

[ ] M-03 边界测试补充

优先级: P2
状态: 待处理
负责人: 待分配
预计工时: 4h

文件修改:

• internal/app/*_test.go

测试场景:

• 空字符串参数
• 超长参数（256+ 字符）
• 特殊字符参数
• 边界数值参数

---

[ ] M-04 添加版本信息端点

优先级: P2
状态: 待处理
负责人: 待分配
预计工时: 3h

文件修改:

• internal/app/http_api.go
• Makefile 或 Dockerfile

验收标准:

• GET /version 端点返回版本信息
• 包含 version、commit、build_time

---

📅 执行日历

Week 1: BLOCKER 修复

日期	任务	状态
Mon	B-01 HTTP Server 超时	[ ]
Tue	B-02 日志结构化	[ ]
Wed	B-03 日志轮转	[ ]
Thu	B-04 CI/CD 配置	[ ]
Fri	BLOCKER 集成测试	[ ]

Week 2: HIGH 修复

日期	任务	状态
Mon	H-01 testutil 测试	[ ]
Tue	H-02 migrations 测试	[ ]
Wed	H-03 日志 flush 监控	[ ]
Thu	H-04 Prometheus	[ ]
Fri	H-05 Dockerfile	[ ]

Week 3: MEDIUM + 验收

日期	任务	状态
Mon	M-01 panic 替换	[ ]
Tue	M-02 错误匹配优化	[ ]
Wed	M-03 边界测试	[ ]
Thu	M-04 版本端点	[ ]
Fri	全量回归测试	[ ]

---

📝 任务状态更新日志

2026-06-01

• 任务清单创建完成
• 状态：初始状态，未开始

---

🎯 完成标准

BLOCKER 完成检查

• B-01 代码审查通过
• B-02 代码审查通过
• B-03 代码审查通过
• B-04 代码审查通过
• 所有 BLOCKER PR 合并
• BLOCKER 集成测试通过

HIGH 完成检查

• H-01 代码审查通过
• H-02 代码审查通过
• H-03 代码审查通过
• H-04 代码审查通过
• H-05 代码审查通过
• 所有 HIGH PR 合并

最终验收

• 综合评级从 B 提升到 A
• 全量测试通过
• 性能测试达标
• 安全扫描通过
• 生产就绪评审通过

---

清单版本: v1.0 生成时间: 2026-06-01 对应 Review: 2026-06-01-SYSTEMATIC-REVIEW-REPORT.md

---

🔧 最佳实践补充任务（审核后添加）

高优先级补充任务（4 项，10h）

[ ] H-1a: 日志敏感信息脱敏

优先级: P1
状态: 待处理
负责人: 待分配
预计工时: 2h
依赖: B-02

文件新建:

• internal/log/sanitize.go

实现内容:

func Sanitize(fields map[string]interface{}) map[string]interface{}
// 自动脱敏: token, password, key, secret, credential

---

[ ] H-2a: CI/CD 安全扫描

优先级: P1
状态: 待处理
负责人: 待分配
预计工时: 3h
依赖: B-04

文件修改:

• .github/workflows/ci.yml

添加步骤:

- name: Run govulncheck
  run: go install golang.org/x/vuln/cmd/govulncheck@latest && govulncheck ./...

- name: Run gosec
  run: go install github.com/securego/gosec/v2/cmd/gosec@latest && gosec ./...

- name: Run staticcheck
  run: go install honnef.co/go/tools/cmd/staticcheck@latest && staticcheck ./...

---

[ ] H-3a: Dockerfile 非 root 用户

优先级: P1
状态: 待处理
负责人: 待分配
预计工时: 1h
依赖: H-05

文件修改:

• Dockerfile

添加指令:

RUN groupadd -r appgroup && useradd -r -g appgroup appuser
USER appuser

---

[ ] H-4a: 新建故障处理手册

优先级: P1
状态: 待处理
负责人: 待分配
预计工时: 4h
依赖: -

文件新建:

• docs/RUNBOOK.md

内容章节:

• 启动失败诊断
• 数据库连接问题
• 宿主 API 连接超时
• 导入失败回滚
• 对账异常处理
• 日志排查指南
• 告警响应流程

---

中优先级补充任务（5 项，15h）

[ ] M-1a: 添加 ReadHeaderTimeout

优先级: P2
状态: 待处理
负责人: 待分配
预计工时: 1h
依赖: B-01

修改:

server: &http.Server{
    ReadTimeout:       30 * time.Second,
    ReadHeaderTimeout: 10 * time.Second,  // 新增
    WriteTimeout:      30 * time.Second,
    IdleTimeout:       120 * time.Second,
}

---

[ ] M-2a: 添加 trace_id 支持

优先级: P2
状态: 待处理
负责人: 待分配
预计工时: 3h
依赖: B-02

文件修改:

• internal/log/log.go
• internal/app/middleware.go

实现:

• 生成 trace_id
• 注入 context
• 所有日志携带 trace_id

---

[ ] M-3a: 添加模糊测试

优先级: P2
状态: 待处理
负责人: 待分配
预计工时: 4h
依赖: -

文件新建:

• internal/provision/import_fuzz_test.go
• internal/pack/validate_fuzz_test.go

---

[ ] M-4a: 添加业务指标

优先级: P2
状态: 待处理
负责人: 待分配
预计工时: 3h
依赖: H-04

文件修改:

• internal/metrics/business.go

添加指标:

• import_runs_total
• import_success_rate
• reconcile_drift_total
• route_proxy_duration

---

[ ] M-5a: API 限流实现

优先级: P2
状态: 待处理
负责人: 待分配
预计工时: 4h
依赖: -

文件新建:

• internal/app/ratelimit.go

实现:

// Token bucket rate limiter
// 100 req/s, burst 10
// 按 IP 和按 Token 双维度

---

📊 更新后任务统计

类别	原始任务	补充任务	总计	工时
BLOCKER	4	0	4	16h
HIGH	5	4	9	30h
MEDIUM	4	5	9	27h
总计	13	13	22	73h

---

任务清单版本: v2.0（审核后更新） 更新时间: 2026-06-01 更新原因: 最佳实践审核发现 9 项补充任务