csxj2026/junhong_cmp_fiber
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
Files
main
junhong_cmp_fiber/openspec/changes/archive/2026-04-14-tech-debt-cleanup/tasks.md
huang d9de704d73
All checks were successful
构建并部署到测试环境（无 SSH） / build-and-deploy (push) Successful in 49s
Details
归档
2026-04-14 12:14:29 +08:00

11 KiB
Raw Permalink Blame History

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

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

  • 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 协助生成

  • 0.4 创建 migrations/000115_init_data.up.sql（初始化数据）

    • 合并轮询配置初始数据 + 历史订单 purchase_role 回填
    • 所有操作幂等（ON CONFLICT DO NOTHING / WHERE xxx IS NULL）
    • 验证：✅ 已创建

  • 0.5 创建 migrations/000115_init_data.down.sql（回滚初始数据）

    • 验证：✅ 已创建

  • 0.6 归档旧迁移文件

    • 000000~000113 共 228 个文件移入 migrations/archive/
    • backfill_order_purchase_role.sql 一并归档
    • 验证：✅ migrations/ 目录只剩 000115、000116

  • 0.7 编写测试环境重置脚本 scripts/reset_db.sh

    • 含 000114 缺失时的主动报错和提示
    • 验证：✅ 已创建，可执行

  • 0.8 在全新数据库上验证 migrate up 完整链路

    • [阻塞] 依赖 0.2（000114 基线）

  • 0.9 重置测试环境数据库，切换到新基线

    • [跳过] 测试环境正常运行中，不需要重置；现有表结构和数据均正确

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

  • 1.1 在 pkg/constants/redis.go 中新增支付配置 Redis Key 生成函数

    • 新增 RedisPaymentConfigKey(configID uint) string，返回格式 payment:config:{configID}
    • 验证：✅ 编译通过

  • 1.2 确认现有 pkg/payment/ 包中的 Payment 接口/类型定义

    • 确认 pkg/payment/ 不存在，此步骤为新建包
    • 验证：✅ 完成

  • 1.3 创建 pkg/payment/loader.go 文件，定义 PaymentConfigLoader 接口和实现

    • 接口：LoadConfig(ctx, configID uint) (wechat.PaymentServiceInterface, error)
    • Redis 缓存 WechatConfig JSON（TTL 1h），每次从缓存数据构建支付实例
    • 实现：v2PaymentAdapter 适配 PaymentV2Service
    • 验证：✅ 编译通过

  • 1.4 修改 internal/service/order/service.go，实现动态加载

    • 注入 paymentLoader 依赖，替换两处 s.wechatPayment 单例
    • 验证：✅ 编译通过，go vet 无报告

  • 1.5 修改 internal/service/recharge/service.go，实现动态加载

    • 注入 paymentLoader 依赖
    • 验证：✅ 编译通过，go vet 无报告

  • 1.7 运行 go build ./cmd/api ./cmd/worker 确认编译通过

    • 验证：✅ 编译通过，go vet 无报告

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

  • 2.1 修改 cmd/api/docs.go，在 BuildDocHandlers() 中补全所有 Handler

    • 补全 ClientAuth、AdminAuth、AssetLifecycle 三个缺失 Handler
    • 移除冗余的手动覆写
    • 验证：✅ 编译通过

  • 2.2 修改 cmd/gendocs/main.go，同步补全

    • 验证：✅ 编译通过

  • 2.3 运行 go run cmd/gendocs/main.go 生成 OpenAPI 文档

    • 验证：✅ 生成成功，190 个 API 路径

  • 2.4 人工核查生成文档接口数量与路由注册数量一致

    • 验证：✅ 190 个路径，覆盖所有 Handler

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

  • 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 确认无剩余硬编码，go vet 通过

    • 验证：✅ grep 无结果，vet 通过

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

  • 4.1 删除 internal/task/sync.go 整个文件，清理 handler 注册和常量

    • 验证：✅ 文件已删除，grep 无残留

  • 4.2 全局搜索 pkg/constants/wallet.go 中的废弃别名，确认引用情况

    • 验证：✅ 完成，找出所有引用文件

  • 4.3 对有引用的废弃别名，替换为新常量

    • 验证：✅ 完成，编译通过

  • 4.4 删除 pkg/constants/wallet.go 中所有废弃别名定义（87 行）

    • 验证：✅ 完成

  • 4.5 删除 internal/model/dto/enterprise_card_authorization_dto.go 中的 3 个废弃 DTO 类型

    • DeviceBundle、DeviceBundleCard、AllocatedDevice
    • 验证：✅ 完成

  • 4.6 删除 internal/service/order/service.go 中的 CreateLegacy() 方法（~244 行）

    • 验证：✅ 完成

  • 4.7 CheckAndStopCard() 方法

    • [跳过] 该方法在 StopResumeServiceInterface 接口中声明且被 2 个地方调用，是活跃方法，不是废弃代码

  • 4.8 go build ./cmd/api ./cmd/worker 和 go vet 确认无编译错误

    • 验证：✅ 完成

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

    • 验证：✅ 已创建

  • 5.4 创建 migrations/000116_remove_legacy_commission_fields.down.sql

    • 验证：✅ 已创建

  • 5.5 确认字段已从数据库删除

    • 通过 PostgreSQL MCP 查询 information_schema.columns，两个字段均不存在
    • 验证：✅ 字段不存在于 DB

  • 5.6 go build ./cmd/api ./cmd/worker 确认编译通过

    • 验证：✅ 完成

