docs: 分销v2设计+附录C角色矩阵更新(家庭套餐/超级会员暂缓)

docs/distribution-model-v2.md

@@ -0,0 +1,278 @@
+# 分销体系重构设计 v2
+> 从两级分销 → 一级分销 + 能量师团队分红
+> 状态：Draft，待用户确认佣金比例
+
+---
+
+## 一、设计目标
+
+1. **简化层级**：取消二级佣金（A的下级B再推荐C，A不再拿C的佣金）
+2. **扩大分销主体**：所有付费用户（C端/家庭套餐/超级会员）均可发展下级
+3. **能量师团队制**：能量师组建团队，享受团队销售利润分红
+4. **合规性**：一级分销 + 团队分红（非直推计酬），符合《禁止传销条例》
+
+---
+
+## 二、新角色与分销权限
+
+| 角色 | 年费 | 可发展下级 | 一级佣金 | 团队分红 | 数据库标记 |
+|------|------|-----------|---------|---------|-----------|
+| 普通用户 | ¥0 | ❌ | — | — | `vipType=NULL` |
+| C端会员 | ¥131 | ✅ | 有 | ❌ | `vipType='annual'` |
+| 家庭套餐 | ¥686 | ✅ | 有 | ❌ | `vipType='family_plan'` |
+| 超级会员 | ¥1,314 | ✅ | 有 | ❌ | `vipType='super_annual'`（暂缓） |
+| 能量师 | ¥1,314+ | ✅ | 有 | ✅ | `vipType='practitioner'` |
+
+**核心规则：**
+- 只有付费用户可以发展下级（免费用户不行）
+- 一级佣金 = 直接推荐的人购买时，推荐人获得的佣金
+- 团队分红 = 能量师从其团队（直接下级）的总销售额中获得额外分红
+- 同一用户最多只有一个上级（关系锁定，不可变更）
+
+---
+
+## 三、佣金触发事件
+
+以下购买行为触发佣金结算：
+
+| 购买事件 | 触发对象 | 一级佣金给 | 团队分红 |
+|---------|---------|-----------|---------|
+| 购买 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');
+```
+
+### 6.4 推荐关系表
+
+现有 `referrerId` 单字段即可支撑一级分销，无需额外表。
+
+---
+
+## 七、前端改动
+
+### 7.1 豁免的关系
+
+付费用户（C端/家庭/超级/能量师）均可发展下级，推广码面板不再仅限于能量师。
+
+### 7.2 能量师额外展示
+
+能量师个人中心增加「我的团队」板块：
+```
+┌─────────────────────────┐
+│ 我的团队                │
+├─────────────────────────┤
+│ 直接下级：12人          │
+│ 本月团队销售额：¥8,680  │
+│ 本月团队分红：¥434.00   │
+│ [查看团队列表 →]        │
+└─────────────────────────┘
+```
+
+### 7.3 佣金类型标签
+
+佣金记录增加类型区分：
+- `一级佣金`（蓝色标签）
+- `团队分红`（金色标签）
+
+---
+
+## 八、与现有系统兼容
+
+| 现有功能 | 影响 | 处理方式 |
+|---------|------|---------|
+| `commissions` 表 | `level` 字段含义变化 | 迁移脚本更新注释 |
+| `OrderService.paySuccess()` | 二级佣金逻辑删除 | 改为只调用一级佣金结算 |
+| `UserService.hasPermission()` | 推广权限从 `practitioner` 扩展为所有付费用户 | 修改判断条件 |
+| 个人中心推广码 | 能量师专属 → 所有付费用户可见 | UI 改为按角色展示 |
+| 提现系统 | 不影响 | 佣金来源变了，提现逻辑不变 |
+| 团队分红 | 新功能 | 新增月度定时任务 |
+
+---
+
+## 九、待确认事项
+
+1. **佣金比例**：一级佣金 15%/18%/20% 是否合适？团队分红 5% 是否合理？
+2. **团队分红基数**：是否包含推广码带来的所有购买（C端/家庭/能量师）？还是只算能量师购买？
+3. **C端会员推广家庭套餐**：C端会员推荐朋友买家庭套餐，C端会员能否拿一级佣金？（方案：可以）
+4. **能量师团队是否包含其他能量师**：能量师A的下级B也成为能量师，B的销售是否计入A的团队？（方案：是，直接下级全部计入）
+5. **超级会员暂缓**：超级会员的一级佣金比例和团队分红是否和能量师相同？（建议不同，待上线时定）

docs/phase1-user-stories.md

@@ -2904,13 +2904,18 @@ dify:
 
 ### C.1 概览
 
-| | 普通用户 | C端年费用户 | **超级会员** | 能量师用户 |
-|--|---------|------------|-------------|-----------|
-| **年费** | ¥0 | ¥131 | **¥1,314（固定）** | ¥1,314（种子）/ ¥1,986（标准） |
-| **数据库标记** | `vipType=NULL` | `vipType='annual'` | **`vipType='super_annual'`** | `vipType='practitioner'` |
-| **到期降级** | — | → 普通用户 | → 普通用户 | → 普通用户 |
-| **续费价格** | — | 标准价 ¥131 | 标准价 ¥1,314（固定价） | 标准价 ¥1,986（种子价仅限创始人码首次购买） |
-| **定位** | 浏览体验 | 给自己看，轻度社交 | **关系能量分析 + 自用** | 给客户看，商业工具 |
+| | 普通用户 | C端年费用户 | **家庭套餐** | **超级会员（暂缓）** | 能量师用户 |
+|--|---------|------------|-------------|-------------------|-----------|
+| **年费** | ¥0 | ¥131 | **¥686** | **¥1,314（暂缓上线）** | ¥1,314（种子）/ ¥1,986（标准） |
+| **数据库标记** | `vipType=NULL` | `vipType='annual'` | **`vipType='family_plan'`** | `vipType='super_annual'`（预留） | `vipType='practitioner'` |
+| **到期降级** | — | → 普通用户 | → 普通用户 | → 普通用户（上线后） | → 普通用户 |
+| **续费价格** | — | 标准价 ¥131 | 标准价 ¥686 | 标准价 ¥1,314（固定价） | 标准价 ¥1,986 |
+| **定位** | 浏览体验 | 给自己看，轻度社交 | **家庭关系能量分析** | 待定（后续能量包） | 给客户看，商业工具 |
+| **可咨询人数** | 3人 | **9人** | **9人** | 9人（暂缓） | 不限 |
+| **每人聊天次数** | 3次/天 | **不限** | **不限** | 不限（暂缓） | 不限 |
+| **关系能量分析** | ❌ | ❌ | **✅** | ✅（暂缓） | ✅ |
+| **八星号码分析** | ❌ | ❌ | ❌ | ✅（暂缓） | ✅ |
+| **推广佣金** | ❌ | ✅ | **✅** | ✅（暂缓） | ✅（固定金额） |
 
 ### C.2 功能权限总表