num/docs/bonus-scheme-design.md

能量师月度分红方案设计（资金池版）

平台拿出月收入的 10% 作为分红总池，拆分为个人分红池（5%）和团队分红池（5%），按参与者的销售占比竞争分配
状态：v1.0 Draft，待确认参数

---

一、核心公式

平台月总收入 = 当月所有付费订单实付金额总和（扣除退款）

个人分红池 = 平台月总收入 × 5%
团队分红池 = 平台月总收入 × 5%
总分红池   = 平台月总收入 × 10%

1.1 个人分红（单人）

个人当月直接销售额 = 该能量师直接下级的所有付费订单总和

所有活跃能量师直接销售总额 = Σ(每个能量师个人当月直接销售额)

个人分红 = (个人当月直接销售额 / 所有活跃能量师直接销售总额) × 个人分红池

示例：

平台月总收入：¥100,000
个人分红池：¥100,000 × 5% = ¥5,000

参与分红的活跃能量师共 3 人：

        直接销售额    占比        个人分红
A        ¥20,000      20%         ¥1,000
B        ¥50,000      50%         ¥2,500
C        ¥30,000      30%         ¥1,500
        ────────    ──────      ────────
总计     ¥100,000      100%       ¥5,000 ✅ 池子分完

1.2 团队分红（单人）

个人当月团队销售额 = 该能量师团队的总付费订单（不限层级，逐层递归，
                    遇到当月无直接销售的成员则截断该分支，不计入）

所有能量师团队销售总额 = Σ(每个能量师团队当月销售额)

团队分红 = (个人当月团队销售额 / 所有能量师团队销售总额) × 团队分红池

示例：

平台月总收入：¥100,000
团队分红池：¥100,000 × 5% = ¥5,000

参与分红的团队长共 3 人：

        团队销售额    占比        团队分红
A        ¥40,000      20%         ¥1,000
B        ¥100,000     50%         ¥2,500
C        ¥60,000      30%         ¥1,500
        ────────    ──────      ────────
总计     ¥200,000      100%       ¥5,000 ✅ 池子分完

团队截断示例：

能量师 A 的团队结构：
A（直接销售¥5,000）
├── B（直接销售¥3,000）  ← 有销售，纳入
│   ├── D（直接销售¥1,000）  ← 有销售，纳入
│   └── E（直接销售¥0）     ← ❌ 无销售，截断（E及E的下级都不计入）
├── C（直接销售¥0）         ← ❌ 无销售，截断
└── F（直接销售¥2,000）  ← 有销售，纳入

A 的团队销售额 = ¥5,000（A本身）+ ¥3,000（B）+ ¥1,000（D）+ ¥2,000（F）
                = ¥11,000
E 和 C 的分支被截断，不计入

1.3 单人月分红总额

月分红总额 = 个人分红 + 团队分红
           = (个人直接销售占比 × 5% + 个人团队销售占比 × 5%) × 平台月总收入

---

二、关键特征（与传统提成制的区别）

维度	传统提成制（旧方案）	资金池制（本方案）
分红来源	平台从利润中另出	平台月收入的固定比例（10%）
分配方式	固定比例（个人5%+团队5%）	按销售占比竞争分配
总额是否固定	不固定（看个人销售额）	固定（看平台总收入）
相互影响	各人独立，互不影响	一人多拿则另一人少拿
平台风险	不可控（销售额越高支出越高）	可控（固定10%支出）

举例说明差异：

传统提成制下：
A 个人销售 ¥20,000 → 固定拿 ¥1,000（5%）
B 个人销售 ¥50,000 → 固定拿 ¥2,500（5%）
平台需支出：¥3,500

资金池制下：
个人分红池 = ¥5,000（固定）
A 占 20% → ¥1,000
B 占 50% → ¥2,500
平台支出：¥5,000（固定）

差异：传统制下平台总支出随销售额增长而线性增长，
      资金池制下平台总支出 = 总收入×5%，始终可控。

