junhong_cmp_fiber/docs/COMMISSION_DOCS_INDEX.md

差价佣金文档索引

本索引汇总了所有关于差价佣金计算和分配的文档，帮助快速定位所需信息。

📚 文档列表

1. commission-search-result.md (237行)

内容: 差价佣金计算和分配逻辑的完整搜索结果

包含内容:

• ✅ 差价佣金的计算方式（公式、流程、示例）
• ✅ 差价佣金的发放条件（触发条件、发放流程、入账步骤）
• ✅ 差价佣金与订单状态的关系（状态定义、转换关系、关键字段）
• ✅ 关键代码位置总结（表格形式）
• ✅ 相关常量定义

适合场景: 需要快速了解差价佣金的完整逻辑

快速导航:

• 差价佣金计算公式 → 第一部分 1.1
• 计算流程详解 → 第一部分 1.2
• 触发条件 → 第二部分 2.1
• 发放流程 → 第二部分 2.2
• 佣金入账 → 第二部分 2.3

---

2. commission-flow-diagram.md (319行)

内容: 差价佣金计算的可视化流程图

包含内容:

• ✅ 订单支付到佣金入账的完整流程（ASCII流程图）
• ✅ 成本价差佣金计算详细流程（分步骤流程图）
• ✅ 佣金入账流程（5个步骤）
• ✅ 订单状态转换图
• ✅ 佣金记录状态转换图
• ✅ 代理链佣金分配示例（实际案例）

适合场景: 需要理解整个流程的全貌，或向他人解释流程

快速导航:

• 完整流程 → 第一部分
• 计算细节 → 第二部分
• 入账步骤 → 第三部分
• 状态转换 → 第四、五部分
• 实际案例 → 第六部分

---

3. commission-quick-reference.md (283行)

内容: 差价佣金的快速参考指南

包含内容:

• ✅ 关键文件位置表（8个关键功能）
• ✅ 关键常量速查（任务类型、佣金来源、状态常量）
• ✅ 关键数据库表（5个核心表）
• ✅ 常见问题快速查询（10个Q&A）
• ✅ 调试技巧（6个SQL查询示例）
• ✅ 性能优化建议（3个优化方向）
• ✅ 常见错误排查（3个常见错误）

适合场景: 开发过程中快速查询信息，或调试问题

快速导航:

• 找代码位置 → 快速查询表 1
• 找常量值 → 快速查询表 2
• 找数据库表 → 快速查询表 3
• 常见问题 → 常见问题快速查询
• 调试SQL → 调试技巧
• 性能问题 → 性能优化建议
• 错误处理 → 常见错误排查

---

4. commission-package-model.md (351行)

内容: 套餐与佣金业务模型（原有文档）

包含内容:

• ✅ 核心概念（两种佣金类型、实体关系）
• ✅ 套餐模型详解
• ✅ 差价佣金规则（计算规则、关键区分）
• ✅ 一次性佣金规则（触发条件、链式分配、流程）
• ✅ 梯度佣金规则
• ✅ 约束规则（6个约束）
• ✅ 操作流程（理想的线性流程）

适合场景: 需要理解完整的业务规则和约束

快速导航:

• 两种佣金类型 → 第一部分 1.1
• 差价佣金规则 → 第三部分
• 一次性佣金规则 → 第四部分
• 约束规则 → 第六部分

---

🎯 使用指南

场景1: 我是新开发者，想快速了解差价佣金

推荐阅读顺序:

1. 先读 commission-flow-diagram.md 的第一部分（了解整体流程）
2. 再读 commission-search-result.md 的第一部分（理解计算方式）
3. 最后读 commission-quick-reference.md 的常见问题（掌握细节）

预计时间: 30分钟

---

场景2: 我需要修改佣金计算逻辑

推荐阅读顺序:

1. 先读 commission-search-result.md 的第一部分（理解当前逻辑）
2. 查看 commission-quick-reference.md 的关键文件位置（定位代码）
3. 查看 commission-flow-diagram.md 的第二部分（理解计算细节）
4. 打开代码文件进行修改

