feat: 技术债务清理（支付配置动态化、API文档补全、轮询常量提取、废弃代码清理）

.sisyphus/notepads/tech-debt-cleanup/learnings.md

@@ -0,0 +1,181 @@
+# tech-debt-cleanup 学习记录
+
+## [2026-04-14] 初始化
+
+### 项目规范关键点
+- 所有注释必须使用中文
+- Redis Key 必须通过函数生成（格式：`Redis{Module}{Purpose}Key(params...)`）
+- 错误码必须定义在 `pkg/errors/codes.go`
+- 常量定义在 `pkg/constants/` 
+- 架构：Handler → Service → Store → Model
+- 禁止使用外键约束
+- 禁止 Go 测试文件（*_test.go）
+
+### 关键文件路径
+- 支付服务: `internal/service/order/service.go`, `internal/service/recharge/service.go`
+- 轮询服务: `internal/service/polling/manual_trigger_service.go`, `alert_service.go`
+- 轮询 Handler: `internal/handler/admin/polling_manual_trigger.go`
+- 轮询 Store: `internal/store/postgres/polling_manual_trigger_store.go`
+- 文档生成: `cmd/api/docs.go`, `cmd/gendocs/main.go`
+- Redis Key: `pkg/constants/redis.go`
+- 支付包: `pkg/payment/`
+- 废弃 DTO: `internal/model/dto/enterprise_card_authorization_dto.go`
+- 废弃任务: `internal/task/sync.go`
+- 空文件: `internal/routes/recharge.go`
+- Model: `internal/model/iot_card.go`, `internal/model/device.go`
+
+## [2026-04-14] Task 3: 轮询状态常量提取
+
+### 发现和注意点
+
+1. **alert_service.go 的 "pending" 只有 1 处**：`NotificationStatus: "pending"` 在 `triggerAlert()` 函数中，其他字符串如 `"sent"`、`"partial"`、`"failed"` 是通知发送状态（非轮询触发日志状态），不在替换范围内。
+
+2. **Store 层 SQL 字符串处理**：`polling_manual_trigger_store.go` 中 `GetRunning` 函数原本使用 SQL 字面量 `status IN ('pending', 'processing')`，改为 GORM 参数化查询 `status IN (?, ?)` 并传入常量，既消除硬编码又提升安全性。
+
+3. **Store 层需要新增 import**：`polling_manual_trigger_store.go` 原本未导入 `constants` 包，添加时注意 Go import 分组规范（stdlib / 第三方 / 内部包）。
+
+4. **constants 包在 handler 文件已存在**：`polling_manual_trigger.go` 已导入 `pkg/constants`，无需额外修改 import。
+
+5. **manual_trigger_service.go 共 6 处替换**：3 处 `"processing"`（triggerLog 创建）、2 处 `"completed"`（UpdateStatus 调用）、1 处同时含 `"pending"` + `"processing"` + `"cancelled"` 的 CancelTrigger 状态检查。
+
+## [2026-04-14] Task 4: 废弃代码清理
+
+### 废弃别名实际引用情况
+扫描 `internal/` 和 `pkg/` 后，真正使用废弃别名的只有 3 处（其他文件早已用新常量）：
+- `shop_commission/service.go:645` → `TransactionTypeWithdrawal` 替换为 `AgentTransactionTypeWithdrawal`
+- `recharge/service.go:91,94,417,418` → `RechargeMinAmount/RechargeMaxAmount` 替换为 `AssetRechargeMinAmount/AssetRechargeMaxAmount`（资产钱包充值场景，最小1元/最大100000元）
+
+### CheckAndStopCard 无法删除
+`stop_resume_service.go` 中的 `CheckAndStopCard` 在接口 `StopResumeServiceInterface`（`usage_service.go:20`）中声明，并在 `package_activation_handler.go`（327、347行）和 `usage_service.go`（230、255行）中活跃调用。任务描述要求"确认无调用后再删除"，此方法有调用，故跳过删除。
+
+### grep 验证注意事项
+- `SyncHandler` 的 grep 命中了 `CommissionStatsSyncHandler`（合法），不是废弃的 DataSync handler。
+- `CardWallet` 出现在 `data_scope.go:82` 的注释字符串里（非代码引用），不需要修改。
+
+### 删除的代码统计
+- `sync.go` 整个文件（166行）
+- `handler.go` 3行（syncHandler var + HandleFunc + logger.Info）
+- `constants.go` 1行（TaskTypeDataSync）
+- `wallet.go` 86行（149-234行废弃别名块）
+- `enterprise_card_authorization_dto.go` 22行（DeviceBundle、DeviceBundleCard、AllocatedDevice）
+- `order/service.go` 约243行（CreateLegacy 方法）
+
+## [2026-04-14] Task 7+8: 常量清理和空文件删除
+
+### 执行内容
+
+**Task 7.1：删除 CodeExceedLimit 错误码**
+- 删除常量定义：`CodeExceedLimit = 1055` (line 68)
+- 删除 allErrorCodes 列表条目 (line 227)
+- 删除 errorMessages 映射条目 (line 359)
+- 验证：grep 确认代码库中无任何引用
+
+**Task 7.2：为预留常量添加 [预留] 注释**
+- LadderType 系列（激活量、提货量、充值量）：添加 `[预留] 用于分佣阶梯功能，待产品规划`
+- ApprovalType/ApprovalStatus 系列（审批类型/状态）：添加 `[预留] 用于审批流程功能，待产品规划`
+- MerchantType 系列（支付宝、微信、银行卡）：添加 `[预留] 用于未来商户管理功能，待产品规划`
+- ReplacementStatus 系列（换卡申请状态）：添加 `[预留] 用于换卡申请功能，待产品规划`
+- ReplacementReason 系列（换货原因）：添加 `[预留] 用于换卡原因管理功能，待产品规划`
+
+**Task 8.1：删除空文件**
+- 删除 `internal/routes/recharge.go`（仅包含 `package routes`）
+
+**Task 8.2：删除 postgres.go 的 AutoMigrate 注释块**
+- 删除 lines 90-95 的注释掉的 AutoMigrate 代码块
+
+**Task 8.3：更新 client_order/service.go 注释**
+- 在 line 140 的实名认证检查注释前添加：`// [待确认] 业务是否需要实名认证检查？参见 tech-debt-cleanup 提案`
+
+### 验证结果
+- ✅ `go build ./cmd/api ./cmd/worker` 通过
+- ✅ `go vet ./pkg/errors/ ./pkg/constants/ ./pkg/database/` 无报告
+- ✅ `grep -r "CodeExceedLimit"` 无结果（完全删除）
+- ✅ 所有预留常量已添加 [预留] 标记和产品规划说明
+
+## [2026-04-14] Task 2: API 文档生成器补全
+
+### 发现
+
+- `BuildDocHandlers()` 缺少 3 个 Handler：`ClientAuth`、`AdminAuth`、`AssetLifecycle`，它们在 `bootstrap/types.go` 中有定义，但从未加入文档生成器
+- `AdminAuth` 在 `docs.go` 和 `gendocs/main.go` 中**完全未被设置**（连手动覆写都没有），这意味着 Admin Auth 相关路由一直缺失于 OpenAPI 文档
+- `docs.go` 和 `gendocs/main.go` 的手动覆写列表（9 行 `handlers.Xxx = ...`）中，大多数 handler 其实已经在 `BuildDocHandlers()` 中了，属于纯冗余
+
+### 操作
+
+1. `pkg/openapi/handlers.go`：按 types.go 字段顺序插入 `ClientAuth`（PersonalCustomer 后）、`AdminAuth`（ShopRole 后）、`AssetLifecycle`（Asset 后）
+2. `cmd/api/docs.go`：删除所有手动覆写行（9 行）+ 移除 `admin` 和 `apphandler` import
+3. `cmd/gendocs/main.go`：同上
+
+### 注意点
+
+- `admin.NewAuthHandler` 需要 2 个 nil 参数（authService + validator）
+- `app.NewClientAuthHandler` 需要 2 个 nil 参数（service + logger）
+- `admin.NewAssetLifecycleHandler` 只需 1 个 nil 参数（service 接口）
+- 清理完 import 后 `go build` + `go vet` 均通过，无报错
+
+## [2026-04-14] Task 5: Model 废弃字段清理
+
+### 引用情况（超出预期的额外文件）
+
+计划中列出的文件之外，还发现了额外引用：
+- `internal/service/device/service.go` line 576-577：`DeviceResponse` 构建中有引用（计划中未提及）
+- `internal/service/recharge/service.go` line 31：`ForceRechargeRequirement` struct 有 `FirstCommissionPaid` 字段
+- `internal/service/recharge/service.go` line 458：`result.FirstCommissionPaid = firstCommissionPaid` 赋值
+
+### 关键判断：recharge/service.go 的 firstCommissionPaid 变量
+
+`checkForceRechargeRequirement` 中的 `firstCommissionPaid` 变量**不是废弃字段**：
+- 它读自 `card.IsFirstRechargeTriggeredBySeries(*seriesID)` 和 `device.IsFirstRechargeTriggeredBySeries(*seriesID)`（均是新 BySeries 方法）
+- 该变量用于 `if firstCommissionPaid {` 的业务判断（已发放则跳过强充检查）
+- 正确做法：只删 `ForceRechargeRequirement.FirstCommissionPaid` 字段 + `result.FirstCommissionPaid = firstCommissionPaid` 赋值，保留变量声明和 if 判断
+
+### 迁移文件
+- 新建 `migrations/000116_remove_legacy_commission_fields.up.sql`
+- 新建 `migrations/000116_remove_legacy_commission_fields.down.sql`
+
+### 验证结果
+- ✅ `go build ./cmd/api ./cmd/worker` 通过，无任何错误
+
+## [2026-04-14] Task 1: 支付配置动态加载
+
+### 实现架构决策
+
+#### 1. PaymentConfigLoader 位置
+- 新建 `pkg/payment/loader.go`（包名 `payment`）
+- `pkg/` 下可以 import `internal/` 包（项目中已有先例：`pkg/wechat/config.go` import `internal/model`）
+
+#### 2. 缓存策略
+- 不缓存 Payment 实例（含连接/状态，不可序列化）
+- 缓存 **WechatConfig JSON 数据**（key: `payment:config:{id}`，TTL: 1 小时）
+- 每次从缓存数据构建 Payment 实例（轻量操作，无 I/O）
+
+#### 3. v2 适配器模式
+- `PaymentV2Service` 未实现完整 `PaymentServiceInterface`（缺少 H5/查单/关单/HandlePaymentNotify）
+- 通过 `v2PaymentAdapter` 包装，补全缺失方法（返回"不支持"错误）
+- **不修改** `payment_v2.go` 原文件
+
+#### 4. `appID` 来源
+- `NewPaymentAppFromConfig` / `NewPaymentV2ServiceFromConfig` 均需要 `appID` 参数
+- 使用 `wechatConfig.OaAppID`（公众号 AppID）
+
+#### 5. wechatCache 共享
+- loader 在构造时通过 `wechat.NewRedisCache(rdb)` 创建一次，所有 LoadConfig 调用复用
+- v3 Payment 实例构建需要此 cache（用于 PowerWeChat SDK 内部 token 缓存）
+
+#### 6. worker_services.go 也需更新
+- `internal/bootstrap/worker_services.go` 里有另一处 `orderSvc.New` 调用（超时取消专用）
+- 需额外传 `nil` 占位
+
+### 关键文件变更
+| 文件 | 变更内容 |
+|------|---------|
+| `pkg/constants/redis.go` | +`RedisPaymentConfigKey` |
+| `pkg/payment/loader.go` | 新建：接口 + 实现 + v2 适配器 |
+| `internal/service/order/service.go` | +`paymentLoader` 字段/参数，替换 2 处 TODO |
+| `internal/service/recharge/service.go` | +`paymentLoader` 字段/参数，更新 1 处 TODO 注释 |
+| `internal/bootstrap/services.go` | 创建 loader 实例，传入 Order/Recharge 构造函数 |
+| `internal/bootstrap/worker_services.go` | `orderSvc.New` 补传 `nil` |
+
+### 验证结果
+- ✅ `go build ./cmd/api ./cmd/worker` 通过，无任何错误
+- ✅ `go vet` 无报告