141 lines
6.4 KiB
Markdown
141 lines
6.4 KiB
Markdown
# Commission Share Guide
|
||
|
||
## 1. Purpose
|
||
|
||
This document describes the end-to-end flow **channel commission → agent tree split → admin wallet credit**, so operations, finance, and engineering share the same configuration and settlement rules.
|
||
|
||
---
|
||
|
||
## 2. Overall Structure (Two Layers + Tree)
|
||
|
||
Commission is calculated in two steps:
|
||
|
||
### A. Layer 1: Channel settlement (platform → channel)
|
||
|
||
- Compute **channel total commission** from `channel.agent_mode`:
|
||
- **turnover**: base = sum of settled bet amounts; commission = total bet × `turnover_share_rate`
|
||
- **affiliate**: base = platform profit after cost deduction; commission = base × ladder share rate
|
||
- Data scope: `bet_order.status = 2` (settled), period = **last settlement end ~ current settlement time**
|
||
- Output: `agent_settlement_period` snapshot
|
||
|
||
### B. Layer 2: Agent tree split (channel total → each admin’s net amount)
|
||
|
||
- **Do not** configure flat channel-wide shares on the channel page (`channel_admin_share` is deprecated in UI; table may remain for history)
|
||
- Maintain the agent tree in **Administrator Management** (`/admin/auth/admin`):
|
||
- `parent_admin_id`: parent agent (**required for non–top-level role groups**; **disabled and empty when role group `admin_group.pid = 0`**)
|
||
- `commission_share_rate`:
|
||
- **Top-level role group**: share (%) of **channel period total commission**; amount = channel period total × this rate
|
||
- **Sub-agent**: share (%) taken from **parent’s commission for this period**
|
||
- At settlement, `AdminCommissionDistributionService` splits recursively:
|
||
1. Channel total commission is allocated to **top-level agents** by their `commission_share_rate` (sum per channel ≤ 100%; legacy equal split if rates missing)
|
||
2. Each agent allocates to direct children by `commission_share_rate` from **their own received amount**
|
||
3. **Parent keeps** = received amount − sum allocated to children
|
||
|
||
**Example** (parent receives 3000 this period):
|
||
|
||
| Sub-agent | Rate | Amount |
|
||
|-----------|------|--------|
|
||
| Sub-agent A | 20% | 600 |
|
||
| Sub-agent B | 40% | 1200 |
|
||
| Parent | — | 1200 (3000 − 600 − 1200) |
|
||
|
||
If a sub-agent has further downline, the same rules apply on **their received amount**.
|
||
|
||
---
|
||
|
||
## 3. Configuration & Permissions
|
||
|
||
| Capability | Entry | Notes |
|
||
|------------|-------|-------|
|
||
| Channel commission params | `/admin/channel` | `agent_mode`, turnover/affiliate rates, settlement cycle, etc. |
|
||
| Agent tree & share rates | `/admin/auth/admin` | Tree list; parent agent, share rate, channel |
|
||
| Channel filter | Admin list common search | Super admin can filter by channel |
|
||
| Visibility | Admin list | Non–super admin sees **self + all downline** only |
|
||
| Settlement | `/admin/channel` manual / cron | **Super admin only**; credits `admin_wallet` on settle |
|
||
|
||
### 3.1 Share rate validation
|
||
|
||
**Top-level role group** (`admin_group.pid = 0`):
|
||
|
||
- No parent agent required or allowed
|
||
- `commission_share_rate` is required: share of **channel period total commission**
|
||
- Under the same `channel_id`, top-level agents’ rates **must not exceed 100% in total**
|
||
- Form shows remaining allocatable share on the channel
|
||
|
||
**Sub-agent** (non–top-level role group):
|
||
|
||
- `parent_admin_id` required
|
||
- `commission_share_rate` is share from **parent’s net amount this period**
|
||
- Under the same `parent_admin_id`, enabled sub-agents’ rates **must not exceed 100% in total**
|
||
- Form shows remaining allocatable share under the parent
|
||
|
||
If a level totals 100%, the parent at that level keeps **no commission**.
|
||
|
||
### 3.2 Role groups
|
||
|
||
- `admin_group` is for **menu/data permissions only**
|
||
- **Not** used in amount calculation
|
||
|
||
---
|
||
|
||
## 4. Settlement Flow
|
||
|
||
1. Super admin triggers channel settlement (manual or `ChannelAutoSettleTicker`)
|
||
2. `ChannelSettlementService::buildSettlePayload` aggregates bets and computes channel total commission
|
||
3. `AdminCommissionDistributionService::distributeChannelCommission` splits by agent tree
|
||
4. In one transaction:
|
||
- Insert `agent_settlement_period` (`status = 2` completed)
|
||
- Insert `agent_commission_record` per admin with amount > 0 (`status = 1` paid)
|
||
- `AdminWalletService::creditCommission` → `admin_wallet` + `admin_wallet_record` (`biz_type = commission_income`)
|
||
5. Reset `channel.carryover_balance` to 0 (settle-and-pay; no channel pending pool)
|
||
|
||
**Prerequisite**: at least one **top-level agent** for the channel (`channel_id` match, `parent_admin_id` empty); otherwise settlement fails.
|
||
|
||
---
|
||
|
||
## 5. Recommended wording (operations / stakeholders)
|
||
|
||
1. **Channel commission**: computed from settled bets for the period (**not** from deposit volume).
|
||
2. **Distribution**: total commission enters the channel top agent, then splits down by **parent/child and share rates** in Administrator Management; parent keeps the remainder after paying children.
|
||
3. **Role groups**: permissions only, not money.
|
||
4. **Traceability**: each `agent_commission_record` links to `agent_settlement_period`; wallet `commission_income` traces back to commission records.
|
||
|
||
---
|
||
|
||
## 6. Core fields
|
||
|
||
| Table / field | Role |
|
||
|---------------|------|
|
||
| `channel.agent_mode` / `turnover_share_rate` / `affiliate_*` | Channel commission calculation |
|
||
| `admin.parent_admin_id` | Parent agent |
|
||
| `admin.channel_id` | Channel |
|
||
| `admin.commission_share_rate` | Top-level role group: share of channel period total (%); sub-agent: share from parent (%) |
|
||
| `agent_settlement_period` | Settlement period snapshot |
|
||
| `agent_commission_record` | Paid commission per admin |
|
||
| `admin_wallet` / `admin_wallet_record` | Admin wallet & ledger |
|
||
|
||
> **Legacy** `channel_admin_share`: flat 100% split (2026-04-18); tree split since 2026-05-29. Do not configure via this table.
|
||
|
||
---
|
||
|
||
## 7. Related code
|
||
|
||
| Module | Path |
|
||
|--------|------|
|
||
| Channel settlement | `app/common/service/ChannelSettlementService.php` |
|
||
| Tree split | `app/common/service/AdminCommissionDistributionService.php` |
|
||
| Admin CRUD / validation | `app/admin/controller/auth/Admin.php` |
|
||
| Admin UI | `web/src/views/backend/auth/admin/` |
|
||
| Auto settlement | `app/process/ChannelAutoSettleTicker.php` |
|
||
|
||
---
|
||
|
||
## 8. Changelog
|
||
|
||
| Date | Change |
|
||
|------|--------|
|
||
| 2026-04-18 | `channel_admin_share` flat split; removed `admin`/`admin_group.commission_rate` |
|
||
| 2026-04-23 | Settle-and-pay to admin wallet; `admin_wallet` system |
|
||
| 2026-05-29 | **Agent tree commission** in Administrator Management; removed channel share UI; tree list & downline visibility |
|
||
| 2026-05-29 | Top-level role groups (`pid=0`) require channel share rate; parent agent disabled in form |
|