1.优化分红方式

docs/en/36zihua-mobile-api-design-draft.md

@@ -871,19 +871,29 @@ flowchart TD
 | Field | Description |
 |-------|-------------|
 | `channel_id` | Channel (super-admin selectable; others follow role/account) |
-| `parent_admin_id` | Parent agent; empty = channel **root agent** |
-| `commission_share_rate` | Share taken from parent’s period commission (0–100); required when parent set |
-| `group_arr` | Role group (single select, permissions only) |
+| `parent_admin_id` | Parent agent; **top-level role group** (`admin_group.pid=0`): empty and disabled |
+| `commission_share_rate` | **Top-level role group**: share of channel period total (0–100), required; **sub-agent**: share from parent’s net amount, required when parent set |
+| `group_arr` | Role group (single select, permissions; top-level when `pid=0`) |
 
 ### 10.3 Validation & Hints
 
+**Top-level role group:**
+
+- Parent agent field disabled with hint “no parent required”
+- Share rate required; amount = **channel period total × this rate**
+- Under same `channel_id`, top-level agents’ rates **≤ 100% total**
+- **GET** `/admin/auth.Admin/commissionShareRemainder?is_top_level=1&channel_id=&exclude_id=`
+- Role group linkage: **GET** `/admin/auth.Admin/groupMeta?group_id=`
+
+**Sub-agent:**
+
 - Under same `parent_admin_id`, sum of enabled children’s `commission_share_rate` **≤ 100%**
-- Form calls **GET** `/admin/auth.Admin/commissionShareRemainder?parent_admin_id=&exclude_id=` for remaining allocatable %
+- **GET** `/admin/auth.Admin/commissionShareRemainder?parent_admin_id=&exclude_id=` for remaining allocatable %
 - At 100% total: hint that parent retains no share at this level
 
 ### 10.4 Settlement Split (Channel Settlement Integration)
 
-- After channel settlement total commission, **`AdminCommissionDistributionService`** splits recursively from root agent
+- After channel settlement total commission, **`AdminCommissionDistributionService`** allocates to top-level agents by `commission_share_rate`, then splits recursively downline
 - Each admin’s net amount → `agent_commission_record` and **immediate credit** to `admin_wallet`
 - At least one channel root agent required; else settlement fails
 

docs/en/commission-share-guide.md

@@ -22,10 +22,12 @@ Commission is calculated in two steps:
 
 - **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)
+  - `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 goes to **top-level agent(s)** (`parent_admin_id` is null)
+  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
 
@@ -51,12 +53,23 @@ If a sub-agent has further downline, the same rules apply on **their received am
 | 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
+### 3.1 Share rate 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`
+**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
 
@@ -96,7 +109,7 @@ If a sub-agent has further downline, the same rules apply on **their received am
 | `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 |
+| `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 |
@@ -124,3 +137,4 @@ If a sub-agent has further downline, the same rules apply on **their received am
 | 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 |