huang
8f66ca7bcb
All checks were successful
构建并部署到测试环境（无 SSH） / build-and-deploy (push) Successful in 7m14s
236 lines
7.8 KiB
Markdown
236 lines
7.8 KiB
Markdown
# 差价佣金文档索引
|
||
|
||
本索引汇总了所有关于差价佣金计算和分配的文档，帮助快速定位所需信息。
|
||
|
||
## 📚 文档列表
|
||
|
||
### 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` 的常见问题
|
||
|