---

三、资格与淘汰机制

3.1 参与资格

角色	个人分红	团队分红
活跃能量师（当月有直接销售）	✅	✅（有团队即参与）
非活跃能量师（当月无直接销售）	❌	❌
连续 3 个月无直接销售	❌（资格取消）	❌（资格取消）
恢复销售当月	✅ 自动恢复	✅ 自动恢复

3.2 资格取消的影响

被取消资格的能量师：
- 不计入"所有活跃能量师"
- 其直接销售额不计入总分母
- 其团队销售额不计入总分母
- 当月不分任何分红

→ 其他活跃能量师的分红比例自动变大

示例：

个人分红池 = ¥5,000

情况A（全员活跃）：
A ¥20,000 / 总¥100,000 (20%) → ¥1,000
B ¥50,000 / 总¥100,000 (50%) → ¥2,500
C ¥30,000 / 总¥100,000 (30%) → ¥1,500

情况B（C被取消资格）：
A ¥20,000 / 总¥70,000   (28.6%) → ¥1,429
B ¥50,000 / 总¥70,000   (71.4%) → ¥3,571
                       ────────      ──────
                                    ¥5,000 ✅ 池子不变，分配比例重算

---

四、淘汰逻辑（月度判定）

每月 1 日，遍历所有能量师（vipType='practitioner'）：

步骤 1：统计上月个人直接销售额
├─ > 0 → 当月合格，记 consecutive_zero_months = 0
└─ = 0 → consecutive_zero_months + 1

步骤 2：判定资格
├─ consecutive_zero_months < 3 → 正常参与分红
└─ consecutive_zero_months ≥ 3 → disqualified = true
   └─ 本月不参与任何分红

步骤 3：恢复判断
├─ 合格月：disqualified = false
└─ 恢复销售当月 → 立即 disqualified = false

步骤 4：计算个人分红
公式：个人占池 = 个人直接销售额 / 所有活跃能量师直接销售额总和
       个人分红 = 个人占池 × 个人分红池

步骤 5：计算团队分红
公式：个人占池 = 个人团队销售额 / 所有活跃能量师团队销售额总和
       团队分红 = 个人占池 × 团队分红池

步骤 6：写入数据库

---

五、数据库设计

5.1 monthly_bonus_records（月度分红结算表）

