443 lines
15 KiB
Markdown
443 lines
15 KiB
Markdown
# SMANAGE 抽象分佣引擎 — 设计文档
|
||
|
||
## 一、设计背景
|
||
|
||
通过对阿龙电竞平台分佣机制的完整分析，提取出 **6 种核心分佣模式**：
|
||
订单分佣、邀请链分佣、阶梯分佣、提现抽成、罚款分红、跨平台预结算。
|
||
|
||
这些模式都有一个共同的本质：**事件 → 规则 → 分账**。SMANAGE 分佣引擎将这一本质抽象为 SAAS 级通用模块，子服务只管说"发生了什么"，SAAS 负责"怎么分"。
|
||
|
||
---
|
||
|
||
## 二、设计原则
|
||
|
||
| 原则 | 说明 |
|
||
|------|------|
|
||
| **事件驱动** | 子服务触发分佣事件（order_complete / member_purchase / recharge / penalty），引擎自动匹配规则计算分账 |
|
||
| **规则外置** | 分账比例、层级、公式全部存储于 `CommissionRule` 表，零硬编码 |
|
||
| **策略模式** | 比例/固定/阶梯/剩余 四种策略独立封装，新增分账逻辑只需添加策略类 |
|
||
| **参与方可配置** | 参与者身份和金额由 JSON 配置，适配任意业务场景 |
|
||
| **邀请链通用化** | 不管叫"管事/组长"还是"上级/上上级"，都是链式分佣 |
|
||
| **幂等保护** | `(TenantUUID, EventKey)` 联合唯一约束，防止重复分账 |
|
||
| **快照不可变** | `CommissionRecord` 生成后冻结，规则变更不影响历史记录 |
|
||
| **与支付解耦** | 分佣算出"该分多少"，支付模块负责"怎么打到账" |
|
||
|
||
---
|
||
|
||
## 三、架构分层
|
||
|
||
```
|
||
子服务（如阿龙电竞）
|
||
│
|
||
│ 订单完成 / 会员购买 / 用户充值 / 罚款缴纳
|
||
│
|
||
└──→ CommissionEngine.Dispatch(event_type, event_key, total_amount, ...)
|
||
│
|
||
├── 1. 写入 CommissionEvent（幂等检查）
|
||
├── 2. 匹配 CommissionRule（按优先级）
|
||
├── 3. 调用策略引擎计算分账
|
||
│ ├── PercentageStrategy → total × rate
|
||
│ ├── FixedStrategy → 固定金额
|
||
│ ├── TieredStrategy → 按次数/档位查表
|
||
│ └── RemainderStrategy → 剩余归平台
|
||
├── 4. 写入 CommissionRecord（不可变流水）
|
||
└── 5. 返回分账结果
|
||
```
|
||
|
||
---
|
||
|
||
## 四、文件清单（10 个文件）
|
||
|
||
| 层级 | 文件 | 职责 |
|
||
|------|------|------|
|
||
| **模型** | `models.py` | 6 张核心表：Event / Rule / RateTable / RateEntry / Record / PreSettlement |
|
||
| **策略** | `strategies/engine.py` | 5 种策略类 + 策略工厂 `CreateStrategy()` |
|
||
| **编排器** | `manager.py` | `CommissionEngine` — Dispatch / PreSettle / 邀请链 / 费率计算 / 统计查询 |
|
||
| **API** | `views.py` | 10 个 REST 端点 |
|
||
| **序列化** | `serializers.py` | 12 个 Serializer |
|
||
| **路由** | `urls.py` | 10 个 URL 路由 |
|
||
| **配置** | `apps.py` | AppConfig |
|
||
| **管理** | `admin.py` | 6 个 Django Admin 注册 |
|
||
|
||
---
|
||
|
||
## 五、核心数据模型
|
||
|
||
### 5.1 CommissionEvent — 分佣事件
|
||
|
||
子服务触发的分佣事件记录：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| EventUUID | UUID | 主键 |
|
||
| TenantUUID | UUID | 租户 |
|
||
| EventType | CharField(32) | `order_complete` / `member_purchase` / `recharge` / `penalty` / `register` / `custom` |
|
||
| EventKey | CharField(128) | 业务唯一键（幂等保护），如订单ID |
|
||
| TotalAmount | DecimalField | 可分佣总金额 |
|
||
| SourceUserUUID | UUID | 触发者（如付费用户） |
|
||
| EventPayload | JSONField | 业务上下文（由子服务自行解析） |
|
||
| Participants | JSONField | 参与者映射 `{role: user_id}` |
|
||
| EventStatus | SmallIntegerField | 0=待处理 1=处理中 2=已结算 3=失败 |
|
||
|
||
唯一约束：`(TenantUUID, EventKey)` — 同一事件不可重复分账
|
||
|
||
### 5.2 CommissionRule — 分佣规则
|
||
|
||
定义"怎么分"：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| RuleUUID | UUID | 主键 |
|
||
| TenantUUID | UUID | 租户 |
|
||
| EventType | CharField(32) | 绑定的分佣事件类型 |
|
||
| RuleName | CharField(128) | 规则名称 |
|
||
| ParticipantRules | JSONField | 参与者分账规则列表 |
|
||
| RateTable | ForeignKey | 可选关联费率表 |
|
||
| MaxInviteLevel | SmallIntegerField | 邀请链最大层级（默认2级） |
|
||
| RulePriority | IntegerField | 优先级 |
|
||
|
||
#### ParticipantRules JSON 结构示例
|
||
|
||
```json
|
||
[
|
||
{ "role": "worker", "type": "percentage", "value": 0.80 },
|
||
{ "role": "agent", "type": "fixed", "value": 10 },
|
||
{ "role": "leader", "type": "tiered", "tiers": { "1": 5, "2": 8, "3": 10 } },
|
||
{ "role": "platform", "type": "remainder" }
|
||
]
|
||
```
|
||
|
||
### 5.3 RateTable + RateEntry — 费率表
|
||
|
||
可复用的动态费率配置：
|
||
|
||
```
|
||
RateTable: { TableCode: 'dashou_order_split', TableName: '打手订单分成费率' }
|
||
├── RateEntry: { RateKey: '1', RateLabel: '平台订单打手分成', RateValue: 0.8000 }
|
||
├── RateEntry: { RateKey: '3', RateLabel: '商家订单打手分成', RateValue: 0.7000 }
|
||
├── RateEntry: { RateKey: '5', RateLabel: '打手提现抽成', RateValue: 0.0100 }
|
||
└── RateEntry: { RateKey: '6', RateLabel: '管事提现抽成', RateValue: 0.0100 }
|
||
```
|
||
|
||
### 5.4 CommissionRecord — 分佣记录（不可变）
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| RecordUUID | UUID | 主键 |
|
||
| TenantUUID | UUID | 租户 |
|
||
| Event | ForeignKey | 关联分佣事件 |
|
||
| Rule | ForeignKey | 关联分佣规则（可空，规则删除后保留快照） |
|
||
| ParticipantID | CharField(128) | 分账对象ID |
|
||
| ParticipantRole | CharField(64) | 分账角色（worker / agent / platform / ...） |
|
||
| SplitType | CharField(16) | percentage / fixed / tiered / remainder |
|
||
| Amount | DecimalField | 分账金额 |
|
||
| RuleSnapshot | JSONField | 规则快照（规则变更后保留历史） |
|
||
| TierIndex | IntegerField | 阶梯索引（多次分红时标识第几次） |
|
||
| Status | SmallIntegerField | 0=待结算 1=已结算 2=已提现 3=已取消 |
|
||
|
||
### 5.5 PreSettlement — 预结算
|
||
|
||
跨平台订单待确认款项：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| EventKey | CharField(128) | 业务唯一键 |
|
||
| ExternalPlatform | CharField(64) | 外部平台标识 |
|
||
| ExternalOrderID | CharField(128) | 外部订单ID |
|
||
| ParticipantID | CharField(128) | 应分账对象 |
|
||
| Amount | DecimalField | 预分金额 |
|
||
| Status | SmallIntegerField | 0=待确认 1=已确认 2=已拒绝 |
|
||
|
||
---
|
||
|
||
## 六、策略引擎
|
||
|
||
策略模式实现，四种核心策略 + 一种扩展策略：
|
||
|
||
### 6.1 PercentageStrategy — 比例分账
|
||
|
||
```python
|
||
# 配置: { role: 'worker', type: 'percentage', value: 0.80 }
|
||
amount = total_amount × 0.80
|
||
# 支持保底/封顶:
|
||
# { role: 'worker', type: 'percentage', value: 0.80, min_amount: 5, max_amount: 500 }
|
||
```
|
||
|
||
### 6.2 FixedStrategy — 固定金额
|
||
|
||
```python
|
||
# 配置: { role: 'agent', type: 'fixed', value: 10 }
|
||
amount = 10 # 不受 total_amount 影响
|
||
# 也支持从费率表读取:
|
||
# { role: 'agent', type: 'fixed', rate_table_key: 'guanshi_fc' }
|
||
```
|
||
|
||
### 6.3 TieredStrategy — 阶梯分账
|
||
|
||
```python
|
||
# 配置: { role: 'agent', type: 'tiered', tiers: { "1": 5, "2": 8, "3": 10 } }
|
||
# tier_index=1 → amount=5
|
||
# tier_index=2 → amount=8
|
||
# tier_index=3 → amount=10
|
||
# 支持百分比阶梯: { "1": "5%", "2": "8%" }
|
||
```
|
||
|
||
### 6.4 RemainderStrategy — 剩余归平台
|
||
|
||
```python
|
||
# 配置: { role: 'platform', type: 'remainder' }
|
||
amount = total_amount - SUM(其他所有参与者分账)
|
||
# 自动排在最后计算，确保剩余金额正确
|
||
```
|
||
|
||
### 6.5 WithdrawalFeeStrategy — 提现手续费（扩展）
|
||
|
||
```python
|
||
# 配置: { role: 'platform', type: 'withdrawal_fee', value: 0.01 }
|
||
fee = total_amount × 0.01
|
||
```
|
||
|
||
### 新增策略只需两步
|
||
|
||
```python
|
||
# 1. 实现策略类
|
||
class FormulaStrategy(BaseSplitStrategy):
|
||
def Calculate(self, total_amount, tier_index=0, **context):
|
||
return total_amount * Decimal('0.5') + Decimal('10')
|
||
|
||
# 2. 注册到策略映射
|
||
STRATEGY_MAP['formula'] = FormulaStrategy
|
||
```
|
||
|
||
---
|
||
|
||
## 七、CommissionEngine 编排器
|
||
|
||
```python
|
||
class CommissionEngine:
|
||
def __init__(self, tenant_uuid)
|
||
|
||
# 规则管理
|
||
def ConfigureRule(event_type, rule_name, participant_rules, ...) # 配置分佣规则
|
||
def ConfigureRateTable(table_code, table_name, entries, ...) # 配置费率表
|
||
|
||
# 核心分佣
|
||
def Dispatch(event_type, event_key, total_amount, participants, ...) # 触发分佣
|
||
def BuildInviteChainCommission(event_type, event_key, ...) # 邀请链分佣
|
||
|
||
# 预结算
|
||
def PreSettle(event_key, external_platform, external_order_id, ...) # 创建预结算
|
||
def ConfirmPreSettlement(event_key, participant_id, ...) # 确认
|
||
def RejectPreSettlement(event_key, participant_id, ...) # 拒绝
|
||
|
||
# 查询
|
||
def CalculateFee(total_amount, rate_table_code, rate_key) # 计算手续费
|
||
def QueryRecords(participant_id, event_type, status, ...) # 查询分佣记录
|
||
def TotalByParticipant(participant_id, start_date, end_date) # 统计总额
|
||
```
|
||
|
||
---
|
||
|
||
## 八、API 端点
|
||
|
||
```
|
||
# 规则管理
|
||
GET /api/commission/rule/ # 查询分佣规则列表
|
||
POST /api/commission/rule/ # 创建分佣规则
|
||
DELETE /api/commission/rule/ # 禁用分佣规则
|
||
|
||
# 费率表管理
|
||
GET /api/commission/rate/ # 查询费率表列表
|
||
POST /api/commission/rate/ # 创建费率表
|
||
|
||
# 分佣操作
|
||
POST /api/commission/dispatch/ # 触发分佣事件
|
||
POST /api/commission/dispatch/invite_chain/ # 邀请链分佣
|
||
|
||
# 查询统计
|
||
GET /api/commission/query/ # 查询分佣记录
|
||
GET /api/commission/total/<participant_id>/ # 统计某人分佣总额
|
||
POST /api/commission/fee/ # 计算手续费
|
||
|
||
# 预结算
|
||
POST /api/commission/presettle/ # 创建预结算
|
||
POST /api/commission/presettle/confirm/ # 确认预结算
|
||
|
||
# 事件查询
|
||
GET /api/commission/event/ # 查询分佣事件列表
|
||
```
|
||
|
||
---
|
||
|
||
## 九、子服务集成示例
|
||
|
||
### 9.1 订单分佣
|
||
|
||
```python
|
||
from gvsds.apps.commission.manager import CommissionEngine
|
||
|
||
engine = CommissionEngine(tenant_uuid='al_long_001')
|
||
|
||
# 配置分佣规则
|
||
engine.ConfigureRule(
|
||
event_type='order_complete',
|
||
rule_name='平台订单打手8成',
|
||
participant_rules=[
|
||
{'role': 'worker', 'type': 'percentage', 'value': 0.80},
|
||
{'role': 'platform', 'type': 'remainder'},
|
||
],
|
||
)
|
||
|
||
# 订单完成时触发分佣
|
||
records = engine.Dispatch(
|
||
event_type='order_complete',
|
||
event_key='ORDER-20260611-001', # 幂等键
|
||
total_amount=Decimal('100.00'),
|
||
participants={
|
||
'worker': 'dashou_123',
|
||
},
|
||
payload={'order_id': 'xxx', 'game': 'LoL', 'shop_id': 'shop_001'},
|
||
)
|
||
|
||
# records = [
|
||
# {ParticipantID: 'dashou_123', ParticipantRole: 'worker', Amount: 80},
|
||
# {ParticipantID: 'platform_default', ParticipantRole: 'platform', Amount: 20},
|
||
# ]
|
||
```
|
||
|
||
### 9.2 会员购买+邀请链
|
||
|
||
```python
|
||
# 配置会员购买分佣规则
|
||
engine.ConfigureRule(
|
||
event_type='member_purchase',
|
||
rule_name='会员购买管事+组长分红',
|
||
participant_rules=[
|
||
{'role': 'agent', 'type': 'fixed', 'value': 10},
|
||
{'role': 'leader', 'type': 'fixed', 'value': 5},
|
||
{'role': 'platform', 'type': 'remainder'},
|
||
],
|
||
)
|
||
|
||
# 打手购买会员 → 触发邀请链分佣
|
||
records = engine.BuildInviteChainCommission(
|
||
event_type='member_purchase',
|
||
event_key='MEMBER-VIP001-20260611-001',
|
||
total_amount=Decimal('50.00'),
|
||
source_user_uuid='dashou_123',
|
||
invite_chain=[
|
||
{'user_uuid': 'guanshi_456', 'level': 1, 'role': 'agent'},
|
||
{'user_uuid': 'zuzhang_789', 'level': 2, 'role': 'leader'},
|
||
],
|
||
rule_name='会员购买管事+组长分红',
|
||
participant_rules=[
|
||
{'role': 'agent', 'type': 'fixed', 'value': 10},
|
||
{'role': 'leader', 'type': 'fixed', 'value': 5},
|
||
{'role': 'platform', 'type': 'remainder'},
|
||
],
|
||
)
|
||
|
||
# records = [
|
||
# {ParticipantID: 'guanshi_456', ParticipantRole: 'agent', Amount: 10},
|
||
# {ParticipantID: 'zuzhang_789', ParticipantRole: 'leader', Amount: 5},
|
||
# {ParticipantID: 'platform_default', ParticipantRole: 'platform', Amount: 35},
|
||
# ]
|
||
```
|
||
|
||
### 9.3 阶梯分佣（多次购买）
|
||
|
||
```python
|
||
# 第一次购买
|
||
engine.Dispatch(
|
||
event_type='member_purchase',
|
||
event_key='STAGED-VIP001-DASHOU_123-1',
|
||
total_amount=Decimal('50.00'),
|
||
tier_index=1,
|
||
participants={'agent': 'guanshi_456'},
|
||
)
|
||
|
||
# 第二次购买（金额不同）
|
||
engine.Dispatch(
|
||
event_type='member_purchase',
|
||
event_key='STAGED-VIP001-DASHOU_123-2',
|
||
total_amount=Decimal('50.00'),
|
||
tier_index=2,
|
||
participants={'agent': 'guanshi_456'},
|
||
)
|
||
```
|
||
|
||
### 9.4 提现手续费
|
||
|
||
```python
|
||
# 配置提现费率表
|
||
engine.ConfigureRateTable(
|
||
table_code='withdrawal_fee',
|
||
table_name='提现手续费率',
|
||
entries={
|
||
'dashou': '0.0100', # 打手提现 1%
|
||
'guanshi': '0.0100', # 管事提现 1%
|
||
'zuzhang': '0.0100', # 组长提现 1%
|
||
},
|
||
)
|
||
|
||
# 计算手续费
|
||
fee = engine.CalculateFee(
|
||
total_amount=Decimal('1000.00'),
|
||
rate_table_code='withdrawal_fee',
|
||
rate_key='dashou',
|
||
)
|
||
# fee = 10.00 → 实际到账 990.00
|
||
```
|
||
|
||
### 9.5 跨平台预结算
|
||
|
||
```python
|
||
# 创建预结算
|
||
ps = engine.PreSettle(
|
||
event_key='ORDER-CROSS-001',
|
||
external_platform='partner_club_002',
|
||
external_order_id='P-ORDER-888',
|
||
participant_id='dashou_123',
|
||
amount=Decimal('80.00'),
|
||
order_amount=Decimal('100.00'),
|
||
)
|
||
|
||
# 对方确认后
|
||
engine.ConfirmPreSettlement(
|
||
event_key='ORDER-CROSS-001',
|
||
confirmed_by='partner_admin',
|
||
)
|
||
```
|
||
|
||
---
|
||
|
||
## 十、与支付模块的关系
|
||
|
||
```
|
||
┌────────────────────────────────────────────────────────────┐
|
||
│ 子服务业务层 │
|
||
│ │
|
||
│ 订单完成 ──→ CommissionEngine.Dispatch() ──→ 算出分账 │
|
||
│ │ │
|
||
│ ▼ │
|
||
│ 用户提现 ──→ PaymentManager.Transfer() ──→ 执行打款 │
|
||
│ │
|
||
└────────────────────────────────────────────────────────────┘
|
||
|
||
分佣引擎 → 算出来"该分多少"
|
||
支付网关 → 执行"怎么打到账"
|
||
|
||
两者通过 CommissionRecord.Amount 桥接：
|
||
· CommissionRecord 中的分账金额作为 PaymentManager.Transfer 的输入
|
||
· 打款完成后，CommissionRecord 状态从 'settled' → 'withdrawn'
|
||
```
|
||
|
||
---
|
||
|
||
## 十一、配置变更记录
|
||
|
||
| 文件 | 变更 |
|
||
|------|------|
|
||
| `settings.py` | 新增 `'gvsds.apps.commission'` 到 `INSTALLED_APPS` |
|
||
| `db_router.py` | 新增 `'commission': 'default'` 到 `app_db_map` |
|
||
| `urls.py` | 新增 `path('api/commission/', include('gvsds.apps.commission.urls'))` | |