文档提交

docs/order_status_search_summary.md

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