1.新增显示分红说明文档菜单

2.文档新增英文版

docs/en/commission-share-guide.md

@@ -0,0 +1,126 @@
+# 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 |