# 订单状态与佣金系统文档索引

本索引汇总了关于订单状态、冻结状态和差价佣金的所有文档和代码位置。

## 📚 文档列表

### 1. [order_status_commission_analysis.md](order_status_commission_analysis.md)
**完整的系统分析报告** - 适合深入理解系统设计

**包含内容**：
- ✅ 订单状态定义（支付状态、佣金状态）
- ✅ 订单状态流转逻辑（3种支付方式）
- ✅ 订单超时自动取消机制
- ✅ 佣金系统与订单的关系
- ✅ 钱包冻结与提现流程（3阶段）
- ✅ 关键数据模型说明
- ✅ 完整流程图
- ✅ 业务规则总结
- ✅ 文件索引表

**适用场景**：
- 需要全面理解系统设计
- 进行系统架构评审
- 编写相关功能文档

---

### 2. [order_status_quick_reference.md](order_status_quick_reference.md)
**快速参考指南** - 适合日常开发查询

**包含内容**：
- ✅ 订单支付状态速查表
- ✅ 订单佣金状态速查表
- ✅ 订单创建流程速查
- ✅ 钱包冻结状态速查表
- ✅ 提现流程速查（3阶段）
- ✅ 佣金类型速查
- ✅ 关键代码位置速查
- ✅ 常用常量速查
- ✅ 常见问题解答
- ✅ 数据库查询示例
- ✅ 业务规则速查

**适用场景**：
- 快速查询状态值
- 查找代码位置
- 解答常见问题
- 编写 SQL 查询

---

### 3. [order_status_search_summary.md](order_status_search_summary.md)
**搜索结果总结** - 适合了解核心发现

**包含内容**：
- ✅ 搜索范围说明
- ✅ 5个核心发现
- ✅ 关键代码位置索引
- ✅ 重要业务规则
- ✅ 数据流向图
- ✅ 生成的文档说明
- ✅ 关键发现总结
- ✅ 注意事项
- ✅ 最佳实践

**适用场景**：
- 快速了解系统概况
- 查找关键代码位置
- 了解业务规则
- 学习最佳实践

---

## 🔍 核心概念速查

### 订单状态
| 状态 | 值 | 说明 |
|------|-----|------|
| 待支付 | 1 | 微信/支付宝支付时的初始状态 |
| 已支付 | 2 | 线下/钱包支付或支付回调后的状态 |
| 已取消 | 3 | 待支付订单超时30分钟后的状态 |
| 已退款 | 4 | 退款操作后的状态 |

### 佣金状态
| 状态 | 值 | 说明 |
|------|-----|------|
| 待计算 | 1 | 订单创建时的初始状态 |
| 已计算 | 2 | 佣金计算完成后的状态 |

### 钱包冻结
| 字段 | 说明 |
|------|------|
| balance | 总余额 |
| frozen_balance | 冻结余额（用于提现） |
| 可用余额 | balance - frozen_balance |

---

## 📍 关键代码位置

### 订单相关
```
internal/model/order.go
├─ 第 98-104 行：支付状态常量
├─ 第 106-110 行：佣金状态常量
└─ 第 9-138 行：订单模型定义

internal/service/order/service.go
├─ 第 114-354 行：CreateLegacy（已废弃）
├─ 第 359-674 行：CreateAdminOrder（后台订单创建）
├─ 第 679-928 行：CreateH5Order（H5订单创建）
└─ 第 1314-1385 行：订单超时自动取消
```

### 佣金相关
```
internal/service/commission_calculation/service.go
├─ 第 74-119 行：佣金计算主逻辑
└─ 第 121-230 行：成本价差佣金计算

internal/model/commission.go
└─ 第 9-46 行：佣金记录模型
```

### 提现相关
```
internal/service/shop_commission/service.go
└─ 第 517-649 行：代理发起提现申请

internal/service/commission_withdrawal/service.go
├─ 第 145-256 行：平台审核通过
└─ 第 258-310 行：平台审核拒绝
```

### 钱包相关
```
internal/model/agent_wallet.go
├─ 第 9-30 行：代理钱包模型
└─ 第 37-94 行：钱包交易记录模型

pkg/constants/wallet.go
├─ 第 17-22 行：钱包状态常量
├─ 第 83-91 行：交易状态常量
└─ 第 1-234 行：所有钱包相关常量
```

---

## 🎯 常见任务指南

### 任务 1：查询订单状态
**文档**：order_status_quick_reference.md - 订单支付状态速查表
**代码**：internal/model/order.go:98-104

### 任务 2：理解佣金计算
**文档**：order_status_commission_analysis.md - 第三章
**代码**：internal/service/commission_calculation/service.go:74-230

### 任务 3：实现提现功能
**文档**：order_status_commission_analysis.md - 第四章
**代码**：
- 发起申请：internal/service/shop_commission/service.go:517-649
- 审核通过：internal/service/commission_withdrawal/service.go:145-256
- 审核拒绝：internal/service/commission_withdrawal/service.go:258-310

### 任务 4：查询可提现金额
**文档**：order_status_quick_reference.md - 数据库查询速查
**SQL**：
```sql
SELECT balance - frozen_balance as available_balance 
FROM tb_agent_wallet 
WHERE shop_id = ? AND wallet_type = 'commission';
```

### 任务 5：处理订单超时
**文档**：order_status_commission_analysis.md - 第二章
**代码**：internal/service/order/service.go:1314-1385

---

## ⚠️ 重要注意事项

1. **订单没有冻结状态**
   - 冻结状态存在于代理钱包，不在订单
   - 订单只有支付状态和佣金状态

2. **订单超时不计算佣金**
   - 取消的订单佣金状态保持为"待计算"
   - 不会入队佣金计算任务

3. **代购订单不计算一次性佣金**
   - 一次性佣金仅对非代购订单触发
   - 仅在首次购买时触发

4. **提现流程中的冻结机制**
   - 提现申请时冻结余额
   - 审核通过时从冻结余额直接扣款
   - 审核拒绝时解冻余额

---

## 📊 文档统计

| 文档 | 大小 | 章节数 | 代码位置数 |
|------|------|--------|-----------|
| order_status_commission_analysis.md | 14K | 9 | 20+ |
| order_status_quick_reference.md | 6.0K | 12 | 15+ |
| order_status_search_summary.md | 6.1K | 8 | 10+ |

**总计**：26.1K，29个章节，45+个代码位置

---

## 🚀 快速开始

### 第一次接触系统？
1. 阅读 order_status_search_summary.md（5分钟）
2. 查看 order_status_commission_analysis.md 的流程图（10分钟）
3. 收藏 order_status_quick_reference.md（备用）

### 需要快速查询？
1. 打开 order_status_quick_reference.md
2. 使用速查表或常见问题部分
3. 参考代码位置索引

### 需要深入理解？
1. 阅读 order_status_commission_analysis.md 的完整内容
2. 对照代码位置查看源代码
3. 参考业务规则总结

---

## 📞 相关资源

### 相关文档
- [套餐与佣金业务模型](../commission-package-model.md)
- [分佣逻辑验证指引](../优化说明/分佣逻辑正确与否验证.md)

### 相关代码
- 订单服务：`internal/service/order/`
- 佣金服务：`internal/service/commission_calculation/`
- 提现服务：`internal/service/commission_withdrawal/`
- 钱包服务：`internal/service/shop_commission/`

---

**最后更新**：2024年4月11日
**文档版本**：1.0
**维护者**：开发团队