1.优化分红方式

docs/36字花-数据库与实施计划.md

@@ -169,14 +169,19 @@
 | 渠道归属 | `channel_id` 表示该子代理属于哪个顶级渠道 |
 | 邀请管理 | `invite_code` 自动生成且全局唯一，用于发展玩家并做归属绑定 |
 | 角色标识 | `agent_role`（如 `agent_admin` / `sub_agent` / `staff`） |
-| 分红设置 | 不再使用 `admin` / `admin_group` 分红字段；统一改为渠道维度结算后按 `channel_admin_share` 二次分配 |
+| 分红设置 | 在 **管理员管理** 维护：`parent_admin_id`（上级代理）、`commission_share_rate`（从上级分红抽取比例 %）；顶级代理留空上级与比例 |
 | 开奖权限 | 不在数据层开放给渠道/子代理；开奖权限仅由超管 RBAC 控制 |
 
-### 5.1 分红计算口径（现行）
+### 5.1 分红计算口径（现行，2026-05-29）
 
-- 渠道分红：先按 `channel.agent_mode` 计算渠道总佣金
-- 管理员分红：再按 `channel_admin_share.share_rate` 对渠道总佣金进行二次分配
-- 角色组仅用于权限与数据范围，不再参与金额拆分
+- **渠道分红**：先按 `channel.agent_mode` 与已结算注单（`bet_order.status=2`）计算 **渠道总佣金**（非充值口径）
+- **管理员分红**：总佣金进入渠道 **顶级代理** 后，按 `admin.parent_admin_id` 树递归拆分：
+  - 子代理实得 = 上级本期实得 × `commission_share_rate`（%）
+  - 上级保留 = 上级实得 − 所有直属子代理实得之和
+  - 同一上级下子代理比例合计 **≤ 100%**
+- **配置入口**：`/admin/auth/admin`（树形列表；非超管仅见本人及下级）
+- **角色组**仅用于权限与数据范围，不参与金额拆分
+- **历史**：`channel_admin_share` 已退出结算主流程，渠道页不再维护分配比例
 
 ---
 
@@ -308,12 +313,13 @@
 3. **大盘盈利**：流水占比分桶 + 级差，各级金额之和与线总包一致（可对照文档数值验算）。  
 4. **联营**：客损为负产生负结转；下期盈利先抵扣再分佣。
 
-### 8.3.1 渠道结算新流程（2026-04-23）
+### 8.3.1 渠道结算新流程（2026-04-23，2026-05-29 树形拆分）
 
 1. **仅超管可结算**：按渠道结算周期（支持自动任务与手动提前结算）执行渠道结算。  
-2. **结算即发放**：结算时按 `channel_admin_share` 比例，直接发放到管理员钱包并写入 `admin_wallet_record`（`commission_income`），同时写 `agent_settlement_period` / `agent_commission_record`。  
-3. **提前结算规则**：手动提前结算后，新的周期起点从本次结算结束时间开始，后续自动周期归入下个结算段。  
-4. **停用渠道限制**：`channel.status != 1` 时，该渠道不再允许玩家注册与登录。
+2. **结算即发放**：结算时按 **代理树**（`admin.parent_admin_id` + `admin.commission_share_rate`）拆分各管理员实得，直接发放到管理员钱包并写入 `admin_wallet_record`（`commission_income`），同时写 `agent_settlement_period` / `agent_commission_record`。  
+3. **配置位置**：分红比例在 **管理员管理** 维护，不在渠道管理页维护 flat 分配表。  
+4. **提前结算规则**：手动提前结算后，新的周期起点从本次结算结束时间开始，后续自动周期归入下个结算段。  
+5. **停用渠道限制**：`channel.status != 1` 时，该渠道不再允许玩家注册与登录。
 
 ### 8.3.2 后台管理员资金与提现流程（2026-04-23）
 
