# 分红说明文档（现状分析 + 简化设计建议）

## 1. 文档目的

本文用于回答两个问题：

1. 甲方管理员是否容易看懂当前分红方式？
2. 是否有更简单、更容易执行和对账的分红设计？

并给出推荐方案与落地路径。

---

## 2. 当前分红设计现状（按代码实际行为）

## 2.1 配置层面（看起来是三级）

历史上后台有三处比例字段（其中后两项已下线）：

- `channel`：渠道分红参数（`turnover_share_rate`、`affiliate_*` 等）
- `admin_group`：角色组 `commission_rate`（已删除）
- `admin`：管理员 `commission_rate`（已删除）

从“配置界面”角度，容易被理解为：  
**渠道比例 -> 角色组比例 -> 管理员比例** 的三级链路。

## 2.2 结算层面（实际执行是单层）

当前手动结算逻辑在 `Channel` 控制器中：

- 按渠道下注汇总计算 `total_bet_amount / platform_profit_amount`
- 根据 `channel.agent_mode` 计算佣金基数与佣金比例
- 生成 `agent_settlement_period` 与 `agent_commission_record`

关键点：**佣金记录只写了一条 admin_id（渠道下首个管理员）**，并未按角色组/管理员比例拆分多条佣金明细。  
也就是说，目前“角色组比例、管理员比例”主要在新增/编辑时做约束校验，但**没有进入最终结算分账公式**。

---

## 3. 当前方案对甲方可理解性的评估

结论：**一般不容易看懂，且容易产生“配置了却不生效”的认知落差。**

主要原因：

1. **心智复杂**：甲方要同时理解渠道模式（返水/联营）、角色组比例、管理员比例三层规则。
2. **口径不一致**：界面上有三级比例，但结算时是渠道单层落账，容易质疑“为什么不是按我配的三级比例发放”。
3. **对账难**：财务看到佣金记录时只能看到渠道维度，不容易反推角色组和管理员分配关系。
4. **运维负担高**：层级变化（调组、换管理员）后，历史解释成本高。

---

## 4. 更简单的分红设计方式（推荐）

## 4.1 推荐方案：`渠道结算 + 渠道内二次分配`（两层）

将分红流程拆为两个明确步骤：

### A. 一级：渠道结算（平台对渠道）

- 保留当前 `channel.agent_mode` 的计算方式（turnover/affiliate）
- 先得到一个渠道应发佣金：`channel_commission_amount`
- 生成渠道结算单（当前已具备）

### B. 二级：渠道内分配（渠道对管理员）

- 不再使用“角色组分红比例”参与金额运算（角色组只负责权限）
- 仅维护“渠道下管理员分配权重”（例如总和=100%）
- 自动拆分：`admin_commission = channel_commission_amount × admin_weight`
- 为每个管理员生成独立佣金记录（多条）

> 这样甲方只需要理解一句话：  
> **平台先算渠道总佣金，再按渠道内管理员权重拆分。**

## 4.2 为什么推荐该方案

1. **业务更直观**：甲方看“渠道总佣金 + 管理员占比”即可。
2. **和现有代码贴近**：你们当前已经是“先算渠道佣金”，只需补“二次拆分”。
3. **对账容易**：每个管理员佣金来源清晰，可直接汇总对账。
4. **后续可扩展**：以后要按团队、按代理线拆分，可以在“二次分配”层升级，不影响一级结算。

---

## 5. 备选方案对比

## 5.1 方案A（现状表象）：渠道 -> 角色组 -> 管理员三级

- 优点：理论上精细
- 缺点：配置理解成本高、维护复杂、容易和实际结算脱节
- 适用：组织结构非常稳定、财务系统成熟的大盘

## 5.2 方案B（推荐）：渠道 -> 管理员两级

- 优点：简单、易讲、易对账、改造成本低
- 缺点：若强依赖“角色组抽成”会减少一层表达
- 适用：当前阶段（快速上线、减少运营误解）

## 5.3 方案C（最简）：仅渠道一级

- 优点：最简单
- 缺点：无法直接落地到管理员收益，不利于激励
- 适用：仅用于统计，不用于发佣

---

## 6. 建议的产品口径（给甲方的话术）

建议统一说明为：

1. **渠道分红**：系统按渠道配置（返水或联营）自动计算该周期渠道总佣金。
2. **人员分配**：渠道总佣金按“渠道内管理员分配比例”自动拆分。
3. **角色组作用**：角色组只负责菜单权限与数据权限，不参与金额运算。
4. **结算可追溯**：每条管理员佣金都能追溯到对应渠道结算单。

---

## 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%）
- 管理员离职/禁用时自动重算或禁止结算
- 结算后锁单，后改比例不影响历史账单

---

## 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%”以保证兼容历史流程。