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