230 lines
13 KiB
Markdown
230 lines
13 KiB
Markdown
# 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` 无报告
|
||
|
||
## [2026-04-14] Task 6: DTO _name 字段补全
|
||
|
||
### 概述
|
||
为所有 Response DTO 中的 `int` 类型状态字段补全对应 `string` 类型 `_name` 字段，并在 Service 层赋值。
|
||
|
||
### 常量映射函数（新增）
|
||
|
||
**`pkg/constants/constants.go`：**
|
||
- `GetStatusName(status int) string` — 通用 0=禁用/1=启用
|
||
- `GetShelfStatusName(status int) string` — 1=上架/2=下架
|
||
- `GetExchangeStatusName(status int) string` — 换货单状态
|
||
|
||
**`pkg/constants/iot.go`：**
|
||
- `GetIotCardStatusName` — 1=在库, 2=已分销, 3=已激活, 4=已停用
|
||
- `GetActivationStatusName` — 0=未激活, 1=已激活
|
||
- `GetRealNameStatusName` — 0=未实名, 1=已实名
|
||
- `GetNetworkStatusName` — 0=停机, 1=开机
|
||
- `GetCommissionRecordStatusName` — 1=已冻结/2=解冻中/3=已发放/4=已失效/99=待人工修正
|
||
- `GetOrderPaymentStatusName` — 1=待支付/2=已支付/3=已取消/4=已退款
|
||
- `GetOrderCommissionStatusName` — 1=待计算/2=已计算
|
||
- `GetRefundStatusName` — 1=待审批/2=已通过/3=已拒绝/4=已退回
|
||
|
||
### 模块处理情况
|
||
|
||
| 模块 | DTO 改动 | Service 赋值位置 | 备注 |
|
||
|------|---------|-----------------|------|
|
||
| Account | `AccountResponse` + `status_name` | `toAccountResponse()` | constants 已导入 |
|
||
| Shop | `ShopResponse` + `status_name` | Create/Update/ListShopResponses（3处）| constants 已导入 |
|
||
| IotCard | `StandaloneIotCardResponse` + 4个 `_name` 字段 | `toStandaloneResponse()` | status/activation/realname/network |
|
||
| Order | `OrderResponse` + `commission_status_name` | `buildOrderResponse()` | payment_status 已有 `_text` 字段 |
|
||
| Package | `PackageResponse` + `status_name`/`shelf_status_name` | `toResponse()` 末尾（agent 覆盖后赋值） | my_package.go 也同步更新（不涉及 service）|
|
||
| Refund | `RefundResponse` + `status_name` | `buildRefundResponse()` | constants 已导入 |
|
||
| Device | `DeviceCardBindingResponse` + `status_name` | `device/binding.go` | 新增 constants import |
|
||
| Asset | `AssetResolveResponse` + `status_name` | `buildDeviceResolveResponse` + `buildCardResolveResponse` | constants 已导入 |
|
||
| Commission | `CommissionRecordResponse` + `status_name` | 未找到 service 调用（DTO 未被使用，ShopCommissionRecordItem 已有 status_name）| 仅 DTO 更新；同时修正了 description 错误 |
|
||
| Client Asset | `AssetInfoResponse` + 4个 `_name` 字段 | handler `client_asset.go`（直接赋值）| constants 已导入 |
|
||
| Client Order | `ClientOrderInfo/ListItem/DetailResponse` + `payment_status_name`; `ClientRechargeInfo` + `status_name` | `client_order/service.go` | 增加 `clientRechargeStatusName` 辅助函数 |
|
||
| MyPackage | `MyPackageResponse/DetailResponse` + `status_name`/`shelf_status_name`; `MySeriesAllocationResponse` + `status_name` | 未找到 service 调用，仅 DTO 更新 | |
|
||
|
||
### 关键发现
|
||
1. `CommissionRecordResponse.status` description 原先错误（写的 "1:已入账" 但常量是 "1:已冻结"），已修正为正确值
|
||
2. `ClientRechargeInfo.Status` 使用的是 `rechargeStatusToClientStatus()` 转换后的值（0/1/2），与 RechargeStatus* 常量不同
|
||
3. 部分 DTO（MyPackage、CommissionRecord）未被 service 层引用，仅更新 DTO 定义
|
||
4. `DeviceResponse` 和 `ImportTaskResponse` 已经有 `status_name` 和 `status_text` 字段，无需修改
|
||
|
||
### 验证结果
|
||
- ✅ `go build ./cmd/api ./cmd/worker` 通过，无任何错误
|