# 分销体系重构设计 v2
> 从两级分销 → 一级分销 + 能量师团队分红 + tarunner 运营官
> 状态：v1.0 参数已确认，待编码实现

---

## 一、设计目标

1. **简化层级**：取消二级佣金（A的下级B再推荐C，A不再拿C的佣金）
2. **扩大分销主体**：所有付费用户（C端/家庭套餐/超级会员）均可发展下级，系统运营官（tarunner）有每日邀请上限
3. **能量师团队制**：能量师组建团队，享受团队销售利润分红
4. **合规性**：一级分销 + 团队分红（非直推计酬），符合《禁止传销条例》

---

## 二、新角色与分销权限

| 角色 | 年费 | 可发展下级 | 一级佣金 | 团队分红 | 数据库标记 | 每日邀请上限 |
|------|------|-----------|---------|---------|-----------|------------|
| 普通用户 | ¥0 | ❌ | — | — | `vipType=NULL` | — |
| C端会员 | ¥131 | ✅ | 有 | ❌ | `vipType='annual'` | 默认受限，按需放开 |
| 家庭套餐 | ¥686 | ✅ | 有 | ❌ | `vipType='family_plan'` | 默认受限，按需放开 |
| 超级会员 | ¥1,314 | ✅ | 有 | ❌ | `vipType='super_annual'`（暂缓） | 默认受限，按需放开 |
| 能量师 | ¥1,314+ | ✅ | 有 | ✅ | `vipType='practitioner'` | 默认开放 |
| 系统运营官 | — | ✅ | 有 | ❌ | `role='tarunner'` | 按配置 |

**核心规则：**
- 只有付费用户可以发展下级（免费用户不行）
- 一级佣金 = 直接推荐的人购买时，推荐人获得的佣金
- 团队分红 = 能量师从其团队（直接下级）的总销售额中获得额外分红
- 同一用户最多只有一个上级（关系锁定，不可变更）
- tarunner 默认日限模式，通过 sys_config.allow_tarunner 按需放开上限

---

## 三、佣金触发事件

以下购买行为触发佣金结算：

| 购买事件 | 触发对象 | 一级佣金给 | 团队分红 |
|---------|---------|-----------|---------|
| 购买 C端年费 ¥131 | 推荐人 | ✅ | ❌（仅能量师团队分红） |
| 购买 家庭套餐 ¥686 | 推荐人 | ✅ | ❌ |
| 购买 超级会员 ¥1,314 | 推荐人 | ✅ | ❌ |
| 购买 能量师年费 ¥1,314+ | 推荐人 | ✅ | ✅（能量师的上级拿一级佣金 + 团队分红） |

> **注意**：团队分红不是多级佣金，而是能量师作为团队长的**管理绩效奖**——基于团队整体业绩的额外激励，而非每个下级的逐层提成。

---

## 四、佣金结构（推荐方案）

### 4.1 一级分销佣金

```
用户B通过能量师A的推广链接注册
│
▼
用户B购买任意付费产品
│
▼
能量师A获得一级佣金 = 购买金额 × 一级佣金比例
```

| 推荐人角色 | 一级佣金比例 | 说明 |
|-----------|-------------|------|
| C端会员 | **15%** | 推荐他人购买时获得 |
| 家庭套餐 | **18%** | 推荐他人购买时获得 |
| 超级会员 | **20%** | 暂缓上线 |
| 能量师 | **20%** | 推荐他人购买时获得 |

### 4.2 团队销售利润分红（能量师专属）

```
能量师A 的直接下级团队：
├── B（购买了 ¥131 C端会员）→ A 团队分红基数 += ¥131
├── C（购买了 ¥686 家庭套餐）→ A 团队分红基数 += ¥686
└── D（购买了 ¥1,314 能量师）→ A 团队分红基数 += ¥1,314

月末结算：
团队分红 = 团队月度总销售额 × 团队分红比例（5%）
```

| 指标 | 默认值 | 说明 |
|------|--------|------|
| 团队分红比例 | **5%** | 月度团队总销售额的 5% |
| 结算周期 | **每月** | 每月 1 日结算上月数据 |
| 最低发放门槛 | ¥50 | 分红 < ¥50 滚入下月 |
| 计算范围 | 直接下级 | 仅第一层，不递归 |

### 4.3 完整示例

