183 lines
6.9 KiB
Markdown
183 lines
6.9 KiB
Markdown
# 分红说明文档（现状分析 + 简化设计建议）
|
||
|
||
## 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%”以保证兼容历史流程。
|
||
|