junhong_cmp_fiber/.planning/phases/04-refund-pay-ops/04-CONTEXT.md

Phase 4: 退款 + 支付 + 运营修复 - Context

Gathered: 2026-03-28 Status: Ready for planning

## Phase Boundary

实现完整退款流程（REFUND-0103）、补全富友支付 JSAPI/小程序接口（PAY-0104）、修复运营逻辑断点（OPS-01~02）。共 9 个需求：

• REFUND：新功能模块（退款申请→审批→佣金回扣）
• PAY：留桩替换（富友支付 JSAPI/小程序，平台代购场景修复）
• OPS：业务逻辑修复（卡/设备 status 3/4 触发、payment_status 枚举统一）

## Implementation Decisions

Plan 分组策略

• D-01: 拆分为 2 个 Plan：
  • Plan 1（REFUND）：REFUND-01 先行（DB 迁移 + Model + Store），然后串行完成 REFUND-02（7 个接口）+ REFUND-03（佣金扣减逻辑嵌入 Approve）
  • Plan 2（PAY + OPS 合并）：PAY-0104 + OPS-0102 共 6 个需求，两者互相独立可并行编排
• D-02: REFUND-01 必须先于 REFUND-02/03 执行（DB 迁移和模型是所有上层代码的基础）
• D-03: 每个子任务独立一个 commit（延续 Phase 1/2/3 粒度规范）

退款状态机（REFUND）

• D-04: 退款单号生成规则：{order_no}-RF{seq}（同一订单第 1 次退款为 RF1，第 2 次为 RF2，以此类推）。Create 时查询该订单现有退款数量 +1 作为序号
• D-05: 同一订单同时只允许一个"待处理"状态的退款申请（status=pending/returned），防止重复退款
• D-06: 退款状态流转：
  • pending → approved（审批通过，触发佣金扣减 + 更新订单 payment_status=4）
  • pending → rejected（审批拒绝，必填拒绝原因）
  • pending → returned（审批人退回，申请人可重提）
  • returned → pending（申请人 Resubmit 重提）
• D-07: Return（退回）由审批人操作，退回后状态变为 returned，申请人可调用 Resubmit 重新提交变回 pending
• D-08: 审批人可修改退款金额（approved_refund_amount 可与 requested_refund_amount 不同）。佣金扣减以 approved_refund_amount 为准
• D-09: 审批通过后同步更新订单 payment_status = 4（已退款），与 OPS-02 的 payment_status 枚举统一对齐

退款佣金扣减（REFUND-03）

• D-10: 佣金扣减内嵌在 Approve() 事务内同步执行（不走 Asynq 异步任务）。原子性：退款审批通过、佣金扣减、订单状态更新在同一事务中完成，失败可回滚
• D-11: 佣金扣减算法（禁用 float64，使用整数算术）：

  deductAmount := commission.Amount * refund.ApprovedRefundAmount / refund.ActualReceivedAmount
  

  先乘后除，全程 int64，防止整数除法精度丢失。对该订单所有佣金记录逐一计算扣减额，写负向交易流水
• D-12: 佣金扣减允许余额变为负数（规格书明确：允许为负数）

富友支付（PAY）

• D-13: FuiouPayJSAPI 和 FuiouPayMiniApp 函数签名需从 error 改为 (*dto.FuiouPayJSAPIResponse, error)，参考 WechatPayJSAPI 的返回结构
• D-14: 新建 FuiouPayJSAPIResponse DTO，字段从 pkg/fuiou/types.go 的 WxPreCreateResponse SDK 字段映射（SdkAppid, SdkTimestamp, SdkNoncestr, SdkPrepayid, SdkPackage, SdkSigntype, SdkPaysign），与微信官方 wx.requestPayment() 参数对齐
• D-15: JSAPI（公众号）tradeType = JSAPI；小程序 tradeType = LETPAY（两者逻辑相同，仅此字段不同）
• D-16: 已有富友 SDK 实现（pkg/fuiou/client.go + wxprecreate.go），直接调用 client.WxPreCreate() 方法

平台代理钱包代购（PAY-04）

• D-17: 修改 CreateAdminOrder（不是 CreateLegacy，CreateLegacy 已废弃，Handler 实际调用的是 CreateAdminOrder）
• D-18: 触发条件：buyerType == "" && resourceShopID != nil（平台用户在 Handler 层传入 buyerType="" buyerID=0）
• D-19: 钱包和成本价均来自**资产所属代理（*resourceShopID）**的钱包和成本价（等同于代理自购场景）
• D-20: 订单标记：purchaseRole = purchased_by_platform，operatorType = "platform"
• D-21: sellerCostPrice = resourceShop 代理的成本价（与代理自购相同，上下级佣金链照常计算）

卡/设备 status 3/4 触发（OPS-01）

• D-22: status=3（已激活）：在 activation_service.go 套餐激活事务内同步更新卡/设备表的 status=3（不走 goroutine，保证原子性）
• D-23: status=4（已停用）：在 activation_service.go 的套餐到期检测逻辑中，调用 activateNextMainPackage 后，若无法找到下一个待激活套餐（即无剩余 active/pending 套餐），则同步更新卡/设备 status=4
• D-24: 卡和设备分开更新两张表（tb_iot_card 和 tb_device），根据 carrierType 分支处理，无需统一封装
• D-25: status 更新在已有套餐激活/到期事务内完成，失败可回滚

payment_status 枚举统一（OPS-02）