关键文件: internal/service/commission_calculation/service.go:121-225

---

场景3: 我需要调试佣金计算问题

推荐阅读顺序:

1. 先读 commission-quick-reference.md 的调试技巧（获取SQL查询）
2. 执行SQL查询获取数据
3. 对比 commission-flow-diagram.md 的第六部分（验证计算结果）
4. 查看 commission-quick-reference.md 的常见错误排查（定位问题）

关键SQL: 见 commission-quick-reference.md 的调试技巧部分

---

场景4: 我需要向产品经理解释佣金逻辑

推荐阅读顺序:

1. 先读 commission-package-model.md 的第三部分（业务规则）
2. 使用 commission-flow-diagram.md 的第六部分（实际案例）
3. 使用 commission-flow-diagram.md 的流程图（可视化展示）

关键资源: commission-flow-diagram.md 的第六部分（代理链佣金分配示例）

---

场景5: 我需要验证佣金计算的正确性

推荐阅读顺序:

1. 先读 commission-quick-reference.md 的Q10（验证方法）
2. 执行SQL查询获取数据
3. 按照验证步骤进行检查
4. 如有问题，查看常见错误排查

关键内容: commission-quick-reference.md 的Q10

---

📊 文档对比表

文档	长度	类型	适合场景	重点
commission-search-result.md	237行	参考	快速了解逻辑	代码位置、计算方式
commission-flow-diagram.md	319行	可视化	理解流程	流程图、状态转换
commission-quick-reference.md	283行	工具	开发调试	常见问题、SQL查询
commission-package-model.md	351行	规范	业务理解	业务规则、约束

---

🔗 关键代码位置速查

功能	文件	行号	文档位置
差价佣金计算	internal/service/commission_calculation/service.go	121-225	search-result 1.2
佣金入账	internal/service/commission_calculation/service.go	641-687	search-result 2.3
佣金计算触发	internal/service/order/service.go	2132-2150	search-result 2.1
订单支付完成	internal/service/order/service.go	1431-1623	search-result 2.1
异步任务处理	internal/task/commission_calculation.go	40-62	search-result 2.2

---

💡 常见问题速查

问题	答案位置
差价佣金什么时候计算？	quick-reference Q1
差价佣金的计算公式是什么？	quick-reference Q2 / search-result 1.1
如何查询某个订单的佣金记录？	quick-reference Q3
佣金什么时候入账？	quick-reference Q4
链路断裂是什么意思？	quick-reference Q5
如何追踪佣金计算过程？	quick-reference Q6
代理钱包余额如何更新？	quick-reference Q7
如何处理佣金计算失败？	quick-reference Q8
一个订单产生多少条佣金记录？	quick-reference Q9
如何验证佣金计算的正确性？	quick-reference Q10

---

📝 文档维护

最后更新时间

• commission-search-result.md: 2025-04-11
• commission-flow-diagram.md: 2025-04-11
• commission-quick-reference.md: 2025-04-11
• commission-package-model.md: 2025-02-03

更新日志

• 2025-04-11: 新增三份文档（search-result, flow-diagram, quick-reference）
• 2025-02-03: 原有 commission-package-model.md

如何贡献

如果发现文档有误或需要补充，请：

1. 提交 Issue 描述问题
2. 或直接提交 PR 修改文档
3. 确保修改后的文档保持一致性

---

🚀 快速开始

第一次接触差价佣金？

1. 花5分钟看 commission-flow-diagram.md 的第一部分
2. 花10分钟看 commission-search-result.md 的第一部分
3. 需要时查阅 commission-quick-reference.md

预计总时间: 15分钟快速入门

---

📞 获取帮助

• 代码问题: 查看 commission-quick-reference.md 的常见错误排查
• 业务问题: 查看 commission-package-model.md 的约束规则
• 流程问题: 查看 commission-flow-diagram.md 的流程图
• 其他问题: 查看 commission-quick-reference.md 的常见问题