junhong_cmp_fiber/docs/order_status_quick_reference.md

订单状态与佣金系统 - 快速参考

订单支付状态速查表

状态值	常量名	说明	触发条件	后续操作
1	PaymentStatusPending	待支付	微信/支付宝支付创建订单	支付回调或30分钟超时
2	PaymentStatusPaid	已支付	线下/钱包支付或支付成功回调	激活套餐、计算佣金
3	PaymentStatusCancelled	已取消	待支付订单超时30分钟	解冻钱包余额
4	PaymentStatusRefunded	已退款	退款操作	返还金额

订单佣金状态速查表

状态值	常量名	说明	触发条件	后续操作
1	CommissionStatusPending	待计算	订单创建时默认	异步任务计算佣金
2	CommissionStatusCalculated	已计算	佣金计算完成	佣金入账到分佣钱包

订单创建流程速查

线下支付（offline）

创建订单 → PaymentStatus=2(已支付) → 激活套餐 → 入队佣金计算

钱包支付（wallet）

创建订单 → PaymentStatus=2(已支付) → 扣款 → 激活套餐 → 入队佣金计算

微信/支付宝（wechat/alipay）

创建订单 → PaymentStatus=1(待支付) → 支付回调 → PaymentStatus=2 → 激活套餐 → 入队佣金计算
                                    ↓
                            30分钟超时 → PaymentStatus=3(已取消) → 解冻余额

钱包冻结状态速查表

字段	说明	计算方式
balance	总余额	充值 + 佣金入账 - 扣款
frozen_balance	冻结余额	提现申请时冻结
可用余额	可提现金额	balance - frozen_balance

提现流程速查

阶段 1: 代理发起申请

验证可用余额 ✓
    ↓
冻结余额 (frozen_balance += amount)
    ↓
创建提现申请 (Status=1 待审核)
    ↓
创建钱包流水 (Status=3 处理中)

阶段 2a: 平台审核通过

检查冻结余额 ✓
    ↓
从冻结余额扣款 (frozen_balance -= amount)
    ↓
创建提现交易流水
    ↓
更新提现申请 (Status=2 已通过)

阶段 2b: 平台审核拒绝

解冻余额 (frozen_balance -= amount)
    ↓
创建退款交易流水
    ↓
更新提现申请 (Status=3 已拒绝)

佣金类型速查

佣金类型	常量值	触发条件	计算方式
成本价差	cost_diff	所有订单	销售价 - 销售成本价
一次性	one_time	非代购订单首次购买	根据配置

关键代码位置速查

订单相关

• 订单模型: internal/model/order.go:98-110
• 订单创建: internal/service/order/service.go:114-928
• 订单超时: internal/service/order/service.go:1314-1385

佣金相关

• 佣金计算: internal/service/commission_calculation/service.go:74-119
• 成本价差: internal/service/commission_calculation/service.go:121-230

提现相关

• 发起申请: internal/service/shop_commission/service.go:517-649
• 审核通过: internal/service/commission_withdrawal/service.go:145-256
• 审核拒绝: internal/service/commission_withdrawal/service.go:258-310

常用常量速查

// 订单超时
constants.OrderExpireTimeout = 30 * time.Minute

// 钱包状态
constants.AgentWalletStatusNormal = 1   // 正常
constants.AgentWalletStatusFrozen = 2   // 冻结
constants.AgentWalletStatusClosed = 3   // 关闭

// 交易状态
constants.TransactionStatusSuccess    = 1 // 成功
constants.TransactionStatusFailed     = 2 // 失败
constants.TransactionStatusProcessing = 3 // 处理中

// 提现状态
constants.WithdrawalStatusPending  = 1 // 待审核
constants.WithdrawalStatusApproved = 2 // 已通过
constants.WithdrawalStatusRejected = 3 // 已拒绝

常见问题速查

Q: 订单什么时候计算佣金？

A: 订单支付成功后立即入队佣金计算任务（异步）。线下/钱包支付创建时已支付，微信/支付宝支付在回调时支付。

Q: 提现时冻结的余额什么时候解冻？

A:

• 审核通过：从冻结余额扣款（不解冻，直接扣除）
• 审核拒绝：解冻余额回到可用余额

Q: 可用余额如何计算？

A: 可用余额 = 总余额 - 冻结余额

Q: 订单超时自动取消后还会计算佣金吗？

A: 不会。取消的订单佣金状态保持为 待计算，不会入队计算。

Q: 代购订单是否计算一次性佣金？

A: 不计算。一次性佣金仅对非代购订单触发。

Q: 成本价差佣金如何沿代理链分配？

A: 从销售店铺开始，沿着 parent_id 向上逐级分配。每一级的佣金 = 该级成本价 - 下级成本价。

数据库查询速查

查询待支付订单

SELECT * FROM tb_order WHERE payment_status = 1 AND expires_at < NOW();

查询待计算佣金的订单

SELECT * FROM tb_order WHERE commission_status = 1;

查询店铺可用余额

SELECT balance - frozen_balance as available_balance 
FROM tb_agent_wallet 
WHERE shop_id = ? AND wallet_type = 'commission';

查询提现中的金额

SELECT SUM(amount) as withdrawing_amount 
FROM tb_commission_withdrawal_request 
WHERE shop_id = ? AND status = 1;

查询已提现的金额

SELECT SUM(amount) as withdrawn_amount 
FROM tb_commission_withdrawal_request 
WHERE shop_id = ? AND status = 2;

业务规则速查

1. 订单支付规则

   • 待支付订单 30 分钟未支付自动取消
   • 取消时解冻钱包余额（如有）
   • 防止重复下单（幂等性检查）

2. 佣金计算规则

   • 成本价差佣金：仅当 销售价 > 销售成本价 时计算
   • 一次性佣金：仅非代购订单首次购买时触发
   • 佣金链路断裂时标记为待审核

3. 提现规则

   • 提现申请时冻结余额
   • 可用余额 = 总余额 - 冻结余额
   • 手续费 = 提现金额 × 费率 / 10000
   • 实际到账 = 提现金额 - 手续费