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

## 订单支付状态速查表

| 状态值 | 常量名 | 说明 | 触发条件 | 后续操作 |
|-------|-------|------|---------|---------|
| 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`

## 常用常量速查

```go
// 订单超时
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` 向上逐级分配。每一级的佣金 = 该级成本价 - 下级成本价。

## 数据库查询速查

### 查询待支付订单
```sql
SELECT * FROM tb_order WHERE payment_status = 1 AND expires_at < NOW();
```

### 查询待计算佣金的订单
```sql
SELECT * FROM tb_order WHERE commission_status = 1;
```

### 查询店铺可用余额
```sql
SELECT balance - frozen_balance as available_balance 
FROM tb_agent_wallet 
WHERE shop_id = ? AND wallet_type = 'commission';
```

### 查询提现中的金额
```sql
SELECT SUM(amount) as withdrawing_amount 
FROM tb_commission_withdrawal_request 
WHERE shop_id = ? AND status = 1;
```

### 查询已提现的金额
```sql
SELECT SUM(amount) as withdrawn_amount 
FROM tb_commission_withdrawal_request 
WHERE shop_id = ? AND status = 2;
```

## 业务规则速查

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

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

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