# 技术债务清理实现任务清单

## 0. 数据库迁移文件合并为生产基线（优先执行）

- [x] 0.1 确认当前数据库 schema 完整可用
  - 通过 PostgreSQL MCP 确认 66 张业务表存在，服务正常
  - 验证：✅ 完成

- [ ] 0.2 使用 `pg_dump` 生成当前完整 schema（仅 DDL，不含数据）
  - **[阻塞]** pg_dump 不在当前环境，待发布前在有 psql 工具的机器上执行
  - 详细步骤见 `migrations/README.md` 「发布前必做」章节
  - 命令：`pg_dump --schema-only --no-owner --no-acl -h <host> -U <user> -d <dbname> > migrations/000114_squash_baseline.up.sql`

- [ ] 0.3 编写 `migrations/000114_squash_baseline.down.sql`（DROP 所有表）
  - **[阻塞]** 依赖 0.2，完成后找 AI 协助生成

- [x] 0.4 创建 `migrations/000115_init_data.up.sql`（初始化数据）
  - 合并轮询配置初始数据 + 历史订单 purchase_role 回填
  - 所有操作幂等（ON CONFLICT DO NOTHING / WHERE xxx IS NULL）
  - 验证：✅ 已创建

- [x] 0.5 创建 `migrations/000115_init_data.down.sql`（回滚初始数据）
  - 验证：✅ 已创建

- [x] 0.6 归档旧迁移文件
  - 000000~000113 共 228 个文件移入 `migrations/archive/`
  - backfill_order_purchase_role.sql 一并归档
  - 验证：✅ migrations/ 目录只剩 000115、000116

- [x] 0.7 编写测试环境重置脚本 `scripts/reset_db.sh`
  - 含 000114 缺失时的主动报错和提示
  - 验证：✅ 已创建，可执行

- [ ] 0.8 在全新数据库上验证 migrate up 完整链路
  - **[阻塞]** 依赖 0.2（000114 基线）

- [ ] 0.9 重置测试环境数据库，切换到新基线
  - **[跳过]** 测试环境正常运行中，不需要重置；现有表结构和数据均正确

---

## 1. 支付配置动态加载（三个 TODO 点）

- [x] 1.1 在 `pkg/constants/redis.go` 中新增支付配置 Redis Key 生成函数
  - 新增 `RedisPaymentConfigKey(configID uint) string`，返回格式 `payment:config:{configID}`
  - 验证：✅ 编译通过

- [x] 1.2 确认现有 `pkg/payment/` 包中的 `Payment` 接口/类型定义
  - 确认 `pkg/payment/` 不存在，此步骤为新建包
  - 验证：✅ 完成

- [x] 1.3 创建 `pkg/payment/loader.go` 文件，定义 `PaymentConfigLoader` 接口和实现
  - 接口：`LoadConfig(ctx, configID uint) (wechat.PaymentServiceInterface, error)`
  - Redis 缓存 WechatConfig JSON（TTL 1h），每次从缓存数据构建支付实例
  - 实现：`v2PaymentAdapter` 适配 PaymentV2Service
  - 验证：✅ 编译通过

- [x] 1.4 修改 `internal/service/order/service.go`，实现动态加载
  - 注入 `paymentLoader` 依赖，替换两处 `s.wechatPayment` 单例
  - 验证：✅ 编译通过，`go vet` 无报告

- [x] 1.5 修改 `internal/service/recharge/service.go`，实现动态加载
  - 注入 `paymentLoader` 依赖
  - 验证：✅ 编译通过，`go vet` 无报告

- [x] 1.7 运行 `go build ./cmd/api ./cmd/worker` 确认编译通过
  - 验证：✅ 编译通过，`go vet` 无报告

---

## 2. API 文档生成器补全（39 个缺失 Handler）

- [x] 2.1 修改 `cmd/api/docs.go`，在 `BuildDocHandlers()` 中补全所有 Handler
  - 补全 ClientAuth、AdminAuth、AssetLifecycle 三个缺失 Handler
  - 移除冗余的手动覆写
  - 验证：✅ 编译通过

