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

## 搜索范围
- 关键词：订单状态、冻结、差价佣金、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`
- 提现流程中使用事务确保数据一致性