huang
42c5ec912f
All checks were successful
构建并部署到测试环境（无 SSH） / build-and-deploy (push) Successful in 7m13s
5.0 KiB
5.0 KiB
Why
项目经过持续迭代，积累了一批历史技术债务：API 文档覆盖率仅 18.75%（9/48 Handler）、废弃代码和常量散布各处、DTO 规范缺口近 122 处、支付配置硬编码导致多商户场景下验签会失败。数据库迁移文件在开发阶段逐步累积至 114 个，包含 1 个缺失 .down.sql 的数据迁移和 1 个游离的 backfill 脚本，无法支撑生产环境干净、可重复的部署。现阶段业务功能趋于稳定，是集中清理的最佳时机，不解决这些问题将持续拖累新功能开发效率和系统可靠性。
What Changes
- 补全 API 文档生成器：
cmd/api/docs.go和cmd/gendocs/main.go注册缺失的 39 个 Handler，使文档覆盖率达到 100% - 实现支付动态配置加载：
order/service.go和recharge/service.go中 3 处 TODO，从payment_config_id动态加载支付配置，替代全局单例s.wechatPayment - 提取轮询状态常量：将
polling_manual_trigger、manual_trigger_service、polling_manual_trigger_store、alert_service等文件中 10+ 处硬编码字符串（"pending"、"completed"、"cancelled"等）提取到pkg/constants/ - 删除废弃模板代码：
internal/task/sync.go是从未被入队的模板代码（轮询系统已实现真正的同步逻辑），连同pkg/constants/constants.go中的TaskTypeDataSync常量一并删除 - 清理废弃常量别名：
pkg/constants/wallet.go中 15 个已标注Deprecated的常量别名（WalletTypeMain、WalletResourceType*、Card*前缀等），全局替换引用后删除 - 删除废弃 DTO 和方法：确认无引用后删除
DeviceBundle、DeviceBundleCard、AllocatedDevice三个 DTO 类型，以及CreateLegacy()、CheckAndStopCard()两个废弃方法 - 删除 Model 废弃字段并迁移：
iot_card.go和device.go中的FirstCommissionPaid、AccumulatedRecharge字段（已被*BySeriesJSON替代），删除 Model 定义并创建数据库迁移删除对应列 - 清理空文件和注释代码：删除
internal/routes/recharge.go空文件；删除pkg/database/postgres.go中注释掉的AutoMigrate()代码块；保留client_order/service.go中的实名认证检查注释（业务意图未确定） - 批量补全 DTO
_name字段：122 个 Response DTO 中 int 类型状态字段缺少对应的_name/_text文字字段，补全字段定义和 Service 层赋值逻辑 - 清理未使用常量和错误码：删除
CodeExceedLimit错误码；为pkg/constants/iot.go中约 22 个未引用的预留常量添加"预留用于未来功能"注释 - 数据库迁移文件合并为生产基线：将开发阶段积累的 114 个迁移文件（000000~000113）归档到
migrations/archive/，生成两个生产就绪的迁移文件：000114_squash_baseline：从当前数据库 schema 导出的完整建表 SQL，一条命令完成全量建库000115_init_data：初始化数据（轮询系统预置配置 + 历史订单purchase_role回填，均幂等）- 配套测试环境重置脚本
scripts/reset_db.sh
Capabilities
New Capabilities
payment-dynamic-config：支付配置动态加载能力——订单和充值流程从payment_config_id动态加载对应的微信支付配置，支持多商户场景polling-status-constants：轮询触发日志状态常量——将分散的魔法字符串统一到pkg/constants/中，消除硬编码migration-baseline：生产就绪数据库迁移基线——将 114 个开发期迁移合并为 2 个生产基线迁移，支持一条命令完成全量建库与数据初始化
Modified Capabilities
api-doc-coverage：API 文档完整性——docs.go/gendocs 补全所有 Handler 注册，规范要求接口必须出现在 OpenAPI 文档中dto-name-fields：Response DTO 规范——补全 int 状态字段对应的_name/_text文字字段，满足项目 DTO 规范
Impact
- 影响文件：
cmd/api/docs.go、cmd/gendocs/main.go、internal/service/order/service.go、internal/service/recharge/service.go、pkg/constants/（wallet.go、constants.go、iot.go 等）、pkg/errors/codes.go、internal/model/iot_card.go、internal/model/device.go、internal/model/dto/下多个文件、internal/task/sync.go、internal/routes/recharge.go、pkg/database/postgres.go、pkg/queue/handler.go - 数据库变更：
- 新增
000114_squash_baseline.up/down.sql（完整 schema 基线） - 新增
000115_init_data.up/down.sql（初始化数据） - 新增
000116_remove_legacy_commission_fields.up/down.sql（删除first_commission_paid、accumulated_recharge列） - 归档 000000~000113 至
migrations/archive/
- 新增
- API 变更：无（均为内部清理，不影响 API 契约）
- 破坏性变更：无（生产环境首次部署，不存在历史数据迁移问题）
- 依赖变更：无新增依赖
- 环境影响：测试环境需执行
./scripts/reset_db.sh重置为新基线（旧的 000000~000113 迁移历史将被清空）