```
场景：能量师A 发展了 3 个直接下级（B/C/D）

B 购买了 C端会员 ¥131 → A 一级佣金 = ¥131 × 20% = ¥26.20
C 购买了 家庭套餐 ¥686  → A 一级佣金 = ¥686 × 20% = ¥137.20
D 购买了 能量师 ¥1,314  → A 一级佣金 = ¥1,314 × 20% = ¥262.80

当月团队销售额 = ¥131 + ¥686 + ¥1,314 = ¥2,131
团队分红 = ¥2,131 × 5% = ¥106.55

A 本月总收入 = ¥26.20 + ¥137.20 + ¥262.80 + ¥106.55 = ¥532.75
```

---

## 五、与旧体系对比

| 维度 | 旧体系（两级分销） | 新体系（一级+团队分红） |
|------|-----------------|---------------------|
| 分销层级 | 两级（一级30% + 二级10%） | 一级（直接推荐佣金） |
| 可发展下级 | 仅能量师 | 所有付费用户 |
| 能量师激励 | 二级佣金10% | 团队分红5%（基于团队业绩） |
| 下级推广动力 | 强（下级也能拿二级佣金） | 弱（下级只能拿一级佣金，和普通付费用户一样） |
| 平台留存 | 60% | 约 65%-80%（取决于配置） |
| 合规定性 | 两级 = 安全边界 | 一级 + 团队分红 = 更安全 |
| 结算复杂度 | 中（需追踪两级关系） | 低（仅需追踪直接上级） |

---

## 六、后端设计

### 6.1 佣金计算逻辑

```java
// CommissionService.java - 核心逻辑

// 1. 一级佣金（简化：只结算给直接上级）
public void settleFirstLevelCommission(Long buyerId, Long productId, int amountFen) {
    User buyer = userRepo.findById(buyerId).orElseThrow();
    Long referrerId = buyer.getReferrerId(); // 直接上级
    
    if (referrerId == null) return; // 无上级，不结算
    
    User referrer = userRepo.findById(referrerId).orElse(null);
    if (referrer == null || !isPaidUser(referrer)) return; // 上级未付费，不结算
    
    // 根据上级角色确定佣金比例
    BigDecimal rate = getFirstLevelRate(referrer.getVipType());
    BigDecimal commission = new BigDecimal(amountFen).multiply(rate);
    
    // 创建佣金记录
    Commission c = new Commission();
    c.setUserId(referrerId);
    c.setAmountFen(commission.intValue());
    c.setLevel(1); // 一级
    c.setSourceUserId(buyerId);
    c.setProductType(productId);
    c.setStatus("available");
    commissionRepo.save(c);
}

// 2. 团队分红（月度批量结算，仅能量师）
@Scheduled(cron = "0 0 1 * * ?") // 每月1日 00:00
public void settleTeamBonus() {
    // 找出所有能量师
    List<User> practitioners = userRepo.findByVipType("practitioner");
    
    for (User practitioner : practitioners) {
        // 直接下级团队
        List<User> directTeam = userRepo.findByReferrerId(practitioner.getId());
        
        // 计算团队月度购买总额
        int teamMonthlySales = commissionRepo.sumTeamMonthlySales(directTeam);
        
        // 团队分红 = 销售额 × 5%
        BigDecimal bonus = new BigDecimal(teamMonthlySales).multiply(new BigDecimal("0.05"));
        
        if (bonus.compareTo(new BigDecimal(5000)) < 0) continue; // < ¥50 跳过
        
        // 创建分红记录
        Commission c = new Commission();
        c.setUserId(practitioner.getId());
        c.setAmountFen(bonus.intValue());
        c.setLevel(0); // 0 = 团队分红（特殊标记）
        c.setStatus("available");
        c.setRemark("月度团队分红");
        commissionRepo.save(c);
    }
}
```

### 6.2 数据库变更

#### `commissions` 表字段调整

```sql
-- level 字段含义调整：
-- 0 = 团队分红（月度）
-- 1 = 一级佣金
-- 2 = （不再使用，预留）

ALTER TABLE commissions 
  MODIFY COLUMN level INT COMMENT '0=团队分红 1=一级佣金 2=预留';
```

#### 新增 `team_bonus_monthly` 汇总表（可选，用于对账）