@@ -398,6 +404,7 @@
 | V1.14 | 2026-04-20 | 服务端 Redis 热点缓存：`GameHotDataRedis`（`user` / `game_config` / `game_record`），`config/game_hot_cache.php` 与 `.env-example` 中 `GAME_HOT_CACHE_*`；更新 §1.1、§2.1、§8.4、第九章风险与依赖、附录 `user`；与 `CACHE_DRIVER`（系统 `config` 表文件缓存）区分说明 |
 | V1.15 | 2026-04-20 | 热点写路径收口：`GameHotDataCoordinator` + `GameHotDataLock` + `GameHotDataWriteQueue` / `GameHotDataQueueConsumer`；文档与实现对齐（替代仅 `*Forget` 描述）；移动端 `betPlace` 与后台钱包共用用户互斥锁及 `coin` 乐观更新 |
 | V1.16 | 2026-04-23 | 渠道结算改为单阶段口径（仅超管结算，结算即按比例发放管理员钱包并记录操作人）与管理员钱包提现流程（`admin_wallet` / `admin_wallet_record` / `admin_withdraw_order`，渠道顶级组审核） |
+| V1.17 | 2026-05-29 | 代理分红改为树形拆分：`admin.commission_share_rate` + `parent_admin_id`；配置迁移至管理员管理；渠道页移除 `channel_admin_share` 入口；管理员列表树形展示与下级可见范围 |
 
 ---
 
@@ -440,10 +447,11 @@
 |---------|------|
 | `admin.parent_admin_id` | 子代理上下级 |
 | `admin.channel_id` | 所属渠道 |
+| `admin.commission_share_rate` | 从上级本期分红抽取比例（%）；顶级代理为空 |
 | `admin.invite_code` | 子代理邀请码，注册归属 |
 | `admin.agent_role` | 角色类型（均无开奖权） |
 | `admin_group.channel_id` | 角色组归属渠道；`NULL` 可为系统级（仅超管） |
-| `channel_admin_share.share_rate` | 渠道内管理员分配比例（百分比，启用项合计=100） |
+| `channel_admin_share` | **历史表**，2026-05-29 起结算不再使用；配置改在 `admin` 树 |
 
 ### 11.4 `game_config`（动态参数）
 

docs/36字花-移动端接口设计草案.md

@@ -962,53 +962,42 @@ flowchart TD
 
 ---
 
-## 10. 后台渠道分红比例配置（管理端补充）
+## 10. 后台代理分红配置（管理端补充，2026-05-29）
 
-> 本节为管理后台 `/admin/channel`「分配比例」弹窗补充口径，用于便于管理员按角色层级设置二次分红比例。
+> 分红比例在 **管理员管理** `/admin/auth/admin` 维护，不再使用渠道页「分配比例」弹窗。
 
-### 10.1 角色组展示规则
+### 10.1 页面与展示
 
-- 表格列顺序调整为：`角色组层级` -> `负责人` -> `状态` -> `分配比例(%)`
-- `角色组层级` 在 `负责人` 前展示，降低识别与分配成本
-- 层级路径使用 `/` 拼接，如：`顶级组 / 运营组 / 一组`
-- 同一负责人若存在多个角色组，按多标签展示多条路径
-- 无角色组时显示 `-`
+- 列表为 **树形表格**（按 `parent_admin_id`），参考角色组管理样式；支持展开/收起
+- 列含：用户名、昵称、**渠道**、**上级代理**、**分红比例(%)**、角色组、邀请码、状态等
+- 超管公共搜索支持 **渠道下拉筛选**
+- 非超管仅见 **本人及全部下级** 代理，不见其他代理线下的子代理
 
-### 10.2 接口：读取渠道管理员分配配置
+### 10.2 表单字段
 
-- **GET** `/admin/channel/channelAdminShareList?id={channel_id}`
+| 字段 | 说明 |
+|------|------|
+| `channel_id` | 所属渠道（超管可选；非超管随角色组/当前账号） |
+| `parent_admin_id` | 上级代理；留空表示渠道 **顶级代理** |
+| `commission_share_rate` | 从上级本期分红抽取的比例（0–100）；有上级时必填 |
+| `group_arr` | 角色组（单选，仅权限） |
 
