huang
8f66ca7bcb
All checks were successful
构建并部署到测试环境（无 SSH） / build-and-deploy (push) Successful in 7m14s
251 lines
6.7 KiB
Markdown
251 lines
6.7 KiB
Markdown
# 订单状态与佣金系统文档索引
|
||
|
||
本索引汇总了关于订单状态、冻结状态和差价佣金的所有文档和代码位置。
|
||
|
||
## 📚 文档列表
|
||
|
||
### 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
|
||
**维护者**：开发团队
|
||
|