CREATE TABLE `monthly_bonus_records` (
  `id` BIGINT PRIMARY KEY AUTO_INCREMENT,
  `energy_master_id` BIGINT NOT NULL COMMENT '能量师用户ID',
  `year_month` VARCHAR(7) NOT NULL COMMENT '结算月份（如 2026-06）',

  -- 平台数据
  `platform_revenue_fen` BIGINT NOT NULL DEFAULT 0 COMMENT '平台当月总收入（分）',
  `personal_pool_fen` BIGINT NOT NULL DEFAULT 0 COMMENT '个人分红池总金额（分）',
  `team_pool_fen` BIGINT NOT NULL DEFAULT 0 COMMENT '团队分红池总金额（分）',

  -- 个人销售数据
  `personal_sales_fen` BIGINT NOT NULL DEFAULT 0 COMMENT '个人直接销售金额（分）',
  `total_personal_sales_fen` BIGINT NOT NULL DEFAULT 0 COMMENT '所有活跃能量师直接销售总额（分）',
  `personal_share_pct` INT NOT NULL DEFAULT 0 COMMENT '个人占池百分比（万分比，如 2000=20%）',

  -- 团队销售数据
  `team_sales_fen` BIGINT NOT NULL DEFAULT 0 COMMENT '个人团队销售金额（分）',
  `total_team_sales_fen` BIGINT NOT NULL DEFAULT 0 COMMENT '所有活跃能量师团队销售总额（分）',
  `team_share_pct` INT NOT NULL DEFAULT 0 COMMENT '团队占池百分比（万分比）',

  -- 分红结果
  `personal_bonus_fen` BIGINT NOT NULL DEFAULT 0 COMMENT '个人分红金额（分）',
  `team_bonus_fen` BIGINT NOT NULL DEFAULT 0 COMMENT '团队分红金额（分）',
  `total_bonus_fen` BIGINT NOT NULL DEFAULT 0 COMMENT '总分红金额（分）',

  -- 资格状态
  `disqualified` TINYINT(1) NOT NULL DEFAULT 0 COMMENT '是否被取消资格（0=正常 1=已取消）',
  `consecutive_zero_months` INT NOT NULL DEFAULT 0 COMMENT '连续无直接销售月数',

  -- 结算状态
  `status` VARCHAR(20) NOT NULL DEFAULT 'pending' COMMENT 'pending/approved/paid/cancelled',
  `settled_at` DATETIME COMMENT '结算处理时间',
  `paid_at` DATETIME COMMENT '实际发放时间',
  `remark` VARCHAR(200) COMMENT '备注',

  UNIQUE KEY `uk_master_month` (`energy_master_id`, `year_month`),
  INDEX `idx_year_month` (`year_month`),
  INDEX `idx_status` (`status`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='能量师月度分红结算表';

5.2 sys_config 参数

INSERT INTO sys_config (`key`, `value`, `desc`, `value_type`) VALUES
-- 分红比例（占总收入）
('bonus.personal.pool_rate', '500', '个人分红池占总收入万分比（500=5%）', 'percent'),
('bonus.team.pool_rate', '500', '团队分红池占总收入万分比（500=5%）', 'percent'),
-- 资格规则
('bonus.disqualify_months', '3', '连续无直接销售月数上限', 'number'),
-- 结算规则
('bonus.settlement_day', '1', '月度结算日（每月第几天）', 'number'),
('bonus.min_payout', '5000', '最低发放金额（分，¥50），不足滚入下月', 'amount');

---

六、结算流程

每月 1 日 00:00 触发结算
│
├─ 第一步：计算平台当月总收入（所有付费订单实付金额，扣除退款）
│   └─ personal_pool = 总收入 × 5%
│   └─ team_pool = 总收入 × 5%
│
├─ 第二步：查询所有能量师，逐一判定资格
│   ├─ 无销售 → consecutive_zero_months + 1
│   └─ 有销售 → consecutive_zero_months = 0
│
├─ 第三步：计算活跃能量师（合格者）的个人销售总额 & 团队销售总额
│   ├─ 个人销售额 = 本人直接下级所有付费订单
│   └─ 团队销售额 = 递归计算：本人 + 下级（有销售则继续递归，遇到无销售则截断）
│
├─ 第四步：对每个活跃能量师，计算占比和分红
│   ├─ 个人分红 = (个人销售额 / 总个人销售额) × personal_pool
│   └─ 团队分红 = (团队销售额 / 总团队销售额) × team_pool
│
├─ 第五步：写入 monthly_bonus_records
│
├─ 第六步：发放（生成提现记录）
│   └─ total_bonus_fen < min_payout → 标记 "rollover"，下月合并发放
│
└─ 第七步：通知（站内信）

---

七、与现有分销体系的关系

现有机制	是否受影响	说明
直接邀请佣金（40%）	❌ 不受影响	即时结算，独立于分红池
间接邀请积分（10分）	❌ 不受影响	即时发放
旧团队分红（5%单轨）	✅ 被替换	新方案双池竞争制替换旧单轨
提现机制	❌ 不受影响	分红直接入 user_wallet，走提现流程

---

八、待确认事项

#	事项	建议	你的决定
1	总分红池比例	10%（个人5%+团队5%）	—
2	个人 vs 团队池拆分比例	各5% 对半	—
3	淘汰月数	连续3个月无直接销售	—
4	最低发放金额	¥50（不足滚入下月）	—
5	团队层级	✅ 已确认：不限层级，遇到无销售成员截断	—
6	分红数据来源	订单实付金额（扣除退款）	—