This commit is contained in:
319
docs/commission-flow-diagram.md
Normal file
319
docs/commission-flow-diagram.md
Normal file
@@ -0,0 +1,319 @@
|
||||
# 差价佣金计算流程图
|
||||
|
||||
## 一、订单支付到佣金入账的完整流程
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────┐
|
||||
│ 客户下单购买套餐 │
|
||||
└────────────────────────────┬────────────────────────────────────────┘
|
||||
│
|
||||
┌────────▼────────┐
|
||||
│ 创建订单 │
|
||||
│ order.id = 123 │
|
||||
│ commission_status = 1 (待计算)
|
||||
│ payment_status = 1 (待支付)
|
||||
└────────┬────────┘
|
||||
│
|
||||
┌────────▼────────┐
|
||||
│ 用户支付 │
|
||||
│ WalletPay() │
|
||||
└────────┬────────┘
|
||||
│
|
||||
┌────────▼────────┐
|
||||
│ 更新订单状态 │
|
||||
│ payment_status = 2 (已支付)
|
||||
│ paid_at = now │
|
||||
└────────┬────────┘
|
||||
│
|
||||
┌────────▼────────────────────────┐
|
||||
│ 激活套餐 │
|
||||
│ activatePackage() │
|
||||
│ (分配套餐到卡/设备) │
|
||||
└────────┬────────────────────────┘
|
||||
│
|
||||
┌────────▼────────────────────────┐
|
||||
│ 入队佣金计算任务 │
|
||||
│ enqueueCommissionCalculation() │
|
||||
│ task_type = "commission:calculate"
|
||||
│ payload = {order_id: 123} │
|
||||
└────────┬────────────────────────┘
|
||||
│
|
||||
│ (异步处理)
|
||||
│
|
||||
┌────────────────────▼────────────────────┐
|
||||
│ Asynq Worker 处理任务 │
|
||||
│ HandleCommissionCalculation() │
|
||||
└────────────────────┬────────────────────┘
|
||||
│
|
||||
┌────────▼────────────────────┐
|
||||
│ CalculateCommission() │
|
||||
│ 开启数据库事务 │
|
||||
└────────┬────────────────────┘
|
||||
│
|
||||
┌────────────────────▼────────────────────┐
|
||||
│ 1. 检查订单佣金状态 │
|
||||
│ if commission_status == 2 → 跳过 │
|
||||
└────────────────────┬────────────────────┘
|
||||
│
|
||||
┌────────────────────▼────────────────────┐
|
||||
│ 2. 计算成本价差佣金 │
|
||||
│ CalculateCostDiffCommission() │
|
||||
└────────────────────┬────────────────────┘
|
||||
│
|
||||
▼
|
||||
```
|
||||
|
||||
## 二、成本价差佣金计算详细流程
|
||||
|
||||
```
|
||||
┌──────────────────────────────────────────────────────────────┐
|
||||
│ CalculateCostDiffCommission(order) │
|
||||
└────────────────────┬─────────────────────────────────────────┘
|
||||
│
|
||||
┌────────────▼────────────┐
|
||||
│ 获取销售店铺信息 │
|
||||
│ seller_shop_id = 10 │
|
||||
└────────────┬────────────┘
|
||||
│
|
||||
┌────────────▼────────────────────────────┐
|
||||
│ 计算销售端利润 │
|
||||
│ profit = total_amount - seller_cost_price
|
||||
│ profit = 200 - 130 = 70元 │
|
||||
│ 为销售店铺创建佣金记录 │
|
||||
│ commission_record { │
|
||||
│ shop_id: 10, │
|
||||
│ amount: 70, │
|
||||
│ commission_source: "cost_diff" │
|
||||
│ } │
|
||||
└────────────┬────────────────────────────┘
|
||||
│
|
||||
┌────────────▼────────────────────────────┐
|
||||
│ 链式向上计算 │
|
||||
│ current_shop_id = seller_shop_id │
|
||||
│ child_cost_price = seller_cost_price │
|
||||
└────────────┬────────────────────────────┘
|
||||
│
|
||||
┌────────────▼────────────────────────────┐
|
||||
│ 循环：while current_shop_id != null │
|
||||
└────────────┬────────────────────────────┘
|
||||
│
|
||||
┌────────────▼────────────────────────────┐
|
||||
│ 1. 获取上级店铺 │
|
||||
│ parent_shop_id = current_shop.parent_id
|
||||
│ if parent_shop_id == null → 结束 │
|
||||
└────────────┬────────────────────────────┘
|
||||
│
|
||||
┌────────────▼────────────────────────────┐
|
||||
│ 2. 查询上级的套餐分配配置 │
|
||||
│ allocation = ShopPackageAllocation │
|
||||
│ where shop_id = parent_shop_id │
|
||||
│ and package_id = order.package_id │
|
||||
└────────────┬────────────────────────────┘
|
||||
│
|
||||
├─ 未找到 ──┐
|
||||
│ │
|
||||
│ ┌──────▼──────────────────┐
|
||||
│ │ 链路断裂处理 │
|
||||
│ │ 创建待审佣金记录 │
|
||||
│ │ status = 99 │
|
||||
│ │ amount = 0 │
|
||||
│ │ remark = "套餐系列未分配" │
|
||||
│ │ 结束循环 │
|
||||
│ └─────────────────────────┘
|
||||
│
|
||||
└─ 找到 ──┐
|
||||
│
|
||||
┌─────────────────────▼──────────────────┐
|
||||
│ 3. 计算差价 │
|
||||
│ my_cost_price = allocation.cost_price
|
||||
│ profit = child_cost_price - my_cost_price
|
||||
│ profit = 130 - 120 = 10元 │
|
||||
└─────────────────────┬──────────────────┘
|
||||
│
|
||||
┌─────────────────────▼──────────────────┐
|
||||
│ 4. 如果差价 > 0，创建佣金记录 │
|
||||
│ commission_record { │
|
||||
│ shop_id: parent_shop_id, │
|
||||
│ amount: profit, │
|
||||
│ commission_source: "cost_diff" │
|
||||
│ } │
|
||||
└─────────────────────┬──────────────────┘
|
||||
│
|
||||
┌─────────────────────▼──────────────────┐
|
||||
│ 5. 更新变量，继续向上 │
|
||||
│ child_cost_price = my_cost_price │
|
||||
│ current_shop_id = parent_shop_id │
|
||||
│ 继续循环 │
|
||||
└─────────────────────┬──────────────────┘
|
||||
│
|
||||
┌─────────▴─────────┐
|
||||
│ 返回佣金记录列表 │
|
||||
└───────────────────┘
|
||||
```
|
||||
|
||||
## 三、佣金入账流程
|
||||
|
||||
```
|
||||
┌──────────────────────────────────────────────────────────────┐
|
||||
│ 对每条佣金记录调用 creditCommissionInTx() │
|
||||
└────────────────────┬─────────────────────────────────────────┘
|
||||
│
|
||||
┌────────────▼────────────────────────┐
|
||||
│ 1. 获取店铺的分佣钱包 │
|
||||
│ wallet = AgentWallet │
|
||||
│ where shop_id = record.shop_id │
|
||||
│ and wallet_type = 'commission' │
|
||||
└────────────┬────────────────────────┘
|
||||
│
|
||||
┌────────────▼────────────────────────┐
|
||||
│ 2. 增加钱包余额 │
|
||||
│ wallet.balance += record.amount │
|
||||
│ wallet.version += 1 │
|
||||
│ (乐观锁防并发) │
|
||||
└────────────┬────────────────────────┘
|
||||
│
|
||||
┌────────────▼────────────────────────┐
|
||||
│ 3. 更新佣金记录 │
|
||||
│ commission_record.status = 3 │
|
||||
│ (CommissionStatusReleased) │
|
||||
│ commission_record.released_at = now
|
||||
│ commission_record.balance_after │
|
||||
│ = balance_before + amount │
|
||||
└────────────┬────────────────────────┘
|
||||
│
|
||||
┌────────────▼────────────────────────┐
|
||||
│ 4. 创建钱包交易记录 │
|
||||
│ transaction { │
|
||||
│ agent_wallet_id: wallet.id, │
|
||||
│ transaction_type: 'commission',│
|
||||
│ amount: record.amount, │
|
||||
│ balance_before: ..., │
|
||||
│ balance_after: ..., │
|
||||
│ reference_type: 'commission', │
|
||||
│ reference_id: record.id │
|
||||
│ } │
|
||||
└────────────┬────────────────────────┘
|
||||
│
|
||||
┌────────────▼────────────────────────┐
|
||||
│ 5. 事务提交 │
|
||||
│ 佣金入账完成 │
|
||||
└────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## 四、订单状态转换图
|
||||
|
||||
```
|
||||
┌─────────────────┐
|
||||
│ 订单创建 │
|
||||
└────────┬────────┘
|
||||
│
|
||||
┌────────▼────────────────────┐
|
||||
│ commission_status = 1 │
|
||||
│ payment_status = 1 │
|
||||
│ (待计算, 待支付) │
|
||||
└────────┬────────────────────┘
|
||||
│
|
||||
┌────────▼────────────────────┐
|
||||
│ 用户支付 │
|
||||
└────────┬────────────────────┘
|
||||
│
|
||||
┌────────▼────────────────────┐
|
||||
│ payment_status = 2 │
|
||||
│ (已支付) │
|
||||
│ commission_status = 1 │
|
||||
│ (待计算) │
|
||||
└────────┬────────────────────┘
|
||||
│
|
||||
┌────────▼────────────────────┐
|
||||
│ 异步佣金计算 │
|
||||
└────────┬────────────────────┘
|
||||
│
|
||||
┌────────▼────────────────────┐
|
||||
│ commission_status = 2 │
|
||||
│ (已计算) │
|
||||
│ 佣金已入账到代理钱包 │
|
||||
└────────────────────────────┘
|
||||
```
|
||||
|
||||
## 五、佣金记录状态转换图
|
||||
|
||||
```
|
||||
┌──────────────────┐
|
||||
│ 佣金记录创建 │
|
||||
│ status = 3 │
|
||||
│ (已发放) │
|
||||
└────────┬─────────┘
|
||||
│
|
||||
┌────────▼──────────────────┐
|
||||
│ 入账到代理钱包 │
|
||||
│ released_at = now │
|
||||
│ balance_after = ... │
|
||||
└────────┬──────────────────┘
|
||||
│
|
||||
┌────────▼──────────────────┐
|
||||
│ 佣金可用于提现 │
|
||||
│ 或继续分配给下级 │
|
||||
└───────────────────────────┘
|
||||
|
||||
┌──────────────────┐
|
||||
│ 链路断裂情况 │
|
||||
│ status = 99 │
|
||||
│ (待人工修正) │
|
||||
└────────┬─────────┘
|
||||
│
|
||||
┌────────▼──────────────────┐
|
||||
│ 平台人工审核 │
|
||||
│ 修正或失效 │
|
||||
└───────────────────────────┘
|
||||
```
|
||||
|
||||
## 六、代理链佣金分配示例
|
||||
|
||||
```
|
||||
平台 (基础成本价: 100元)
|
||||
│
|
||||
├─ 代理A (成本价: 120元)
|
||||
│ │
|
||||
│ ├─ 代理A1 (成本价: 130元)
|
||||
│ │ │
|
||||
│ │ └─ 代理A1a (成本价: 140元)
|
||||
│ │ │
|
||||
│ │ └─ 客户购买，售价: 200元
|
||||
│ │
|
||||
│ └─ 代理A2 (成本价: 135元)
|
||||
│
|
||||
└─ 代理B (成本价: 125元)
|
||||
|
||||
订单信息:
|
||||
seller_shop_id = A1a (代理A1a)
|
||||
seller_cost_price = 140元
|
||||
total_amount = 200元
|
||||
|
||||
佣金计算结果:
|
||||
┌─────────────────────────────────────────┐
|
||||
│ A1a (销售店铺) │
|
||||
│ 销售利润 = 200 - 140 = 60元 │
|
||||
│ 佣金记录: amount=60, commission_source=cost_diff
|
||||
└─────────────────────────────────────────┘
|
||||
|
||||
┌─────────────────────────────────────────┐
|
||||
│ A1 (A1a的上级) │
|
||||
│ 差价 = 140 - 130 = 10元 │
|
||||
│ 佣金记录: amount=10, commission_source=cost_diff
|
||||
└─────────────────────────────────────────┘
|
||||
|
||||
┌─────────────────────────────────────────┐
|
||||
│ A (A1的上级) │
|
||||
│ 差价 = 130 - 120 = 10元 │
|
||||
│ 佣金记录: amount=10, commission_source=cost_diff
|
||||
└─────────────────────────────────────────┘
|
||||
|
||||
┌─────────────────────────────────────────┐
|
||||
│ 平台 (A的上级) │
|
||||
│ 差价 = 120 - 100 = 20元 │
|
||||
│ (平台收入，不作为佣金) │
|
||||
└─────────────────────────────────────────┘
|
||||
|
||||
总计: 60 + 10 + 10 + 20 = 100元 ✓
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user