# 分销与积分体系重构设计 v2
> 从两级分销 → 一级分销（统一40%）+ 间接邀请积分 + 能量师团队分红
> 状态：v1.0 参数全部锁定，待编码实现

---

## 一、设计目标

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

---

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

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

**核心规则：**
- 只有付费用户可以发展下级（免费用户不行）
- 直接邀请佣金 = 购买金额 × 40%，即时结算
- 间接邀请不结算佣金，仅奖励 10 积分/次
- 同一用户只能被邀请一次（上级锁定，不可变更）
- tarunner 默认日限模式，通过 sys_config.allow_tarunner 按需放开上限

---

## 三、佣金与积分触发事件

---

## 三、触发事件与结算规则

### 3.1 直接邀请佣金（一级）

| 购买事件 | 直接邀请人获得 | 间接邀请人获得 | 团队分红 |
|---------|-------------|-------------|---------|
| 购买 C端年费 ¥131 | 40% 佣金（¥52.40） | 10 积分 | ❌ |
| 购买 家庭套餐 ¥686 | 40% 佣金（¥274.40） | 10 积分 | ❌ |
| 购买 超级会员 ¥1,314 | 40% 佣金（¥525.60） | 10 积分 | ❌ |
| 购买 能量师 ¥1,314+ | 40% 佣金（¥525.60） | 10 积分 | ✅（能量师的直接上级拿佣金，能量师自己的团队拿分红） |

> **注意**：直接邀请不赠送积分，仅结算佣金。间接邀请不结算佣金，仅奖励 10 积分。团队分红不是多级佣金，而是能量师作为团队长的管理绩效奖。  



## 四、佣金与积分结构

### 4.1 直接邀请佣金（一级分销）

```
用户 B 被推广者 A 直接邀请注册
│
▼
用户 B 完成任意付费购买
│
▼
推广者 A 获得佣金 = 购买金额 × 40%
```

| 推荐人角色 | 佣金比例 | 说明 |
|-----------|---------|------|
| 所有付费用户（C端/家庭/能量师） | **40%** | 统一比例，推广任意付费产品均按 40% 结算 |

> 直接邀请不赠送积分，仅结算佣金。

### 4.2 间接邀请积分

```
推广者 A → 用户 B（直接邀请）
            │
            └→ 用户 C（B 邀请，即 A 的间接邀请）
               │
               ▼ C 完成付费购买
               │
               ▼ A 获得 10 积分（固定，非按比例）
```

| 指标 | 默认值 | 说明 |
|------|--------|------|
| 间接邀请积分 | **10** | 每笔间接付费下单奖励，固定值 |

> 10 积分为示例值，通过 `sys_config.indirect_invite.points` 可动态调整。

### 4.3 能量师团队分红（与积分挂钩）

```
能量师 A 的直接下级团队购买：
├── B 购买 → A 团队分红基数 += 购买金额
├── C 购买 → A 团队分红基数 += 购买金额
└── D 购买 → A 团队分红基数 += 购买金额

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

团队分红可额外挂钩积分激励：每月团队销售产生的积分可转化为能量师个人积分，作为其团队贡献值的计算依据。

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

### 4.4 积分抵扣兑换规则（用户侧）

普通用户（非能量师）积分可作为替代分析次数的兑换单位：

| 兑换项 | 消耗积分 | 说明 |
|--------|---------|------|
| 单人能量盘分析 | **100** | 100 积分兑换 1 次分析（等同原免费 1 次配额） |
| 其他商品 | 按兑换项配置 | 通过 `points_rewards` 表维护，后台可增删改 |

> 100 积分解耦于原"3 人 × 3 次/天"配额，属独立兑换通道。

### 4.5 完整示例

```
场景：推广者 A 发展了 2 个直接下级 B、C

B 通过 A 的推广码购买 C端会员 ¥131
→ A 佣金 = ¥131 × 40% = ¥52.40

C 通过 B 的推广码购买 家庭套餐 ¥686（A 的间接邀请）
→ A 佣金 = 0（只有直接邀请才有佣金）
→ A 获得间接积分 = 10 积分
```

---

## 五、与现有 sys_config 的对应关系

## 五、与旧体系对比

| 维度 | 旧体系（两级分销） | 新体系（一级+团队分红） |
|------|-----------------|---------------------|
| 分销层级 | 两级（一级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_unified', '4000', '一级佣金统一万分比（4000=40%）', 'percent'),
-- 间接邀请积分
('commission.indirect_invite.points', '10', '间接邀请（二级）每次付费奖励积分（固定值）', 'number'),
-- 团队分红
('commission.team_bonus.rate', '500', '团队月度分红万分比（500=5%）', 'percent'),
('commission.team_bonus.min_payout', '5000', '团队分红最低发放金额（分，¥50）', 'amount'),
('commission.team_bonus.settlement_day', '1', '月度分红结算日（每月第几天）', 'number'),
-- 团队规模上限
('commission.team.max_members', '5', '能量师直接下级人数上限（0=不限制）', 'number'),
-- tarunner（系统运营官）每日邀请上限
('tarunner.invite_daily_limit', '50', 'tarunner 每日邀请人数上限（0=不限制）', 'number'),
('system.allow_tarunner', 'false', '是否允许 tarunner 申请/入驻（默认关闭，按需放开）', 'boolean'),
-- 积分系统
('points.checkin.daily', '1', '每日签到积分', 'number'),
('points.consultation.complete', '1', '完成一次咨询积分', 'number'),
('points.redeem.analysis_cost', '100', '积分兑换单人能量盘分析所需积分（等同1次免费配额）', 'number'),
('points.redeem.min', '10', '最低兑换积分门槛', 'number'),
('points.year_expire_enabled', 'true', '是否开启年度过期', 'boolean'),
('points.year_remind_day', '1101', '过期提醒日期（MMDD格式）', 'number');
```

### 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. 年度汇算清缴结果回填与用户通知流程（税务）