# 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 (empty for top-level)
  - `commission_share_rate`: percentage taken from **parent’s commission for this period** (sub-agents only)
- At settlement, `AdminCommissionDistributionService` splits recursively:
  1. Channel total commission goes to **top-level agent(s)** (`parent_admin_id` is null)
  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 Sub-agent share validation

- Under the same `parent_admin_id`, enabled sub-agents’ `commission_share_rate` **must not exceed 100% in total**
- Form shows **remaining allocatable rate** when creating/editing sub-agents
- If total is 100%, parent keeps **no commission** at this level
- Top-level agents (no parent) **do not** set `commission_share_rate`

### 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` | Share from parent (%); null for top-level |
| `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 |