- [x] 2.2 修改 `cmd/gendocs/main.go`，同步补全
  - 验证：✅ 编译通过

- [x] 2.3 运行 `go run cmd/gendocs/main.go` 生成 OpenAPI 文档
  - 验证：✅ 生成成功，190 个 API 路径

- [x] 2.4 人工核查生成文档接口数量与路由注册数量一致
  - 验证：✅ 190 个路径，覆盖所有 Handler

---

## 3. 轮询状态常量提取（10+ 处硬编码）

- [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 确认无剩余硬编码，`go vet` 通过
  - 验证：✅ grep 无结果，vet 通过

---

## 4. 废弃代码清理（15 个别名 + 3 个 DTO + 2 个方法）

- [x] 4.1 删除 `internal/task/sync.go` 整个文件，清理 handler 注册和常量
  - 验证：✅ 文件已删除，grep 无残留

- [x] 4.2 全局搜索 `pkg/constants/wallet.go` 中的废弃别名，确认引用情况
  - 验证：✅ 完成，找出所有引用文件

- [x] 4.3 对有引用的废弃别名，替换为新常量
  - 验证：✅ 完成，编译通过

- [x] 4.4 删除 `pkg/constants/wallet.go` 中所有废弃别名定义（87 行）
  - 验证：✅ 完成

- [x] 4.5 删除 `internal/model/dto/enterprise_card_authorization_dto.go` 中的 3 个废弃 DTO 类型
  - DeviceBundle、DeviceBundleCard、AllocatedDevice
  - 验证：✅ 完成

- [x] 4.6 删除 `internal/service/order/service.go` 中的 `CreateLegacy()` 方法（~244 行）
  - 验证：✅ 完成

- [x] 4.7 `CheckAndStopCard()` 方法
  - **[跳过]** 该方法在 `StopResumeServiceInterface` 接口中声明且被 2 个地方调用，是活跃方法，不是废弃代码

- [x] 4.8 `go build ./cmd/api ./cmd/worker` 和 `go vet` 确认无编译错误
  - 验证：✅ 完成

---

## 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`
  - 验证：✅ 已创建

- [x] 5.4 创建 `migrations/000116_remove_legacy_commission_fields.down.sql`
  - 验证：✅ 已创建

- [x] 5.5 确认字段已从数据库删除
  - 通过 PostgreSQL MCP 查询 `information_schema.columns`，两个字段均不存在
  - 验证：✅ 字段不存在于 DB

- [x] 5.6 `go build ./cmd/api ./cmd/worker` 确认编译通过
  - 验证：✅ 完成

---

## 6. DTO `_name` 字段补全

- [x] 6.1 统计所有 int 类型状态字段缺少 `_name` 字段的清单
  - 验证：✅ 完成，共 41 处 `_name` 字段需补全

- [x] 6.2 **Account 模块**：补全 DTO `_name` 字段 + 常量映射函数 + Service 层赋值
  - `GetStatusName()` 公共函数，`account/service.go` 赋值
  - 验证：✅ 完成

- [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、CommissionWithdrawal、Enterprise 等）：批量补全
  - 额外发现：各 Service 内原有私有映射函数，已统一提升为 `pkg/constants/` 公共函数并替换
  - 新增公共函数：`GetWithdrawalStatusName`、`GetRechargeStatusName`
  - 验证：✅ 完成

- [x] 6.8 全量编译与静态分析
  - 验证：✅ `go build` 通过，`go vet` 无报告

- [x] 6.9 抽查接口确认 `_name` 字段有值
  - 通过代码审查确认 Service 层赋值逻辑正确
  - 运行时验证需服务启动后手动测试

---

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

- [x] 7.1 删除 `pkg/errors/codes.go` 中的 `CodeExceedLimit` 常量和对应错误消息映射
  - 验证：✅ 完成，grep 无残留

- [x] 7.2 处理 `pkg/constants/iot.go` 中的预留/废弃常量
  - **调整**：经过调查，部分"预留"常量对应功能已废弃或从未实现
  - 已删除（废弃）：`MerchantType*`（对应 PaymentMerchantSetting 模型无业务代码）、`ReplacementStatus*`、`ReplacementReason*`（换卡功能已下线，表改名为 legacy）
  - 已保留并加注释（真正预留）：`LadderType*`、`ApprovalType*`、`ApprovalStatus*`
  - 同步删除废弃 Model：`internal/model/card_replacement.go`、`internal/model/financial.go` 中的 `PaymentMerchantSetting`
  - 验证：✅ 完成

- [x] 7.3 `go build` 和 `go vet` 确认清理无破坏
  - 验证：✅ 完成

---

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

- [x] 8.1 删除 `internal/routes/recharge.go` 空文件
  - 验证：✅ 已删除

- [x] 8.2 删除 `pkg/database/postgres.go` 中的 AutoMigrate 注释块
  - 验证：✅ 已删除

- [x] 8.3 处理 `internal/service/client_order/service.go` 中的实名认证检查注释
  - **决策**：暂不做实名认证拦截，由网关侧处理，待业务明确后按卡类型分支启用
  - 已将 `[待确认]` 改为明确说明原因的注释
  - 验证：✅ 完成

---

## 9. 全量编译验证

- [x] 9.1 `go mod tidy` 确认依赖无变化
  - 验证：✅ `git diff go.mod go.sum` 无变化

- [x] 9.2 `go build ./cmd/api` 和 `go build ./cmd/worker` 通过
  - 验证：✅ 完成

- [x] 9.3 `go vet ./...` 静态分析
  - 验证：✅ 无报告

- [x] 9.4 `gofmt -l ./internal ./pkg` 检查代码格式
  - 修复了 2 个预存格式问题（`pkg/openapi/generator.go`、`pkg/utils/excel.go`）
  - 验证：✅ 完成

---

## 10. 全面测试与集成验证

- [x] 10.1 `go build ./...` 全量编译，`go vet ./...` 全量静态分析
  - 验证：✅ 完成

- [ ] 10.2 在测试环境启动 API 服务，运行完整业务流程测试
  - 测试支付流程、轮询系统、各模块 `_name` 字段响应
  - **待执行**：需服务启动

- [x] 10.3 `go vet ./internal/... ./pkg/...` 确认无静态分析问题
  - 验证：✅ 完成

- [ ] 10.4 验证数据库迁移执行
  - **[部分]** 000116 SQL 文件已创建，字段已不存在于 DB（字段之前已手动移除）
  - 000115 幂等迁移未显式通过 migrate 工具执行（测试环境已正常运行，不影响）

- [ ] 10.5 检查 Redis 缓存功能（支付配置加载）
  - **待执行**：需服务启动后验证缓存行为

- [x] 10.6 生成最终 OpenAPI 文档并审查
  - 验证：✅ 190 个路径，`go run cmd/gendocs/main.go` 成功

---

## 11-13. 代码审查、部署、验收

- [ ] 11.x 代码审查与合并前检查
  - **待执行**：需团队 review

- [ ] 12.x 部署与监控
  - **待执行**：正式发布前执行，需先完成 0.2（pg_dump 基线）

- [ ] 13.x 最终验收与文档更新
  - **待执行**

---

## 完成标准

| 标准 | 状态 |
|------|------|
| 编译通过：`go build ./cmd/api ./cmd/worker` 无错误 | ✅ |
| 静态分析：`go vet ./...` 无报告 | ✅ |
| 代码格式：`gofmt` 无问题 | ✅ |
| API 文档：190 个路径，覆盖所有 Handler | ✅ |
| 支付动态化：`PaymentConfigLoader` 已实现 | ✅ |
| 废弃代码：sync.go、wallet 别名、废弃 DTO/方法已删除 | ✅ |
| DTO _name：41 个 `_name` 字段已补全，Service 层赋值 | ✅ |
| 数据库迁移文件：000115、000116 已创建，旧文件已归档 | ✅ |
| **迁移基线（000114）** | ⏳ 待发布前用 pg_dump 生成 |
| 运行时验证（支付、轮询、_name 字段） | ⏳ 待服务启动后手动验证 |
| 生产部署 | ⏳ 发布阶段执行 |