6.9 KiB
6.9 KiB
分红说明文档（现状分析 + 简化设计建议）
1. 文档目的
本文用于回答两个问题：
- 甲方管理员是否容易看懂当前分红方式？
- 是否有更简单、更容易执行和对账的分红设计？
并给出推荐方案与落地路径。
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. 当前方案对甲方可理解性的评估
结论：一般不容易看懂，且容易产生“配置了却不生效”的认知落差。
主要原因：
- 心智复杂：甲方要同时理解渠道模式（返水/联营）、角色组比例、管理员比例三层规则。
- 口径不一致：界面上有三级比例，但结算时是渠道单层落账，容易质疑“为什么不是按我配的三级比例发放”。
- 对账难：财务看到佣金记录时只能看到渠道维度，不容易反推角色组和管理员分配关系。
- 运维负担高：层级变化（调组、换管理员）后，历史解释成本高。
4. 更简单的分红设计方式（推荐）
4.1 推荐方案：渠道结算 + 渠道内二次分配（两层）
将分红流程拆为两个明确步骤：
A. 一级：渠道结算（平台对渠道）
- 保留当前
channel.agent_mode的计算方式（turnover/affiliate） - 先得到一个渠道应发佣金：
channel_commission_amount - 生成渠道结算单（当前已具备）
B. 二级：渠道内分配（渠道对管理员）
- 不再使用“角色组分红比例”参与金额运算（角色组只负责权限）
- 仅维护“渠道下管理员分配权重”（例如总和=100%）
- 自动拆分：
admin_commission = channel_commission_amount × admin_weight - 为每个管理员生成独立佣金记录（多条）
这样甲方只需要理解一句话：
平台先算渠道总佣金，再按渠道内管理员权重拆分。
4.2 为什么推荐该方案
- 业务更直观：甲方看“渠道总佣金 + 管理员占比”即可。
- 和现有代码贴近：你们当前已经是“先算渠道佣金”，只需补“二次拆分”。
- 对账容易：每个管理员佣金来源清晰，可直接汇总对账。
- 后续可扩展：以后要按团队、按代理线拆分，可以在“二次分配”层升级，不影响一级结算。
5. 备选方案对比
5.1 方案A（现状表象）：渠道 -> 角色组 -> 管理员三级
- 优点：理论上精细
- 缺点：配置理解成本高、维护复杂、容易和实际结算脱节
- 适用：组织结构非常稳定、财务系统成熟的大盘
5.2 方案B（推荐）：渠道 -> 管理员两级
- 优点：简单、易讲、易对账、改造成本低
- 缺点：若强依赖“角色组抽成”会减少一层表达
- 适用：当前阶段（快速上线、减少运营误解）
5.3 方案C（最简）：仅渠道一级
- 优点：最简单
- 缺点：无法直接落地到管理员收益，不利于激励
- 适用：仅用于统计，不用于发佣
6. 建议的产品口径（给甲方的话术）
建议统一说明为：
- 渠道分红：系统按渠道配置（返水或联营）自动计算该周期渠道总佣金。
- 人员分配：渠道总佣金按“渠道内管理员分配比例”自动拆分。
- 角色组作用：角色组只负责菜单权限与数据权限，不参与金额运算。
- 结算可追溯：每条管理员佣金都能追溯到对应渠道结算单。
7. 数据与实现改造建议（按最小改动）
7.1 数据字段建议
- 保留：
channel的分红计算参数（现有） - 建议新增（任选其一）：
- 在
admin增加channel_share_rate（该管理员在所属渠道的拆分比例） - 或新增
channel_admin_share(channel_id, admin_id, share_rate)
- 在
7.2 逻辑改造建议
- 渠道结算得到
commission_amount - 拉取该渠道有效管理员分配比例列表（总和=100%）
- 按比例拆分并批量写入
agent_commission_record - 若分配比例未配置：
- 方案一：默认100%给渠道负责人
- 方案二：阻止结算并提示“请先配置渠道管理员分配比例”
7.3 风险控制建议
- 分配比例总和强校验（必须=100%）
- 管理员离职/禁用时自动重算或禁止结算
- 结算后锁单，后改比例不影响历史账单
8. 迁移策略建议
分三步上线：
- 第1步（兼容期）：保留现有字段，新增“渠道内管理员分配比例”配置
- 第2步（双轨期）：结算时同时产出“旧口径结果 + 新口径预览”用于核对
- 第3步（切换期）：正式切到“渠道+管理员两级”，角色组比例仅保留展示或下线
9. 最终建议结论
从“甲方能否看懂”和“系统可维护性”来看，建议采用：
渠道结算 + 渠道内管理员二次分配（两级）。
这是在你们当前代码基础上改造成本最低、解释成本最低、财务对账最清晰的方案。
不建议继续强化“渠道->角色组->管理员”三级分红公式作为主线。
10. 本次已落地改造（2026-04-18）
已在系统中完成以下改造：
- 新增渠道管理员分配表：
channel_admin_share - 下线并删除旧字段：
admin_group.commission_rate、admin.commission_rate - 新增后台接口：
channelAdminShareList：读取渠道管理员分配配置saveChannelAdminShare：保存渠道管理员分配配置（启用项合计必须100%）
- 手动结算改造：
- 先算渠道总佣金
- 再按
channel_admin_share比例拆分为多条agent_commission_record - 结算预览支持查看拆分明细
- 渠道后台页面新增“分配比例”按钮与配置弹窗，用于维护管理员分配比例
- 角色组与管理员页面已移除旧分红比例字段展示与编辑项
说明：
- 若未配置
channel_admin_share，系统会回退为“渠道首个管理员100%”以保证兼容历史流程。