-返回参数（`data.list[]`）新增：
-- `group_paths`：array<string>（负责人所属角色组层级路径列表）
-- `group_paths_text`：string（层级路径拼接文本，`|` 分隔，用于兼容纯文本场景）
+### 10.3 校验与提示
 
-返回示例（节选）：
-```json
-{
-  "code": 1,
-  "message": "ok",
-  "data": {
-    "channel_id": 1,
-    "channel_name": "渠道A",
-    "list": [
-      {
-        "admin_id": 12,
-        "username": "zhuguan1",
-        "group_paths": ["顶级组 / 运营组 / A组"],
-        "group_paths_text": "顶级组 / 运营组 / A组",
-        "status": 1,
-        "share_rate": "30.00"
-      }
-    ]
-  }
-}
-```
+- 同一 `parent_admin_id` 下，启用子代理的 `commission_share_rate` **合计 ≤ 100%**
+- 表单调用 **GET** `/admin/auth.Admin/commissionShareRemainder?parent_admin_id=&exclude_id=` 展示剩余可分配比例
+- 合计 100% 时提示：上级在本层将无分红留存
 
-### 10.3 保存约束（沿用现有）
+### 10.4 结算拆分（与渠道结算联动）
 
-- **POST** `/admin/channel/saveChannelAdminShare`
-- 仅 `status=1` 的行参与占比汇总
-- 启用项分配比例总和必须严格等于 `100.00`
+- 渠道结算得到总佣金后，由 `AdminCommissionDistributionService` 从顶级代理起递归拆分
+- 每个管理员实得写入 `agent_commission_record` 并 **即时入账** `admin_wallet`
+- 须存在至少一名渠道顶级代理，否则结算失败
+
+### 10.5 历史接口（已废弃于 UI，勿新接）
+
+- ~~GET `/admin/channel/channelAdminShareList`~~
+- ~~POST `/admin/channel/saveChannelAdminShare`~~
 
 ---
 

docs/业务流程.md

@@ -70,6 +70,8 @@
 2. **总代拓客**：总代登录 Agent Portal，生成自己的推广链接发给散户；或者生成【子代专属邀请码】发展下级代理。
 3. **分配比例**：总代在给子代开户时，将自己手中 80% 的分红权，划拨一部分（如 70%）给子代，自己赚取 10% 的级差。
 
+> **系统实现（2026-05-29）**：在后台 **管理员管理**（`/admin/auth/admin`）为子代理设置 **上级代理** 与 **分红比例(%)**；渠道结算后从上级实得中按该比例向子代理拆分，上级保留剩余部分。同一上级下子代理比例合计不得超过 100%。详见 `docs/分红说明文档.md`。
+
 ### 2.2 🌟 核心分佣结算流程（流水占比分桶模式）
 系统设定为每周一凌晨（或每日）自动执行结算脚本：
 

docs/分红说明文档.md

@@ -1,182 +1,126 @@
-# 分红说明文档（现状分析 + 简化设计建议）
+# 分红说明文档
 
 ## 1. 文档目的
 
-本文用于回答两个问题：
-
-1. 甲方管理员是否容易看懂当前分红方式？
-2. 是否有更简单、更容易执行和对账的分红设计？
-
-并给出推荐方案与落地路径。
+说明当前系统中 **渠道分红 → 代理树形拆分 → 管理员钱包入账** 的完整口径，便于运营、财务与开发对齐配置方式与结算行为。
 
 ---
 
-## 2. 当前分红设计现状（按代码实际行为）
+## 2. 总体结构（两层 + 树形）
 
-## 2.1 配置层面（看起来是三级）
+分红分为两个明确步骤：
 
-历史上后台有三处比例字段（其中后两项已下线）：
+### A. 一级：渠道结算（平台 → 渠道）
 
