huang
42c5ec912f
All checks were successful
构建并部署到测试环境（无 SSH） / build-and-deploy (push) Successful in 7m13s
109 lines
6.3 KiB
Markdown
109 lines
6.3 KiB
Markdown
# 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 回滚）
|
||
- [ ] 5.5 在测试环境执行迁移，通过 PostgreSQL MCP 确认字段已删除（需 DB 环境）
|
||
- [x] 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 使用 curl/Postman 抽查各模块接口，确认 _name 字段有值且正确
|
||
|
||
### 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: 全量编译验证
|
||
|
||
- [ ] 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` 检查代码格式
|
||
|
||
### Task 0: 数据库迁移文件合并为生产基线（需 DB 环境）
|
||
|
||
- [ ] 0.1 确认当前数据库 schema 完整可用（服务启动无错误）
|
||
- [ ] 0.2 使用 pg_dump 生成当前完整 schema（仅 DDL）→ `migrations/000114_squash_baseline.up.sql`
|
||
- [ ] 0.3 编写 `migrations/000114_squash_baseline.down.sql`（DROP 所有表）
|
||
- [ ] 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 脚本）
|
||
- [ ] 0.7 编写测试环境重置脚本 `scripts/reset_db.sh`
|
||
- [ ] 0.8 在全新数据库上验证 migrate up 完整链路
|
||
- [ ] 0.9 重置测试环境数据库，切换到新基线
|
||
|
||
---
|
||
|
||
## Final Verification Wave
|
||
|
||
- [ ] F1 全量编译通过：`go build ./cmd/api ./cmd/worker` 无错误
|
||
- [ ] F2 静态分析通过：`go vet ./...` 无报告，`gofmt -l` 无格式问题
|
||
- [ ] F3 API 文档覆盖率 100%：`go run cmd/gendocs/main.go` 生成文档包含 48/48 Handler
|
||
- [ ] F4 核心功能验证：支付、轮询、账号管理等模块接口正常响应，_name 字段有值
|