docs: 分红方案设计——资金池制(个人5%+团队5%池，按占比分配，团队截断至无销售成员)

docs/bonus-scheme-design.md

@@ -0,0 +1,312 @@
+# 能量师月度分红方案设计（资金池版）
+
+> 平台拿出月收入的 **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（月度分红结算表）
+
+```sql
+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 参数
+
+```sql
+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 | 分红数据来源 | 订单实付金额（扣除退款） | — |