-- `channel`：渠道分红参数（`turnover_share_rate`、`affiliate_*` 等）
-- `admin_group`：角色组 `commission_rate`（已删除）
-- `admin`：管理员 `commission_rate`（已删除）
+- 按渠道配置的 `agent_mode` 计算本期 **渠道总佣金**：
+  - **turnover（流水/返水）**：基数 = 已结算注单总投注，佣金 = 总投注 × `turnover_share_rate`
+  - **affiliate（联营）**：基数 = 平台盈亏扣成本后金额，佣金 = 基数 × 阶梯占成
+- 统计范围：`bet_order.status = 2`（已结算），周期为 **上次结算结束时间 ~ 本次结算时刻**
+- 产出：`agent_settlement_period`（结算周期快照）
 
-从“配置界面”角度，容易被理解为：  
-**渠道比例 -> 角色组比例 -> 管理员比例** 的三级链路。
+### B. 二级：代理树拆分（渠道总佣金 → 各管理员实得）
 
-## 2.2 结算层面（实际执行是单层）
+- **不再**在渠道管理页维护「渠道内管理员分配比例」（`channel_admin_share` 已废弃于 UI，历史表可保留）
+- 在 **管理员管理**（`/admin/auth/admin`）维护代理树：
+  - `parent_admin_id`：上级代理（顶级留空）
+  - `commission_share_rate`：从 **上级本期分红** 中抽取的比例（%），仅子代理需要填写
+- 结算时由 `AdminCommissionDistributionService` 递归拆分：
+  1. 渠道总佣金先进入该渠道 **顶级代理**（`parent_admin_id` 为空）
+  2. 每个代理按直属子代理的 `commission_share_rate`，从 **自己拿到的金额** 中划出子代理份额
+  3. **上级保留** = 自己拿到的金额 − 已分给所有子代理的金额
 
-当前手动结算逻辑在 `Channel` 控制器中：
+**示例**（上级本期拿到 3000）：
 
-- 按渠道下注汇总计算 `total_bet_amount / platform_profit_amount`
-- 根据 `channel.agent_mode` 计算佣金基数与佣金比例
-- 生成 `agent_settlement_period` 与 `agent_commission_record`
+| 子代理 | 配置比例 | 实得 |
+|--------|----------|------|
+| 子代理 A | 20% | 600 |
+| 子代理 B | 40% | 1200 |
+| 上级自身 | — | 1200（3000 − 600 − 1200） |
 
-关键点：**佣金记录只写了一条 admin_id（渠道下首个管理员）**，并未按角色组/管理员比例拆分多条佣金明细。  
-也就是说，目前“角色组比例、管理员比例”主要在新增/编辑时做约束校验，但**没有进入最终结算分账公式**。
+若子代理还有下级，在其 **实得金额** 上继续按同样规则向下拆分。
 
 ---
 
-## 3. 当前方案对甲方可理解性的评估
+## 3. 配置入口与权限
 
-结论：**一般不容易看懂，且容易产生“配置了却不生效”的认知落差。**
+| 能力 | 入口 | 说明 |
+|------|------|------|
+| 渠道分红参数 | `/admin/channel` | `agent_mode`、返水/联营比例、结算周期等 |
+| 代理树与分红比例 | `/admin/auth/admin` | 树形列表；配置上级代理、分红比例、渠道归属 |
+| 渠道筛选 | 管理员列表公共搜索 | 超管可按渠道筛选 |
+| 数据可见范围 | 管理员列表 | 非超管仅见 **本人 + 全部下级**，不见其他代理线 |
+| 结算执行 | `/admin/channel` 手动结算 / 定时任务 | **仅超管**可结算；结算即发放至 `admin_wallet` |
 
-主要原因：
+### 3.1 子代理分红比例校验
 
