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 添加超时配置
```yaml
优先级: 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 日志结构化改造
```yaml
优先级: 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 日志轮转配置
```yaml
优先级: P0
状态: 待处理
负责人: 待分配
开始日期: 待确定
预计工时: 4h
阻塞: 是
```

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

**文件修改**:
- `internal/log/log.go`
- `go.mod`

**依赖**:
- `gopkg.in/natefinch/lumberjack.v2`

**验收标准**:
- [ ] 单日志文件 100MB 限制
- [ ] 保留 3 个历史日志
- [ ] 历史日志自动压缩
- [ ] 7 天自动清理

---

### [ ] B-04 CI/CD 工作流配置
```yaml
优先级: P0
状态: 待处理
负责人: 待分配
开始日期: 待确定
预计工时: 4h
阻塞: 是
```

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

**文件新建**:
- `.github/workflows/ci.yml`
- `.github/workflows/release.yml`

**验收标准**:
- [ ] CI 触发测试、覆盖率检查
- [ ] CI 触发格式化检查
- [ ] Release 构建多平台二进制
- [ ] Release 推送 Docker 镜像

---

## 🔴 HIGH 任务（建议完成）

### [ ] H-01 补充 testutil 测试
```yaml
优先级: P1
状态: 待处理
负责人: 待分配
预计工时: 3h
```

**文件新建**:
- `internal/testutil/sqlite_test.go`

**验收标准**:
- [ ] TestNewTestDB 覆盖率 100%
- [ ] TestNewTestDBWithMigrations 覆盖率 100%

---

### [ ] H-02 补充 migrations 测试
```yaml
优先级: P1
状态: 待处理
负责人: 待分配
预计工时: 4h
```

**文件新建**:
- `internal/store/migrations/migrations_test.go`

**验收标准**:
- [ ] TestMigrationScripts 验证关键表
- [ ] TestMigrationIdempotency 验证幂等性

---

### [ ] H-03 日志 flush 错误监控
```yaml
优先级: P1
状态: 待处理
负责人: 待分配
预计工时: 3h
```

**文件修改**:
- `internal/routing/logwriter.go`

**验收标准**:
- [ ] 添加 flush 错误计数
- [ ] 添加 Prometheus 指标暴露
- [ ] 超过阈值告警

---

### [ ] H-04 Prometheus 指标暴露
```yaml
优先级: P1
状态: 待处理
负责人: 待分配
预计工时: 6h
```

**文件新建**:
- `internal/metrics/metrics.go`

**文件修改**:
- `internal/app/http_api.go`
- `go.mod`

**依赖**:
- `github.com/prometheus/client_golang/prometheus`

**验收标准**:
- [ ] HTTP 请求指标（总量、延迟）
- [ ] 业务指标（导入、对账）
- [ ] /metrics 端点可访问

---

### [ ] H-05 移除 Dockerfile 默认值
```yaml
优先级: P1
状态: 待处理
负责人: 待分配
预计工时: 1h
```

**文件修改**:
- `Dockerfile`

**文件新建**:
- `scripts/docker-entrypoint.sh`

**验收标准**:
- [ ] 移除 SUB2API_CRM_ADMIN_TOKEN 默认值
- [ ] 添加启动时强制检查
- [ ] 缺少必需变量时优雅退出

---

## 🟡 MEDIUM 任务（可选完成）

### [ ] M-01 测试代码 panic 替换
```yaml
优先级: P2
状态: 待处理
负责人: 待分配
预计工时: 2h
```

**文件修改**:
- `internal/store/sqlite/packs_repo_test.go:208`
- `internal/store/sqlite/providers_repo_test.go:316`

**修改内容**:
```go
// panic("unexpected QueryRowContext")
// ->
t.Fatalf("unexpected QueryRowContext")
```

---

### [ ] M-02 错误信息字符串匹配优化
```yaml
优先级: P2
状态: 待处理
负责人: 待分配
预计工时: 3h
```

**文件新建**:
- `internal/errors/errors.go`

**修改目标**:
- 多处测试使用 `strings.Contains(err.Error(), ...)`
- 改为使用 `errors.Is()`

---

### [ ] M-03 边界测试补充
```yaml
优先级: P2
状态: 待处理
负责人: 待分配
预计工时: 4h
```

**文件修改**:
- `internal/app/*_test.go`

**测试场景**:
- [ ] 空字符串参数
- [ ] 超长参数（256+ 字符）
- [ ] 特殊字符参数
- [ ] 边界数值参数

---

### [ ] M-04 添加版本信息端点
```yaml
优先级: 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: 日志敏感信息脱敏
```yaml
优先级: P1
状态: 待处理
负责人: 待分配
预计工时: 2h
依赖: B-02
```

**文件新建**:
- `internal/log/sanitize.go`

**实现内容**:
```go
func Sanitize(fields map[string]interface{}) map[string]interface{}
// 自动脱敏: token, password, key, secret, credential
```

---

#### [ ] H-2a: CI/CD 安全扫描
```yaml
优先级: P1
状态: 待处理
负责人: 待分配
预计工时: 3h
依赖: B-04
```

**文件修改**:
- `.github/workflows/ci.yml`

**添加步骤**:
```yaml
- 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 用户
```yaml
优先级: P1
状态: 待处理
负责人: 待分配
预计工时: 1h
依赖: H-05
```

**文件修改**:
- `Dockerfile`

**添加指令**:
```dockerfile
RUN groupadd -r appgroup && useradd -r -g appgroup appuser
USER appuser
```

---

#### [ ] H-4a: 新建故障处理手册
```yaml
优先级: P1
状态: 待处理
负责人: 待分配
预计工时: 4h
依赖: -
```

**文件新建**:
- `docs/RUNBOOK.md`

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

---

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

#### [ ] M-1a: 添加 ReadHeaderTimeout
```yaml
优先级: P2
状态: 待处理
负责人: 待分配
预计工时: 1h
依赖: B-01
```

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

---

#### [ ] M-2a: 添加 trace_id 支持
```yaml
优先级: P2
状态: 待处理
负责人: 待分配
预计工时: 3h
依赖: B-02
```

**文件修改**:
- `internal/log/log.go`
- `internal/app/middleware.go`

**实现**:
- 生成 trace_id
- 注入 context
- 所有日志携带 trace_id

---

#### [ ] M-3a: 添加模糊测试
```yaml
优先级: P2
状态: 待处理
负责人: 待分配
预计工时: 4h
依赖: -
```

**文件新建**:
- `internal/provision/import_fuzz_test.go`
- `internal/pack/validate_fuzz_test.go`

---

#### [ ] M-4a: 添加业务指标
```yaml
优先级: P2
状态: 待处理
负责人: 待分配
预计工时: 3h
依赖: H-04
```

**文件修改**:
- `internal/metrics/business.go`

**添加指标**:
- `import_runs_total`
- `import_success_rate`
- `reconcile_drift_total`
- `route_proxy_duration`

---

#### [ ] M-5a: API 限流实现
```yaml
优先级: P2
状态: 待处理
负责人: 待分配
预计工时: 4h
依赖: -
```

**文件新建**:
- `internal/app/ratelimit.go`

**实现**:
```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 项补充任务