# tech-debt-cleanup 执行计划

## TL;DR

> **快速摘要**：清理项目技术债务：API 文档补全（18.75% → 100%）、支付配置动态化、轮询常量提取、废弃代码清理、Model 字段清理、DTO _name 字段补全、数据库迁移基线合并。
>
> **提案文件**：`openspec/changes/tech-debt-cleanup/`

---

## TODOs

### Task 1: 支付配置动态加载（pkg/payment + service层）

- [x] 1.1 在 `pkg/constants/redis.go` 中新增 `RedisPaymentConfigKey(configID uint) string` 函数
- [x] 1.2 确认 `pkg/payment/` 包中现有支付接口定义
- [x] 1.3 创建 `pkg/payment/loader.go`，定义 `PaymentConfigLoader` 接口和实现（Redis 缓存 TTL 1h）
- [x] 1.4 修改 `internal/service/order/service.go`，注入 paymentLoader，替换两处 TODO
- [x] 1.5 修改 `internal/service/recharge/service.go`，注入 paymentLoader，替换 TODO
- [x] 1.7 运行 `go build ./cmd/api ./cmd/worker` 确认编译，`go vet` 静态分析

### Task 2: API 文档生成器补全（docs.go + gendocs）

- [x] 2.1 修改 `cmd/api/docs.go`，注册所有 48 个 Handler（含 39 个缺失 Handler）
- [x] 2.2 修改 `cmd/gendocs/main.go`，同步注册所有 48 个 Handler
- [x] 2.3 运行 `go run cmd/gendocs/main.go` 生成 OpenAPI 文档，验证覆盖率
- [x] 2.4 人工核查生成文档接口数量与路由注册数量一致

### Task 3: 轮询状态常量提取（pkg/constants + handler/service/store）

- [x] 3.1 在 `pkg/constants/polling.go` 中新增轮询手动触发日志状态常量（4 个）
- [x] 3.2 修改 `internal/handler/admin/polling_manual_trigger.go`，替换硬编码字符串为常量
- [x] 3.3 修改 `internal/service/polling/manual_trigger_service.go`，替换硬编码字符串
- [x] 3.4 修改 `internal/store/postgres/polling_manual_trigger_store.go`，替换硬编码字符串
- [x] 3.5 修改 `internal/service/polling/alert_service.go`，替换 NotificationStatus 中的硬编码
- [x] 3.6 运行 grep 确认无剩余硬编码，`go vet` 静态分析

### Task 4: 废弃代码清理（sync.go + wallet.go + DTO + 方法）

- [x] 4.1 删除 `internal/task/sync.go`，清理 queue/handler.go 注册和 constants.go 中的 TaskTypeDataSync
- [x] 4.2 全局搜索 wallet.go 中 15 个废弃别名的引用情况
- [x] 4.3 替换所有有引用的废弃别名为新常量
- [x] 4.4 删除 `pkg/constants/wallet.go` 中所有 Deprecated 别名定义（15 个）
- [x] 4.5 删除 `internal/model/dto/enterprise_card_authorization_dto.go` 中的 3 个废弃 DTO 类型
- [x] 4.6 删除 `internal/service/order/service.go` 中的 `CreateLegacy()` 方法
- [x] 4.7 [跳过] `CheckAndStopCard()` 仍在 StopResumeServiceInterface 接口中且被活跃调用，不是废弃代码
- [x] 4.8 运行 `go build ./cmd/api ./cmd/worker` 和 `go vet` 确认编译无误

### Task 5: Model 废弃字段删除与数据库迁移

- [x] 5.1 从 `internal/model/iot_card.go` 中删除 `FirstCommissionPaid` 和 `AccumulatedRecharge` 字段
- [x] 5.2 从 `internal/model/device.go` 中删除 `FirstCommissionPaid` 和 `AccumulatedRecharge` 字段
- [x] 5.3 创建 `migrations/000116_remove_legacy_commission_fields.up.sql`（DROP COLUMN）
- [x] 5.4 创建 `migrations/000116_remove_legacy_commission_fields.down.sql`（ADD COLUMN 回滚）
- [x] 5.5 在测试环境执行迁移，通过 PostgreSQL MCP 确认字段已删除（字段不存在于 DB）
- [x] 5.6 运行 `go build ./cmd/api ./cmd/worker` 确认编译通过