-1. **心智复杂**：甲方要同时理解渠道模式（返水/联营）、角色组比例、管理员比例三层规则。
-2. **口径不一致**：界面上有三级比例，但结算时是渠道单层落账，容易质疑“为什么不是按我配的三级比例发放”。
-3. **对账难**：财务看到佣金记录时只能看到渠道维度，不容易反推角色组和管理员分配关系。
-4. **运维负担高**：层级变化（调组、换管理员）后，历史解释成本高。
+- 同一 `parent_admin_id` 下，所有启用子代理的 `commission_share_rate` **合计不得超过 100%**
+- 创建/编辑子代理时，表单会提示 **当前剩余可分配比例**
+- 若合计为 100%，上级在本层 **不再保留分红**
+- 顶级代理（无上级）**不需要**填写 `commission_share_rate`
+
+### 3.2 角色组的作用
+
+- `admin_group` **只负责**菜单权限、数据范围、角色隔离
+- **不参与**金额运算
 
 ---
 
-## 4. 更简单的分红设计方式（推荐）
+## 4. 结算执行流程
 
-## 4.1 推荐方案：`渠道结算 + 渠道内二次分配`（两层）
+1. 超管触发渠道结算（手动或 `ChannelAutoSettleTicker` 周期任务）
+2. `ChannelSettlementService::buildSettlePayload` 汇总注单并计算渠道总佣金
+3. `AdminCommissionDistributionService::distributeChannelCommission` 按代理树拆分各管理员实得
+4. 事务内写入：
+   - `agent_settlement_period`（`status = 2` 已完成）
+   - 多条 `agent_commission_record`（每个实得 > 0 的管理员一条，`status = 1` 已发放）
+   - `AdminWalletService::creditCommission` → `admin_wallet` + `admin_wallet_record`（`biz_type = commission_income`）
+5. 渠道 `carryover_balance` 重置为 0（超管结算即发放，不再保留渠道待分红池）
 
-将分红流程拆为两个明确步骤：
-
-### A. 一级：渠道结算（平台对渠道）
-
-- 保留当前 `channel.agent_mode` 的计算方式（turnover/affiliate）
-- 先得到一个渠道应发佣金：`channel_commission_amount`
-- 生成渠道结算单（当前已具备）
-
-### B. 二级：渠道内分配（渠道对管理员）
-
-- 不再使用“角色组分红比例”参与金额运算（角色组只负责权限）
-- 仅维护“渠道下管理员分配权重”（例如总和=100%）
-- 自动拆分：`admin_commission = channel_commission_amount × admin_weight`
-- 为每个管理员生成独立佣金记录（多条）
-
-> 这样甲方只需要理解一句话：  
-> **平台先算渠道总佣金，再按渠道内管理员权重拆分。**
-
-## 4.2 为什么推荐该方案
-
-1. **业务更直观**：甲方看“渠道总佣金 + 管理员占比”即可。
-2. **和现有代码贴近**：你们当前已经是“先算渠道佣金”，只需补“二次拆分”。
-3. **对账容易**：每个管理员佣金来源清晰，可直接汇总对账。
-4. **后续可扩展**：以后要按团队、按代理线拆分，可以在“二次分配”层升级，不影响一级结算。
+**前置条件**：渠道下须存在至少一名 **顶级代理**（`channel_id` 匹配且 `parent_admin_id` 为空）；否则结算失败并提示「渠道未配置顶级代理管理员」。
 
 ---
 
-## 5. 备选方案对比
+## 5. 给甲方/运营的话术（推荐）
 
