# 差价佣金文档索引

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

## 📚 文档列表

### 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` 的常见问题