junhong_cmp_fiber/docs/order_status_search_summary.md

订单状态与佣金系统搜索结果总结

搜索范围

• 关键词：订单状态、冻结、差价佣金、order status、frozen、commission
• 搜索范围：整个项目代码库
• 文件类型：Go 源代码文件

核心发现

1. 订单状态定义（无冻结状态）

重要发现：订单本身没有冻结状态，只有支付状态和佣金状态。

订单支付状态（4 种）

• PaymentStatusPending = 1：待支付
• PaymentStatusPaid = 2：已支付
• PaymentStatusCancelled = 3：已取消
• PaymentStatusRefunded = 4：已退款

订单佣金状态（2 种）

• CommissionStatusPending = 1：待计算
• CommissionStatusCalculated = 2：已计算

文件位置：internal/model/order.go:98-110

2. 冻结状态存在于钱包，不在订单

重要发现：冻结状态是钱包的概念，用于提现流程。

代理钱包状态（3 种）

• AgentWalletStatusNormal = 1：正常
• AgentWalletStatusFrozen = 2：冻结（整个钱包冻结）
• AgentWalletStatusClosed = 3：关闭

钱包冻结余额字段

• balance：总余额
• frozen_balance：冻结余额（用于提现）
• 可用余额 = balance - frozen_balance

文件位置：pkg/constants/wallet.go:17-22、internal/model/agent_wallet.go:15-16

3. 订单状态流转逻辑

支付方式决定初始状态

1. 线下支付（offline）：创建时直接为 PaymentStatusPaid
2. 钱包支付（wallet）：创建时直接为 PaymentStatusPaid
3. 微信/支付宝（wechat/alipay）：创建时为 PaymentStatusPending，支付回调后变为 PaymentStatusPaid

订单超时自动取消

• 待支付订单 30 分钟未支付自动取消
• 状态变为 PaymentStatusCancelled
• 解冻钱包余额（如有）

文件位置：internal/service/order/service.go:1314-1385

4. 订单与佣金的关系

佣金计算触发条件

• 订单支付成功后立即入队佣金计算任务
• 异步处理，不阻塞订单创建

佣金类型

1. 成本价差佣金（cost_diff）

   • 计算方式：销售价 - 销售成本价
   • 沿代理链向上分配

2. 一次性佣金（one_time）

   • 仅非代购订单触发
   • 仅首次购买时触发

文件位置：internal/service/commission_calculation/service.go:74-230

5. 佣金提现流程（3 阶段）

阶段 1：代理发起申请

• 验证可用余额
• 冻结余额（frozen_balance += amount）
• 创建提现申请（Status = 待审核）

阶段 2a：平台审核通过

• 检查冻结余额
• 从冻结余额扣款（frozen_balance -= amount）
• 更新提现申请（Status = 已通过）

阶段 2b：平台审核拒绝

• 解冻余额（frozen_balance -= amount）
• 更新提现申请（Status = 已拒绝）

文件位置：

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

关键代码位置

功能	文件	行数
订单模型定义	internal/model/order.go	9-138
订单支付状态常量	internal/model/order.go	98-104
订单佣金状态常量	internal/model/order.go	106-110
订单创建逻辑	internal/service/order/service.go	114-928
订单超时取消	internal/service/order/service.go	1314-1385
佣金计算	internal/service/commission_calculation/service.go	74-230
提现申请	internal/service/shop_commission/service.go	517-649
提现审核	internal/service/commission_withdrawal/service.go	145-310
钱包模型	internal/model/agent_wallet.go	9-94
钱包常量	pkg/constants/wallet.go	1-234

重要业务规则

订单支付规则

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

佣金计算规则

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

提现规则

1. 提现申请时冻结余额
2. 可用余额 = 总余额 - 冻结余额
3. 手续费 = 提现金额 × 费率 / 10000

数据流向图

订单创建
  ├─ 线下/钱包支付 → PaymentStatus=2(已支付) → 激活套餐 → 入队佣金计算
  └─ 微信/支付宝 → PaymentStatus=1(待支付) → 支付回调 → PaymentStatus=2 → 激活套餐 → 入队佣金计算
                                          ↓
                                  30分钟超时 → PaymentStatus=3(已取消)

佣金计算
  ├─ 成本价差佣金：销售价 - 销售成本价 → 沿代理链分配 → 入账分佣钱包
  └─ 一次性佣金：非代购订单首次购买 → 入账分佣钱包

提现流程
  ├─ 代理申请 → 冻结余额 → 创建申请(待审核)
  ├─ 平台通过 → 从冻结余额扣款 → 更新申请(已通过)
  └─ 平台拒绝 → 解冻余额 → 更新申请(已拒绝)

生成的文档

已生成两份详细文档：

1. order_status_commission_analysis.md

   • 完整的系统分析报告
   • 包含所有状态定义、流程、数据模型
   • 适合深入理解系统设计

2. order_status_quick_reference.md

   • 快速参考指南
   • 包含速查表、常见问题、SQL 查询
   • 适合日常开发查询

关键发现总结

✅ 已确认

• 订单有支付状态和佣金状态，但没有冻结状态
• 冻结状态存在于代理钱包，用于提现流程
• 差价佣金通过 seller_cost_price 字段计算
• 佣金与订单的关系通过 commission_status 字段维护

⚠️ 注意事项

• 订单超时自动取消不会触发佣金计算
• 代购订单不计算一次性佣金
• 提现时冻结的余额在审核通过时直接扣款，不是解冻后再扣

📌 最佳实践

• 查询订单时同时检查 payment_status 和 commission_status
• 查询可提现金额时使用 balance - frozen_balance
• 提现流程中使用事务确保数据一致性