junhong_cmp_fiber/docs/ORDER_STATUS_INDEX.md

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

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

📚 文档列表

1. order_status_commission_analysis.md

完整的系统分析报告 - 适合深入理解系统设计

包含内容：

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

适用场景：

• 需要全面理解系统设计
• 进行系统架构评审
• 编写相关功能文档

---

2. order_status_quick_reference.md

快速参考指南 - 适合日常开发查询

包含内容：

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

适用场景：

• 快速查询状态值
• 查找代码位置
• 解答常见问题
• 编写 SQL 查询

---

3. 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：

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. 参考业务规则总结

---

📞 相关资源

相关文档

• 套餐与佣金业务模型
• 分佣逻辑验证指引

相关代码

• 订单服务：internal/service/order/
• 佣金服务：internal/service/commission_calculation/
• 提现服务：internal/service/commission_withdrawal/
• 钱包服务：internal/service/shop_commission/

---

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