```sql
CREATE TABLE `team_bonus_monthly` (
  `id` BIGINT PRIMARY KEY AUTO_INCREMENT,
  `practitioner_id` BIGINT NOT NULL,
  `year_month` VARCHAR(7) NOT NULL, -- '2026-06'
  `team_sales_fen` INT NOT NULL DEFAULT 0,
  `bonus_fen` INT NOT NULL DEFAULT 0,
  `member_count` INT NOT NULL DEFAULT 0,
  `settled_at` DATETIME,
  UNIQUE KEY `uk_practitioner_month` (`practitioner_id`, `year_month`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
```

### 6.3 sys_config 参数

```sql
-- 一级分销佣金比例
INSERT INTO sys_config (`key`, `value`, `desc`, `value_type`) VALUES
('commission.level1.rate_annual', '1500', 'C端会员一级佣金万分比（1500=15%）', 'percent'),
('commission.level1.rate_family', '1800', '家庭套餐一级佣金万分比（1800=18%）', 'percent'),
('commission.level1.rate_super', '2000', '超级会员一级佣金万分比（2000=20%）', 'percent'),
('commission.level1.rate_practitioner', '2000', '能量师一级佣金万分比（2000=20%）', 'percent'),
('commission.team_bonus.rate', '500', '团队月度分红万分比（500=5%）', 'percent'),
('commission.team_bonus.min_payout', '5000', '团队分红最低发放金额（分，¥50）', 'amount'),
('commission.team_bonus.settlement_day', '1', '月度分红结算日（每月第几天）', 'number'),
-- tarunner（系统运营官）每日邀请上限
('tarunner.invite_daily_limit', '50', 'tarunner 每日邀请人数上限（0=不限制）', 'number'),
('system.allow_tarunner', 'false', '是否允许 tarunner 申请/入驻（默认关闭，按需放开）', 'boolean');
```

### 6.4 推荐关系表

现有 `referrerId` 单字段即可支撑一级分销，无需额外表。

---

## 七、前端改动

### 7.1 豁免的关系

付费用户（C端/家庭/超级/能量师）均可发展下级，推广码面板不再仅限于能量师。

### 7.2 能量师额外展示

能量师个人中心增加「我的团队」板块：
```
┌─────────────────────────┐
│ 我的团队                │
├─────────────────────────┤
│ 直接下级：12人          │
│ 本月团队销售额：¥8,680  │
│ 本月团队分红：¥434.00   │
│ [查看团队列表 →]        │
└─────────────────────────┘
```

### 7.3 佣金类型标签

佣金记录增加类型区分：
- `一级佣金`（蓝色标签）
- `团队分红`（金色标签）

---

## 八、与现有系统兼容

| 现有功能 | 影响 | 处理方式 |
|---------|------|---------|
| `commissions` 表 | `level` 字段含义变化 | 迁移脚本更新注释 |
| `OrderService.paySuccess()` | 二级佣金逻辑删除 | 改为只调用一级佣金结算 |
| `UserService.hasPermission()` | 推广权限从 `practitioner` 扩展为所有付费用户 | 修改判断条件 |
| 个人中心推广码 | 能量师专属 → 所有付费用户可见 | UI 改为按角色展示 |
| 提现系统 | 不影响 | 佣金来源变了，提现逻辑不变 |
| 团队分红 | 新功能 | 新增月度定时任务 |

---

## 九、已确认决策快照（v1.0）

| 决策项 | 结论 | 落地位置 |
|--------|------|---------|
| 佣金比例（一级） | C端15% / 家庭18% / 能量师20% | sys_config `commission.level1.*` |
| 团队分红比例 | 5%（月度直接下级销售额） | sys_config `commission.team_bonus.rate` |
| 团队规模上限 | 直接下级 **5人**，之后按负载放开 | 代码硬上限 + 配置化预留 |
| tarunner 邀请策略 | **选项A**：默认日限，按需放开 | sys_config `tarunner.invite_daily_limit` + `system.allow_tarunner` |
| 超级会员上线节奏 | 暂缓，v1.0 不包含 | 文档标记「暂缓」，不投入开发 |
| 升级路径 | 全部含在当前版本，不分拆 v1.1 | 实现清单归一到 v1.0 |
| 团队分红基数 | 所有购买事件（C端/家庭/能量师）均计入 | `team_bonus_monthly` 聚合逻辑 |

---

## 十、v1.0 交付后仍开放的议题

1. tarunner 日限放开阈值（预估流量达到 X 时提升）  
2. 团队 5 人上限解除后的扩容触发条件  
3. 超级会员上线时的权益定价与佣金比例确认  
4. 年度汇算清缴结果回填与用户通知流程（税务）