From 42c5ec912f2250a0b5ae56f5d7eb322de218c6e2 Mon Sep 17 00:00:00 2001 From: huang Date: Tue, 14 Apr 2026 11:11:15 +0800 Subject: [PATCH] =?UTF-8?q?feat:=20=E6=8A=80=E6=9C=AF=E5=80=BA=E5=8A=A1?= =?UTF-8?q?=E6=B8=85=E7=90=86=EF=BC=88=E6=94=AF=E4=BB=98=E9=85=8D=E7=BD=AE?= =?UTF-8?q?=E5=8A=A8=E6=80=81=E5=8C=96=E3=80=81API=E6=96=87=E6=A1=A3?= =?UTF-8?q?=E8=A1=A5=E5=85=A8=E3=80=81=E8=BD=AE=E8=AF=A2=E5=B8=B8=E9=87=8F?= =?UTF-8?q?=E6=8F=90=E5=8F=96=E3=80=81=E5=BA=9F=E5=BC=83=E4=BB=A3=E7=A0=81?= =?UTF-8?q?=E6=B8=85=E7=90=86=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .sisyphus/boulder.json | 12 +- .../notepads/tech-debt-cleanup/decisions.md | 15 + .../notepads/tech-debt-cleanup/issues.md | 5 + .../notepads/tech-debt-cleanup/learnings.md | 181 ++++++++ .sisyphus/plans/tech-debt-cleanup.md | 108 +++++ cmd/api/docs.go | 15 +- cmd/gendocs/main.go | 13 +- internal/bootstrap/services.go | 8 +- internal/bootstrap/worker_services.go | 1 + .../handler/admin/polling_manual_trigger.go | 8 +- internal/model/device.go | 4 +- internal/model/dto/account_dto.go | 1 + internal/model/dto/asset_dto.go | 29 +- internal/model/dto/client_asset_dto.go | 38 +- internal/model/dto/commission.go | 3 +- internal/model/dto/device_dto.go | 43 +- .../dto/enterprise_card_authorization_dto.go | 23 - internal/model/dto/iot_card_dto.go | 6 +- internal/model/dto/my_package.go | 5 + internal/model/dto/order_dto.go | 1 + internal/model/dto/package_dto.go | 2 + internal/model/dto/recharge.go | 2 - internal/model/dto/refund_dto.go | 1 + internal/model/dto/shop_dto.go | 1 + internal/model/iot_card.go | 2 - internal/routes/recharge.go | 1 - internal/service/account/service.go | 1 + internal/service/asset/service.go | 98 ++-- internal/service/client_order/service.go | 1 + internal/service/device/binding.go | 4 +- internal/service/device/service.go | 48 +- internal/service/exchange/migration.go | 4 - internal/service/iot_card/service.go | 6 +- internal/service/order/service.go | 287 ++---------- internal/service/package/service.go | 2 + internal/service/polling/alert_service.go | 2 +- .../service/polling/manual_trigger_service.go | 14 +- internal/service/recharge/service.go | 16 +- internal/service/refund/service.go | 1 + internal/service/shop/service.go | 3 + internal/service/shop_commission/service.go | 2 +- .../postgres/polling_manual_trigger_store.go | 5 +- internal/task/sync.go | 166 ------- ...6_remove_legacy_commission_fields.down.sql | 5 + ...116_remove_legacy_commission_fields.up.sql | 6 + .../changes/tech-debt-cleanup/.openspec.yaml | 2 + openspec/changes/tech-debt-cleanup/design.md | 340 ++++++++++++++ .../changes/tech-debt-cleanup/proposal.md | 46 ++ .../specs/api-doc-coverage/spec.md | 45 ++ .../specs/dto-name-fields/spec.md | 83 ++++ .../specs/payment-dynamic-config/spec.md | 69 +++ .../specs/polling-status-constants/spec.md | 44 ++ openspec/changes/tech-debt-cleanup/tasks.md | 435 ++++++++++++++++++ pkg/constants/constants.go | 46 +- pkg/constants/iot.go | 177 ++++++- pkg/constants/polling.go | 12 + pkg/constants/redis.go | 12 + pkg/constants/wallet.go | 87 ---- pkg/database/postgres.go | 6 - pkg/errors/codes.go | 3 - pkg/openapi/handlers.go | 3 + pkg/payment/loader.go | 141 ++++++ pkg/queue/handler.go | 4 - 63 files changed, 1979 insertions(+), 775 deletions(-) create mode 100644 .sisyphus/notepads/tech-debt-cleanup/decisions.md create mode 100644 .sisyphus/notepads/tech-debt-cleanup/issues.md create mode 100644 .sisyphus/notepads/tech-debt-cleanup/learnings.md create mode 100644 .sisyphus/plans/tech-debt-cleanup.md delete mode 100644 internal/routes/recharge.go delete mode 100644 internal/task/sync.go create mode 100644 migrations/000116_remove_legacy_commission_fields.down.sql create mode 100644 migrations/000116_remove_legacy_commission_fields.up.sql create mode 100644 openspec/changes/tech-debt-cleanup/.openspec.yaml create mode 100644 openspec/changes/tech-debt-cleanup/design.md create mode 100644 openspec/changes/tech-debt-cleanup/proposal.md create mode 100644 openspec/changes/tech-debt-cleanup/specs/api-doc-coverage/spec.md create mode 100644 openspec/changes/tech-debt-cleanup/specs/dto-name-fields/spec.md create mode 100644 openspec/changes/tech-debt-cleanup/specs/payment-dynamic-config/spec.md create mode 100644 openspec/changes/tech-debt-cleanup/specs/polling-status-constants/spec.md create mode 100644 openspec/changes/tech-debt-cleanup/tasks.md create mode 100644 pkg/payment/loader.go diff --git a/.sisyphus/boulder.json b/.sisyphus/boulder.json index 4388c06..98fec88 100644 --- a/.sisyphus/boulder.json +++ b/.sisyphus/boulder.json @@ -1,12 +1,12 @@ { - "active_plan": "/Users/break/csxjProject/junhong_cmp_fiber/.sisyphus/plans/realname-trigger-priority-enhancement.md", - "started_at": "2026-04-13T06:40:48.711Z", + "active_plan": "/Users/break/csxjProject/junhong_cmp_fiber/.sisyphus/plans/tech-debt-cleanup.md", + "started_at": "2026-04-14T02:13:33.272Z", "session_ids": [ - "ses_27a6dbcacffe7LBhCAdrKJVgDi" + "ses_2763c0ebcffexMb1ee6rY7gHOT" ], "session_origins": { - "ses_27a6dbcacffe7LBhCAdrKJVgDi": "direct" + "ses_2763c0ebcffexMb1ee6rY7gHOT": "start-work" }, - "plan_name": "realname-trigger-priority-enhancement", + "plan_name": "tech-debt-cleanup", "agent": "atlas" -} \ No newline at end of file +} diff --git a/.sisyphus/notepads/tech-debt-cleanup/decisions.md b/.sisyphus/notepads/tech-debt-cleanup/decisions.md new file mode 100644 index 0000000..f84a94c --- /dev/null +++ b/.sisyphus/notepads/tech-debt-cleanup/decisions.md @@ -0,0 +1,15 @@ +# tech-debt-cleanup 决策记录 + +## [2026-04-14] 初始化 + +### 任务执行顺序策略 +1. **优先执行独立任务（并行）**：Task 2 (API docs)、Task 3 (polling constants)、Task 4 (deprecated cleanup)、Task 7 (unused constants)、Task 8 (empty files) +2. **Task 1（支付配置）**：需要先确认 pkg/payment/ 现有结构 +3. **Task 5（Model 字段）**：代码变更可与其他任务并行，DB 迁移执行需 DB 环境 +4. **Task 6（DTO _name）**：分模块逐批，每批独立验证 +5. **Task 0（DB迁移合并）**：需要 DB 环境，最后执行 + +### 支付配置动态加载架构 +- 新建 `pkg/payment/loader.go`，定义 `PaymentConfigLoader` 接口 +- Redis 缓存 TTL 1h，key: `payment:config:{configID}` +- 权限检查：仅用户主动操作时校验；支付回调场景验证商户号一致性 diff --git a/.sisyphus/notepads/tech-debt-cleanup/issues.md b/.sisyphus/notepads/tech-debt-cleanup/issues.md new file mode 100644 index 0000000..ee5193e --- /dev/null +++ b/.sisyphus/notepads/tech-debt-cleanup/issues.md @@ -0,0 +1,5 @@ +# tech-debt-cleanup 问题记录 + +## [2026-04-14] 初始化 + +暂无已知问题。执行过程中发现的问题将记录于此。 diff --git a/.sisyphus/notepads/tech-debt-cleanup/learnings.md b/.sisyphus/notepads/tech-debt-cleanup/learnings.md new file mode 100644 index 0000000..1641f4c --- /dev/null +++ b/.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` 无报告 diff --git a/.sisyphus/plans/tech-debt-cleanup.md b/.sisyphus/plans/tech-debt-cleanup.md new file mode 100644 index 0000000..088f503 --- /dev/null +++ b/.sisyphus/plans/tech-debt-cleanup.md @@ -0,0 +1,108 @@ +# tech-debt-cleanup 执行计划 + +## TL;DR + +> **快速摘要**：清理项目技术债务：API 文档补全（18.75% → 100%）、支付配置动态化、轮询常量提取、废弃代码清理、Model 字段清理、DTO _name 字段补全、数据库迁移基线合并。 +> +> **提案文件**：`openspec/changes/tech-debt-cleanup/` + +--- + +## TODOs + +### Task 1: 支付配置动态加载（pkg/payment + service层） + +- [x] 1.1 在 `pkg/constants/redis.go` 中新增 `RedisPaymentConfigKey(configID uint) string` 函数 +- [x] 1.2 确认 `pkg/payment/` 包中现有支付接口定义 +- [x] 1.3 创建 `pkg/payment/loader.go`，定义 `PaymentConfigLoader` 接口和实现（Redis 缓存 TTL 1h） +- [x] 1.4 修改 `internal/service/order/service.go`，注入 paymentLoader，替换两处 TODO +- [x] 1.5 修改 `internal/service/recharge/service.go`，注入 paymentLoader，替换 TODO +- [x] 1.7 运行 `go build ./cmd/api ./cmd/worker` 确认编译，`go vet` 静态分析 + +### Task 2: API 文档生成器补全（docs.go + gendocs） + +- [x] 2.1 修改 `cmd/api/docs.go`，注册所有 48 个 Handler（含 39 个缺失 Handler） +- [x] 2.2 修改 `cmd/gendocs/main.go`，同步注册所有 48 个 Handler +- [x] 2.3 运行 `go run cmd/gendocs/main.go` 生成 OpenAPI 文档，验证覆盖率 +- [x] 2.4 人工核查生成文档接口数量与路由注册数量一致 + +### Task 3: 轮询状态常量提取（pkg/constants + handler/service/store） + +- [x] 3.1 在 `pkg/constants/polling.go` 中新增轮询手动触发日志状态常量（4 个） +- [x] 3.2 修改 `internal/handler/admin/polling_manual_trigger.go`，替换硬编码字符串为常量 +- [x] 3.3 修改 `internal/service/polling/manual_trigger_service.go`，替换硬编码字符串 +- [x] 3.4 修改 `internal/store/postgres/polling_manual_trigger_store.go`，替换硬编码字符串 +- [x] 3.5 修改 `internal/service/polling/alert_service.go`，替换 NotificationStatus 中的硬编码 +- [x] 3.6 运行 grep 确认无剩余硬编码，`go vet` 静态分析 + +### Task 4: 废弃代码清理（sync.go + wallet.go + DTO + 方法） + +- [x] 4.1 删除 `internal/task/sync.go`，清理 queue/handler.go 注册和 constants.go 中的 TaskTypeDataSync +- [x] 4.2 全局搜索 wallet.go 中 15 个废弃别名的引用情况 +- [x] 4.3 替换所有有引用的废弃别名为新常量 +- [x] 4.4 删除 `pkg/constants/wallet.go` 中所有 Deprecated 别名定义（15 个） +- [x] 4.5 删除 `internal/model/dto/enterprise_card_authorization_dto.go` 中的 3 个废弃 DTO 类型 +- [x] 4.6 删除 `internal/service/order/service.go` 中的 `CreateLegacy()` 方法 +- [x] 4.7 [跳过] `CheckAndStopCard()` 仍在 StopResumeServiceInterface 接口中且被活跃调用，不是废弃代码 +- [x] 4.8 运行 `go build ./cmd/api ./cmd/worker` 和 `go vet` 确认编译无误 + +### Task 5: Model 废弃字段删除与数据库迁移 + +- [x] 5.1 从 `internal/model/iot_card.go` 中删除 `FirstCommissionPaid` 和 `AccumulatedRecharge` 字段 +- [x] 5.2 从 `internal/model/device.go` 中删除 `FirstCommissionPaid` 和 `AccumulatedRecharge` 字段 +- [x] 5.3 创建 `migrations/000116_remove_legacy_commission_fields.up.sql`（DROP COLUMN） +- [x] 5.4 创建 `migrations/000116_remove_legacy_commission_fields.down.sql`（ADD COLUMN 回滚） +- [ ] 5.5 在测试环境执行迁移，通过 PostgreSQL MCP 确认字段已删除（需 DB 环境） +- [x] 5.6 运行 `go build ./cmd/api ./cmd/worker` 确认编译通过 + +### Task 6: DTO _name 字段补全（分模块逐批） + +- [ ] 6.1 遍历 `internal/model/dto/` 统计所有 int 状态字段缺少 _name 字段的清单 +- [ ] 6.2 **Account 模块**：补全 DTO _name 字段 + 常量映射函数 + Service 层赋值 +- [ ] 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 等）：批量补全 +- [ ] 6.8 全量编译与静态分析（`go build + go vet`） +- [ ] 6.9 使用 curl/Postman 抽查各模块接口，确认 _name 字段有值且正确 + +### Task 7: 未使用常量和错误码清理 + +- [x] 7.1 删除 `pkg/errors/codes.go` 中的 `CodeExceedLimit` 常量和对应错误消息映射 +- [x] 7.2 为 `pkg/constants/iot.go` 中约 22 个未引用的预留常量添加用途注释 +- [x] 7.3 运行 `go build` 和 `go vet` 确认清理无破坏 + +### Task 8: 删除空文件和注释代码 + +- [x] 8.1 删除 `internal/routes/recharge.go` 空文件 +- [x] 8.2 删除 `pkg/database/postgres.go` 中的 AutoMigrate 注释块（行 90-95） +- [x] 8.3 保留 `internal/service/client_order/service.go` 中的实名认证检查注释，添加待确认标记 + +### Task 9: 全量编译验证 + +- [ ] 9.1 运行 `go mod tidy` 确认依赖无变化 +- [ ] 9.2 运行 `go build ./cmd/api` 和 `go build ./cmd/worker` 确认编译通过 +- [ ] 9.3 运行 `go vet ./...` 进行静态分析 +- [ ] 9.4 运行 `gofmt -l ./internal ./pkg` 检查代码格式 + +### Task 0: 数据库迁移文件合并为生产基线（需 DB 环境） + +- [ ] 0.1 确认当前数据库 schema 完整可用（服务启动无错误） +- [ ] 0.2 使用 pg_dump 生成当前完整 schema（仅 DDL）→ `migrations/000114_squash_baseline.up.sql` +- [ ] 0.3 编写 `migrations/000114_squash_baseline.down.sql`（DROP 所有表） +- [ ] 0.4 创建 `migrations/000115_init_data.up.sql`（合并轮询配置初始数据 + purchase_role 回填） +- [ ] 0.5 创建 `migrations/000115_init_data.down.sql`（回滚初始数据） +- [ ] 0.6 归档旧迁移文件到 `migrations/archive/`（000000~000113 + backfill 脚本） +- [ ] 0.7 编写测试环境重置脚本 `scripts/reset_db.sh` +- [ ] 0.8 在全新数据库上验证 migrate up 完整链路 +- [ ] 0.9 重置测试环境数据库，切换到新基线 + +--- + +## Final Verification Wave + +- [ ] F1 全量编译通过：`go build ./cmd/api ./cmd/worker` 无错误 +- [ ] F2 静态分析通过：`go vet ./...` 无报告，`gofmt -l` 无格式问题 +- [ ] F3 API 文档覆盖率 100%：`go run cmd/gendocs/main.go` 生成文档包含 48/48 Handler +- [ ] F4 核心功能验证：支付、轮询、账号管理等模块接口正常响应，_name 字段有值 diff --git a/cmd/api/docs.go b/cmd/api/docs.go index df82a08..f51356b 100644 --- a/cmd/api/docs.go +++ b/cmd/api/docs.go @@ -5,8 +5,6 @@ import ( "go.uber.org/zap" "github.com/break/junhong_cmp_fiber/internal/bootstrap" - "github.com/break/junhong_cmp_fiber/internal/handler/admin" - apphandler "github.com/break/junhong_cmp_fiber/internal/handler/app" "github.com/break/junhong_cmp_fiber/internal/routes" "github.com/break/junhong_cmp_fiber/pkg/openapi" ) @@ -22,22 +20,13 @@ func generateOpenAPIDocs(outputPath string, logger *zap.Logger) { // 2. 创建临时 Fiber App 用于路由注册 app := fiber.New() - // 3. 创建 Handler（使用 nil 依赖,因为只需要路由结构） + // 3. 创建所有 Handler（使用 nil 依赖，因为只需要路由结构） handlers := openapi.BuildDocHandlers() - handlers.AssetLifecycle = admin.NewAssetLifecycleHandler(nil) - handlers.ClientAuth = apphandler.NewClientAuthHandler(nil, nil) - handlers.ClientAsset = apphandler.NewClientAssetHandler(nil, nil, nil, nil, nil, nil, nil, nil, nil) - handlers.ClientWallet = apphandler.NewClientWalletHandler(nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil) - handlers.ClientOrder = apphandler.NewClientOrderHandler(nil, nil) - handlers.ClientExchange = apphandler.NewClientExchangeHandler(nil) - handlers.ClientRealname = apphandler.NewClientRealnameHandler(nil, nil, nil, nil, nil, nil, nil, nil) - handlers.ClientDevice = apphandler.NewClientDeviceHandler(nil, nil, nil, nil, nil, nil, nil) - handlers.AdminExchange = admin.NewExchangeHandler(nil, nil) // 4. 注册所有路由到文档生成器 routes.RegisterRoutesWithDoc(app, handlers, &bootstrap.Middlewares{}, adminDoc) - // 6. 保存规范到指定路径 + // 5. 保存规范到指定路径 if err := adminDoc.Save(outputPath); err != nil { logger.Error("生成 OpenAPI 文档失败", zap.String("path", outputPath), zap.Error(err)) return diff --git a/cmd/gendocs/main.go b/cmd/gendocs/main.go index a6f541f..ba9feca 100644 --- a/cmd/gendocs/main.go +++ b/cmd/gendocs/main.go @@ -7,8 +7,6 @@ import ( "github.com/gofiber/fiber/v2" "github.com/break/junhong_cmp_fiber/internal/bootstrap" - "github.com/break/junhong_cmp_fiber/internal/handler/admin" - apphandler "github.com/break/junhong_cmp_fiber/internal/handler/app" "github.com/break/junhong_cmp_fiber/internal/routes" "github.com/break/junhong_cmp_fiber/pkg/openapi" ) @@ -31,17 +29,8 @@ func generateAdminDocs(outputPath string) error { // 2. 创建临时 Fiber App 用于路由注册 app := fiber.New() - // 3. 创建 Handler（使用 nil 依赖,因为只需要路由结构） + // 3. 创建所有 Handler（使用 nil 依赖，因为只需要路由结构） handlers := openapi.BuildDocHandlers() - handlers.AssetLifecycle = admin.NewAssetLifecycleHandler(nil) - handlers.ClientAuth = apphandler.NewClientAuthHandler(nil, nil) - handlers.ClientAsset = apphandler.NewClientAssetHandler(nil, nil, nil, nil, nil, nil, nil, nil, nil) - handlers.ClientWallet = apphandler.NewClientWalletHandler(nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil) - handlers.ClientOrder = apphandler.NewClientOrderHandler(nil, nil) - handlers.ClientExchange = apphandler.NewClientExchangeHandler(nil) - handlers.ClientRealname = apphandler.NewClientRealnameHandler(nil, nil, nil, nil, nil, nil, nil, nil) - handlers.ClientDevice = apphandler.NewClientDeviceHandler(nil, nil, nil, nil, nil, nil, nil) - handlers.AdminExchange = admin.NewExchangeHandler(nil, nil) // 4. 注册所有路由到文档生成器 routes.RegisterRoutesWithDoc(app, handlers, &bootstrap.Middlewares{}, adminDoc) diff --git a/internal/bootstrap/services.go b/internal/bootstrap/services.go index 3bf29d6..4780dd4 100644 --- a/internal/bootstrap/services.go +++ b/internal/bootstrap/services.go @@ -18,6 +18,7 @@ import ( commissionWithdrawalSettingSvc "github.com/break/junhong_cmp_fiber/internal/service/commission_withdrawal_setting" "github.com/break/junhong_cmp_fiber/internal/store/postgres" "github.com/break/junhong_cmp_fiber/pkg/constants" + "github.com/break/junhong_cmp_fiber/pkg/payment" assetSvc "github.com/break/junhong_cmp_fiber/internal/service/asset" assetWalletSvc "github.com/break/junhong_cmp_fiber/internal/service/asset_wallet" @@ -125,6 +126,9 @@ func initServices(s *stores, deps *Dependencies) *services { // 创建支付配置服务（Order 和 Recharge 依赖） wechatConfig := wechatConfigSvc.New(s.WechatConfig, s.Order, s.AssetRecharge, s.AgentRecharge, accountAudit, deps.Redis, deps.Logger) + // 创建支付配置动态加载器（Order 和 Recharge 依赖） + paymentLoader := payment.NewPaymentConfigLoader(s.WechatConfig, deps.Redis, deps.Logger) + packageActivation := packageSvc.NewActivationService( deps.DB, deps.Redis, @@ -199,9 +203,9 @@ func initServices(s *stores, deps *Dependencies) *services { ShopSeriesGrant: shopSeriesGrantSvc.New(deps.DB, s.ShopSeriesAllocation, s.ShopPackageAllocation, s.ShopPackageAllocationPriceHistory, s.Shop, s.Package, s.PackageSeries, deps.Logger), CommissionStats: commissionStatsSvc.New(s.ShopSeriesCommissionStats), PurchaseValidation: purchaseValidation, - Order: orderSvc.New(deps.DB, deps.Redis, s.Order, s.OrderItem, s.AgentWallet, s.AssetWallet, purchaseValidation, s.ShopPackageAllocation, s.ShopSeriesAllocation, s.IotCard, s.Device, s.PackageSeries, s.PackageUsage, s.Package, wechatConfig, deps.WechatPayment, deps.QueueClient, deps.Logger, s.AssetIdentifier, s.PersonalCustomer, s.PersonalCustomerPhone), + Order: orderSvc.New(deps.DB, deps.Redis, s.Order, s.OrderItem, s.AgentWallet, s.AssetWallet, purchaseValidation, s.ShopPackageAllocation, s.ShopSeriesAllocation, s.IotCard, s.Device, s.PackageSeries, s.PackageUsage, s.Package, wechatConfig, deps.WechatPayment, paymentLoader, deps.QueueClient, deps.Logger, s.AssetIdentifier, s.PersonalCustomer, s.PersonalCustomerPhone), Exchange: exchangeSvc.New(deps.DB, s.ExchangeOrder, s.IotCard, s.Device, s.AssetWallet, s.AssetWalletTransaction, s.PackageUsage, s.PackageUsageDailyRecord, s.ResourceTag, s.PersonalCustomerDevice, deps.Logger), - Recharge: rechargeSvc.New(deps.DB, s.AssetRecharge, s.AssetWallet, s.AssetWalletTransaction, s.IotCard, s.Device, s.ShopSeriesAllocation, s.PackageSeries, s.CommissionRecord, wechatConfig, deps.Logger, deps.QueueClient), + Recharge: rechargeSvc.New(deps.DB, s.AssetRecharge, s.AssetWallet, s.AssetWalletTransaction, s.IotCard, s.Device, s.ShopSeriesAllocation, s.PackageSeries, s.CommissionRecord, wechatConfig, paymentLoader, deps.Logger, deps.QueueClient), PollingConfig: pollingSvc.NewConfigService(s.PollingConfig), PollingConcurrency: pollingSvc.NewConcurrencyService(s.PollingConcurrencyConfig, deps.Redis), PollingMonitoring: pollingSvc.NewMonitoringService(deps.Redis), diff --git a/internal/bootstrap/worker_services.go b/internal/bootstrap/worker_services.go index b697a8a..52700a5 100644 --- a/internal/bootstrap/worker_services.go +++ b/internal/bootstrap/worker_services.go @@ -98,6 +98,7 @@ func initWorkerServices(stores *queue.WorkerStores, deps *WorkerDependencies) *q stores.Package, nil, // wechatConfigService: 超时取消不需要 nil, // wechatPayment: 超时取消不需要 + nil, // paymentLoader: 超时取消不需要 nil, // queueClient: 超时取消不触发分佣 deps.Logger, stores.AssetIdentifier, diff --git a/internal/handler/admin/polling_manual_trigger.go b/internal/handler/admin/polling_manual_trigger.go index 86cb5be..144c167 100644 --- a/internal/handler/admin/polling_manual_trigger.go +++ b/internal/handler/admin/polling_manual_trigger.go @@ -293,13 +293,13 @@ func (h *PollingManualTriggerHandler) getTriggerTypeName(triggerType string) str func (h *PollingManualTriggerHandler) getStatusName(status string) string { switch status { - case "pending": + case constants.PollingManualTriggerStatusPending: return "待处理" - case "processing": + case constants.PollingManualTriggerStatusProcessing: return "处理中" - case "completed": + case constants.PollingManualTriggerStatusCompleted: return "已完成" - case "cancelled": + case constants.PollingManualTriggerStatusCancelled: return "已取消" default: return status diff --git a/internal/model/device.go b/internal/model/device.go index 3ecd4fb..ab808fb 100644 --- a/internal/model/device.go +++ b/internal/model/device.go @@ -31,14 +31,12 @@ type Device struct { DevicePasswordEncrypted string `gorm:"column:device_password_encrypted;type:varchar(255);comment:设备登录密码(加密)" json:"device_password_encrypted"` DeviceAPIEndpoint string `gorm:"column:device_api_endpoint;type:varchar(500);comment:设备API端点" json:"device_api_endpoint"` SeriesID *uint `gorm:"column:series_id;index;comment:套餐系列ID(关联PackageSeries)" json:"series_id,omitempty"` - FirstCommissionPaid bool `gorm:"column:first_commission_paid;type:boolean;default:false;comment:一次性佣金是否已发放(废弃,使用按系列追踪)" json:"first_commission_paid"` - AccumulatedRecharge int64 `gorm:"column:accumulated_recharge;type:bigint;default:0;comment:累计充值金额(分,废弃,使用按系列追踪)" json:"accumulated_recharge"` AccumulatedRechargeBySeriesJSON string `gorm:"column:accumulated_recharge_by_series;type:jsonb;default:'{}';comment:按套餐系列追踪的累计充值金额" json:"-"` FirstRechargeTriggeredBySeriesJSON string `gorm:"column:first_recharge_triggered_by_series;type:jsonb;default:'{}';comment:按套餐系列追踪的首充触发状态" json:"-"` AssetStatus int `gorm:"column:asset_status;type:int;not null;default:1;comment:业务状态 1-在库 2-已销售 3-已换货 4-已停用" json:"asset_status"` Generation int `gorm:"column:generation;type:int;not null;default:1;comment:资产世代编号" json:"generation"` // EnablePolling 是否参与轮询，false 时设备下所有卡不加入轮询队列 - EnablePolling bool `gorm:"column:enable_polling;not null;default:true" json:"enable_polling"` + EnablePolling bool `gorm:"column:enable_polling;not null;default:true" json:"enable_polling"` // 以下字段由 Gateway sync-info 接口同步，有离线存储意义 OnlineStatus int `gorm:"column:online_status;type:int;not null;default:0;comment:在线状态：0未知 1在线 2离线" json:"online_status"` LastOnlineTime *time.Time `gorm:"column:last_online_time;comment:最后在线时间（来自 Gateway sync-info）" json:"last_online_time,omitempty"` diff --git a/internal/model/dto/account_dto.go b/internal/model/dto/account_dto.go index f02b661..ca911fc 100644 --- a/internal/model/dto/account_dto.go +++ b/internal/model/dto/account_dto.go @@ -41,6 +41,7 @@ type AccountResponse struct { EnterpriseID *uint `json:"enterprise_id,omitempty" description:"关联企业ID"` EnterpriseName string `json:"enterprise_name,omitempty" description:"企业名称"` Status int `json:"status" description:"状态 (0:禁用, 1:启用)"` + StatusName string `json:"status_name" description:"状态名称（中文）"` Creator uint `json:"creator" description:"创建人ID"` Updater uint `json:"updater" description:"更新人ID"` CreatedAt string `json:"created_at" description:"创建时间"` diff --git a/internal/model/dto/asset_dto.go b/internal/model/dto/asset_dto.go index 3af1f3e..8c0084f 100644 --- a/internal/model/dto/asset_dto.go +++ b/internal/model/dto/asset_dto.go @@ -4,21 +4,20 @@ import "time" // AssetResolveResponse 统一资产解析响应 type AssetResolveResponse struct { - AssetType string `json:"asset_type" description:"资产类型：card 或 device"` - AssetID uint `json:"asset_id" description:"资产数据库ID"` - Identifier string `json:"identifier,omitempty" description:"解析时使用的标识符"` - VirtualNo string `json:"virtual_no" description:"虚拟号"` - Status int `json:"status" description:"资产状态"` - BatchNo string `json:"batch_no" description:"批次号"` - ShopID *uint `json:"shop_id,omitempty" description:"所属店铺ID"` - ShopName string `json:"shop_name,omitempty" description:"所属店铺名称"` - SeriesID *uint `json:"series_id,omitempty" description:"套餐系列ID"` - SeriesName string `json:"series_name,omitempty" description:"套餐系列名称"` - FirstCommissionPaid bool `json:"first_commission_paid" description:"一次性佣金是否已发放"` - AccumulatedRecharge int64 `json:"accumulated_recharge" description:"累计充值金额(分)"` - ActivatedAt *time.Time `json:"activated_at,omitempty" description:"激活时间"` - CreatedAt time.Time `json:"created_at" description:"创建时间"` - UpdatedAt time.Time `json:"updated_at" description:"更新时间"` + AssetType string `json:"asset_type" description:"资产类型：card 或 device"` + AssetID uint `json:"asset_id" description:"资产数据库ID"` + Identifier string `json:"identifier,omitempty" description:"解析时使用的标识符"` + VirtualNo string `json:"virtual_no" description:"虚拟号"` + Status int `json:"status" description:"资产状态 (1:在库, 2:已分销, 3:已激活, 4:已停用)"` + StatusName string `json:"status_name" description:"资产状态名称（中文）"` + BatchNo string `json:"batch_no" description:"批次号"` + ShopID *uint `json:"shop_id,omitempty" description:"所属店铺ID"` + ShopName string `json:"shop_name,omitempty" description:"所属店铺名称"` + SeriesID *uint `json:"series_id,omitempty" description:"套餐系列ID"` + SeriesName string `json:"series_name,omitempty" description:"套餐系列名称"` + ActivatedAt *time.Time `json:"activated_at,omitempty" description:"激活时间"` + CreatedAt time.Time `json:"created_at" description:"创建时间"` + UpdatedAt time.Time `json:"updated_at" description:"更新时间"` // 状态聚合字段 RealNameStatus int `json:"real_name_status" description:"实名状态：0未实名 1已实名"` RealNameAt *time.Time `json:"real_name_at" description:"最近一次完成实名的时间，未实名时为 null"` diff --git a/internal/model/dto/client_asset_dto.go b/internal/model/dto/client_asset_dto.go index 9b5e4e4..f1ed134 100644 --- a/internal/model/dto/client_asset_dto.go +++ b/internal/model/dto/client_asset_dto.go @@ -18,16 +18,18 @@ type AssetInfoResponse struct { BoundPhone string `json:"bound_phone" description:"当前登录用户绑定的手机号"` // === 基础信息（通用） === - AssetType string `json:"asset_type" description:"资产类型（card:卡, device:设备）"` - AssetID uint `json:"asset_id" description:"资产ID"` - Identifier string `json:"identifier" description:"资产标识符"` - VirtualNo string `json:"virtual_no" description:"虚拟号"` - Status int `json:"status" description:"状态（1:在库, 2:已分销, 3:已激活, 4:已停用）"` - RealNameStatus int `json:"real_name_status" description:"实名状态（0:未实名, 1:已实名）"` - CarrierName string `json:"carrier_name" description:"运营商名称"` - Generation string `json:"generation" description:"世代"` - WalletBalance int64 `json:"wallet_balance" description:"钱包余额（分）"` - ActivatedAt *time.Time `json:"activated_at,omitempty" description:"激活时间"` + AssetType string `json:"asset_type" description:"资产类型（card:卡, device:设备）"` + AssetID uint `json:"asset_id" description:"资产ID"` + Identifier string `json:"identifier" description:"资产标识符"` + VirtualNo string `json:"virtual_no" description:"虚拟号"` + Status int `json:"status" description:"状态（1:在库, 2:已分销, 3:已激活, 4:已停用）"` + StatusName string `json:"status_name" description:"状态名称（中文）"` + RealNameStatus int `json:"real_name_status" description:"实名状态（0:未实名, 1:已实名）"` + RealNameStatusName string `json:"real_name_status_name" description:"实名状态名称（中文）"` + CarrierName string `json:"carrier_name" description:"运营商名称"` + Generation string `json:"generation" description:"世代"` + WalletBalance int64 `json:"wallet_balance" description:"钱包余额（分）"` + ActivatedAt *time.Time `json:"activated_at,omitempty" description:"激活时间"` // === 套餐信息（通用） === CurrentPackage string `json:"current_package" description:"当前套餐名称（无套餐时为空）"` @@ -48,13 +50,15 @@ type AssetInfoResponse struct { DeviceProtectStatus string `json:"device_protect_status,omitempty" description:"设备保护期状态（none:无, stop:停机保护, start:开机保护）"` // === 卡专属字段（asset_type=card 时有效） === - ICCID string `json:"iccid,omitempty" description:"卡ICCID"` - MSISDN string `json:"msisdn,omitempty" description:"手机号"` - CarrierID uint `json:"carrier_id,omitempty" description:"运营商ID"` - CarrierType string `json:"carrier_type,omitempty" description:"运营商类型（CMCC/CUCC/CTCC/CBN）"` - NetworkStatus int `json:"network_status,omitempty" description:"网络状态（0:停机, 1:开机）"` - ActivationStatus int `json:"activation_status,omitempty" description:"激活状态（0:未激活, 1:已激活）"` - CardCategory string `json:"card_category,omitempty" description:"卡业务类型（normal:普通卡, industry:行业卡）"` + ICCID string `json:"iccid,omitempty" description:"卡ICCID"` + MSISDN string `json:"msisdn,omitempty" description:"手机号"` + CarrierID uint `json:"carrier_id,omitempty" description:"运营商ID"` + CarrierType string `json:"carrier_type,omitempty" description:"运营商类型（CMCC/CUCC/CTCC/CBN）"` + NetworkStatus int `json:"network_status,omitempty" description:"网络状态（0:停机, 1:开机）"` + NetworkStatusName string `json:"network_status_name,omitempty" description:"网络状态名称（中文）"` + ActivationStatus int `json:"activation_status,omitempty" description:"激活状态（0:未激活, 1:已激活）"` + ActivationStatusName string `json:"activation_status_name,omitempty" description:"激活状态名称（中文）"` + CardCategory string `json:"card_category,omitempty" description:"卡业务类型（normal:普通卡, industry:行业卡）"` // === 卡绑定设备信息（asset_type=card 且绑定了设备时有效） === BoundDeviceID *uint `json:"bound_device_id,omitempty" description:"绑定的设备ID"` diff --git a/internal/model/dto/commission.go b/internal/model/dto/commission.go index e4910f6..d385564 100644 --- a/internal/model/dto/commission.go +++ b/internal/model/dto/commission.go @@ -14,7 +14,8 @@ type CommissionRecordResponse struct { CommissionSource string `json:"commission_source" description:"佣金来源 (cost_diff:成本价差, one_time:一次性佣金)"` Amount int64 `json:"amount" description:"佣金金额（分）"` BalanceAfter int64 `json:"balance_after" description:"入账后钱包余额（分）"` - Status int `json:"status" description:"状态 (1:已入账, 2:已失效, 99:待人工修正)"` + Status int `json:"status" description:"状态 (1:已冻结, 2:解冻中, 3:已发放, 4:已失效, 99:待人工修正)"` + StatusName string `json:"status_name" description:"状态名称（中文）"` ReleasedAt string `json:"released_at" description:"入账时间"` Remark string `json:"remark" description:"备注"` CreatedAt string `json:"created_at" description:"创建时间"` diff --git a/internal/model/dto/device_dto.go b/internal/model/dto/device_dto.go index dc20b40..1bbbc75 100644 --- a/internal/model/dto/device_dto.go +++ b/internal/model/dto/device_dto.go @@ -18,28 +18,26 @@ type ListDeviceRequest struct { } type DeviceResponse struct { - ID uint `json:"id" description:"设备ID"` - VirtualNo string `json:"virtual_no" description:"设备虚拟号/别名"` - IMEI string `json:"imei" description:"设备IMEI"` - SN string `json:"sn" description:"设备序列号"` - DeviceName string `json:"device_name" description:"设备名称"` - DeviceModel string `json:"device_model" description:"设备型号"` - DeviceType string `json:"device_type" description:"设备类型"` - MaxSimSlots int `json:"max_sim_slots" description:"最大插槽数"` - Manufacturer string `json:"manufacturer" description:"制造商"` - BatchNo string `json:"batch_no" description:"批次号"` - ShopID *uint `json:"shop_id" description:"店铺ID"` - ShopName string `json:"shop_name" description:"店铺名称"` - Status int `json:"status" description:"状态 (1:在库, 2:已分销, 3:已激活, 4:已停用)"` - StatusName string `json:"status_name" description:"状态名称"` - BoundCardCount int `json:"bound_card_count" description:"已绑定卡数量"` - SeriesID *uint `json:"series_id" description:"套餐系列ID"` - SeriesName string `json:"series_name" description:"套餐系列名称"` - FirstCommissionPaid bool `json:"first_commission_paid" description:"一次性佣金是否已发放"` - AccumulatedRecharge int64 `json:"accumulated_recharge" description:"累计充值金额(分)"` - ActivatedAt *time.Time `json:"activated_at" description:"激活时间"` - CreatedAt time.Time `json:"created_at" description:"创建时间"` - UpdatedAt time.Time `json:"updated_at" description:"更新时间"` + ID uint `json:"id" description:"设备ID"` + VirtualNo string `json:"virtual_no" description:"设备虚拟号/别名"` + IMEI string `json:"imei" description:"设备IMEI"` + SN string `json:"sn" description:"设备序列号"` + DeviceName string `json:"device_name" description:"设备名称"` + DeviceModel string `json:"device_model" description:"设备型号"` + DeviceType string `json:"device_type" description:"设备类型"` + MaxSimSlots int `json:"max_sim_slots" description:"最大插槽数"` + Manufacturer string `json:"manufacturer" description:"制造商"` + BatchNo string `json:"batch_no" description:"批次号"` + ShopID *uint `json:"shop_id" description:"店铺ID"` + ShopName string `json:"shop_name" description:"店铺名称"` + Status int `json:"status" description:"状态 (1:在库, 2:已分销, 3:已激活, 4:已停用)"` + StatusName string `json:"status_name" description:"状态名称"` + BoundCardCount int `json:"bound_card_count" description:"已绑定卡数量"` + SeriesID *uint `json:"series_id" description:"套餐系列ID"` + SeriesName string `json:"series_name" description:"套餐系列名称"` + ActivatedAt *time.Time `json:"activated_at" description:"激活时间"` + CreatedAt time.Time `json:"created_at" description:"创建时间"` + UpdatedAt time.Time `json:"updated_at" description:"更新时间"` // 设备实时同步字段（由 sync-info 接口写入） OnlineStatus int `json:"online_status" description:"在线状态：0未知 1在线 2离线"` LastOnlineTime *time.Time `json:"last_online_time" description:"最后在线时间"` @@ -80,6 +78,7 @@ type DeviceCardBindingResponse struct { MSISDN string `json:"msisdn" description:"接入号"` CarrierName string `json:"carrier_name" description:"运营商名称"` Status int `json:"status" description:"卡状态 (1:在库, 2:已分销, 3:已激活, 4:已停用)"` + StatusName string `json:"status_name" description:"卡状态名称（中文）"` BindTime *time.Time `json:"bind_time" description:"绑定时间"` IsCurrent bool `json:"is_current" description:"是否为当前使用的卡"` } diff --git a/internal/model/dto/enterprise_card_authorization_dto.go b/internal/model/dto/enterprise_card_authorization_dto.go index f98ccd9..cc36498 100644 --- a/internal/model/dto/enterprise_card_authorization_dto.go +++ b/internal/model/dto/enterprise_card_authorization_dto.go @@ -13,29 +13,6 @@ type StandaloneCard struct { StatusName string `json:"status_name" description:"状态名称"` } -// Deprecated: 已废弃，不再支持通过单卡授权接口授权设备卡，请使用设备授权接口 -type DeviceBundle struct { - DeviceID uint `json:"device_id" description:"设备ID"` - VirtualNo string `json:"virtual_no" description:"设备虚拟号"` - TriggerCard DeviceBundleCard `json:"trigger_card" description:"触发卡（用户选择的卡）"` - BundleCards []DeviceBundleCard `json:"bundle_cards" description:"连带卡（同设备的其他卡）"` -} - -// Deprecated: 已废弃，不再支持通过单卡授权接口授权设备卡，请使用设备授权接口 -type DeviceBundleCard struct { - ICCID string `json:"iccid" description:"ICCID"` - IotCardID uint `json:"iot_card_id" description:"卡ID"` - MSISDN string `json:"msisdn" description:"手机号"` -} - -// Deprecated: 已废弃，不再支持通过单卡授权接口授权设备卡，请使用设备授权接口 -type AllocatedDevice struct { - DeviceID uint `json:"device_id" description:"设备ID"` - VirtualNo string `json:"virtual_no" description:"设备虚拟号"` - CardCount int `json:"card_count" description:"卡数量"` - ICCIDs []string `json:"iccids" description:"卡ICCID列表"` -} - type FailedItem struct { ICCID string `json:"iccid" description:"ICCID"` Reason string `json:"reason" description:"失败原因"` diff --git a/internal/model/dto/iot_card_dto.go b/internal/model/dto/iot_card_dto.go index 3d530bd..a873589 100644 --- a/internal/model/dto/iot_card_dto.go +++ b/internal/model/dto/iot_card_dto.go @@ -33,12 +33,16 @@ type StandaloneIotCardResponse struct { BatchNo string `json:"batch_no" description:"批次号"` Supplier string `json:"supplier" description:"供应商"` Status int `json:"status" description:"状态 (1:在库, 2:已分销, 3:已激活, 4:已停用)"` + StatusName string `json:"status_name" description:"状态名称（中文）"` ShopID *uint `json:"shop_id" description:"店铺ID"` ShopName string `json:"shop_name" description:"店铺名称"` ActivatedAt *time.Time `json:"activated_at" description:"激活时间"` ActivationStatus int `json:"activation_status" description:"激活状态 (0:未激活, 1:已激活)"` + ActivationStatusName string `json:"activation_status_name" description:"激活状态名称（中文）"` RealNameStatus int `json:"real_name_status" description:"实名状态 (0:未实名, 1:已实名)"` + RealNameStatusName string `json:"real_name_status_name" description:"实名状态名称（中文）"` NetworkStatus int `json:"network_status" description:"网络状态 (0:停机, 1:开机)"` + NetworkStatusName string `json:"network_status_name" description:"网络状态名称（中文）"` DataUsageMB int64 `json:"data_usage_mb" description:"累计流量使用(MB)"` CurrentMonthUsageMB float64 `json:"current_month_usage_mb" description:"本月已用流量(MB)"` CurrentMonthStartDate *time.Time `json:"current_month_start_date" description:"本月开始日期"` @@ -48,8 +52,6 @@ type StandaloneIotCardResponse struct { EnablePolling bool `json:"enable_polling" description:"是否参与轮询"` SeriesID *uint `json:"series_id" description:"套餐系列ID"` SeriesName string `json:"series_name" description:"套餐系列名称"` - FirstCommissionPaid bool `json:"first_commission_paid" description:"一次性佣金是否已发放"` - AccumulatedRecharge int64 `json:"accumulated_recharge" description:"累计充值金额(分)"` DeviceVirtualNo string `json:"device_virtual_no" description:"绑定设备的虚拟号（未绑定时为空字符串）"` CreatedAt time.Time `json:"created_at" description:"创建时间"` UpdatedAt time.Time `json:"updated_at" description:"更新时间"` diff --git a/internal/model/dto/my_package.go b/internal/model/dto/my_package.go index 1109c19..6d148b1 100644 --- a/internal/model/dto/my_package.go +++ b/internal/model/dto/my_package.go @@ -21,7 +21,9 @@ type MyPackageResponse struct { ProfitMargin int64 `json:"profit_margin" description:"利润空间（分）= 建议售价 - 成本价"` PriceSource string `json:"price_source" description:"价格来源 (series_pricing:系列加价, package_override:单套餐覆盖)"` Status int `json:"status" description:"套餐状态 (0:禁用, 1:启用)"` + StatusName string `json:"status_name" description:"状态名称（中文）"` ShelfStatus int `json:"shelf_status" description:"上架状态 (1:上架, 2:下架)"` + ShelfStatusName string `json:"shelf_status_name" description:"上架状态名称（中文）"` } // MyPackagePageResult 我的可售套餐分页结果 @@ -46,7 +48,9 @@ type MyPackageDetailResponse struct { ProfitMargin int64 `json:"profit_margin" description:"利润空间（分）"` PriceSource string `json:"price_source" description:"价格来源 (series_pricing:系列加价, package_override:单套餐覆盖)"` Status int `json:"status" description:"套餐状态 (0:禁用, 1:启用)"` + StatusName string `json:"status_name" description:"状态名称（中文）"` ShelfStatus int `json:"shelf_status" description:"上架状态 (1:上架, 2:下架)"` + ShelfStatusName string `json:"shelf_status_name" description:"上架状态名称（中文）"` } // MySeriesAllocationListRequest 我的套餐系列分配列表请求 @@ -66,6 +70,7 @@ type MySeriesAllocationResponse struct { AvailablePackageCount int `json:"available_package_count" description:"可售套餐数量"` AllocatorShopName string `json:"allocator_shop_name" description:"分配者店铺名称"` Status int `json:"status" description:"状态 (0:禁用, 1:启用)"` + StatusName string `json:"status_name" description:"状态名称（中文）"` } // MySeriesAllocationPageResult 我的套餐系列分配分页结果 diff --git a/internal/model/dto/order_dto.go b/internal/model/dto/order_dto.go index b44f419..3dba6c1 100644 --- a/internal/model/dto/order_dto.go +++ b/internal/model/dto/order_dto.go @@ -64,6 +64,7 @@ type OrderResponse struct { PaymentVoucherKey string `json:"payment_voucher_key,omitempty" description:"线下支付凭证对象存储file_key（仅线下支付订单有值）"` IsPurchaseOnBehalf bool `json:"is_purchase_on_behalf" description:"是否为代购订单"` CommissionStatus int `json:"commission_status" description:"佣金状态 (1:待计算, 2:已计算)"` + CommissionStatusName string `json:"commission_status_name" description:"佣金状态名称（中文）"` CommissionConfigVersion int `json:"commission_config_version" description:"佣金配置版本"` // 操作者信息 diff --git a/internal/model/dto/package_dto.go b/internal/model/dto/package_dto.go index 98ac2b2..0e77e01 100644 --- a/internal/model/dto/package_dto.go +++ b/internal/model/dto/package_dto.go @@ -85,7 +85,9 @@ type PackageResponse struct { CostPrice int64 `json:"cost_price" description:"成本价(分)"` OneTimeCommissionAmount *int64 `json:"one_time_commission_amount,omitempty" description:"一次性佣金金额（分，代理视角）"` Status int `json:"status" description:"状态 (0:禁用, 1:启用)"` + StatusName string `json:"status_name" description:"状态名称（中文）"` ShelfStatus int `json:"shelf_status" description:"上架状态 (1:上架, 2:下架)"` + ShelfStatusName string `json:"shelf_status_name" description:"上架状态名称（中文）"` CreatedAt string `json:"created_at" description:"创建时间"` UpdatedAt string `json:"updated_at" description:"更新时间"` RetailPrice *int64 `json:"retail_price,omitempty" description:"代理零售价（分），仅代理用户可见"` diff --git a/internal/model/dto/recharge.go b/internal/model/dto/recharge.go index 287bc80..29aeb2a 100644 --- a/internal/model/dto/recharge.go +++ b/internal/model/dto/recharge.go @@ -96,8 +96,6 @@ type RechargeCheckResponse struct { Threshold int64 `json:"threshold" description:"佣金触发阈值（分）"` // 提示信息 Message string `json:"message" description:"提示信息"` - // 一次性佣金是否已发放 - FirstCommissionPaid bool `json:"first_commission_paid" description:"一次性佣金是否已发放"` } // GetRechargeRequest 获取充值订单详情请求 diff --git a/internal/model/dto/refund_dto.go b/internal/model/dto/refund_dto.go index 1e6666c..8d86168 100644 --- a/internal/model/dto/refund_dto.go +++ b/internal/model/dto/refund_dto.go @@ -63,6 +63,7 @@ type RefundResponse struct { ApprovedRefundAmount *int64 `json:"approved_refund_amount,omitempty" description:"审批实际退款金额（分）"` RefundReason string `json:"refund_reason" description:"退款原因"` Status int `json:"status" description:"状态 (1:待审批, 2:已通过, 3:已拒绝, 4:已退回)"` + StatusName string `json:"status_name" description:"状态名称（中文）"` ProcessorID *uint `json:"processor_id,omitempty" description:"审批人ID"` ProcessedAt string `json:"processed_at,omitempty" description:"审批时间"` RejectReason string `json:"reject_reason,omitempty" description:"拒绝原因"` diff --git a/internal/model/dto/shop_dto.go b/internal/model/dto/shop_dto.go index cd1a116..6402913 100644 --- a/internal/model/dto/shop_dto.go +++ b/internal/model/dto/shop_dto.go @@ -51,6 +51,7 @@ type ShopResponse struct { District string `json:"district" description:"区县"` Address string `json:"address" description:"详细地址"` Status int `json:"status" description:"状态 (0:禁用, 1:启用)"` + StatusName string `json:"status_name" description:"状态名称（中文）"` CreatedAt string `json:"created_at" description:"创建时间"` UpdatedAt string `json:"updated_at" description:"更新时间"` } diff --git a/internal/model/iot_card.go b/internal/model/iot_card.go index 16f318f..288b805 100644 --- a/internal/model/iot_card.go +++ b/internal/model/iot_card.go @@ -39,8 +39,6 @@ type IotCard struct { LastProtectCheckAt *time.Time `gorm:"column:last_protect_check_at;comment:上次保护期一致性检查时间" json:"last_protect_check_at"` LastSyncTime *time.Time `gorm:"column:last_sync_time;comment:最后一次与Gateway同步时间" json:"last_sync_time"` SeriesID *uint `gorm:"column:series_id;index;comment:套餐系列ID(关联PackageSeries)" json:"series_id,omitempty"` - FirstCommissionPaid bool `gorm:"column:first_commission_paid;type:boolean;default:false;comment:一次性佣金是否已发放(废弃,使用按系列追踪)" json:"first_commission_paid"` - AccumulatedRecharge int64 `gorm:"column:accumulated_recharge;type:bigint;default:0;comment:累计充值金额(分,废弃,使用按系列追踪)" json:"accumulated_recharge"` AccumulatedRechargeBySeriesJSON string `gorm:"column:accumulated_recharge_by_series;type:jsonb;default:'{}';comment:按套餐系列追踪的累计充值金额" json:"-"` FirstRechargeTriggeredBySeriesJSON string `gorm:"column:first_recharge_triggered_by_series;type:jsonb;default:'{}';comment:按套餐系列追踪的首充触发状态" json:"-"` diff --git a/internal/routes/recharge.go b/internal/routes/recharge.go deleted file mode 100644 index 0db51ae..0000000 --- a/internal/routes/recharge.go +++ /dev/null @@ -1 +0,0 @@ -package routes diff --git a/internal/service/account/service.go b/internal/service/account/service.go index 81c0924..7bf63f8 100644 --- a/internal/service/account/service.go +++ b/internal/service/account/service.go @@ -797,6 +797,7 @@ func (s *Service) toAccountResponse(acc *model.Account, shopMap map[uint]string, ShopID: acc.ShopID, EnterpriseID: acc.EnterpriseID, Status: acc.Status, + StatusName: constants.GetStatusName(acc.Status), Creator: acc.Creator, Updater: acc.Updater, CreatedAt: acc.CreatedAt.Format("2006-01-02 15:04:05"), diff --git a/internal/service/asset/service.go b/internal/service/asset/service.go index 9921bea..f0efcdf 100644 --- a/internal/service/asset/service.go +++ b/internal/service/asset/service.go @@ -140,31 +140,30 @@ func (s *Service) Resolve(ctx context.Context, identifier string) (*dto.AssetRes // buildDeviceResolveResponse 构建设备类型的资产解析响应 func (s *Service) buildDeviceResolveResponse(ctx context.Context, device *model.Device) (*dto.AssetResolveResponse, error) { resp := &dto.AssetResolveResponse{ - AssetType: "device", - AssetID: device.ID, - VirtualNo: device.VirtualNo, - Status: device.Status, - BatchNo: device.BatchNo, - ShopID: device.ShopID, - SeriesID: device.SeriesID, - FirstCommissionPaid: device.FirstCommissionPaid, - AccumulatedRecharge: device.AccumulatedRecharge, - ActivatedAt: device.ActivatedAt, - CreatedAt: device.CreatedAt, - UpdatedAt: device.UpdatedAt, - DeviceName: device.DeviceName, - IMEI: device.IMEI, - SN: device.SN, - DeviceModel: device.DeviceModel, - DeviceType: device.DeviceType, - MaxSimSlots: device.MaxSimSlots, - Manufacturer: device.Manufacturer, - OnlineStatus: device.OnlineStatus, - LastOnlineTime: device.LastOnlineTime, - SoftwareVersion: device.SoftwareVersion, - SwitchMode: device.SwitchMode, - LastGatewaySyncAt: device.LastGatewaySyncAt, - EnablePolling: device.EnablePolling, + AssetType: "device", + AssetID: device.ID, + VirtualNo: device.VirtualNo, + Status: device.Status, + StatusName: constants.GetIotCardStatusName(device.Status), + BatchNo: device.BatchNo, + ShopID: device.ShopID, + SeriesID: device.SeriesID, + ActivatedAt: device.ActivatedAt, + CreatedAt: device.CreatedAt, + UpdatedAt: device.UpdatedAt, + DeviceName: device.DeviceName, + IMEI: device.IMEI, + SN: device.SN, + DeviceModel: device.DeviceModel, + DeviceType: device.DeviceType, + MaxSimSlots: device.MaxSimSlots, + Manufacturer: device.Manufacturer, + OnlineStatus: device.OnlineStatus, + LastOnlineTime: device.LastOnlineTime, + SoftwareVersion: device.SoftwareVersion, + SwitchMode: device.SwitchMode, + LastGatewaySyncAt: device.LastGatewaySyncAt, + EnablePolling: device.EnablePolling, } // 查绑定卡 @@ -235,31 +234,30 @@ func (s *Service) buildDeviceResolveResponse(ctx context.Context, device *model. // buildCardResolveResponse 构建卡类型的资产解析响应 func (s *Service) buildCardResolveResponse(ctx context.Context, card *model.IotCard) (*dto.AssetResolveResponse, error) { resp := &dto.AssetResolveResponse{ - AssetType: "card", - AssetID: card.ID, - VirtualNo: card.VirtualNo, - Status: card.Status, - BatchNo: card.BatchNo, - ShopID: card.ShopID, - SeriesID: card.SeriesID, - FirstCommissionPaid: card.FirstCommissionPaid, - AccumulatedRecharge: card.AccumulatedRecharge, - ActivatedAt: card.ActivatedAt, - CreatedAt: card.CreatedAt, - UpdatedAt: card.UpdatedAt, - RealNameStatus: card.RealNameStatus, - RealNameAt: card.FirstRealnameAt, - NetworkStatus: card.NetworkStatus, - ICCID: card.ICCID, - CarrierID: card.CarrierID, - CarrierType: card.CarrierType, - CarrierName: card.CarrierName, - MSISDN: card.MSISDN, - IMSI: card.IMSI, - CardCategory: card.CardCategory, - Supplier: card.Supplier, - ActivationStatus: card.ActivationStatus, - EnablePolling: card.EnablePolling, + AssetType: "card", + AssetID: card.ID, + VirtualNo: card.VirtualNo, + Status: card.Status, + StatusName: constants.GetIotCardStatusName(card.Status), + BatchNo: card.BatchNo, + ShopID: card.ShopID, + SeriesID: card.SeriesID, + ActivatedAt: card.ActivatedAt, + CreatedAt: card.CreatedAt, + UpdatedAt: card.UpdatedAt, + RealNameStatus: card.RealNameStatus, + RealNameAt: card.FirstRealnameAt, + NetworkStatus: card.NetworkStatus, + ICCID: card.ICCID, + CarrierID: card.CarrierID, + CarrierType: card.CarrierType, + CarrierName: card.CarrierName, + MSISDN: card.MSISDN, + IMSI: card.IMSI, + CardCategory: card.CardCategory, + Supplier: card.Supplier, + ActivationStatus: card.ActivationStatus, + EnablePolling: card.EnablePolling, } // 查绑定设备 diff --git a/internal/service/client_order/service.go b/internal/service/client_order/service.go index b4e2f6c..aa7a22d 100644 --- a/internal/service/client_order/service.go +++ b/internal/service/client_order/service.go @@ -137,6 +137,7 @@ func (s *Service) CreateOrder(ctx context.Context, customerID uint, req *dto.Cli return nil, err } + // [待确认] 业务是否需要实名认证检查？参见 tech-debt-cleanup 提案 // REALNAME-03: 按卡类型判断实名需求，普通卡需要实名，行业卡不需要 // if assetInfo.CardCategory == "normal" && assetInfo.RealNameStatus != constants.RealNameStatusVerified { // return nil, errors.New(errors.CodeNeedRealname) diff --git a/internal/service/device/binding.go b/internal/service/device/binding.go index 1ed464e..503bdea 100644 --- a/internal/service/device/binding.go +++ b/internal/service/device/binding.go @@ -5,6 +5,7 @@ import ( "github.com/break/junhong_cmp_fiber/internal/model" "github.com/break/junhong_cmp_fiber/internal/model/dto" + "github.com/break/junhong_cmp_fiber/pkg/constants" "github.com/break/junhong_cmp_fiber/pkg/errors" "github.com/break/junhong_cmp_fiber/pkg/logger" "go.uber.org/zap" @@ -56,8 +57,9 @@ func (s *Service) ListBindings(ctx context.Context, deviceID uint) (*dto.ListDev IotCardID: binding.IotCardID, ICCID: card.ICCID, MSISDN: card.MSISDN, - CarrierName: card.CarrierName, // 直接使用 IotCard 的冗余字段 + CarrierName: card.CarrierName, Status: card.Status, + StatusName: constants.GetIotCardStatusName(card.Status), BindTime: binding.BindTime, IsCurrent: binding.IsCurrent, } diff --git a/internal/service/device/service.go b/internal/service/device/service.go index 6edc8e0..f7f10f9 100644 --- a/internal/service/device/service.go +++ b/internal/service/device/service.go @@ -558,31 +558,29 @@ func (s *Service) extractDeviceIDs(devices []*model.Device) []uint { func (s *Service) toDeviceResponse(device *model.Device, shopMap map[uint]string, seriesMap map[uint]string, bindingCounts map[uint]int64) *dto.DeviceResponse { resp := &dto.DeviceResponse{ - ID: device.ID, - VirtualNo: device.VirtualNo, - IMEI: device.IMEI, - SN: device.SN, - DeviceName: device.DeviceName, - DeviceModel: device.DeviceModel, - DeviceType: device.DeviceType, - MaxSimSlots: device.MaxSimSlots, - Manufacturer: device.Manufacturer, - BatchNo: device.BatchNo, - ShopID: device.ShopID, - Status: device.Status, - StatusName: s.getDeviceStatusName(device.Status), - BoundCardCount: int(bindingCounts[device.ID]), - SeriesID: device.SeriesID, - FirstCommissionPaid: device.FirstCommissionPaid, - AccumulatedRecharge: device.AccumulatedRecharge, - ActivatedAt: device.ActivatedAt, - CreatedAt: device.CreatedAt, - UpdatedAt: device.UpdatedAt, - OnlineStatus: device.OnlineStatus, - LastOnlineTime: device.LastOnlineTime, - SoftwareVersion: device.SoftwareVersion, - SwitchMode: device.SwitchMode, - LastGatewaySyncAt: device.LastGatewaySyncAt, + ID: device.ID, + VirtualNo: device.VirtualNo, + IMEI: device.IMEI, + SN: device.SN, + DeviceName: device.DeviceName, + DeviceModel: device.DeviceModel, + DeviceType: device.DeviceType, + MaxSimSlots: device.MaxSimSlots, + Manufacturer: device.Manufacturer, + BatchNo: device.BatchNo, + ShopID: device.ShopID, + Status: device.Status, + StatusName: s.getDeviceStatusName(device.Status), + BoundCardCount: int(bindingCounts[device.ID]), + SeriesID: device.SeriesID, + ActivatedAt: device.ActivatedAt, + CreatedAt: device.CreatedAt, + UpdatedAt: device.UpdatedAt, + OnlineStatus: device.OnlineStatus, + LastOnlineTime: device.LastOnlineTime, + SoftwareVersion: device.SoftwareVersion, + SwitchMode: device.SwitchMode, + LastGatewaySyncAt: device.LastGatewaySyncAt, } if device.ShopID != nil && *device.ShopID > 0 { diff --git a/internal/service/exchange/migration.go b/internal/service/exchange/migration.go index 37a9570..1b49135 100644 --- a/internal/service/exchange/migration.go +++ b/internal/service/exchange/migration.go @@ -178,8 +178,6 @@ func (s *Service) copyAccumulatedFieldsWithTx(tx *gorm.DB, oldAsset, newAsset *r return errors.New(errors.CodeAssetNotFound) } if err := tx.Model(&model.IotCard{}).Where("id = ?", newAsset.AssetID).Updates(map[string]any{ - "accumulated_recharge": oldAsset.Card.AccumulatedRecharge, - "first_commission_paid": oldAsset.Card.FirstCommissionPaid, "accumulated_recharge_by_series": oldAsset.Card.AccumulatedRechargeBySeriesJSON, "first_recharge_triggered_by_series": oldAsset.Card.FirstRechargeTriggeredBySeriesJSON, "updated_at": time.Now(), @@ -193,8 +191,6 @@ func (s *Service) copyAccumulatedFieldsWithTx(tx *gorm.DB, oldAsset, newAsset *r return errors.New(errors.CodeAssetNotFound) } if err := tx.Model(&model.Device{}).Where("id = ?", newAsset.AssetID).Updates(map[string]any{ - "accumulated_recharge": oldAsset.Device.AccumulatedRecharge, - "first_commission_paid": oldAsset.Device.FirstCommissionPaid, "accumulated_recharge_by_series": oldAsset.Device.AccumulatedRechargeBySeriesJSON, "first_recharge_triggered_by_series": oldAsset.Device.FirstRechargeTriggeredBySeriesJSON, "updated_at": time.Now(), diff --git a/internal/service/iot_card/service.go b/internal/service/iot_card/service.go index bd4e5b1..5b5359a 100644 --- a/internal/service/iot_card/service.go +++ b/internal/service/iot_card/service.go @@ -264,11 +264,15 @@ func (s *Service) toStandaloneResponse(card *model.IotCard, shopMap map[uint]str BatchNo: card.BatchNo, Supplier: card.Supplier, Status: card.Status, + StatusName: constants.GetIotCardStatusName(card.Status), ShopID: card.ShopID, ActivatedAt: card.ActivatedAt, ActivationStatus: card.ActivationStatus, + ActivationStatusName: constants.GetActivationStatusName(card.ActivationStatus), RealNameStatus: card.RealNameStatus, + RealNameStatusName: constants.GetRealNameStatusName(card.RealNameStatus), NetworkStatus: card.NetworkStatus, + NetworkStatusName: constants.GetNetworkStatusName(card.NetworkStatus), DataUsageMB: card.DataUsageMB, CurrentMonthUsageMB: card.CurrentMonthUsageMB, CurrentMonthStartDate: card.CurrentMonthStartDate, @@ -277,8 +281,6 @@ func (s *Service) toStandaloneResponse(card *model.IotCard, shopMap map[uint]str LastRealNameCheckAt: card.LastRealNameCheckAt, EnablePolling: card.EnablePolling, SeriesID: card.SeriesID, - FirstCommissionPaid: card.FirstCommissionPaid, - AccumulatedRecharge: card.AccumulatedRecharge, DeviceVirtualNo: card.DeviceVirtualNo, CreatedAt: card.CreatedAt, UpdatedAt: card.UpdatedAt, diff --git a/internal/service/order/service.go b/internal/service/order/service.go index 81077ea..7579b57 100644 --- a/internal/service/order/service.go +++ b/internal/service/order/service.go @@ -18,6 +18,7 @@ import ( "github.com/break/junhong_cmp_fiber/pkg/errors" "github.com/break/junhong_cmp_fiber/pkg/fuiou" "github.com/break/junhong_cmp_fiber/pkg/middleware" + "github.com/break/junhong_cmp_fiber/pkg/payment" "github.com/break/junhong_cmp_fiber/pkg/queue" "github.com/break/junhong_cmp_fiber/pkg/wechat" "github.com/redis/go-redis/v9" @@ -48,6 +49,7 @@ type Service struct { packageStore *postgres.PackageStore wechatConfigService WechatConfigServiceInterface wechatPayment wechat.PaymentServiceInterface + paymentLoader payment.PaymentConfigLoader queueClient *queue.Client logger *zap.Logger resumeCallback packagepkg.ResumeCallback @@ -73,6 +75,7 @@ func New( packageStore *postgres.PackageStore, wechatConfigService WechatConfigServiceInterface, wechatPayment wechat.PaymentServiceInterface, + paymentLoader payment.PaymentConfigLoader, queueClient *queue.Client, logger *zap.Logger, assetIdentifierStore *postgres.AssetIdentifierStore, @@ -96,6 +99,7 @@ func New( packageStore: packageStore, wechatConfigService: wechatConfigService, wechatPayment: wechatPayment, + paymentLoader: paymentLoader, queueClient: queueClient, logger: logger, assetIdentifierStore: assetIdentifierStore, @@ -109,250 +113,6 @@ func (s *Service) SetResumeCallback(callback packagepkg.ResumeCallback) { s.resumeCallback = callback } -// CreateLegacy 创建订单（已废弃） -// Deprecated: 使用 CreateAdminOrder 或 CreateH5Order 替代。保留用于回滚。 -func (s *Service) CreateLegacy(ctx context.Context, req *dto.CreateOrderRequest, buyerType string, buyerID uint) (*dto.OrderResponse, error) { - var validationResult *purchase_validation.PurchaseValidationResult - var err error - - if req.OrderType == model.OrderTypeSingleCard { - if req.IotCardID == nil { - return nil, errors.New(errors.CodeInvalidParam, "单卡购买必须指定IoT卡ID") - } - validationResult, err = s.purchaseValidationService.ValidateCardPurchase(ctx, *req.IotCardID, req.PackageIDs) - } else if req.OrderType == model.OrderTypeDevice { - if req.DeviceID == nil { - return nil, errors.New(errors.CodeInvalidParam, "设备购买必须指定设备ID") - } - validationResult, err = s.purchaseValidationService.ValidateDevicePurchase(ctx, *req.DeviceID, req.PackageIDs) - } else { - return nil, errors.New(errors.CodeInvalidParam, "无效的订单类型") - } - - if err != nil { - return nil, err - } - - // 下单阶段校验混买限制：禁止同一订单同时包含正式套餐和加油包 - if err := validatePackageTypeMixFromPackages(validationResult.Packages); err != nil { - return nil, err - } - - // 幂等性检查：防止同一买家对同一载体短时间内重复下单 - carrierType, carrierID := resolveCarrierInfo(req) - existingOrderID, err := s.checkOrderIdempotency(ctx, buyerType, buyerID, req.OrderType, carrierType, carrierID, req.PackageIDs) - if err != nil { - return nil, err - } - if existingOrderID > 0 { - return s.Get(ctx, existingOrderID) - } - // 获取到分布式锁后，确保无论成功还是失败都释放 - lockKey := constants.RedisOrderCreateLockKey(carrierType, carrierID) - defer s.redis.Del(ctx, lockKey) - - forceRechargeCheck := s.checkForceRechargeRequirement(ctx, validationResult) - if forceRechargeCheck.NeedForceRecharge && validationResult.TotalPrice < forceRechargeCheck.ForceRechargeAmount { - return nil, errors.New(errors.CodeForceRechargeRequired, "首次购买需满足最低充值要求") - } - - userID := middleware.GetUserIDFromContext(ctx) - - // 提取资源所属店铺ID - var resourceShopID *uint - var seriesID *uint - if validationResult.Card != nil { - resourceShopID = validationResult.Card.ShopID - seriesID = validationResult.Card.SeriesID - } else if validationResult.Device != nil { - resourceShopID = validationResult.Device.ShopID - seriesID = validationResult.Device.SeriesID - } - - // 初始化订单字段 - orderBuyerType := buyerType - orderBuyerID := buyerID - totalAmount := validationResult.TotalPrice - paymentMethod := req.PaymentMethod - paymentStatus := model.PaymentStatusPending - var paidAt *time.Time - now := time.Now() - isPurchaseOnBehalf := false - var operatorID *uint - operatorType := "" - var actualPaidAmount *int64 - purchaseRole := "" - var sellerShopID *uint = resourceShopID - var sellerCostPrice int64 - - // 场景判断：offline（平台代购）、wallet（代理钱包支付）、其他（待支付） - if req.PaymentMethod == model.PaymentMethodOffline { - // ==== 场景 1：平台代购（offline）==== - purchaseBuyerID, buyerCostPrice, purchasePaidAt, err := s.resolvePurchaseOnBehalfInfo(ctx, validationResult) - if err != nil { - return nil, err - } - orderBuyerType = model.BuyerTypeAgent - orderBuyerID = purchaseBuyerID - totalAmount = buyerCostPrice - paymentMethod = model.PaymentMethodOffline - paymentStatus = model.PaymentStatusPaid - paidAt = purchasePaidAt - isPurchaseOnBehalf = true - sellerCostPrice = buyerCostPrice - - // 设置操作者信息（平台代购） - operatorID = nil - operatorType = constants.OwnerTypePlatform - purchaseRole = model.PurchaseRolePurchasedByPlatform - actualPaidAmount = nil - - } else if req.PaymentMethod == model.PaymentMethodWallet { - // ==== 场景 2：代理钱包支付（wallet）==== - if buyerType == "" { - if resourceShopID == nil { - return nil, errors.New(errors.CodeInvalidParam, "不支持的钱包支付场景") - } - buyerType = model.BuyerTypeAgent - buyerID = *resourceShopID - } - - // 只有代理账号可以使用钱包支付 - if buyerType != model.BuyerTypeAgent { - return nil, errors.New(errors.CodeInvalidParam, "只有代理账号可以使用钱包支付") - } - operatorShopID := buyerID - - // 判断资源是否属于操作者 - if resourceShopID == nil { - return nil, errors.New(errors.CodeInternalError, "资源店铺ID为空") - } - - // 获取第一个套餐ID用于查询成本价 - if len(validationResult.Packages) == 0 { - return nil, errors.New(errors.CodeInternalError, "套餐列表为空") - } - firstPackageID := validationResult.Packages[0].ID - - if *resourceShopID == operatorShopID { - // ==== 子场景 2.1：代理自购 ==== - costPrice, err := s.getCostPrice(ctx, operatorShopID, firstPackageID) - if err != nil { - return nil, err - } - - orderBuyerType = model.BuyerTypeAgent - orderBuyerID = operatorShopID - totalAmount = costPrice - paymentMethod = model.PaymentMethodWallet - paymentStatus = model.PaymentStatusPaid - paidAt = &now - isPurchaseOnBehalf = false - - operatorID = &operatorShopID - operatorType = "agent" - actualPaidAmountVal := costPrice - actualPaidAmount = &actualPaidAmountVal - purchaseRole = model.PurchaseRoleSelfPurchase - sellerCostPrice = costPrice - - } else { - // ==== 子场景 2.2：代理代购（给下级购买）==== - // 获取买家成本价 - buyerCostPrice, err := s.getCostPrice(ctx, *resourceShopID, firstPackageID) - if err != nil { - return nil, err - } - - // 获取操作者成本价 - operatorCostPrice, err := s.getCostPrice(ctx, operatorShopID, firstPackageID) - if err != nil { - return nil, err - } - - orderBuyerType = model.BuyerTypeAgent - orderBuyerID = *resourceShopID - totalAmount = buyerCostPrice - paymentMethod = model.PaymentMethodWallet - paymentStatus = model.PaymentStatusPaid - paidAt = &now - isPurchaseOnBehalf = true - - operatorID = &operatorShopID - operatorType = "agent" - actualPaidAmount = &operatorCostPrice - purchaseRole = model.PurchaseRolePurchaseForSubordinate - // 代理代购下级时，佣金差额基准应是操作方（代理自己）的成本价，而非下级的成本价 - // 使用 buyerCostPrice 会导致差额为 0，上级代理无法获得应有佣金 - sellerCostPrice = operatorCostPrice - } - } - - order := &model.Order{ - BaseModel: model.BaseModel{ - Creator: userID, - Updater: userID, - }, - OrderNo: s.orderStore.GenerateOrderNo(), - OrderType: req.OrderType, - BuyerType: orderBuyerType, - BuyerID: orderBuyerID, - IotCardID: req.IotCardID, - DeviceID: req.DeviceID, - TotalAmount: totalAmount, - PaymentMethod: paymentMethod, - PaymentStatus: paymentStatus, - PaidAt: paidAt, - CommissionStatus: model.CommissionStatusPending, - CommissionConfigVersion: 0, - SeriesID: seriesID, - SellerShopID: sellerShopID, - SellerCostPrice: sellerCostPrice, - IsPurchaseOnBehalf: isPurchaseOnBehalf, - OperatorID: operatorID, - OperatorType: operatorType, - ActualPaidAmount: actualPaidAmount, - PurchaseRole: purchaseRole, - } - - items := s.buildOrderItems(userID, validationResult.Packages) - - idempotencyKey := buildOrderIdempotencyKey(buyerType, buyerID, req.OrderType, carrierType, carrierID, req.PackageIDs) - - // 根据支付方式选择创建订单的方式 - if req.PaymentMethod == model.PaymentMethodOffline { - // 平台代购：创建订单并立即激活套餐 - if err := s.createOrderWithActivation(ctx, order, items); err != nil { - return nil, err - } - s.enqueueCommissionCalculation(ctx, order.ID) - s.markOrderCreated(ctx, idempotencyKey, order.ID) - return s.buildOrderResponse(order, items), nil - - } else if req.PaymentMethod == model.PaymentMethodWallet { - // 钱包支付：创建订单、扣款、激活套餐（在事务中完成） - if operatorID == nil { - return nil, errors.New(errors.CodeInternalError, "钱包支付场景下 operatorID 不能为空") - } - operatorShopID := *operatorID - buyerShopID := orderBuyerID - - if err := s.createOrderWithWalletPayment(ctx, order, items, operatorShopID, buyerShopID); err != nil { - return nil, err - } - s.markOrderCreated(ctx, idempotencyKey, order.ID) - return s.buildOrderResponse(order, items), nil - - } else { - // 其他支付方式：创建待支付订单 - if err := s.orderStore.Create(ctx, order, items); err != nil { - return nil, err - } - s.markOrderCreated(ctx, idempotencyKey, order.ID) - return s.buildOrderResponse(order, items), nil - } -} - // CreateAdminOrder 后台订单创建（仅支持 wallet/offline，立即扣款或激活） // 与 CreateH5Order 的核心区别：后台订单不创建待支付状态，wallet 立即扣款，offline 立即激活 // POST /api/admin/orders @@ -2227,6 +1987,7 @@ func (s *Service) buildOrderResponse(order *model.Order, items []*model.OrderIte PaymentVoucherKey: order.PaymentVoucherKey, IsPurchaseOnBehalf: order.IsPurchaseOnBehalf, CommissionStatus: order.CommissionStatus, + CommissionStatusName: constants.GetOrderCommissionStatusName(order.CommissionStatus), CommissionConfigVersion: order.CommissionConfigVersion, OperatorID: order.OperatorID, @@ -2251,13 +2012,8 @@ func (s *Service) buildOrderResponse(order *model.Order, items []*model.OrderIte } // WechatPayJSAPI 发起微信 JSAPI 支付 -// TODO: 从 payment_config_id 加载配置动态创建 Payment 实例，替代 s.wechatPayment 单例 +// 通过 order.PaymentConfigID 动态加载支付配置，支持多商户场景 func (s *Service) WechatPayJSAPI(ctx context.Context, orderID uint, openID string, buyerType string, buyerID uint) (*dto.WechatPayJSAPIResponse, error) { - if s.wechatPayment == nil { - s.logger.Error("微信支付服务未配置") - return nil, errors.New(errors.CodeWechatPayFailed, "微信支付服务未配置") - } - order, err := s.orderStore.GetByID(ctx, orderID) if err != nil { if err == gorm.ErrRecordNotFound { @@ -2274,6 +2030,16 @@ func (s *Service) WechatPayJSAPI(ctx context.Context, orderID uint, openID strin return nil, errors.New(errors.CodeInvalidStatus, "订单状态不允许支付") } + // 按 payment_config_id 动态加载支付配置 + if order.PaymentConfigID == nil { + s.logger.Error("订单缺少支付配置", zap.Uint("order_id", orderID)) + return nil, errors.New(errors.CodeWechatConfigNotFound, "订单缺少支付配置") + } + paymentSvc, err := s.paymentLoader.LoadConfig(ctx, *order.PaymentConfigID) + if err != nil { + return nil, err + } + items, err := s.orderItemStore.ListByOrderIDs(ctx, []uint{orderID}) if err != nil { return nil, errors.Wrap(errors.CodeInternalError, err, "查询订单明细失败") @@ -2283,7 +2049,7 @@ func (s *Service) WechatPayJSAPI(ctx context.Context, orderID uint, openID strin description = items[0].PackageName } - result, err := s.wechatPayment.CreateJSAPIOrder(ctx, order.OrderNo, description, openID, int(order.TotalAmount)) + result, err := paymentSvc.CreateJSAPIOrder(ctx, order.OrderNo, description, openID, int(order.TotalAmount)) if err != nil { s.logger.Error("创建 JSAPI 支付失败", zap.Uint("order_id", orderID), @@ -2307,13 +2073,8 @@ func (s *Service) WechatPayJSAPI(ctx context.Context, orderID uint, openID strin } // WechatPayH5 发起微信 H5 支付 -// TODO: 从 payment_config_id 加载配置动态创建 Payment 实例，替代 s.wechatPayment 单例 +// 通过 order.PaymentConfigID 动态加载支付配置，支持多商户场景 func (s *Service) WechatPayH5(ctx context.Context, orderID uint, sceneInfo *dto.WechatH5SceneInfo, buyerType string, buyerID uint) (*dto.WechatPayH5Response, error) { - if s.wechatPayment == nil { - s.logger.Error("微信支付服务未配置") - return nil, errors.New(errors.CodeWechatPayFailed, "微信支付服务未配置") - } - order, err := s.orderStore.GetByID(ctx, orderID) if err != nil { if err == gorm.ErrRecordNotFound { @@ -2330,6 +2091,16 @@ func (s *Service) WechatPayH5(ctx context.Context, orderID uint, sceneInfo *dto. return nil, errors.New(errors.CodeInvalidStatus, "订单状态不允许支付") } + // 按 payment_config_id 动态加载支付配置 + if order.PaymentConfigID == nil { + s.logger.Error("订单缺少支付配置", zap.Uint("order_id", orderID)) + return nil, errors.New(errors.CodeWechatConfigNotFound, "订单缺少支付配置") + } + paymentSvc, err := s.paymentLoader.LoadConfig(ctx, *order.PaymentConfigID) + if err != nil { + return nil, err + } + items, err := s.orderItemStore.ListByOrderIDs(ctx, []uint{orderID}) if err != nil { return nil, errors.Wrap(errors.CodeInternalError, err, "查询订单明细失败") @@ -2344,7 +2115,7 @@ func (s *Service) WechatPayH5(ctx context.Context, orderID uint, sceneInfo *dto. H5Type: sceneInfo.H5Info.Type, } - result, err := s.wechatPayment.CreateH5Order(ctx, order.OrderNo, description, int(order.TotalAmount), h5SceneInfo) + result, err := paymentSvc.CreateH5Order(ctx, order.OrderNo, description, int(order.TotalAmount), h5SceneInfo) if err != nil { s.logger.Error("创建 H5 支付失败", zap.Uint("order_id", orderID), diff --git a/internal/service/package/service.go b/internal/service/package/service.go index a5b6bc1..c176bdb 100644 --- a/internal/service/package/service.go +++ b/internal/service/package/service.go @@ -598,6 +598,8 @@ func (s *Service) toResponse(ctx context.Context, pkg *model.Package) *dto.Packa } } + resp.StatusName = constants.GetStatusName(resp.Status) + resp.ShelfStatusName = constants.GetShelfStatusName(resp.ShelfStatus) return resp } diff --git a/internal/service/polling/alert_service.go b/internal/service/polling/alert_service.go index 60cdb66..1925974 100644 --- a/internal/service/polling/alert_service.go +++ b/internal/service/polling/alert_service.go @@ -264,7 +264,7 @@ func (s *AlertService) triggerAlert(ctx context.Context, rule *model.PollingAler CurrentValue: currentValue, AlertMessage: alertMessage, NotificationChannels: rule.NotificationChannels, - NotificationStatus: "pending", + NotificationStatus: constants.PollingManualTriggerStatusPending, } if err := s.historyStore.Create(ctx, history); err != nil { diff --git a/internal/service/polling/manual_trigger_service.go b/internal/service/polling/manual_trigger_service.go index c0d6ec5..56ee69b 100644 --- a/internal/service/polling/manual_trigger_service.go +++ b/internal/service/polling/manual_trigger_service.go @@ -86,7 +86,7 @@ func (s *ManualTriggerService) TriggerSingle(ctx context.Context, cardID uint, t TriggerType: "single", CardIDs: string(cardIDsJSON), TotalCount: 1, - Status: "processing", + Status: constants.PollingManualTriggerStatusProcessing, TriggeredBy: triggeredBy, TriggeredAt: time.Now(), } @@ -110,7 +110,7 @@ func (s *ManualTriggerService) TriggerSingle(ctx context.Context, cardID uint, t // 更新日志状态 _ = s.logStore.UpdateProgress(ctx, triggerLog.ID, 1, 1, 0) - _ = s.logStore.UpdateStatus(ctx, triggerLog.ID, "completed") + _ = s.logStore.UpdateStatus(ctx, triggerLog.ID, constants.PollingManualTriggerStatusCompleted) s.logger.Info("单卡手动触发成功", zap.Uint("card_id", cardID), @@ -153,7 +153,7 @@ func (s *ManualTriggerService) TriggerBatch(ctx context.Context, cardIDs []uint, TriggerType: "batch", CardIDs: string(cardIDsJSON), TotalCount: len(cardIDs), - Status: "processing", + Status: constants.PollingManualTriggerStatusProcessing, TriggeredBy: triggeredBy, TriggeredAt: time.Now(), } @@ -209,7 +209,7 @@ func (s *ManualTriggerService) processBatchTrigger(ctx context.Context, logID ui // 更新最终状态 _ = s.logStore.UpdateProgress(ctx, logID, processedCount, successCount, failedCount) - _ = s.logStore.UpdateStatus(ctx, logID, "completed") + _ = s.logStore.UpdateStatus(ctx, logID, constants.PollingManualTriggerStatusCompleted) s.logger.Info("批量手动触发完成", zap.Uint("log_id", logID), @@ -274,7 +274,7 @@ func (s *ManualTriggerService) TriggerByCondition(ctx context.Context, filter *C CardIDs: string(cardIDsJSON), ConditionFilter: string(filterJSON), TotalCount: len(cardIDs), - Status: "processing", + Status: constants.PollingManualTriggerStatusProcessing, TriggeredBy: triggeredBy, TriggeredAt: time.Now(), } @@ -344,11 +344,11 @@ func (s *ManualTriggerService) CancelTrigger(ctx context.Context, logID uint, tr return errors.New(errors.CodeForbidden, "无权限取消该任务") } - if log.Status != "pending" && log.Status != "processing" { + if log.Status != constants.PollingManualTriggerStatusPending && log.Status != constants.PollingManualTriggerStatusProcessing { return errors.New(errors.CodeInvalidParam, "任务已完成或已取消") } - return s.logStore.UpdateStatus(ctx, logID, "cancelled") + return s.logStore.UpdateStatus(ctx, logID, constants.PollingManualTriggerStatusCancelled) } // GetRunningTasks 获取正在运行的任务 diff --git a/internal/service/recharge/service.go b/internal/service/recharge/service.go index 560a435..65af108 100644 --- a/internal/service/recharge/service.go +++ b/internal/service/recharge/service.go @@ -12,6 +12,7 @@ import ( "github.com/break/junhong_cmp_fiber/internal/task" "github.com/break/junhong_cmp_fiber/pkg/constants" "github.com/break/junhong_cmp_fiber/pkg/errors" + "github.com/break/junhong_cmp_fiber/pkg/payment" "github.com/break/junhong_cmp_fiber/pkg/queue" "github.com/hibiken/asynq" "go.uber.org/zap" @@ -28,7 +29,6 @@ type ForceRechargeRequirement struct { CurrentAccumulated int64 `json:"current_accumulated"` // 当前累计充值 Threshold int64 `json:"threshold"` // 佣金触发阈值 Message string `json:"message"` // 提示信息 - FirstCommissionPaid bool `json:"first_commission_paid"` // 一次性佣金是否已发放 } // WechatConfigServiceInterface 支付配置服务接口 @@ -49,6 +49,7 @@ type Service struct { packageSeriesStore *postgres.PackageSeriesStore commissionRecordStore *postgres.CommissionRecordStore wechatConfigService WechatConfigServiceInterface + paymentLoader payment.PaymentConfigLoader queueClient *queue.Client // 任务队列客户端，用于触发自动购包任务 logger *zap.Logger } @@ -65,6 +66,7 @@ func New( packageSeriesStore *postgres.PackageSeriesStore, commissionRecordStore *postgres.CommissionRecordStore, wechatConfigService WechatConfigServiceInterface, + paymentLoader payment.PaymentConfigLoader, logger *zap.Logger, queueClient *queue.Client, ) *Service { @@ -79,6 +81,7 @@ func New( packageSeriesStore: packageSeriesStore, commissionRecordStore: commissionRecordStore, wechatConfigService: wechatConfigService, + paymentLoader: paymentLoader, queueClient: queueClient, logger: logger, } @@ -88,10 +91,10 @@ func New( // 验证资源、金额范围、强充要求，生成订单号 func (s *Service) Create(ctx context.Context, req *dto.CreateRechargeRequest, userID uint) (*dto.RechargeResponse, error) { // 1. 验证金额范围 - if req.Amount < constants.RechargeMinAmount { + if req.Amount < constants.AssetRechargeMinAmount { return nil, errors.New(errors.CodeRechargeAmountInvalid, "充值金额不能低于1元") } - if req.Amount > constants.RechargeMaxAmount { + if req.Amount > constants.AssetRechargeMaxAmount { return nil, errors.New(errors.CodeRechargeAmountInvalid, "充值金额不能超过100000元") } @@ -268,7 +271,7 @@ func (s *Service) List(ctx context.Context, req *dto.RechargeListRequest, userID // HandlePaymentCallback 支付回调处理 // 支持幂等性检查、事务处理、更新余额、触发佣金 -// TODO: 按 payment_config_id 加载配置验签（当前留桩，验签由外层处理） +// 验签由外层 Handler 负责；如需按 payment_config_id 加载配置，可通过 s.paymentLoader 获取 func (s *Service) HandlePaymentCallback(ctx context.Context, rechargeNo string, paymentMethod string, paymentTransactionID string) error { // 1. 查询充值订单 recharge, err := s.assetRechargeStore.GetByRechargeNo(ctx, rechargeNo) @@ -414,8 +417,8 @@ func (s *Service) HandlePaymentCallback(ctx context.Context, rechargeNo string, func (s *Service) checkForceRechargeRequirement(ctx context.Context, resourceType string, resourceID uint) (*ForceRechargeRequirement, error) { result := &ForceRechargeRequirement{ NeedForceRecharge: false, - MinAmount: constants.RechargeMinAmount, - MaxAmount: constants.RechargeMaxAmount, + MinAmount: constants.AssetRechargeMinAmount, + MaxAmount: constants.AssetRechargeMaxAmount, Message: "无强充要求，可自由充值", } @@ -455,7 +458,6 @@ func (s *Service) checkForceRechargeRequirement(ctx context.Context, resourceTyp } result.CurrentAccumulated = accumulatedRecharge - result.FirstCommissionPaid = firstCommissionPaid if seriesID == nil || shopID == nil { return result, nil diff --git a/internal/service/refund/service.go b/internal/service/refund/service.go index 31328a9..484cff3 100644 --- a/internal/service/refund/service.go +++ b/internal/service/refund/service.go @@ -651,6 +651,7 @@ func buildRefundResponse(r *model.RefundRequest) *dto.RefundResponse { ApprovedRefundAmount: r.ApprovedRefundAmount, RefundReason: r.RefundReason, Status: r.Status, + StatusName: constants.GetRefundStatusName(r.Status), ProcessorID: r.ProcessorID, RejectReason: r.RejectReason, Remark: r.Remark, diff --git a/internal/service/shop/service.go b/internal/service/shop/service.go index bc1dcd4..b97b8a8 100644 --- a/internal/service/shop/service.go +++ b/internal/service/shop/service.go @@ -189,6 +189,7 @@ func (s *Service) Create(ctx context.Context, req *dto.CreateShopRequest) (*dto. District: shop.District, Address: shop.Address, Status: shop.Status, + StatusName: constants.GetStatusName(shop.Status), CreatedAt: shop.CreatedAt.Format("2006-01-02 15:04:05"), UpdatedAt: shop.UpdatedAt.Format("2006-01-02 15:04:05"), }, nil @@ -232,6 +233,7 @@ func (s *Service) Update(ctx context.Context, id uint, req *dto.UpdateShopReques District: shop.District, Address: shop.Address, Status: shop.Status, + StatusName: constants.GetStatusName(shop.Status), CreatedAt: shop.CreatedAt.Format("2006-01-02 15:04:05"), UpdatedAt: shop.UpdatedAt.Format("2006-01-02 15:04:05"), }, nil @@ -338,6 +340,7 @@ func (s *Service) ListShopResponses(ctx context.Context, req *dto.ShopListReques District: shop.District, Address: shop.Address, Status: shop.Status, + StatusName: constants.GetStatusName(shop.Status), CreatedAt: shop.CreatedAt.Format("2006-01-02 15:04:05"), UpdatedAt: shop.UpdatedAt.Format("2006-01-02 15:04:05"), }) diff --git a/internal/service/shop_commission/service.go b/internal/service/shop_commission/service.go index a29a5df..5f1a7a4 100644 --- a/internal/service/shop_commission/service.go +++ b/internal/service/shop_commission/service.go @@ -642,7 +642,7 @@ func (s *Service) CreateWithdrawalRequest(ctx context.Context, shopID uint, req AgentWalletID: wallet.ID, ShopID: shopID, UserID: currentUserID, - TransactionType: constants.TransactionTypeWithdrawal, + TransactionType: constants.AgentTransactionTypeWithdrawal, Amount: -req.Amount, BalanceBefore: wallet.Balance, BalanceAfter: wallet.Balance - req.Amount, diff --git a/internal/store/postgres/polling_manual_trigger_store.go b/internal/store/postgres/polling_manual_trigger_store.go index f516cef..771b8b4 100644 --- a/internal/store/postgres/polling_manual_trigger_store.go +++ b/internal/store/postgres/polling_manual_trigger_store.go @@ -6,6 +6,7 @@ import ( "gorm.io/gorm" "github.com/break/junhong_cmp_fiber/internal/model" + "github.com/break/junhong_cmp_fiber/pkg/constants" ) // PollingManualTriggerLogStore 手动触发日志存储 @@ -66,7 +67,7 @@ func (s *PollingManualTriggerLogStore) List(ctx context.Context, page, pageSize func (s *PollingManualTriggerLogStore) GetRunning(ctx context.Context, triggeredBy uint) ([]*model.PollingManualTriggerLog, error) { var logs []*model.PollingManualTriggerLog if err := s.db.WithContext(ctx). - Where("triggered_by = ? AND status IN ('pending', 'processing')", triggeredBy). + Where("triggered_by = ? AND status IN (?, ?)", triggeredBy, constants.PollingManualTriggerStatusPending, constants.PollingManualTriggerStatusProcessing). Order("triggered_at DESC"). Find(&logs).Error; err != nil { return nil, err @@ -88,7 +89,7 @@ func (s *PollingManualTriggerLogStore) UpdateProgress(ctx context.Context, id ui // UpdateStatus 更新触发状态 func (s *PollingManualTriggerLogStore) UpdateStatus(ctx context.Context, id uint, status string) error { updates := map[string]any{"status": status} - if status == "completed" || status == "cancelled" { + if status == constants.PollingManualTriggerStatusCompleted || status == constants.PollingManualTriggerStatusCancelled { updates["completed_at"] = gorm.Expr("CURRENT_TIMESTAMP") } return s.db.WithContext(ctx).Model(&model.PollingManualTriggerLog{}). diff --git a/internal/task/sync.go b/internal/task/sync.go deleted file mode 100644 index 613a8d2..0000000 --- a/internal/task/sync.go +++ /dev/null @@ -1,166 +0,0 @@ -package task - -import ( - "context" - "fmt" - "time" - - "github.com/bytedance/sonic" - "github.com/hibiken/asynq" - "go.uber.org/zap" - "gorm.io/gorm" -) - -// DataSyncPayload 数据同步任务载荷 -type DataSyncPayload struct { - RequestID string `json:"request_id"` - SyncType string `json:"sync_type"` // sim_status, flow_usage, real_name - StartDate string `json:"start_date"` // YYYY-MM-DD - EndDate string `json:"end_date"` // YYYY-MM-DD - BatchSize int `json:"batch_size"` // 批量大小 -} - -// SyncHandler 数据同步任务处理器 -type SyncHandler struct { - db *gorm.DB - logger *zap.Logger -} - -// NewSyncHandler 创建数据同步任务处理器 -func NewSyncHandler(db *gorm.DB, logger *zap.Logger) *SyncHandler { - return &SyncHandler{ - db: db, - logger: logger, - } -} - -// HandleDataSync 处理数据同步任务 -func (h *SyncHandler) HandleDataSync(ctx context.Context, task *asynq.Task) error { - // 解析任务载荷 - var payload DataSyncPayload - if err := sonic.Unmarshal(task.Payload(), &payload); err != nil { - h.logger.Error("解析数据同步任务载荷失败", - zap.Error(err), - zap.String("task_id", task.ResultWriter().TaskID()), - ) - return asynq.SkipRetry - } - - // 验证载荷 - if err := h.validatePayload(&payload); err != nil { - h.logger.Error("数据同步任务载荷验证失败", - zap.Error(err), - zap.String("request_id", payload.RequestID), - ) - return asynq.SkipRetry - } - - // 设置默认批量大小 - if payload.BatchSize <= 0 { - payload.BatchSize = 100 - } - - // 记录任务开始 - h.logger.Info("开始处理数据同步任务", - zap.String("request_id", payload.RequestID), - zap.String("sync_type", payload.SyncType), - zap.String("start_date", payload.StartDate), - zap.String("end_date", payload.EndDate), - zap.Int("batch_size", payload.BatchSize), - ) - - // 执行数据同步 - if err := h.syncData(ctx, &payload); err != nil { - h.logger.Error("数据同步失败", - zap.Error(err), - zap.String("request_id", payload.RequestID), - zap.String("sync_type", payload.SyncType), - ) - return err // 同步失败，可以重试 - } - - // 记录任务完成 - h.logger.Info("数据同步成功", - zap.String("request_id", payload.RequestID), - zap.String("sync_type", payload.SyncType), - ) - - return nil -} - -// validatePayload 验证数据同步载荷 -func (h *SyncHandler) validatePayload(payload *DataSyncPayload) error { - if payload.RequestID == "" { - return fmt.Errorf("request_id 不能为空") - } - if payload.SyncType == "" { - return fmt.Errorf("sync_type 不能为空") - } - validTypes := []string{"sim_status", "flow_usage", "real_name"} - valid := false - for _, t := range validTypes { - if payload.SyncType == t { - valid = true - break - } - } - if !valid { - return fmt.Errorf("sync_type 无效，必须为 sim_status, flow_usage, real_name 之一") - } - if payload.StartDate == "" { - return fmt.Errorf("start_date 不能为空") - } - if payload.EndDate == "" { - return fmt.Errorf("end_date 不能为空") - } - return nil -} - -// syncData 执行数据同步 -func (h *SyncHandler) syncData(ctx context.Context, payload *DataSyncPayload) error { - // TODO: 实际实现中需要调用外部 API 或数据源进行同步 - - // 模拟批量同步 - totalRecords := 500 // 假设有 500 条记录需要同步 - batches := (totalRecords + payload.BatchSize - 1) / payload.BatchSize - - for i := 0; i < batches; i++ { - // 检查上下文是否已取消 - select { - case <-ctx.Done(): - return ctx.Err() - default: - } - - // 模拟批量处理 - offset := i * payload.BatchSize - limit := payload.BatchSize - if offset+limit > totalRecords { - limit = totalRecords - offset - } - - h.logger.Debug("同步批次", - zap.String("sync_type", payload.SyncType), - zap.Int("batch", i+1), - zap.Int("total_batches", batches), - zap.Int("offset", offset), - zap.Int("limit", limit), - ) - - // 模拟处理延迟 - time.Sleep(200 * time.Millisecond) - - // TODO: 实际实现中需要： - // 1. 从外部 API 获取数据 - // 2. 使用事务批量更新数据库 - // 3. 记录同步状态 - } - - h.logger.Info("批量同步完成", - zap.String("sync_type", payload.SyncType), - zap.Int("total_records", totalRecords), - zap.Int("batches", batches), - ) - - return nil -} diff --git a/migrations/000116_remove_legacy_commission_fields.down.sql b/migrations/000116_remove_legacy_commission_fields.down.sql new file mode 100644 index 0000000..31f207a --- /dev/null +++ b/migrations/000116_remove_legacy_commission_fields.down.sql @@ -0,0 +1,5 @@ +-- 回滚：恢复已删除的废弃字段（列结构恢复，历史数据已备份） +ALTER TABLE tb_iot_card ADD COLUMN IF NOT EXISTS first_commission_paid boolean NOT NULL DEFAULT false; +ALTER TABLE tb_iot_card ADD COLUMN IF NOT EXISTS accumulated_recharge bigint NOT NULL DEFAULT 0; +ALTER TABLE tb_device ADD COLUMN IF NOT EXISTS first_commission_paid boolean NOT NULL DEFAULT false; +ALTER TABLE tb_device ADD COLUMN IF NOT EXISTS accumulated_recharge bigint NOT NULL DEFAULT 0; diff --git a/migrations/000116_remove_legacy_commission_fields.up.sql b/migrations/000116_remove_legacy_commission_fields.up.sql new file mode 100644 index 0000000..1b30c18 --- /dev/null +++ b/migrations/000116_remove_legacy_commission_fields.up.sql @@ -0,0 +1,6 @@ +-- 删除 tb_iot_card 和 tb_device 表中的废弃分佣追踪字段 +-- 这两个字段已被 accumulated_recharge_by_series (JSONB) 字段替代 +ALTER TABLE tb_iot_card DROP COLUMN IF EXISTS first_commission_paid; +ALTER TABLE tb_iot_card DROP COLUMN IF EXISTS accumulated_recharge; +ALTER TABLE tb_device DROP COLUMN IF EXISTS first_commission_paid; +ALTER TABLE tb_device DROP COLUMN IF EXISTS accumulated_recharge; diff --git a/openspec/changes/tech-debt-cleanup/.openspec.yaml b/openspec/changes/tech-debt-cleanup/.openspec.yaml new file mode 100644 index 0000000..e14f322 --- /dev/null +++ b/openspec/changes/tech-debt-cleanup/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-04-13 diff --git a/openspec/changes/tech-debt-cleanup/design.md b/openspec/changes/tech-debt-cleanup/design.md new file mode 100644 index 0000000..59ac291 --- /dev/null +++ b/openspec/changes/tech-debt-cleanup/design.md @@ -0,0 +1,340 @@ +## Context + +项目于 2024 年初启动，经过一年多的功能迭代，业务模块逐步完善（支付、轮询、分佣、多租户等），但代码库中积累了分散的废弃代码、硬编码常量、规范缺陷和设计遗留问题。这些问题目前不影响功能，但随着新功能增加，维护成本快速上升： + +1. **API 文档覆盖率仅 18.75%**：docs.go/gendocs 只注册了 9 个 Handler，实际路由 48 个，导致 39 个接口无法在 OpenAPI 文档中查阅 +2. **支付配置硬编码**：order/service 和 recharge/service 中 3 处 TODO，直接使用全局 `s.wechatPayment`，多商户场景下无法正确验签 +3. **硬编码魔法字符串**：轮询系统中 10+ 处状态字符串未提取常量，无法被 IDE 重构工具识别，变更风险高 +4. **废弃代码散布各处**：15 个常量别名、3 个 DTO、2 个方法标注废弃但仍保留，新开发者易误用 +5. **Model 数据冗余**：IotCard 和 Device 模型中 4 个字段已被替代但仍保留在数据库，造成数据不一致风险 +6. **DTO 规范缺口**：122 个 Response DTO 缺少 `_name` 文字字段，违反项目规范 +7. **迁移文件堆积，无法支撑生产部署**：开发阶段逐步积累 114 个迁移（000000~000113），包含大量中间过渡状态（重命名表、删除旧表、修复字段类型等），问题具体为： + - `000104_polling_config_data` 仅有 `.up.sql`，缺少 `.down.sql` + - `backfill_order_purchase_role.sql` 游离在外，不符合 golang-migrate 命名规范，不会被自动执行 + - 新环境部署需顺序执行 114 个迁移，任何一步失败即卡住 + +## Goals / Non-Goals + +**Goals:** + +1. **文档完整性**：补全 API 文档生成器，达到 100% 覆盖率，确保前端/对接方能通过 OpenAPI 文档查阅所有接口 +2. **系统可靠性**：实现支付配置动态加载，支持多商户场景，消除验签失败隐患 +3. **代码规范化**：清理所有硬编码常量、废弃代码、重复 DTO，统一提取到 `pkg/constants/`，降低维护成本和新手上手难度 +4. **数据库一致性**：删除废弃 Model 字段和对应数据库列，防止新/旧逻辑产生的数据不一致 +5. **规范落实**：补全 DTO `_name` 字段和 Service 层赋值逻辑，确保规范 100% 贯彻 +6. **生产就绪的迁移基线**：将 114 个开发期迁移合并为 2 个生产基线文件，新环境一条命令完成全量建库，彻底消除中间过渡状态 + +**Non-Goals:** + +- 重构现有业务逻辑（支付、轮询、分佣等），仅清理代码结构 +- 修改 API 契约或响应格式（除了补充 `_name` 字段） +- 优化性能（无性能变更） +- 新增功能 + +## Decisions + +### 决策 1：API 文档生成器补全 + +**选择**：修改 `cmd/api/docs.go` 和 `cmd/gendocs/main.go`，在 `bootstrap.Handlers` 结构体中注册缺失的 39 个 Handler（Account、AdminOrder、Asset、Authorization 等） + +**理由**： +- 这两个文件是唯一的 API 文档入口，所有接口都需在此注册才能出现在 OpenAPI 文档中 +- 注册逻辑简单且低风险（仅字段赋值，无业务逻辑变更） +- 满足项目规范："新增 Handler 时必须同步更新文档生成器" + +**替代方案考虑**： +- ❌ 自动扫描所有 Handler：增加框架复杂性，不符合 Go 惯用模式（显式优于隐式） +- ❌ 分阶段补全：低优先级接口仍可能被遗漏，最终还是需要一次性全部补全 + +--- + +### 决策 2：支付配置动态加载架构 + +**选择**：在 Service 层新增 `PaymentConfigLoader` 接口和实现，`order/service.go` 和 `recharge/service.go` 中调用此接口从 `payment_config_id` 动态获取对应的支付配置实例 + +```go +// pkg/payment/loader.go（新增） +type PaymentConfigLoader interface { + LoadConfig(ctx context.Context, configID uint) (Payment, error) +} + +// internal/service/order/service.go（修改） +func (s *OrderService) PayOrder(ctx context.Context, orderID uint) error { + order := s.store.GetOrder(orderID) + cfg, err := s.paymentLoader.LoadConfig(ctx, order.PaymentConfigID) // 动态加载 + return cfg.Verify(order.PaymentData) +} +``` + +**理由**： +- 解耦支付配置与订单逻辑，支持多商户多配置场景 +- 缓存在 Redis 中（key: `payment:config:{configID}`），减少数据库查询 +- 若配置不存在或无权限，返回 `errors.New(errors.CodePaymentConfigNotFound)` + +**替代方案考虑**： +- ❌ 在 Store 层加载：支付验签是业务逻辑，应在 Service 层处理 +- ❌ 继续使用全局单例：无法支持多商户，前期配置可行但长期不可扩展 + +--- + +### 决策 3：轮询状态常量提取 + +**选择**：在 `pkg/constants/polling.go` 中新增轮询日志状态常量，替换 `polling_manual_trigger.go`、`manual_trigger_service.go`、`polling_manual_trigger_store.go`、`alert_service.go` 中的硬编码字符串 + +```go +// pkg/constants/polling.go（新增） +const ( + // 轮询手动触发日志状态 + PollingManualTriggerStatusPending = "pending" // 待处理 + PollingManualTriggerStatusProcessing = "processing" // 处理中 + PollingManualTriggerStatusCompleted = "completed" // 已完成 + PollingManualTriggerStatusCancelled = "cancelled" // 已取消 +) +``` + +**理由**： +- 集中管理状态值，便于全局修改和 IDE 重构 +- 保持与轮询系统其他常量（`PollingStatusEnabled` 等）的命名一致性 +- 消除硬编码减少代码行数 ~10 行 + +**替代方案考虑**： +- ❌ 定义 enum 类型：Go 中无原生 enum，定义 type+const 更符合惯用模式 +- ❌ 分散定义在各模块：违反"集中在 pkg/constants/"规范 + +**已知遗留问题（不在本次范围内）**： +轮询手动触发日志的状态字段（`status`）在数据库和代码中均为 `string` 类型，而项目规范要求"状态类（生命周期）用 `int`"。本次清理**仅提取常量，不修改字段类型**，原因： +1. 修改字段类型需要数据库迁移，会产生 API 破坏性变更（现有 JSON 字段值改变） +2. 当前没有并行业务需求推动这个改动 +本次提案将此作为已知技术债务记录，待后续版本统一规划。 + +--- + +### 决策 4：废弃代码清理 + +**选择**： +1. **同步模板代码**（`internal/task/sync.go`）：删除整个文件，轮询系统已实现真正的 SIM 卡状态/实名状态/流量同步逻辑 +2. **废弃常量别名**（`pkg/constants/wallet.go`）：全局搜索并替换 15 个 `Deprecated` 别名为新常量，然后删除别名定义 +3. **废弃 DTO 类型**（3 个）：确认无引用后删除 `DeviceBundle`、`DeviceBundleCard`、`AllocatedDevice` +4. **废弃方法**（2 个）：确认无引用后删除 `CreateLegacy()` 和 `CheckAndStopCard()` + +**理由**： +- 废弃代码继续存在会增加代码认知负担，新开发者易误用 +- 同步任务虽然是模板，但从未被入队使用，保留无意义 +- 这些清理是一次性工作，越早做越好（后续修改越多，冲突风险越大） + +**替代方案考虑**： +- ❌ 标注但保留：会持续占用代码审查注意力，推迟问题不是解决方案 +- ❌ 分批清理：逐个清理会产生多个 PR，合并前后的重构冲突难以管理 + +--- + +### 决策 5：Model 废弃字段清理 + +**选择**： +1. 从 `iot_card.go` 和 `device.go` 中删除 `FirstCommissionPaid` 和 `AccumulatedRecharge` 字段定义 +2. 创建数据库迁移脚本（`000XXX_remove_legacy_commission_fields.up.sql`），删除对应列 + +**理由**： +- 这两个字段已被 `AccumulatedRechargeBySeriesJSON` 和 `FirstRechargeTriggeredBySeriesJSON` 替代，新逻辑不再维护它们 +- 保留在数据库中造成数据冗余和不一致风险（新逻辑更新 BySeriesJSON，旧字段不更新） +- GORM 对比迁移后，Model 与数据库结构保持一致 + +**替代方案考虑**： +- ❌ 仅删除 Model 定义不删除数据库列：GORM 迁移时会警告字段缺失，容易引发混淆 +- ❌ 只删除数据库列不删除 Model 定义：运行时可能触发 scanning 错误 + +--- + +### 决策 6：DTO `_name` 字段补全 + +**选择**： +1. 遍历 `internal/model/dto/` 下所有 DTO 文件，找出所有 int 类型状态字段 +2. 为每个状态字段补充 `_name` 或 `_text` 文字字段（命名规则：字段名+`_name`） +3. 在 Service 层使用中间件或钩子函数，自动赋值这些文字字段 + +示例： +```go +// internal/model/dto/account_dto.go（修改） +type AccountResponse struct { + ID uint `json:"id"` + Status int `json:"status" description:"状态 (0:禁用, 1:启用)"` + StatusName string `json:"status_name" description:"状态名称"` // 新增 + // ... +} + +// internal/service/account/service.go（修改） +func (s *Service) GetAccount(ctx context.Context, id uint) (*dto.AccountResponse, error) { + account, err := s.store.Get(ctx, id) + resp := s.toAccountResponse(account) + resp.StatusName = constants.GetAccountStatusName(resp.Status) // 赋值 + return resp, nil +} +``` + +**理由**： +- 规范要求：项目 AGENTS.md 明确规定 "Response DTO 的 int 状态字段必须有 `_name` 字段" +- 无需前端维护枚举映射表，直接使用后端返回的中文文本显示 +- 规范 100% 贯彻，新接口强制遵守，存量接口逐步补全 + +**替代方案考虑**： +- ❌ 统一使用 string 类型状态字段：破坏现有 API 契约，多个客户端需升级 +- ❌ 前端维护枚举映射表：维护成本高，易不同步 + +--- + +### 决策 7：未使用常量清理 + +**选择**： +1. 删除 `pkg/errors/codes.go` 中的 `CodeExceedLimit` 错误码及其消息映射 +2. 为 `pkg/constants/iot.go` 中 ~22 个未引用的预留常量（Replacement/Merchant/Approval 系列）添加注释说明预留用途，暂不删除 + +**理由**： +- `CodeExceedLimit` 完全未使用，删除无损失 +- iot.go 中的常量可能是为未来功能预留（如设备更换流程、商家管理等），贸然删除可能影响后续规划 +- 保留预留常量并标注其用途，便于未来实现相应功能时快速找到 + +**替代方案考虑**： +- ❌ 全部删除：若未来需要这些常量，重新定义会遇到 Git 历史问题 +- ❌ 全部保留不标注：占用代码空间，不清楚预留目的 + +--- + +## Risks / Trade-offs + +### 风险 1：支付配置动态加载的缓存策略 + +**风险**：支付配置改变后，Redis 缓存不会立即更新，旧订单可能使用过期配置验签 + +**缓解**： +- 缓存 TTL 设置为 1 小时（`JUNHONG_PAYMENT_CONFIG_CACHE_TTL=3600`） +- 支付配置变更时主动清除 Redis 缓存（`DELETE payment:config:{configID}`） +- 监控日志记录每次加载的配置 ID 和来源（缓存/DB） + +--- + +### 风险 2：废弃代码全量删除的合并冲突 + +**风险**：若有并行开发的分支引用被删除的废弃 DTO 或方法，合并时会产生编译错误 + +**缓解**： +- 清理前通知团队成员，检查是否有进行中的 Feature 分支 +- 先提交清理 PR，所有进行中的 Feature 分支在合并前需 rebase main +- 提前进行代码搜索确认零引用，避免删除有隐式依赖的代码 + +--- + +### 风险 3：Model 废弃字段删除的数据丢失 + +**风险**：若有代码仍在写入这些字段（虽已确认无引用），删除数据库列后无法回滚 + +**缓解**： +- 迁移前导出这些列的数据备份（`SELECT id, first_commission_paid, accumulated_recharge FROM tb_iot_card`） +- 迁移脚本提供回滚版本（.down.sql） +- 在测试环境验证迁移逻辑和回滚步骤 + +--- + +### 权衡：API 文档生成器的手动注册 vs 自动扫描 + +**当前选择**：手动注册（在 docs.go 中列出所有 Handler） + +**权衡**： +- ✅ 显式、可控、符合 Go 惯用模式 +- ✅ 可灵活控制哪些 Handler 出现在文档中（如隐藏内部接口） +- ❌ 新增 Handler 时需同步更新，易遗漏 + +**为什么不自动扫描**： +- Go 反射在编译期无法获知（需运行时），不符合项目"显式优于隐式"原则 +- 增加框架复杂性，维护成本高 + +--- + +### 决策 8：数据库迁移文件合并策略 + +**选择**：将 000000~000113 归档，生成新的生产基线迁移（000114、000115），编号接续现有序列 + +**执行步骤**： + +``` +Step 1: pg_dump --schema-only 生成当前 schema + → migrations/000114_squash_baseline.up.sql（建表 DDL） + → migrations/000114_squash_baseline.down.sql（DROP 所有表） + +Step 2: 整合数据初始化 + → migrations/000115_init_data.up.sql + 内容：轮询系统初始配置（原 000104 内容）+ + 历史订单 purchase_role 回填（原 backfill 脚本，已幂等） + → migrations/000115_init_data.down.sql + 内容：DELETE 插入的轮询配置行（purchase_role 回填不需要 rollback） + +Step 3: Model 废弃字段删除迁移 + → migrations/000116_remove_legacy_commission_fields.up.sql + DROP COLUMN first_commission_paid, accumulated_recharge（tb_iot_card, tb_device） + → migrations/000116_remove_legacy_commission_fields.down.sql + +Step 4: 归档旧迁移 + → 将 000000~000113 全部移入 migrations/archive/ + +Step 5: 提供重置脚本 + → scripts/reset_db.sh（DROP DATABASE → CREATE DATABASE → migrate up） +``` + +**生产部署流程**（首次）： +```bash +migrate -path migrations -database "$DB_DSN" up +# 执行 000114 → 000115 → 000116，完成建库 + 数据初始化 +``` + +**测试环境重置**： +```bash +./scripts/reset_db.sh # 清空后重建，等价于全新生产部署 +``` + +**理由**： +- 无生产历史数据，squash 没有历史包袱 +- 000114 + 000115 完全等价于顺序执行 000000~000113 的最终结果 +- 消除 114 步执行链的失败风险，部署过程更可控 +- `backfill_order_purchase_role.sql` 已确认执行过（测试环境 5 条记录有 purchase_role），合并进 000115 后幂等安全 + +**替代方案考虑**： +- ❌ 保留全部 114 个迁移：生产首次部署需顺序执行 114 步，中途失败难以排查 +- ❌ 从编号 000001 重新开始：测试环境会产生混淆（历史 PR 记录编号冲突） + +--- + +## Migration Plan + +### 第一阶段：准备（半天） + +1. 通知团队成员，清理方案确认 +2. 备份测试环境数据库（快照或 pg_dump） +3. 确认所有功能分支代码已 merge 或暂存 + +### 第二阶段：实现（4-5 天） + +1. **第 1 天**：迁移文件合并（000114 + 000115 + 000116）+ 测试环境重置验证 +2. **第 2 天**：API 文档补全 + 支付配置动态加载 +3. **第 3 天**：轮询状态常量提取 + 废弃代码清理（别名、DTO、方法、空文件） +4. **第 4 天**：Model 废弃字段清理 + DTO `_name` 字段批量补全 +5. **第 5 天**：未使用常量清理 + 全量编译测试 + 代码审查 + +### 第三阶段：上线准备（1 天） + +1. 在纯净环境验证 `migrate up` 从 0 跑到底（000114 → 000115 → 000116） +2. 验证所有接口正常（特别是支付、轮询、账号管理） +3. 部署到生产环境 + +### 回滚策略 + +- **代码**：git revert（无 API 破坏性变更） +- **数据库 000114**：执行 `.down.sql` 删除所有表（仅在新环境适用，旧数据无法恢复） +- **数据库 000116**：执行 `.down.sql` 恢复废弃列（列结构恢复，历史数据值已备份） + +--- + +## Open Questions + +1. **支付配置 Redis 缓存 TTL**：现拟设置为 1 小时，是否有其他考虑？ +2. **DTO `_name` 字段赋值时机**：是否需要在 Service 层统一处理，还是允许各模块自行处理？ +3. **轮询日志状态是否需要 API 端点查询**：当前只在日志中记录，是否需要开放查询接口？ +4. **实名认证检查的业务意图**（`client_order/service.go:141`）：注释掉的原因是什么，是暂时关闭还是永久删除？ diff --git a/openspec/changes/tech-debt-cleanup/proposal.md b/openspec/changes/tech-debt-cleanup/proposal.md new file mode 100644 index 0000000..390ea81 --- /dev/null +++ b/openspec/changes/tech-debt-cleanup/proposal.md @@ -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 迁移历史将被清空） diff --git a/openspec/changes/tech-debt-cleanup/specs/api-doc-coverage/spec.md b/openspec/changes/tech-debt-cleanup/specs/api-doc-coverage/spec.md new file mode 100644 index 0000000..a731876 --- /dev/null +++ b/openspec/changes/tech-debt-cleanup/specs/api-doc-coverage/spec.md @@ -0,0 +1,45 @@ +# API 文档完整性规范 + +## MODIFIED Requirements + +### Requirement: OpenAPI 文档 100% 覆盖所有路由接口 + +系统的 OpenAPI 文档应包含所有已注册的 HTTP 路由接口，覆盖率达到 100%。 + +#### Scenario: 文档注册所有 Handler + +- **WHEN** 系统启动或生成 OpenAPI 文档 +- **THEN** `cmd/api/docs.go` 中的 `bootstrap.Handlers` 结构体包含全部 48 个 Handler（包括 Account、AdminOrder、AgentRecharge、Asset、AssetWallet 等） +- **THEN** 每个 Handler 对应一个已注册的路由组（如 `/api/admin/accounts` → `handlers.Account`） +- **THEN** 生成的 OpenAPI 文档包含这 48 个 Handler 对应的全部接口 + +#### Scenario: 新增 Handler 时同步文档生成器 + +- **WHEN** 开发者在 `internal/router/` 中新增一个 Handler 并注册到路由 +- **THEN** 开发者必须同时在 `cmd/api/docs.go` 和 `cmd/gendocs/main.go` 中的 `bootstrap.Handlers` 结构体添加该 Handler 字段 +- **THEN** 若遗漏，代码审查应拒绝合并（检查清单项：**新增 Handler 时是否同步更新 docs.go/gendocs/main.go**） + +#### Scenario: OpenAPI 文档校验完整性 + +- **WHEN** 执行 `go run cmd/gendocs/main.go` 生成 OpenAPI 文档 +- **THEN** 文档应包含所有已注册的接口路由 +- **THEN** 无"缺失文档"的警告或错误信息 + +### Requirement: 文档生成器不遗漏 Handler + +文档生成器的 `bootstrap.Handlers` 结构体应显式列出所有 Handler，避免新增后遗漏。 + +#### Scenario: 完整的 Handler 清单 + +- **WHEN** 审阅 `cmd/api/docs.go` 的 `bootstrap.Handlers` 结构体定义 +- **THEN** 该结构体包含以下字段（至少 48 个，按模块分组）： + ```go + Account *admin.AccountHandler + AdminOrder *admin.OrderHandler + AgentRecharge *agent.RechargeHandler + Asset *admin.AssetHandler + AssetWallet *admin.AssetWalletHandler + Authorization *admin.AuthorizationHandler + // ... 共 48 个 + ``` +- **THEN** 注释中标注每个 Handler 对应的路由前缀和功能模块 diff --git a/openspec/changes/tech-debt-cleanup/specs/dto-name-fields/spec.md b/openspec/changes/tech-debt-cleanup/specs/dto-name-fields/spec.md new file mode 100644 index 0000000..de35552 --- /dev/null +++ b/openspec/changes/tech-debt-cleanup/specs/dto-name-fields/spec.md @@ -0,0 +1,83 @@ +# Response DTO 规范规范 + +## MODIFIED Requirements + +### Requirement: Response DTO 必须包含状态文字字段 + +项目所有 Response DTO 中，若包含 int 类型状态字段，必须同时包含对应的 `_name` 或 `_text` 文字字段，用于显示该状态的中文描述。 + +#### Scenario: 账号列表 Response DTO + +- **WHEN** API 返回账号列表（`GET /api/admin/accounts`） +- **THEN** 响应中每个账号对象包含 `status` 字段（int，值：0=禁用，1=启用） +- **THEN** 响应中同时包含 `status_name` 字段（string，值："禁用"或"启用"） +- **THEN** 前端可直接使用 `status_name` 显示在 UI 上，无需维护单独的状态枚举映射表 + +#### Scenario: 资产详情 Response DTO + +- **WHEN** API 返回单个资产信息（`GET /api/admin/assets/:id`） +- **THEN** 响应包含 `status`（int）和 `status_name`（string） +- **WHEN** 资产包含多个状态字段（如 `network_status`、`activation_status`、`online_status`） +- **THEN** 每个状态字段对应一个文字字段：`network_status_name`、`activation_status_name`、`online_status_name` + +#### Scenario: 订单详情中的多重状态 + +- **WHEN** API 返回订单详情（`GET /api/admin/orders/:id`） +- **THEN** 订单对象包含 `payment_status`（int）和 `payment_status_name`（string） +- **THEN** 订单对象包含 `commission_status`（int）和 `commission_status_name`（string） +- **THEN** 若订单还有其他 int 类型状态字段，均配有对应的 `_name` 字段 + +### Requirement: DTO 文字字段命名规则 + +状态文字字段的命名应遵循统一规则：`{状态字段名}_name` 或 `{状态字段名}_text`。 + +#### Scenario: 标准命名 + +- **WHEN** 定义 DTO 时，状态字段为 `Status` +- **THEN** 文字字段命名为 `StatusName`（推荐）或 `StatusText` +- **WHEN** 状态字段为 `PaymentStatus` +- **THEN** 文字字段命名为 `PaymentStatusName` 或 `PaymentStatusText` + +#### Scenario: JSON 序列化一致性 + +- **WHEN** DTO 序列化为 JSON 返回给客户端 +- **THEN** 字段名使用 snake_case（符合项目 API 规范） + - Go 字段 `Status` → JSON `status` + - Go 字段 `StatusName` → JSON `status_name` + +### Requirement: Service 层自动赋值 `_name` 字段 + +Service 层在构建 Response DTO 时，应自动赋值 `_name`/`_text` 字段，映射状态常量到中文描述。 + +#### Scenario: 获取账号详情自动赋值 + +- **WHEN** `AccountService.GetAccount(ctx, accountID)` 被调用 +- **THEN** Service 查询数据库获取账号信息 +- **THEN** Service 构建 Response DTO，自动设置 `StatusName = constants.GetAccountStatusName(account.Status)` +- **THEN** 返回完整的 DTO 给 Handler，Handler 直接序列化响应 + +#### Scenario: 列表查询批量赋值 + +- **WHEN** `AccountService.ListAccounts(ctx, query)` 被调用 +- **THEN** Service 查询数据库获取账号列表 +- **THEN** Service 遍历每个账号，批量赋值 `StatusName` 字段 +- **THEN** 返回完整列表 + +### Requirement: 常量映射函数 + +在 `pkg/constants/` 中为每个业务模块定义 `Get{Module}StatusName(status int) string` 函数，用于映射状态值到中文描述。 + +#### Scenario: 账号状态映射函数 + +- **WHEN** Service 层需要获取账号状态的中文描述 +- **THEN** 调用 `constants.GetAccountStatusName(status)` +- **THEN** 函数返回： + - 若 `status == 0`，返回 `"禁用"` + - 若 `status == 1`，返回 `"启用"` + - 若状态值未知，返回 `"未知"`（不返回空字符串） + +#### Scenario: 订单支付状态映射函数 + +- **WHEN** Service 层需要获取订单支付状态描述 +- **THEN** 调用 `constants.GetOrderPaymentStatusName(status)` +- **THEN** 函数返回对应的中文（如 "待支付"、"已支付"、"已完成" 等） diff --git a/openspec/changes/tech-debt-cleanup/specs/payment-dynamic-config/spec.md b/openspec/changes/tech-debt-cleanup/specs/payment-dynamic-config/spec.md new file mode 100644 index 0000000..06b9524 --- /dev/null +++ b/openspec/changes/tech-debt-cleanup/specs/payment-dynamic-config/spec.md @@ -0,0 +1,69 @@ +# 支付配置动态加载能力规范 + +## ADDED Requirements + +### Requirement: 从支付配置 ID 动态加载支付实例 + +系统在处理支付验签（订单支付回调、充值确认等）时，应根据订单/充值记录中的 `payment_config_id` 字段动态加载对应的支付配置，而不是使用全局单例 `s.wechatPayment`。 + +#### Scenario: 订单支付回调验签 + +- **WHEN** 微信支付回调到达 `/api/callback/wechat`，系统解析回调中的商户号和订单数据 +- **THEN** 系统根据订单表中的 `payment_config_id` 从 Redis（TTL 1h）或数据库加载对应的支付配置 +- **THEN** 系统使用该配置的私钥和证书验签回调数据 +- **THEN** 若配置不存在或当前用户无权限访问该配置，返回 `{code: 1103, msg: "支付配置不存在或无权限"}` + +#### Scenario: 充值订单确认支付 + +- **WHEN** 代理用户在充值页面点击"确认支付"，提交 `recharge_order_id` 和 `amount` +- **THEN** 系统根据充值订单表中的 `payment_config_id` 动态加载支付配置 +- **THEN** 系统调用该配置对应的支付 SDK 创建预支付单（微信 JSAPI 或 H5） +- **THEN** 若配置无效或超配额，返回 `{code: 1103, msg: "支付配置无效，请联系商户"}` + +### Requirement: 支付配置 Redis 缓存 + +系统应缓存支付配置到 Redis，减少数据库查询。 + +#### Scenario: 首次加载配置 + +- **WHEN** 调用 `PaymentConfigLoader.LoadConfig(ctx, configID)` 且 Redis 中不存在该配置 +- **THEN** 系统从数据库查询配置，存入 Redis（key: `payment:config:{configID}`，TTL: 1 小时） +- **THEN** 返回加载的配置对象 + +#### Scenario: 配置缓存命中 + +- **WHEN** 调用 `PaymentConfigLoader.LoadConfig(ctx, configID)` 且 Redis 中存在该配置 +- **THEN** 系统直接返回 Redis 中缓存的配置 +- **THEN** 不查询数据库 + +#### Scenario: 配置变更后清除缓存 + +- **WHEN** 支付配置被修改（通过管理后台） +- **THEN** 系统主动删除 Redis 中的该配置缓存（`DEL payment:config:{configID}`） +- **THEN** 下次加载时重新从数据库读取最新配置 + +### Requirement: 支付配置访问控制 + +系统在加载支付配置时，根据调用场景采用不同的校验策略： + +> **场景分类说明**： +> - **回调场景**：微信支付回调到达 `/api/callback/wechat`，请求来自微信服务器，无登录态，无用户身份上下文 +> - **用户操作场景**：代理用户在前端主动发起的支付相关操作（如创建充值单、查询支付配置等），有完整的登录态和用户上下文 + +#### Scenario: 回调场景 — 商户号一致性校验 + +- **WHEN** 微信支付回调到达，系统解析回调中的商户号（`mchid`） +- **THEN** 系统根据订单的 `payment_config_id` 加载配置，比较配置中存储的商户号与回调携带的商户号是否一致 +- **THEN** 若不一致，记录告警日志并拒绝处理，返回非 2xx 状态码（微信会重试） +- **NOTE** 此场景**不做用户身份鉴权**，无"代理 A/B"概念，只做商户号匹配验证 + +#### Scenario: 用户操作场景 — 归属权限校验 + +- **WHEN** 代理用户在前端主动操作（如创建充值单）需加载支付配置 +- **THEN** 系统检查该配置的归属（`shop_id` 或 `enterprise_id`）与当前登录用户是否匹配 +- **THEN** 若当前用户无权访问该配置，返回 `{code: 403, msg: "无权限访问该支付配置"}` + +#### Scenario: 平台用户无限制访问 + +- **WHEN** 平台管理员的操作需要加载任意支付配置 +- **THEN** 系统跳过归属权限检查，允许访问所有配置（仅限用户操作场景） diff --git a/openspec/changes/tech-debt-cleanup/specs/polling-status-constants/spec.md b/openspec/changes/tech-debt-cleanup/specs/polling-status-constants/spec.md new file mode 100644 index 0000000..936e1ef --- /dev/null +++ b/openspec/changes/tech-debt-cleanup/specs/polling-status-constants/spec.md @@ -0,0 +1,44 @@ +# 轮询触发日志状态常量规范 + +## ADDED Requirements + +### Requirement: 轮询手动触发日志状态常量 + +系统应在 `pkg/constants/polling.go` 中定义轮询手动触发日志的四种状态常量，避免硬编码字符串。 + +**常量定义**： +- `PollingManualTriggerStatusPending = "pending"` +- `PollingManualTriggerStatusProcessing = "processing"` +- `PollingManualTriggerStatusCompleted = "completed"` +- `PollingManualTriggerStatusCancelled = "cancelled"` + +#### Scenario: 轮询触发日志记录使用常量 + +- **WHEN** 系统记录轮询手动触发日志（插入、更新状态） +- **THEN** 系统使用 `constants.PollingManualTriggerStatusPending` 等常量，而不是直接写字符串 `"pending"` + +#### Scenario: 轮询触发日志查询使用常量 + +- **WHEN** 系统查询轮询日志（按状态筛选、状态转移判断等） +- **THEN** 系统使用常量进行比较，而不是硬编码 `status == "pending"` + +#### Scenario: 常量修改时自动重构 + +- **WHEN** 业务要求修改某个状态值（如 `"pending"` → `"awaiting"`） +- **THEN** 开发者修改 `pkg/constants/polling.go` 中的常量定义 +- **THEN** IDE 自动检测所有使用该常量的代码，支持一键重构替换 +- **THEN** 无需手动搜索和替换散落在各文件中的硬编码字符串 + +### Requirement: 轮询触发日志字段描述 + +轮询手动触发日志模型（`tb_polling_manual_trigger_log`）应包含 `status` 字段，并在 DTO 中加入 `status_name` 文字字段。 + +#### Scenario: 查询轮询触发日志返回状态文本 + +- **WHEN** API 返回轮询手动触发日志列表（`GET /api/admin/polling/manual-triggers`） +- **THEN** 响应中的 `status` 字段（int）对应状态常量值 +- **THEN** 响应中的 `status_name` 字段（string）显示该状态的中文描述 + - `"pending"` → `"待处理"` + - `"processing"` → `"处理中"` + - `"completed"` → `"已完成"` + - `"cancelled"` → `"已取消"` diff --git a/openspec/changes/tech-debt-cleanup/tasks.md b/openspec/changes/tech-debt-cleanup/tasks.md new file mode 100644 index 0000000..1eee68b --- /dev/null +++ b/openspec/changes/tech-debt-cleanup/tasks.md @@ -0,0 +1,435 @@ +# 技术债务清理实现任务清单 + +## 0. 数据库迁移文件合并为生产基线（优先执行） + +- [ ] 0.1 确认当前数据库 schema 完整可用 + - 在本地执行 `go run cmd/api/main.go`，确认所有接口正常启动 + - 验证：服务启动无错误 + +- [ ] 0.2 使用 `pg_dump` 生成当前完整 schema（仅 DDL，不含数据） + - 命令：`pg_dump --schema-only --no-owner --no-acl -d junhong_cmp $DB_DSN > migrations/000114_squash_baseline.up.sql` + - 检查生成的 SQL：确认包含所有表（tb_account、tb_iot_card、tb_device、tb_order 等）、所有索引 + - 确认 SQL 中无外键约束（项目禁止）、无 GORM 关联标签 + - 为每张表添加 `CREATE TABLE IF NOT EXISTS` 保护（替换 `CREATE TABLE`） + - 验证：SQL 文件语法正确，能在全新数据库上执行成功 + +- [ ] 0.3 编写 `migrations/000114_squash_baseline.down.sql`（DROP 所有表） + - 按依赖顺序（子表先删、主表后删）逐一 DROP TABLE + - 使用 `DROP TABLE IF EXISTS` 保护 + - 验证：`.down.sql` 在已建库的数据库上能完整回滚（所有表被删除） + +- [ ] 0.4 创建 `migrations/000115_init_data.up.sql`（初始化数据） + - 合并以下内容： + 1. **轮询配置初始数据**（原 `000104_polling_config_data.up.sql` 内容） + 2. **历史订单 purchase_role 回填**（原 `backfill_order_purchase_role.sql` 内容） + - 确认所有 INSERT 使用 `ON CONFLICT DO NOTHING` 保护（幂等性） + - 确认 UPDATE 语句带 `WHERE xxx IS NULL` 条件（幂等性） + - 验证：在空数据库（已跑完 000114）上执行 000115 无报错，数据正确 + +- [ ] 0.5 创建 `migrations/000115_init_data.down.sql`（回滚初始数据） + - DELETE 轮询配置中由 000115 插入的行（按 `config_name` 或 `description` 标识） + - purchase_role 回填不需要 rollback（DOWN 时留空注释说明原因即可） + - 验证：执行后轮询初始配置被清除 + +- [ ] 0.6 归档旧迁移文件 + - 创建 `migrations/archive/` 目录 + - 将 `000000` ~ `000113` 全部移入 `migrations/archive/`（包含 `.up.sql` 和 `.down.sql`） + - 将游离文件 `backfill_order_purchase_role.sql` 也移入 `migrations/archive/` + - 验证：`migrations/` 目录下只剩 `000114`、`000115`（以及后续 `000116` 废弃字段迁移） + +- [ ] 0.7 编写测试环境重置脚本 `scripts/reset_db.sh` + ```bash + #!/bin/bash + # 重置数据库到干净状态（仅用于开发/测试环境） + DB_NAME="${JUNHONG_DATABASE_DBNAME:-junhong_cmp}" + DB_DSN="postgres://..." + + echo "警告：即将清空数据库 $DB_NAME，5 秒后继续..." + sleep 5 + + psql -c "DROP DATABASE IF EXISTS $DB_NAME;" + psql -c "CREATE DATABASE $DB_NAME;" + migrate -path migrations -database "$DB_DSN" up + echo "数据库重置完成" + ``` + - 验证：脚本可执行，在测试环境运行后数据库从 0 恢复到完整状态 + +- [ ] 0.8 在全新数据库上验证 migrate up 完整链路 + - 创建临时空数据库 + - 执行 `migrate -path migrations -database "$DB_DSN" up` + - 确认顺序执行 000114 → 000115（→ 000116 在任务 5 完成后）全部成功 + - 检查表结构与旧测试环境一致（关键表：tb_order、tb_iot_card、tb_device、tb_agent_wallet 等） + - 验证：migrate up 无报错，表结构正确 + +- [ ] 0.9 重置测试环境数据库，切换到新基线 + - 与团队确认测试环境可以重置 + - 执行 `./scripts/reset_db.sh` + - 确认服务重新启动后所有接口正常 + - 验证：测试环境运行正常，migrate status 显示 `000115` 为最新已应用迁移 + +--- + +## 1. 支付配置动态加载（三个 TODO 点） + +- [ ] 1.1 在 `pkg/constants/redis.go` 中新增支付配置 Redis Key 生成函数 + - 新增函数：`RedisPaymentConfigKey(configID uint) string`，返回格式 `payment:config:{configID}` + - 遵循项目规范：所有 Redis Key 必须通过函数生成，禁止硬编码字符串 + - 验证：编译通过，函数签名符合项目现有 `Redis*Key` 命名规范 + +- [ ] 1.2 确认现有 `pkg/payment/` 包中的 `Payment` 接口/类型定义 + - 查阅 `pkg/payment/` 目录，确认是否已存在支付接口（如 `WechatPayment` 等） + - 若已存在统一接口，`LoadConfig` 返回该接口类型；若不存在，在此步骤新建 `Payment` 接口 + - 验证：`LoadConfig` 的返回类型有明确的定义来源，无模糊引用 + +- [ ] 1.3 创建 `pkg/payment/loader.go` 文件，定义 `PaymentConfigLoader` 接口和实现 + - 接口包含 `LoadConfig(ctx context.Context, configID uint) (Payment, error)` 方法 + - 实现中使用 `constants.RedisPaymentConfigKey(configID)` 作为缓存 key（禁止硬编码） + - 实现包含 Redis 缓存逻辑（TTL 1h） + - **权限检查说明**：仅在用户主动操作（创建充值单等）时做权限校验；支付回调场景（`/api/callback/wechat`）无登录态，校验逻辑为"回调商户号与配置商户号一致"，不做用户身份鉴权 + - 验证：编译通过，无语法错误 + +- [ ] 1.4 修改 `internal/service/order/service.go`，在两处 TODO（行 2254、2310）实现动态加载 + - 注入 `paymentLoader` 依赖 + - 替换 `s.wechatPayment` 为 `s.paymentLoader.LoadConfig(ctx, order.PaymentConfigID)` + - 添加错误处理：若配置不存在返回 `errors.New(errors.CodePaymentConfigNotFound)` + - 验证：编译通过，`go vet` 无报告 + +- [ ] 1.5 修改 `internal/service/recharge/service.go`，在 TODO（行 271）实现动态加载 + - 注入 `paymentLoader` 依赖 + - 替换硬编码为 `s.paymentLoader.LoadConfig(ctx, rechargeOrder.PaymentConfigID)` + - 验证：编译通过，`go vet` 无报告 + +- [ ] 1.7 运行 `go build ./cmd/api ./cmd/worker` 确认编译通过，并通过 PostgreSQL MCP 手动验证支付逻辑 + - 执行 `go vet ./internal/service/order/ ./internal/service/recharge/` 静态分析 + - 使用 curl 或 Postman 手动触发支付回调，确认验签逻辑正常 + - 验证：编译通过，vet 无报告，手动验签流程无报错 + +--- + +## 2. API 文档生成器补全（39 个缺失 Handler） + +- [ ] 2.1 修改 `cmd/api/docs.go`，在 `bootstrap.Handlers` 结构体中注册所有 48 个 Handler + - 按模块分组注册（admin、agent、h5 等） + - 每个 Handler 字段添加注释说明对应的路由前缀 + - 完整列表：Account、AdminOrder、AgentRecharge、Asset、AssetAllocationRecord、AssetWallet、Auth、Authorization、Carrier、CommissionWithdrawal、CommissionWithdrawalSetting、Device、DeviceImport、Enterprise、EnterpriseCard、EnterpriseDevice、IotCard、IotCardImport、Package、PackageSeries、PackageUsage、PaymentCallback、Permission、PersonalCustomer、PollingAlert、PollingCleanup、PollingConcurrency、PollingConfig、PollingManualTrigger、PollingMonitoring、Refund、Role、Shop、ShopCommission、ShopPackageBatchAllocation、ShopPackageBatchPricing、ShopRole、ShopSeriesGrant、Storage、WechatConfig + - 验证：代码可编译 + +- [ ] 2.2 修改 `cmd/gendocs/main.go`，在 `bootstrap.Handlers` 结构体中同样注册所有 48 个 Handler + - 保持与 docs.go 中的结构一致 + - 验证：代码可编译 + +- [ ] 2.3 运行 `go run cmd/gendocs/main.go` 生成 OpenAPI 文档，验证包含所有 48 个接口路由 + - 检查生成的文档中是否有所有接口的 path、method、parameters、responses + - 验证：无"缺失 Handler"的警告 + +- [ ] 2.4 人工核查生成的 OpenAPI 文档中接口数量与路由注册数量一致 + - 统计 `internal/router/` 下实际注册的路由数，与文档中的 path 条目数对比 + - 验证：文档中接口数量 ≥ 48，无缺失路由 + +--- + +## 3. 轮询状态常量提取（10+ 处硬编码） + +- [ ] 3.1 在 `pkg/constants/polling.go` 中新增轮询手动触发日志状态常量 + ```go + const ( + PollingManualTriggerStatusPending = "pending" + PollingManualTriggerStatusProcessing = "processing" + PollingManualTriggerStatusCompleted = "completed" + PollingManualTriggerStatusCancelled = "cancelled" + ) + ``` + - 验证：编译通过 + +- [ ] 3.2 修改 `internal/handler/admin/polling_manual_trigger.go`，将硬编码状态字符串替换为常量 + - 搜索并替换所有 `"pending"`、`"completed"`、`"cancelled"` 为对应常量 + - 验证：编译通过，`go vet ./internal/handler/admin/...` 无报告 + +- [ ] 3.3 修改 `internal/service/polling/manual_trigger_service.go`，替换硬编码状态字符串 + - 替换所有 `"pending"`、`"processing"`、`"completed"`、`"cancelled"` 为常量 + - 验证：编译通过，`go vet ./internal/service/polling/...` 无报告 + +- [ ] 3.4 修改 `internal/store/postgres/polling_manual_trigger_store.go`，替换硬编码字符串 + - 替换状态比较和更新操作中的硬编码 + - 验证：编译通过 + +- [ ] 3.5 修改 `internal/service/polling/alert_service.go`，替换 `NotificationStatus` 中的硬编码 + - 将 `"pending"` 替换为常量 + - 验证：编译通过，`go vet ./internal/service/polling/...` 无报告，通过 PostgreSQL MCP 查询告警日志确认状态值正确 + +- [ ] 3.6 运行 `grep -r '"pending"\|"completed"\|"cancelled"' internal/` 确认轮询相关文件中无剩余硬编码 + - 验证：无轮询相关的硬编码字符串 + +--- + +## 4. 废弃代码清理（15 个别名 + 3 个 DTO + 2 个方法） + +- [ ] 4.1 删除 `internal/task/sync.go` 整个文件 + - 在 `pkg/queue/handler.go` 中删除 `syncHandler` 的注册代码（行 61-67） + - 在 `pkg/constants/constants.go` 中删除 `TaskTypeDataSync` 常量定义 + - 验证：`grep -r "TaskTypeDataSync\|SyncHandler\|HandleDataSync" internal/ pkg/` 无结果 + +- [ ] 4.2 全局搜索 `pkg/constants/wallet.go` 中的 15 个废弃别名，确认引用情况 + ``` + WalletTypeMain, WalletTypeCommission, + WalletResourceType*, + WalletStatus*, + TransactionType*, + RechargeOrderPrefix, RechargeMinAmount, RechargeMaxAmount, + Card* 前缀别名（9 个） + ``` + - 运行 `grep -r "WalletTypeMain\|WalletTypeCommission\|WalletResourceType" internal/ pkg/` 统计引用次数 + - 验证：若有引用则记录文件和行号，后续逐个替换 + +- [ ] 4.3 对于每个有引用的废弃别名，替换为新常量 + - 使用 IDE 的重构工具或 `sed` 批量替换 + - 示例：`WalletTypeMain` → `AgentWalletTypeMain` + - 验证：编译通过，无引用残留 + +- [ ] 4.4 删除 `pkg/constants/wallet.go` 中所有 Deprecated 别名定义（共 15 个） + - 删除注释块和别名定义 + - 验证：编译通过，运行 `grep -c "Deprecated" pkg/constants/wallet.go` 返回 0 + +- [ ] 4.5 删除 `internal/model/dto/enterprise_card_authorization_dto.go` 中的 3 个废弃 DTO 类型 + - `DeviceBundle`、`DeviceBundleCard`、`AllocatedDevice` + - 验证：全局搜索确认无引用，编译通过 + +- [ ] 4.6 删除 `internal/service/order/service.go` 中的 `CreateLegacy()` 方法（行 113 及方法体） + - 全局搜索确认无调用点 + - 验证：编译通过 + +- [ ] 4.7 删除 `internal/service/iot_card/stop_resume_service.go` 中的 `CheckAndStopCard()` 方法（行 330） + - 全局搜索确认无调用点 + - 验证：编译通过 + +- [ ] 4.8 运行 `go build ./cmd/api ./cmd/worker` 确认删除未引入编译错误 + - 执行 `go vet ./internal/model/dto/ ./internal/service/order/ ./internal/service/iot_card/` 静态分析 + - 验证：编译通过，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` + ```sql + ALTER TABLE tb_iot_card DROP COLUMN IF EXISTS first_commission_paid; + ALTER TABLE tb_iot_card DROP COLUMN IF EXISTS accumulated_recharge; + ALTER TABLE tb_device DROP COLUMN IF EXISTS first_commission_paid; + ALTER TABLE tb_device DROP COLUMN IF EXISTS accumulated_recharge; + ``` + - 验证：语法正确，在测试数据库上运行成功 + +- [ ] 5.4 创建回滚迁移文件 `migrations/000116_remove_legacy_commission_fields.down.sql` + - 添加这四个列回来，使用原始类型（确认类型后填入） + - 验证：语法正确 + +- [ ] 5.5 在测试环境执行迁移，确认字段被删除，表结构正确 + - 运行 `migrate -path migrations -database "postgres://..." up` + - 通过 PostgreSQL MCP 执行以下 SQL 确认字段已不存在： + ```sql + SELECT column_name FROM information_schema.columns + WHERE table_name IN ('tb_iot_card', 'tb_device') + AND column_name IN ('first_commission_paid', 'accumulated_recharge'); + -- 期望：0 行返回 + ``` + - 验证：迁移成功，查询结果为空 + +- [ ] 5.6 通过 PostgreSQL MCP 查询 `tb_iot_card` 和 `tb_device` 表结构确认字段已删除 + - 执行 `go build ./cmd/api ./cmd/worker` 确认编译通过 + - 验证：`information_schema.columns` 查询结果中不含 `first_commission_paid`、`accumulated_recharge` + +--- + +## 6. DTO `_name` 字段补全（122 处） + +> **分批说明**：122 处分布在多个模块，建议按模块分批提交，每批独立编译验证，避免大批量修改产生难以排查的冲突。推荐顺序：Account → Asset → Order → Commission → IotCard/Device → 其他模块。 + +- [ ] 6.1 遍历 `internal/model/dto/` 中的所有 DTO 文件，统计所有 int 类型状态字段 + - 使用 `grep -rn "int.*\`json:" internal/model/dto/` 列出候选字段 + - 过滤出缺少配套 `_name`/`_text` 字段的条目，生成模块维度的清单 + - 验证：清单按模块分组，总计不少于 122 条 + +- [ ] 6.2 **Account 模块**：补全 DTO `_name` 字段 + 常量映射函数 + Service 层赋值 + - 在 `internal/model/dto/account_dto.go` 中为每个 int 状态字段新增 `_name` 字符串字段 + - 在 `pkg/constants/account.go`（或对应文件）中新增 `GetAccountStatusName(status int) string` + - 在 `internal/service/account/service.go` 中所有构建 Response DTO 的地方赋值 `_name` 字段 + - 验证：`go build ./cmd/api` 通过；`curl /api/admin/accounts/1` 响应包含 `status_name` + +- [ ] 6.3 **Asset 模块**：补全 DTO `_name` 字段 + 常量映射函数 + Service 层赋值 + - 涉及文件：`internal/model/dto/asset_dto.go`、`internal/service/asset/service.go` + - 为 `status`、`network_status`、`activation_status`、`online_status` 等多状态字段各自补全 + - 验证：编译通过；手动调用资产详情接口确认返回 `*_name` 字段 + +- [ ] 6.4 **Order 模块**：补全 DTO `_name` 字段 + 常量映射函数 + Service 层赋值 + - 涉及文件：`internal/model/dto/order_dto.go`、`internal/service/order/service.go` + - 覆盖 `payment_status`、`commission_status`、`order_status` 等字段 + - 验证：编译通过；手动调用订单详情接口确认返回 `*_name` 字段 + +- [ ] 6.5 **Commission 模块**：补全 DTO `_name` 字段 + 常量映射函数 + Service 层赋值 + - 涉及文件：commission 相关 DTO 和 Service + - 验证：编译通过，手动验证分佣列表接口响应 + +- [ ] 6.6 **IotCard / Device 模块**：补全 DTO `_name` 字段 + 常量映射函数 + Service 层赋值 + - 涉及文件：`internal/model/dto/iot_card_dto.go`、`internal/model/dto/device_dto.go` 等 + - 验证：编译通过，手动验证相关接口响应 + +- [ ] 6.7 **剩余模块**（Recharge、Wallet、Package、Shop 等）：按同样模式批量补全 + - 以 6.1 生成的清单为依据，逐模块完成，每模块补完即编译验证一次 + - 验证：所有模块编译通过 + +- [ ] 6.8 全量编译与静态分析 + - 运行 `go build ./cmd/api ./cmd/worker` 和 `go vet ./internal/service/ ./internal/handler/` + - 验证：编译通过，vet 无报告 + +- [ ] 6.9 使用 curl/Postman 抽查各模块代表性接口，确认 `_name` 字段有值且内容正确 + - 示例：`GET /api/admin/accounts/1` 返回 `status_name`；`GET /api/admin/orders/1` 返回 `payment_status_name` + - 验证：响应符合规范，`_name` 字段非空且为正确中文描述 + +--- + +## 7. 未使用常量和错误码清理 + +- [ ] 7.1 删除 `pkg/errors/codes.go` 中的 `CodeExceedLimit` 常量和对应的错误消息映射 + - 搜索确认 `CodeExceedLimit` 无任何引用 + - 验证：编译通过 + +- [ ] 7.2 为 `pkg/constants/iot.go` 中约 22 个未引用的预留常量添加注释 + - Replacement/Merchant/Approval/Ladder/CardType 系列 + - 在每个常量上方添加：`// [预留] 用于未来 XXX 功能，见需求文档 YYY` + - 示例：`// [预留] 用于设备换卡功能，见产品规划 2025Q2` + - 验证：注释清晰，预留用途明确 + +- [ ] 7.3 运行 `go build ./cmd/api ./cmd/worker` 和 `go vet ./pkg/errors/ ./pkg/constants/` 确认清理无破坏 + - 验证：编译通过，vet 无报告 + +--- + +## 8. 删除空文件和注释代码 + +- [ ] 8.1 删除 `internal/routes/recharge.go` 空文件 + - 验证：`ls -la internal/routes/recharge.go` 返回 File not found + +- [ ] 8.2 删除 `pkg/database/postgres.go` 中的 AutoMigrate 注释块（行 90-95） + - 验证：编译通过 + +- [ ] 8.3 保留 `internal/service/client_order/service.go` 中的实名认证检查注释（行 141-142） + - 在注释上方添加：`// [待确认] 业务需要实名认证检查吗？见 ISSUE #XXX` + - 验证：编译通过 + +--- + +## 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 ./...` 进行静态分析 + - 验证：无 vet 错误 + +- [ ] 9.4 运行 `gofmt -l ./internal ./pkg` 检查代码格式 + - 若有格式问题，运行 `gofmt -w ./internal ./pkg` 修复 + - 验证：无格式问题 + +--- + +## 10. 全面测试与集成验证 + +- [ ] 10.1 运行 `go build ./...` 确认全量编译通过，运行 `go vet ./...` 全量静态分析 + - 验证：编译无错误，vet 无报告 + +- [ ] 10.2 在测试环境启动 API 服务，运行完整的业务流程测试 + - 测试支付流程（订单支付 → 回调 → 验签） + - 测试轮询系统（手动触发 → 日志记录 → 状态更新） + - 测试各模块的 API 响应中是否包含 `_name` 字段 + - 验证：所有流程正常，无错误 + +- [ ] 10.3 运行 `go vet ./internal/... ./pkg/...` 确认无静态分析问题 + - 验证：vet 无报告，输出为空 + +- [ ] 10.4 验证数据库迁移（如使用 golang-migrate） + - 在测试环境运行迁移：`migrate -path migrations -database "..." up` + - 验证所有迁移成功执行，表结构正确 + - 验证：迁移完成，无错误 + +- [ ] 10.5 检查 Redis 缓存功能（支付配置加载） + - 启动 Redis，验证支付配置加载时是否正确使用缓存 + - 修改支付配置后验证缓存清除和重新加载 + - 验证：缓存功能正常 + +- [ ] 10.6 生成最终的 OpenAPI 文档并审查 + - 运行 `go run cmd/gendocs/main.go` + - 检查生成的文档是否包含全部 48 个接口 + - 验证：文档完整无误 + +--- + +## 11. 代码审查与合并前检查 + +- [ ] 11.1 检查 commit 历史，确保每个 commit 的 message 清晰且符合规范 + - commit message 格式：`[模块] 功能描述` 或 `fix: 修复内容` + - 验证：commit 历史清晰 + +- [ ] 11.2 运行 `git diff main...HEAD` 审查所有代码变更 + - 确认无意外的格式改动或无关的修改 + - 验证：diff 清晰，仅包含计划内的改动 + +- [ ] 11.3 向团队成员申请代码审查，处理审查意见 + - 验证：至少一人 approve + +- [ ] 11.4 确认所有 CI/CD 检查通过（若项目使用） + - 验证：绿色勾号 + +--- + +## 12. 部署与监控 + +- [ ] 12.1 在预发环境部署最新的代码和数据库迁移 + - 验证：部署成功，服务正常启动 + +- [ ] 12.2 在预发环境执行烟测用例，验证关键功能 + - 支付流程、轮询系统、账号管理 + - 验证：功能正常 + +- [ ] 12.3 灰度发布到生产环境（10% → 50% → 100%） + - 逐步增加流量比例，监控错误率和性能指标 + - 验证：无异常告警 + +- [ ] 12.4 监控生产环境，查看日志确认无错误 + - 特别关注支付验签相关的日志 + - 验证：`grep -i "error\|failed" logs/app.log` 无相关错误 + +--- + +## 13. 最终验收与文档更新 + +- [ ] 13.1 生成变更总结文档，列出所有删除、添加、修改的代码、文件、字段 + - 验证：文档完整准确 + +- [ ] 13.2 更新项目 README 或 CHANGELOG，标注此次技术债务清理的内容 + - 验证：文档同步 + +- [ ] 13.3 向团队分享清理成果和改进点 + - 验证：信息传达完整 + +--- + +## 完成标准 + +**所有上述任务完成后，技术债务清理工作才算完成。具体标准**： + +1. ✅ **编译通过**：`go build ./cmd/api ./cmd/worker` 无错误 +2. ✅ **测试全 PASS**：`go test -v ./...` 所有测试通过 +3. ✅ **文档完整**：OpenAPI 文档覆盖 100%（48/48 Handler），所有接口可查阅 +4. ✅ **代码规范**：无 vet 错误，代码格式统一 +5. ✅ **功能正常**：支付、轮询、账号管理等核心模块功能无破坏 +6. ✅ **数据一致**：数据库迁移成功，废弃字段已删除 +7. ✅ **生产稳定**：灰度部署完成，无生产告警或错误 diff --git a/pkg/constants/constants.go b/pkg/constants/constants.go index db0e779..1e31d7b 100644 --- a/pkg/constants/constants.go +++ b/pkg/constants/constants.go @@ -43,7 +43,6 @@ const ( // 任务类型常量 const ( TaskTypeEmailSend = "email:send" // 发送邮件 - TaskTypeDataSync = "data:sync" // 数据同步 TaskTypeCommission = "commission:calculate" // 分佣计算 TaskTypeIotCardImport = "iot_card:import" // IoT 卡批量导入 TaskTypeDeviceImport = "device:import" // 设备批量导入 @@ -233,3 +232,48 @@ const ( ExchangeAssetTypeIotCard = "iot_card" // 物联网卡 ExchangeAssetTypeDevice = "device" // 设备 ) + +// GetStatusName 获取通用启用/禁用状态名称 +// 用于 status 字段：0=禁用, 1=启用 +func GetStatusName(status int) string { + switch status { + case StatusDisabled: + return "禁用" + case StatusEnabled: + return "启用" + default: + return "未知" + } +} + +// GetShelfStatusName 获取上架状态名称 +// 用于 shelf_status 字段：1=上架, 2=下架 +func GetShelfStatusName(status int) string { + switch status { + case ShelfStatusOn: + return "上架" + case ShelfStatusOff: + return "下架" + default: + return "未知" + } +} + +// GetExchangeStatusName 获取换货单状态名称 +// 用于 exchange_status 字段 +func GetExchangeStatusName(status int) string { + switch status { + case ExchangeStatusPendingInfo: + return "待填写信息" + case ExchangeStatusPendingShip: + return "待发货" + case ExchangeStatusShipped: + return "已发货待确认" + case ExchangeStatusCompleted: + return "已完成" + case ExchangeStatusCancelled: + return "已取消" + default: + return "未知" + } +} diff --git a/pkg/constants/iot.go b/pkg/constants/iot.go index 24d02df..8d74fac 100644 --- a/pkg/constants/iot.go +++ b/pkg/constants/iot.go @@ -186,11 +186,11 @@ const ( CommissionStatusPendingReview = 99 // 待人工修正（链路断裂，需平台处理） ) -// 阶梯类型 +// 阶梯类型（[预留] 用于分佣阶梯功能，待产品规划） const ( - LadderTypeActivation = "activation" // 激活量 - LadderTypePickup = "pickup" // 提货量 - LadderTypeDeposit = "deposit" // 充值量 + LadderTypeActivation = "activation" // 激活量（[预留]） + LadderTypePickup = "pickup" // 提货量（[预留]） + LadderTypeDeposit = "deposit" // 充值量（[预留]） ) // 卡类型 @@ -199,17 +199,17 @@ const ( CardTypeIotCard = "iot_card" // IoT卡 ) -// 审批类型 +// 审批类型（[预留] 用于审批流程功能，待产品规划） const ( - ApprovalTypeAuto = "auto" // 自动 - ApprovalTypeManual = "manual" // 人工 + ApprovalTypeAuto = "auto" // 自动（[预留]） + ApprovalTypeManual = "manual" // 人工（[预留]） ) -// 审批状态 +// 审批状态（[预留] 用于审批流程功能，待产品规划） const ( - ApprovalStatusPending = 1 // 待审批 - ApprovalStatusApproved = 2 // 已通过 - ApprovalStatusRejected = 3 // 已拒绝 + ApprovalStatusPending = 1 // 待审批（[预留]） + ApprovalStatusApproved = 2 // 已通过（[预留]） + ApprovalStatusRejected = 3 // 已拒绝（[预留]） ) // ======================================== @@ -231,23 +231,23 @@ const ( WithdrawalMethodBank = "bank" // 银行卡 ) -// 商户类型 +// 商户类型（[预留] 用于未来商户管理功能，待产品规划） const ( - MerchantTypeAlipay = "alipay" // 支付宝 - MerchantTypeWechat = "wechat" // 微信 - MerchantTypeBank = "bank" // 银行卡 + MerchantTypeAlipay = "alipay" // 支付宝（[预留]） + MerchantTypeWechat = "wechat" // 微信（[预留]） + MerchantTypeBank = "bank" // 银行卡（[预留]） ) // ======================================== // 5. 系统管理常量 // ======================================== -// 换卡申请状态 +// 换卡申请状态（[预留] 用于换卡申请功能，待产品规划） const ( - ReplacementStatusPending = 1 // 待处理 - ReplacementStatusApproved = 2 // 已通过 - ReplacementStatusRejected = 3 // 已拒绝 - ReplacementStatusCompleted = 4 // 已完成 + ReplacementStatusPending = 1 // 待处理（[预留]） + ReplacementStatusApproved = 2 // 已通过（[预留]） + ReplacementStatusRejected = 3 // 已拒绝（[预留]） + ReplacementStatusCompleted = 4 // 已完成（[预留]） ) // ======================================== @@ -261,10 +261,137 @@ const ( CarrierCodeCBN = "CBN" // 广电 ) +// 换货原因（[预留] 用于换卡原因管理功能，待产品规划） const ( - ReplacementReasonDamaged = "damaged" - ReplacementReasonLost = "lost" - ReplacementReasonMalfunction = "malfunction" - ReplacementReasonUpgrade = "upgrade" - ReplacementReasonOther = "other" + ReplacementReasonDamaged = "damaged" // 损坏（[预留]） + ReplacementReasonLost = "lost" // 丢失（[预留]） + ReplacementReasonMalfunction = "malfunction" // 故障（[预留]） + ReplacementReasonUpgrade = "upgrade" // 升级（[预留]） + ReplacementReasonOther = "other" // 其他（[预留]） ) + +// ======================================== +// 状态名称映射函数 +// ======================================== + +// GetIotCardStatusName 获取 IoT 卡业务状态名称 +// 对应 IotCardStatus* 常量：1=在库, 2=已分销, 3=已激活, 4=已停用 +func GetIotCardStatusName(status int) string { + switch status { + case IotCardStatusInStock: + return "在库" + case IotCardStatusDistributed: + return "已分销" + case IotCardStatusActivated: + return "已激活" + case IotCardStatusSuspended: + return "已停用" + default: + return "未知" + } +} + +// GetActivationStatusName 获取激活状态名称 +// 对应 ActivationStatus* 常量：0=未激活, 1=已激活 +func GetActivationStatusName(status int) string { + switch status { + case ActivationStatusInactive: + return "未激活" + case ActivationStatusActive: + return "已激活" + default: + return "未知" + } +} + +// GetRealNameStatusName 获取实名状态名称 +// 对应 RealNameStatus* 常量：0=未实名, 1=已实名 +func GetRealNameStatusName(status int) string { + switch status { + case RealNameStatusNotVerified: + return "未实名" + case RealNameStatusVerified: + return "已实名" + default: + return "未知" + } +} + +// GetNetworkStatusName 获取网络状态名称 +// 对应 NetworkStatus* 常量：0=停机, 1=开机 +func GetNetworkStatusName(status int) string { + switch status { + case NetworkStatusOffline: + return "停机" + case NetworkStatusOnline: + return "开机" + default: + return "未知" + } +} + +// GetCommissionRecordStatusName 获取佣金记录状态名称 +// 对应 CommissionStatus* 常量：1=已冻结, 2=解冻中, 3=已发放, 4=已失效, 99=待人工修正 +func GetCommissionRecordStatusName(status int) string { + switch status { + case CommissionStatusFrozen: + return "已冻结" + case CommissionStatusUnfreezing: + return "解冻中" + case CommissionStatusReleased: + return "已发放" + case CommissionStatusInvalid: + return "已失效" + case CommissionStatusPendingReview: + return "待人工修正" + default: + return "未知" + } +} + +// GetOrderPaymentStatusName 获取订单支付状态名称 +// 1=待支付, 2=已支付, 3=已取消, 4=已退款 +func GetOrderPaymentStatusName(status int) string { + switch status { + case 1: + return "待支付" + case 2: + return "已支付" + case 3: + return "已取消" + case 4: + return "已退款" + default: + return "未知" + } +} + +// GetOrderCommissionStatusName 获取订单佣金计算状态名称 +// 1=待计算, 2=已计算 +func GetOrderCommissionStatusName(status int) string { + switch status { + case 1: + return "待计算" + case 2: + return "已计算" + default: + return "未知" + } +} + +// GetRefundStatusName 获取退款申请状态名称 +// 1=待审批, 2=已通过, 3=已拒绝, 4=已退回 +func GetRefundStatusName(status int) string { + switch status { + case 1: + return "待审批" + case 2: + return "已通过" + case 3: + return "已拒绝" + case 4: + return "已退回" + default: + return "未知" + } +} diff --git a/pkg/constants/polling.go b/pkg/constants/polling.go index 1bf101e..246951c 100644 --- a/pkg/constants/polling.go +++ b/pkg/constants/polling.go @@ -21,3 +21,15 @@ const PollingDefaultMaxConcurrency = 300 // PollingConcurrencyKeyTTL 并发计数 key 的过期时间（秒） // 保证 Worker 意外崩溃（defer Decr 未执行）时计数器在此时间内自动归零 const PollingConcurrencyKeyTTL = 600 // 10 分钟 + +// 轮询手动触发日志状态常量 +const ( + // PollingManualTriggerStatusPending 轮询手动触发日志状态-待处理 + PollingManualTriggerStatusPending = "pending" + // PollingManualTriggerStatusProcessing 轮询手动触发日志状态-处理中 + PollingManualTriggerStatusProcessing = "processing" + // PollingManualTriggerStatusCompleted 轮询手动触发日志状态-已完成 + PollingManualTriggerStatusCompleted = "completed" + // PollingManualTriggerStatusCancelled 轮询手动触发日志状态-已取消 + PollingManualTriggerStatusCancelled = "cancelled" +) diff --git a/pkg/constants/redis.go b/pkg/constants/redis.go index 2367edc..90a9656 100644 --- a/pkg/constants/redis.go +++ b/pkg/constants/redis.go @@ -427,3 +427,15 @@ func RedisPollingShardQueueKey(shardID int, taskType string) string { func RedisPollingDeviceOpLockKey(deviceID uint) string { return fmt.Sprintf("polling:device:op_lock:%d", deviceID) } + +// ======================================== +// 支付配置缓存 Redis Key +// ======================================== + +// RedisPaymentConfigKey 支付配置缓存 Key +// 用途：缓存 WechatConfig 数据（JSON 格式），避免每次支付时重复查询数据库 +// 格式：payment:config:{configID} +// TTL：1 小时 +func RedisPaymentConfigKey(configID uint) string { + return fmt.Sprintf("payment:config:%d", configID) +} diff --git a/pkg/constants/wallet.go b/pkg/constants/wallet.go index 74d137c..c4ebeef 100644 --- a/pkg/constants/wallet.go +++ b/pkg/constants/wallet.go @@ -145,90 +145,3 @@ func RedisAssetWalletBalanceKey(resourceType string, resourceID uint) string { func RedisAssetWalletLockKey(resourceType string, resourceID uint) string { return fmt.Sprintf("asset_wallet:lock:%s:%d", resourceType, resourceID) } - -// ========== 兼容性别名（待清理）========== - -// 以下常量保留用于向后兼容，待旧代码清理后删除 - -// WalletTypeMain 主钱包（已废弃，使用 AgentWalletTypeMain） -const WalletTypeMain = AgentWalletTypeMain - -// WalletTypeCommission 分佣钱包（已废弃，使用 AgentWalletTypeCommission） -const WalletTypeCommission = AgentWalletTypeCommission - -// WalletResourceTypeIotCard 物联网卡钱包（已废弃，使用 AssetWalletResourceTypeIotCard） -const WalletResourceTypeIotCard = AssetWalletResourceTypeIotCard - -// WalletResourceTypeDevice 设备钱包（已废弃，使用 AssetWalletResourceTypeDevice） -const WalletResourceTypeDevice = AssetWalletResourceTypeDevice - -// WalletResourceTypeShop 店铺钱包（已废弃，代理钱包不再使用 resource_type） -const WalletResourceTypeShop = "shop" - -// WalletStatusNormal 钱包状态-正常（已废弃，使用 AgentWalletStatusNormal 或 AssetWalletStatusNormal） -const WalletStatusNormal = AgentWalletStatusNormal - -// WalletStatusFrozen 钱包状态-冻结（已废弃，使用 AgentWalletStatusFrozen 或 AssetWalletStatusFrozen） -const WalletStatusFrozen = AgentWalletStatusFrozen - -// WalletStatusClosed 钱包状态-关闭（已废弃，使用 AgentWalletStatusClosed 或 AssetWalletStatusClosed） -const WalletStatusClosed = AgentWalletStatusClosed - -// TransactionTypeRecharge 交易类型-充值（已废弃，使用 AgentTransactionTypeRecharge 或 AssetTransactionTypeRecharge） -const TransactionTypeRecharge = AgentTransactionTypeRecharge - -// TransactionTypeDeduct 交易类型-扣款（已废弃，使用 AgentTransactionTypeDeduct 或 AssetTransactionTypeDeduct） -const TransactionTypeDeduct = AgentTransactionTypeDeduct - -// TransactionTypeRefund 交易类型-退款（已废弃，使用 AgentTransactionTypeRefund 或 AssetTransactionTypeRefund） -const TransactionTypeRefund = AgentTransactionTypeRefund - -// TransactionTypeCommission 交易类型-分佣（已废弃，使用 AgentTransactionTypeCommission） -const TransactionTypeCommission = AgentTransactionTypeCommission - -// TransactionTypeWithdrawal 交易类型-提现（已废弃，使用 AgentTransactionTypeWithdrawal） -const TransactionTypeWithdrawal = AgentTransactionTypeWithdrawal - -// RechargeOrderPrefix 充值订单号前缀（已废弃，使用 AgentRechargeOrderPrefix 或 AssetRechargeOrderPrefix） -const RechargeOrderPrefix = "RCH" - -// RechargeMinAmount 最小充值金额（已废弃，使用 AgentRechargeMinAmount 或 AssetRechargeMinAmount） -const RechargeMinAmount = AssetRechargeMinAmount - -// RechargeMaxAmount 最大充值金额（已废弃，使用 AgentRechargeMaxAmount 或 AssetRechargeMaxAmount） -const RechargeMaxAmount = AssetRechargeMaxAmount - -// ========== Card* 废弃别名（向后兼容）========== - -// Deprecated: 使用 AssetWalletResourceTypeIotCard -const CardWalletResourceTypeIotCard = AssetWalletResourceTypeIotCard - -// Deprecated: 使用 AssetWalletResourceTypeDevice -const CardWalletResourceTypeDevice = AssetWalletResourceTypeDevice - -// Deprecated: 使用 AssetWalletStatusNormal -const CardWalletStatusNormal = AssetWalletStatusNormal - -// Deprecated: 使用 AssetWalletStatusFrozen -const CardWalletStatusFrozen = AssetWalletStatusFrozen - -// Deprecated: 使用 AssetWalletStatusClosed -const CardWalletStatusClosed = AssetWalletStatusClosed - -// Deprecated: 使用 AssetTransactionTypeRecharge -const CardTransactionTypeRecharge = AssetTransactionTypeRecharge - -// Deprecated: 使用 AssetTransactionTypeDeduct -const CardTransactionTypeDeduct = AssetTransactionTypeDeduct - -// Deprecated: 使用 AssetTransactionTypeRefund -const CardTransactionTypeRefund = AssetTransactionTypeRefund - -// Deprecated: 使用 AssetRechargeOrderPrefix -const CardRechargeOrderPrefix = AssetRechargeOrderPrefix - -// Deprecated: 使用 AssetRechargeMinAmount -const CardRechargeMinAmount = AssetRechargeMinAmount - -// Deprecated: 使用 AssetRechargeMaxAmount -const CardRechargeMaxAmount = AssetRechargeMaxAmount diff --git a/pkg/database/postgres.go b/pkg/database/postgres.go index 27edf65..06e8b3e 100644 --- a/pkg/database/postgres.go +++ b/pkg/database/postgres.go @@ -87,12 +87,6 @@ func InitPostgreSQL(cfg *config.DatabaseConfig, log *zap.Logger) (*gorm.DB, erro zap.Int("max_idle_conns", maxIdleConns), zap.Duration("conn_max_lifetime", connMaxLifetime)) - // db.AutoMigrate( - // &model.Account{}, - // &model.Role{}, - // &model.Permission{}, - // &model.RolePermission{}, - // ) return db, nil } diff --git a/pkg/errors/codes.go b/pkg/errors/codes.go index b2a537f..0dcffc4 100644 --- a/pkg/errors/codes.go +++ b/pkg/errors/codes.go @@ -65,7 +65,6 @@ const ( CodeWithdrawalNotFound = 1052 // 提现申请不存在 CodeWalletNotFound = 1053 // 钱包不存在 CodeInsufficientQuota = 1054 // 额度不足 - CodeExceedLimit = 1055 // 超过限制 // IoT 卡相关错误 (1070-1089) CodeIotCardNotFound = 1070 // IoT 卡不存在 @@ -224,7 +223,6 @@ var allErrorCodes = []int{ CodeWithdrawalNotFound, CodeWalletNotFound, CodeInsufficientQuota, - CodeExceedLimit, CodeIotCardNotFound, CodeIotCardBoundToDevice, CodeIotCardStatusNotAllowed, @@ -356,7 +354,6 @@ var errorMessages = map[int]string{ CodeWithdrawalNotFound: "提现申请不存在", CodeWalletNotFound: "钱包不存在", CodeInsufficientQuota: "额度不足", - CodeExceedLimit: "超过限制", CodeIotCardNotFound: "IoT 卡不存在", CodeIotCardBoundToDevice: "IoT 卡已绑定设备，不能单独操作", CodeIotCardStatusNotAllowed: "卡状态不允许此操作", diff --git a/pkg/openapi/handlers.go b/pkg/openapi/handlers.go index f29a120..901ca42 100644 --- a/pkg/openapi/handlers.go +++ b/pkg/openapi/handlers.go @@ -16,6 +16,7 @@ func BuildDocHandlers() *bootstrap.Handlers { Role: admin.NewRoleHandler(nil, nil), Permission: admin.NewPermissionHandler(nil), PersonalCustomer: app.NewPersonalCustomerHandler(nil, nil), + ClientAuth: app.NewClientAuthHandler(nil, nil), ClientAsset: app.NewClientAssetHandler(nil, nil, nil, nil, nil, nil, nil, nil, nil), ClientWallet: app.NewClientWalletHandler(nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil), ClientOrder: app.NewClientOrderHandler(nil, nil), @@ -24,6 +25,7 @@ func BuildDocHandlers() *bootstrap.Handlers { ClientDevice: app.NewClientDeviceHandler(nil, nil, nil, nil, nil, nil, nil), Shop: admin.NewShopHandler(nil), ShopRole: admin.NewShopRoleHandler(nil), + AdminAuth: admin.NewAuthHandler(nil, nil), ShopCommission: admin.NewShopCommissionHandler(nil), CommissionWithdrawal: admin.NewCommissionWithdrawalHandler(nil, nil), CommissionWithdrawalSetting: admin.NewCommissionWithdrawalSettingHandler(nil), @@ -54,6 +56,7 @@ func BuildDocHandlers() *bootstrap.Handlers { PollingCleanup: admin.NewPollingCleanupHandler(nil), PollingManualTrigger: admin.NewPollingManualTriggerHandler(nil), Asset: admin.NewAssetHandler(nil, nil, nil, nil), + AssetLifecycle: admin.NewAssetLifecycleHandler(nil), AssetWallet: admin.NewAssetWalletHandler(nil), WechatConfig: admin.NewWechatConfigHandler(nil), AgentRecharge: admin.NewAgentRechargeHandler(nil, nil), diff --git a/pkg/payment/loader.go b/pkg/payment/loader.go new file mode 100644 index 0000000..db1857d --- /dev/null +++ b/pkg/payment/loader.go @@ -0,0 +1,141 @@ +// Package payment 提供支付配置动态加载功能 +// 根据 payment_config_id 按需加载支付实例，支持多商户场景 +package payment + +import ( + "context" + "net/http" + "time" + + "github.com/ArtisanCloud/PowerWeChat/v3/src/kernel" + "github.com/bytedance/sonic" + "github.com/redis/go-redis/v9" + "go.uber.org/zap" + "gorm.io/gorm" + + "github.com/break/junhong_cmp_fiber/internal/model" + "github.com/break/junhong_cmp_fiber/internal/store/postgres" + "github.com/break/junhong_cmp_fiber/pkg/constants" + "github.com/break/junhong_cmp_fiber/pkg/errors" + "github.com/break/junhong_cmp_fiber/pkg/wechat" +) + +// PaymentConfigLoader 支付配置加载器接口 +// 根据 payment_config_id 动态加载支付实例，支持多商户场景 +type PaymentConfigLoader interface { + // LoadConfig 加载指定 ID 的支付配置实例 + LoadConfig(ctx context.Context, configID uint) (wechat.PaymentServiceInterface, error) +} + +// paymentConfigLoader PaymentConfigLoader 的具体实现 +type paymentConfigLoader struct { + wechatConfigStore *postgres.WechatConfigStore + redis *redis.Client + wechatCache kernel.CacheInterface + logger *zap.Logger +} + +// NewPaymentConfigLoader 创建 PaymentConfigLoader 实例 +func NewPaymentConfigLoader( + store *postgres.WechatConfigStore, + rdb *redis.Client, + logger *zap.Logger, +) PaymentConfigLoader { + return &paymentConfigLoader{ + wechatConfigStore: store, + redis: rdb, + wechatCache: wechat.NewRedisCache(rdb), + logger: logger, + } +} + +// LoadConfig 根据 configID 加载支付配置实例 +// 优先从 Redis 缓存读取 WechatConfig（TTL 1 小时），未命中则查数据库 +func (l *paymentConfigLoader) LoadConfig(ctx context.Context, configID uint) (wechat.PaymentServiceInterface, error) { + config, err := l.loadConfigFromCacheOrDB(ctx, configID) + if err != nil { + return nil, err + } + return l.buildPaymentService(config) +} + +// loadConfigFromCacheOrDB 从 Redis 缓存或数据库加载 WechatConfig +// 缓存 key: payment:config:{configID}，TTL 1 小时 +func (l *paymentConfigLoader) loadConfigFromCacheOrDB(ctx context.Context, configID uint) (*model.WechatConfig, error) { + cacheKey := constants.RedisPaymentConfigKey(configID) + + val, err := l.redis.Get(ctx, cacheKey).Result() + if err == nil { + var config model.WechatConfig + if unmarshalErr := sonic.UnmarshalString(val, &config); unmarshalErr == nil { + return &config, nil + } + } + + config, dbErr := l.wechatConfigStore.GetByID(ctx, configID) + if dbErr != nil { + if dbErr == gorm.ErrRecordNotFound { + return nil, errors.New(errors.CodeWechatConfigNotFound) + } + return nil, errors.Wrap(errors.CodeInternalError, dbErr, "加载支付配置失败") + } + + if data, marshalErr := sonic.MarshalString(config); marshalErr == nil { + l.redis.Set(ctx, cacheKey, data, time.Hour) + } + + return config, nil +} + +// buildPaymentService 根据 WechatConfig 构建对应的支付服务实例 +// 支持 wechat（v3）和 wechat_v2（v2）两种渠道类型 +func (l *paymentConfigLoader) buildPaymentService(config *model.WechatConfig) (wechat.PaymentServiceInterface, error) { + switch config.ProviderType { + case model.ProviderTypeWechat: + // 微信直连 v3，使用 PowerWeChat SDK + app, err := wechat.NewPaymentAppFromConfig(config, config.OaAppID, l.wechatCache, l.logger) + if err != nil { + return nil, errors.Wrap(errors.CodeWechatPayFailed, err, "构建微信支付 v3 实例失败") + } + return wechat.NewPaymentService(app, l.logger), nil + + case model.ProviderTypeWechatV2: + // 微信直连 v2，仅需 APIv2Key，不要求证书 + svc, err := wechat.NewPaymentV2ServiceFromConfig(config, config.OaAppID, l.logger) + if err != nil { + return nil, errors.Wrap(errors.CodeWechatPayFailed, err, "构建微信支付 v2 实例失败") + } + // v2 不实现完整接口，通过适配器包装 + return &v2PaymentAdapter{svc: svc}, nil + + default: + return nil, errors.New(errors.CodeWechatConfigNotFound, "不支持的支付渠道类型: "+config.ProviderType) + } +} + +// v2PaymentAdapter 微信支付 v2 适配器 +// 将 PaymentV2Service 适配为完整的 PaymentServiceInterface +// v2 仅支持 JSAPI 支付，其余方法返回不支持错误 +type v2PaymentAdapter struct { + svc *wechat.PaymentV2Service +} + +func (a *v2PaymentAdapter) CreateJSAPIOrder(ctx context.Context, orderNo, description, openID string, amount int) (*wechat.JSAPIPayResult, error) { + return a.svc.CreateJSAPIOrder(ctx, orderNo, description, openID, amount) +} + +func (a *v2PaymentAdapter) CreateH5Order(_ context.Context, _ string, _ string, _ int, _ *wechat.H5SceneInfo) (*wechat.H5PayResult, error) { + return nil, errors.New(errors.CodeWechatPayFailed, "微信支付 v2 不支持 H5 支付") +} + +func (a *v2PaymentAdapter) QueryOrder(_ context.Context, _ string) (*wechat.OrderInfo, error) { + return nil, errors.New(errors.CodeWechatPayFailed, "微信支付 v2 暂不支持查单接口") +} + +func (a *v2PaymentAdapter) CloseOrder(_ context.Context, _ string) error { + return errors.New(errors.CodeWechatPayFailed, "微信支付 v2 暂不支持关单接口") +} + +func (a *v2PaymentAdapter) HandlePaymentNotify(_ *http.Request, _ wechat.PaymentNotifyCallback) (*http.Response, error) { + return nil, errors.New(errors.CodeWechatPayFailed, "微信支付 v2 回调请通过 VerifyCallback 处理") +} diff --git a/pkg/queue/handler.go b/pkg/queue/handler.go index 6c9f65d..3da6797 100644 --- a/pkg/queue/handler.go +++ b/pkg/queue/handler.go @@ -58,14 +58,10 @@ func NewHandler( func (h *Handler) RegisterHandlers() *asynq.ServeMux { emailHandler := task.NewEmailHandler(h.redis, h.logger) - syncHandler := task.NewSyncHandler(h.db, h.logger) h.mux.HandleFunc(constants.TaskTypeEmailSend, emailHandler.HandleEmailSend) h.logger.Info("注册邮件发送任务处理器", zap.String("task_type", constants.TaskTypeEmailSend)) - h.mux.HandleFunc(constants.TaskTypeDataSync, syncHandler.HandleDataSync) - h.logger.Info("注册数据同步任务处理器", zap.String("task_type", constants.TaskTypeDataSync)) - h.registerIotCardImportHandler() h.registerDeviceImportHandler() h.registerCommissionStatsHandlers()