6. DTO _name 字段补全

  • 6.1 统计所有 int 类型状态字段缺少 _name 字段的清单

    • 验证：✅ 完成，共 41 处 _name 字段需补全

  • 6.2 Account 模块：补全 DTO _name 字段 + 常量映射函数 + Service 层赋值

    • GetStatusName() 公共函数，account/service.go 赋值
    • 验证：✅ 完成

  • 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、CommissionWithdrawal、Enterprise 等）：批量补全

    • 额外发现：各 Service 内原有私有映射函数，已统一提升为 pkg/constants/ 公共函数并替换
    • 新增公共函数：GetWithdrawalStatusName、GetRechargeStatusName
    • 验证：✅ 完成

  • 6.8 全量编译与静态分析

    • 验证：✅ go build 通过，go vet 无报告

  • 6.9 抽查接口确认 _name 字段有值

    • 通过代码审查确认 Service 层赋值逻辑正确
    • 运行时验证需服务启动后手动测试

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

  • 7.1 删除 pkg/errors/codes.go 中的 CodeExceedLimit 常量和对应错误消息映射

    • 验证：✅ 完成，grep 无残留

  • 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
    • 验证：✅ 完成

  • 7.3 go build 和 go vet 确认清理无破坏

    • 验证：✅ 完成

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

  • 8.1 删除 internal/routes/recharge.go 空文件

    • 验证：✅ 已删除

  • 8.2 删除 pkg/database/postgres.go 中的 AutoMigrate 注释块

    • 验证：✅ 已删除

  • 8.3 处理 internal/service/client_order/service.go 中的实名认证检查注释

    • 决策：暂不做实名认证拦截，由网关侧处理，待业务明确后按卡类型分支启用
    • 已将 [待确认] 改为明确说明原因的注释
    • 验证：✅ 完成

9. 全量编译验证

  • 9.1 go mod tidy 确认依赖无变化

    • 验证：✅ git diff go.mod go.sum 无变化

  • 9.2 go build ./cmd/api 和 go build ./cmd/worker 通过

    • 验证：✅ 完成

  • 9.3 go vet ./... 静态分析

    • 验证：✅ 无报告

  • 9.4 gofmt -l ./internal ./pkg 检查代码格式

    • 修复了 2 个预存格式问题（pkg/openapi/generator.go、pkg/utils/excel.go）
    • 验证：✅ 完成

10. 全面测试与集成验证

  • 10.1 go build ./... 全量编译，go vet ./... 全量静态分析

    • 验证：✅ 完成

  • 10.2 在测试环境启动 API 服务，运行完整业务流程测试

    • 测试支付流程、轮询系统、各模块 _name 字段响应
    • 待执行：需服务启动

  • 10.3 go vet ./internal/... ./pkg/... 确认无静态分析问题

    • 验证：✅ 完成

  • 10.4 验证数据库迁移执行

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

  • 10.5 检查 Redis 缓存功能（支付配置加载）

    • 待执行：需服务启动后验证缓存行为

  • 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 字段） ⏳ 待服务启动后手动验证
生产部署 ⏳ 发布阶段执行
Reference in New Issue View Git Blame Copy Permalink