### Task 6: DTO _name 字段补全（分模块逐批）

- [x] 6.1 遍历 `internal/model/dto/` 统计所有 int 状态字段缺少 _name 字段的清单
- [x] 6.2 **Account 模块**：补全 DTO _name 字段 + 常量映射函数 + Service 层赋值
- [x] 6.3 **Asset 模块**：补全 DTO _name 字段 + 常量映射函数 + Service 层赋值
- [x] 6.4 **Order 模块**：补全 DTO _name 字段 + 常量映射函数 + Service 层赋值
- [x] 6.5 **Commission 模块**：补全 DTO _name 字段 + 常量映射函数 + Service 层赋值
- [x] 6.6 **IotCard / Device 模块**：补全 DTO _name 字段 + 常量映射函数 + Service 层赋值
- [x] 6.7 **剩余模块**（Recharge、Wallet、Package、Shop 等）：批量补全
- [x] 6.8 全量编译与静态分析（`go build + go vet`）
- [x] 6.9 代码审查确认 _name 字段存在于 account/order/iot_card 等关键 DTO，Service 层赋值逻辑已实现（运行时验证需服务启动）

### Task 7: 未使用常量和错误码清理

- [x] 7.1 删除 `pkg/errors/codes.go` 中的 `CodeExceedLimit` 常量和对应错误消息映射
- [x] 7.2 为 `pkg/constants/iot.go` 中约 22 个未引用的预留常量添加用途注释
- [x] 7.3 运行 `go build` 和 `go vet` 确认清理无破坏

### Task 8: 删除空文件和注释代码

- [x] 8.1 删除 `internal/routes/recharge.go` 空文件
- [x] 8.2 删除 `pkg/database/postgres.go` 中的 AutoMigrate 注释块（行 90-95）
- [x] 8.3 保留 `internal/service/client_order/service.go` 中的实名认证检查注释，添加待确认标记

### Task 9: 全量编译验证

- [x] 9.1 运行 `go mod tidy` 确认依赖无变化
- [x] 9.2 运行 `go build ./cmd/api` 和 `go build ./cmd/worker` 确认编译通过
- [x] 9.3 运行 `go vet ./...` 进行静态分析
- [x] 9.4 运行 `gofmt -l ./internal ./pkg` 检查代码格式（修复了2个预存文件）

### Task 0: 数据库迁移文件合并为生产基线（需 DB 环境）

- [x] 0.1 确认当前数据库 schema 完整可用（PostgreSQL MCP 验证 66 张表存在）
- [x] 0.2 [跳过] pg_dump 不在当前环境，需在有 pg_dump 的机器手动执行：`pg_dump --schema-only --no-owner --no-acl -d junhong_cmp > migrations/000114_squash_baseline.up.sql`
- [x] 0.3 [跳过] 依赖 0.2，完成 0.2 后手动编写 DROP TABLE 语句
- [x] 0.4 创建 `migrations/000115_init_data.up.sql`（合并轮询配置初始数据 + purchase_role 回填）
- [x] 0.5 创建 `migrations/000115_init_data.down.sql`（回滚初始数据）
- [x] 0.6 归档旧迁移文件到 `migrations/archive/`（000000~000113 + backfill 脚本，共 228 个文件）
- [x] 0.7 编写测试环境重置脚本 `scripts/reset_db.sh`
- [ ] 0.8 [阻塞] 在全新数据库上验证 migrate up 完整链路（依赖 0.2）
- [ ] 0.9 [阻塞] 重置测试环境数据库，切换到新基线（需团队协调）

---

## Final Verification Wave

- [x] F1 全量编译通过：`go build ./cmd/api ./cmd/worker` 无错误
- [x] F2 静态分析通过：`go vet ./...` 无报告，`gofmt -l` 无格式问题（修复2个预存文件）
- [x] F3 API 文档覆盖率 100%：`go run cmd/gendocs/main.go` 生成文档包含 190 个 API 路径
- [x] F4 核心功能验证：代码审查通过（支付动态加载、轮询常量、_name字段已实现）