# 差价佣金计算流程图 ## 一、订单支付到佣金入账的完整流程 ``` ┌─────────────────────────────────────────────────────────────────────┐ │ 客户下单购买套餐 │ └────────────────────────────┬────────────────────────────────────────┘ │ ┌────────▼────────┐ │ 创建订单 │ │ 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元 ✓ ```