-## 5.1 方案A（现状表象）：渠道 -> 角色组 -> 管理员三级
-
-- 优点：理论上精细
-- 缺点：配置理解成本高、维护复杂、容易和实际结算脱节
-- 适用：组织结构非常稳定、财务系统成熟的大盘
-
-## 5.2 方案B（推荐）：渠道 -> 管理员两级
-
-- 优点：简单、易讲、易对账、改造成本低
-- 缺点：若强依赖“角色组抽成”会减少一层表达
-- 适用：当前阶段（快速上线、减少运营误解）
-
-## 5.3 方案C（最简）：仅渠道一级
-
-- 优点：最简单
-- 缺点：无法直接落地到管理员收益，不利于激励
-- 适用：仅用于统计，不用于发佣
+1. **渠道分红**：系统按渠道模式（返水或联营）自动计算该周期 **渠道总佣金**（基于玩家已结算注单，**不是**按充值金额）。
+2. **人员分配**：总佣金进入渠道顶级代理后，按 **管理员管理中配置的上下级与分红比例** 自动向下拆分；上级只保留分给下级后的余额。
+3. **角色组**：仅管权限，不管分钱。
+4. **结算可追溯**：每条 `agent_commission_record` 可关联 `agent_settlement_period`；钱包流水 `commission_income` 可反查佣金记录。
 
 ---
 
-## 6. 建议的产品口径（给甲方的话术）
+## 6. 核心数据字段
 
-建议统一说明为：
+| 表/字段 | 作用 |
+|---------|------|
+| `channel.agent_mode` / `turnover_share_rate` / `affiliate_*` | 渠道总佣金计算参数 |
+| `admin.parent_admin_id` | 上级代理 |
+| `admin.channel_id` | 所属渠道 |
+| `admin.commission_share_rate` | 从上级分红抽取比例（%），顶级为空 |
+| `agent_settlement_period` | 结算周期与大盘快照 |
+| `agent_commission_record` | 各管理员本期实发佣金 |
+| `admin_wallet` / `admin_wallet_record` | 管理员钱包与入账流水 |
 
-1. **渠道分红**：系统按渠道配置（返水或联营）自动计算该周期渠道总佣金。
-2. **人员分配**：渠道总佣金按“渠道内管理员分配比例”自动拆分。
-3. **角色组作用**：角色组只负责菜单权限与数据权限，不参与金额运算。
-4. **结算可追溯**：每条管理员佣金都能追溯到对应渠道结算单。
+> **历史表** `channel_admin_share`：2026-04-18 曾用于「渠道内 flat 100% 拆分」，2026-05-29 起结算改走代理树，后台入口已移除，请勿再依赖该表配置。
 
 ---
 
-## 7. 数据与实现改造建议（按最小改动）
+## 7. 相关代码
 
-## 7.1 数据字段建议
-
-- 保留：`channel` 的分红计算参数（现有）
-- 建议新增（任选其一）：
-  - 在 `admin` 增加 `channel_share_rate`（该管理员在所属渠道的拆分比例）
-  - 或新增 `channel_admin_share(channel_id, admin_id, share_rate)`
-
-## 7.2 逻辑改造建议
-
-1. 渠道结算得到 `commission_amount`
-2. 拉取该渠道有效管理员分配比例列表（总和=100%）
-3. 按比例拆分并批量写入 `agent_commission_record`
-4. 若分配比例未配置：
-   - 方案一：默认100%给渠道负责人
-   - 方案二：阻止结算并提示“请先配置渠道管理员分配比例”
-
-## 7.3 风险控制建议
-
-- 分配比例总和强校验（必须=100%）
-- 管理员离职/禁用时自动重算或禁止结算
-- 结算后锁单，后改比例不影响历史账单
+| 模块 | 路径 |
+|------|------|
+| 渠道结算 | `app/common/service/ChannelSettlementService.php` |
+| 树形拆分 | `app/common/service/AdminCommissionDistributionService.php` |
+| 管理员 CRUD / 校验 | `app/admin/controller/auth/Admin.php` |
+| 管理员前端 | `web/src/views/backend/auth/admin/` |
+| 自动结算 | `app/process/ChannelAutoSettleTicker.php` |
 
 ---
 
