webman-buildadmin/docs/en/commission-share-guide.md

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, etc.; see channel-admin-guide.md
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
Channel list read scope	/admin/channel	Super admin / unbound groups / viewAllChannels → all channels read-only
Visibility	Admin list	Non–super admin sees self + all downline only
Settlement	/admin/channel manual / cron	Super admin or channel/manualSettle; batch still super admin only

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 or holder of channel/manualSettle triggers settlement (manual or cron; batch API still super admin only)
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
Channel read scope	app/common/service/AdminChannelScopeService.php
Channel admin UI	app/admin/controller/Channel.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
2026-05-30	Channel UI: view-all, bet/dividend dialogs, filters, mobile; manual settle by permission; channel-admin-guide.md