num/docs/distribution-model-v2.md

分销体系重构设计 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 佣金计算逻辑

// 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 表字段调整

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

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

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

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 参数

-- 一级分销佣金比例
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. 年度汇算清缴结果回填与用户通知流程（税务）