huang
8f66ca7bcb
All checks were successful
构建并部署到测试环境（无 SSH） / build-and-deploy (push) Successful in 7m14s
320 lines
20 KiB
Markdown
320 lines
20 KiB
Markdown
# 差价佣金计算流程图
|
||
|
||
## 一、订单支付到佣金入账的完整流程
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────────────┐
|
||
│ 客户下单购买套餐 │
|
||
└────────────────────────────┬────────────────────────────────────────┘
|
||
│
|
||
┌────────▼────────┐
|
||
│ 创建订单 │
|
||
│ 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元 ✓
|
||
```
|
||
|