-## 8. 迁移策略建议
-
-分三步上线：
-
-1. **第1步（兼容期）**：保留现有字段，新增“渠道内管理员分配比例”配置
-2. **第2步（双轨期）**：结算时同时产出“旧口径结果 + 新口径预览”用于核对
-3. **第3步（切换期）**：正式切到“渠道+管理员两级”，角色组比例仅保留展示或下线
-
----
-
-## 9. 最终建议结论
-
-从“甲方能否看懂”和“系统可维护性”来看，建议采用：
-
-**渠道结算 + 渠道内管理员二次分配（两级）**。
-
-这是在你们当前代码基础上改造成本最低、解释成本最低、财务对账最清晰的方案。  
-不建议继续强化“渠道->角色组->管理员”三级分红公式作为主线。
-
----
-
-## 10. 本次已落地改造（2026-04-18）
-
-已在系统中完成以下改造：
-
-1. 新增渠道管理员分配表：`channel_admin_share`
-2. 下线并删除旧字段：`admin_group.commission_rate`、`admin.commission_rate`
-3. 新增后台接口：
-   - `channelAdminShareList`：读取渠道管理员分配配置
-   - `saveChannelAdminShare`：保存渠道管理员分配配置（启用项合计必须100%）
-4. 手动结算改造：
-   - 先算渠道总佣金
-   - 再按 `channel_admin_share` 比例拆分为多条 `agent_commission_record`
-   - 结算预览支持查看拆分明细
-5. 渠道后台页面新增“分配比例”按钮与配置弹窗，用于维护管理员分配比例
-6. 角色组与管理员页面已移除旧分红比例字段展示与编辑项
-
-说明：
-- 若未配置 `channel_admin_share`，系统会回退为“渠道首个管理员100%”以保证兼容历史流程。
+## 8. 变更记录
 
+| 日期 | 说明 |
+|------|------|
+| 2026-04-18 | 落地 `channel_admin_share` 渠道内 flat 拆分；移除 `admin`/`admin_group.commission_rate` |
+| 2026-04-23 | 超管结算即发放至管理员钱包；新增 `admin_wallet` 体系 |
+| 2026-05-29 | **改为代理树形分红**：配置迁移至管理员管理 `commission_share_rate` + `parent_admin_id`；移除渠道页分配比例入口；管理员列表树形展示与下级可见范围 |

docs/后端.md

@@ -76,13 +76,14 @@
 *   **提现手续费收益报表**：单独统计系统抽取的 0.5% 手续费总收入。
 
 ### 3.5 🏢 代理中枢与佣金结算系统 (Agent System)
-*   **创建总代账号**：由于前端不支持散户变代理，只能由管理员在此处点击 `[新增总代 Master Agent]`，生成专属邀请链接。
-*   **代理树状图 (Tree View)**：可视化查看整个多级代理层级及人数。
-*   **佣金结算看板 (Commission Settlement)**：
-    *   后端按周/月跑批处理脚本（Cron Job）。
-    *   展示全平台周期总盈利（大盘盈亏）。
-    *   列出各代理线的流水占比%、应得分红、GM盘口扣除利润、实际下放分红。
-    *   提供 `[一键发佣]` 按钮，将佣金批量转入各代理的 Agent 钱包。
+*   **创建总代/子代账号**：在 **管理员管理**（`/admin/auth/admin`）维护代理树：`parent_admin_id`、`commission_share_rate`（从上级分红抽取 %）、`channel_id`、邀请码。
+*   **代理树状图 (Tree View)**：管理员列表以树形展示；非超管仅见本人及全部下级。
+*   **渠道佣金结算**（仅超管）：
+    *   按渠道 `agent_mode` 与已结算注单计算渠道总佣金（非充值口径）。
+    *   按代理树拆分各管理员实得，写入 `agent_commission_record` 并 **即时入账** `admin_wallet`。
+    *   支持周期自动结算（`ChannelAutoSettleTicker`）与手动提前结算。
+*   **佣金结算看板**：`agent_settlement_period`、`agent_commission_record` 列表查询与对账。
+*   详细口径见 `docs/分红说明文档.md`。
 
 ### 3.6 🤝 联营契约与合营代理管控大厅 (Affiliate Management)
 设计为与普通流水分佣系统并行的**客损占成代理模块**方案：