junhong_cmp_fiber/.sisyphus/plans/tech-debt-cleanup.md

tech-debt-cleanup 执行计划

TL;DR

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

提案文件：openspec/changes/tech-debt-cleanup/

---

TODOs

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Task 9: 全量编译验证

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

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

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

---

Final Verification Wave

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