• D-26: 删除所有 C 端映射函数：
  • internal/service/client_order/service.go 中的 orderStatusToClientStatus()
  • internal/handler/app/client_order.go 中的 orderStatusToClientPaymentStatus() 和 clientPaymentStatusToOrderStatus()
• D-27: C 端直接输出 DB 原始 payment_status 字段（1=待支付, 2=已支付, 3=已取消, 4=已退款），与管理端完全一致

the Agent's Discretion

• 富友支付 WxPreCreate 调用时的 goodsDesc 字段内容（可从 order.OrderNo 或套餐名称组合）
• 退款 Store 层具体查询方法（参考现有 commission_withdrawal_request_store.go 风格）
• status=3/4 更新时的日志内容（按项目中文日志规范）
• getCostPrice 函数参数（已有现成封装，直接复用）

<canonical_refs>

Canonical References

Downstream agents MUST read these before planning or implementing.

修复规格（核心参考）

• .sisyphus/plans/修正业务-完整方案.md — 完整修复规格书：
  • 方案 I（REFUND-01~03）：第 1716 行起（退款表结构、7 个接口清单、佣金扣减逻辑）
  • 方案 J（PAY + OPS）：第 1862 行起（J-1/J-2/J-3/J-4 各子方案代码片段、人工验收清单）
    • J-1：富友支付 JSAPI/小程序（PAY-01/02/03）
    • J-2：平台钱包代购（PAY-04）—— 注意：规格书错误引用了 CreateLegacy（已废弃），实际修改目标是 CreateAdminOrder
    • J-3：status 3/4 触发逻辑（OPS-01）
    • J-4：payment_status 枚举统一（OPS-02）

核心修改文件

• internal/service/order/service.go — FuiouPayJSAPI/FuiouPayMiniApp 留桩替换；CreateAdminOrder 钱包支付 platform 分支（PAY）
• pkg/fuiou/client.go + pkg/fuiou/wxprecreate.go — 富友 SDK（直接调用 WxPreCreate）
• pkg/fuiou/types.go — WxPreCreateResponse 字段（FuiouPayJSAPIResponse DTO 来源）
• internal/service/package/activation_service.go — 套餐激活/到期逻辑（OPS-01 插入点）
• internal/service/client_order/service.go — orderStatusToClientStatus() 删除（OPS-02）
• internal/handler/app/client_order.go — orderStatusToClientPaymentStatus() / clientPaymentStatusToOrderStatus() 删除（OPS-02）

参考结构（REFUND 设计参照）

• internal/service/commission_withdrawal/service.go — Approve/Reject 风格参考（REFUND-02 接口设计）
• internal/model/dto/commission_withdrawal_dto.go — DTO 字段风格参考（REFUND DTO 设计）
• internal/store/postgres/commission_withdrawal_request_store.go — Store 层风格参考（REFUND Store）

依赖项与约束

• .planning/REQUIREMENTS.md — REFUND-0103, PAY-0104, OPS-01~02 完整需求定义
• internal/handler/admin/order.go — PAY-04：Handler 层传入 buyerType="" buyerID=0 的逻辑（了解上下游）

</canonical_refs>

<code_context>

Existing Code Insights

Reusable Assets

• pkg/fuiou/client.go:WxPreCreate() — 富友预下单接口，PAY-01/02 直接调用，无需重写
• internal/service/order/service.go:WechatPayJSAPI() — 参考模板：验证 wechatPayment != nil → 查订单 → 调用 SDK → 返回 DTO
• internal/service/commission_withdrawal/service.go:Approve() — REFUND Approve 逻辑的最佳参考
• internal/service/package/activation_service.go — status=3/4 的插入位置：activateMainPackage（激活）+ 到期检测循环（到期）
• internal/model/order.go:PurchaseRolePurchasedByPlatform — PAY-04 购买角色常量已存在

Established Patterns

• 佣金扣减：参考 internal/service/commission_withdrawal/service.go 的钱包扣款方式（使用 version 乐观锁）
• DB 迁移：双文件形式（.up.sql / .down.sql），编号接续现有最大值（当前 Phase 3 使用了 000090/91）
• 退款单号：参考提现单号的生成逻辑（WD+时间戳+随机数 → 改为 {order_no}-RF{seq}）
• 路由注册：所有新接口通过 internal/routes/registry.go 的 Register() 注册，并同步更新 cmd/api/docs.go 和 cmd/gendocs/main.go

Integration Points

• REFUND Handler 注册到 /api/admin/refunds 路由组（参考 commission_withdrawal 的路由注册方式）
• PAY-04 修改 CreateAdminOrder 的 wallet 分支，Handler 层无需改动
• OPS-01/02 在 activation_service.go 和 client_order 两个文件内修改，无新增路由
• 富友支付 JSAPI/小程序的 Handler 已存在留桩（internal/handler/app/），替换 Service 层即可

</code_context>

## Specific Ideas

• 退款佣金允许负数：规格书明确允许，代理佣金钱包余额可降至负值（为了确保退款公平性）
• CreateLegacy 废弃问题：规格书 J-2 错误引用了已废弃的 CreateLegacy，实际修改目标是 CreateAdminOrder（这一决策在讨论中由用户确认）
• 富友 SDK 已完整：pkg/fuiou/ 包含完整 client + types + notify + wxprecreate，PAY 工作量主要是替换留桩和编写 DTO

## Deferred Ideas

None — discussion stayed within phase scope.

---

Phase: 04-refund-pay-ops Context gathered: 2026-03-28