feat: 技术债务清理（支付配置动态化、API文档补全、轮询常量提取、废弃代码清理）
All checks were successful
构建并部署到测试环境（无 SSH） / build-and-deploy (push) Successful in 7m13s
All checks were successful
构建并部署到测试环境（无 SSH） / build-and-deploy (push) Successful in 7m13s
This commit is contained in:
46
openspec/changes/tech-debt-cleanup/proposal.md
Normal file
46
openspec/changes/tech-debt-cleanup/proposal.md
Normal file
@@ -0,0 +1,46 @@
|
||||
## 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 迁移历史将被清空）
|
||||
Reference in New Issue
Block a user