huang
f339fb1987
All checks were successful
构建并部署到测试环境（无 SSH） / build-and-deploy (push) Successful in 7m8s
- client_order: 新增 getOrCreateWallet 兜底，钱包不存在时自动创建 - device_import: 设备导入事务内同步创建设备钱包 - iot_card_import: IoT卡批量导入后批量创建卡钱包 - queue/handler: 传递 AssetWalletStore 给两个导入 handler - migration 000098: 为存量IoT卡和设备补建资产钱包
3.4 KiB
3.4 KiB
Why
系统目前没有退款功能。当已支付的套餐购买订单需要退款时，只能线下处理，无法追踪退款状态，也无法自动回扣已发放的佣金、停掉已激活的套餐和资产。需要一套完整的退款审批流程：人工申请 → 审批/拒绝/退回 → 审批通过后自动停掉套餐和资产、全额回扣佣金、更新订单状态。
What Changes
- I-1 退款数据模型：新建
tb_refund_request表，定义退款单的完整生命周期字段（退款单号、关联订单、店铺ID、实收金额、申请退款金额、审批金额、状态流转、审批人/审批时间、佣金回扣标记、资产重置标记）。新建internal/model/refund.goGORM Model。 - I-2 退款接口设计：新建完整的 Handler + Service + Store 三层实现，提供 7 个 API 接口：发起申请、列表查询、详情查询、审批通过、审批拒绝、退回申请、重新提交。仅平台账号可操作。状态流转：1(待审批) → 2(已通过)/3(已拒绝)/4(已退回)，4(已退回) → 1(待审批)。创建时检查同一订单不能重复退款（已拒绝的除外）。
- I-3 审批通过后的佣金全额回扣：审批通过后，自动查找该订单产生的所有已入账佣金记录，全额从各代理的佣金钱包中扣减（允许余额为负），写入交易流水。
- I-4 审批通过后的资产处理：审批通过后，自动失效该资产所有套餐、停机（单卡调停机接口、设备调停设备接口停所有绑定卡）、世代重置（generation+1、累计充值清零、asset_status 回到"在库"、清理客户绑定和资产钱包），参照换货模块逻辑。最后更新订单状态为已退款。
Capabilities
New Capabilities
refund-request: 退款申请数据模型和状态流转refund-api: 退款审批流程的 7 个 API 接口（仅平台账号可操作）refund-commission-deduct: 退款审批通过后的佣金全额回扣机制refund-asset-reset: 退款审批通过后的资产处理（套餐失效 + 停机 + 世代重置 + 订单状态更新）
Modified Capabilities
无需修改现有能力的接口签名。需在 package/activation_service.go 中新增 InvalidateAllPackagesByAsset 方法。
Impact
- 新增文件：
internal/model/refund.go、internal/model/dto/refund_dto.go、internal/store/postgres/refund_store.go、internal/service/refund/service.go、internal/handler/admin/refund.go、路由注册文件internal/routes/refund.go - 修改文件：
internal/bootstrap/stores.go、internal/bootstrap/services.go、internal/bootstrap/handlers.go、internal/routes/routes.go、cmd/api/docs.go、cmd/gendocs/main.go、internal/service/package/activation_service.go（新增方法） - DB 迁移：新建
tb_refund_request表 - 新增常量：退款状态常量（RefundStatusPending=1, Approved=2, Rejected=3, Returned=4）、交易类型
AgentTransactionTypeCommissionDeduct、关联业务类型ReferenceTypeRefund - 跨模块依赖：退款 Service 需注入 orderStore、commissionRecordStore、agentWalletStore、agentWalletTransactionStore、stopResumeService、deviceService、packageActivationService、iotCardStore、deviceStore、assetWalletStore（参照换货模块的资产重置）
- 前端影响：管理端需新增退款管理页面；佣金明细需展示
commission_deduct类型流水