docs(分润): v0.6 升级双门槛(业绩分+直推有效新用户>=1) + #12档位入配置/#13/#14按推荐拍板落地

docs/superpowers/specs/2026-11-07-referral-team-profit-sharing.md

@@ -1,10 +1,10 @@
 # 推荐人分润 & 团队分润双体系设计
 
-> **版本**：v0.5（新增「吸引力升级设计」：低利润下的激励放大，借鉴 Enagic 合法精华，待评审）
+> **版本**：v0.6（新增「升级双门槛：每次升级必须直推一个」+ #12/#13/#14 拍板落地，待评审）
 > **日期**：2026-11-07
 > **作者**：研发负责人
 > **状态**：🟡 待评审
-> **修订**：v0.2：① 团队邀请参考家庭邀请（区分已加入/未加入平台）；② 推荐人体系**沿用 CF 值**（现有 F03a/F03b），团队体系**新增货币直接分佣**；③ 补星级量化定义 + 团队奖。v0.3：团队奖池从 T 中切 **20%**（8 份池 = T×80%）。v0.4：星级档位按真实价格校准（0/8千/2.5万/7万/14万/25万）+ **星级透明化与成长可视化**（实时看板 / 差距换算 / 月度简报 / 权益可见，见 §4.3.1）。v0.5：**吸引力升级设计**——单产品利润小下的激励放大（§4.7）：收入管道化 / 星级倍率权重 / 带教里程碑 / 实时可见，借鉴 Enagic 合法精华（不照搬 8 层与终身等级）。
+> **修订**：v0.2：① 团队邀请参考家庭邀请（区分已加入/未加入平台）；② 推荐人体系**沿用 CF 值**（现有 F03a/F03b），团队体系**新增货币直接分佣**；③ 补星级量化定义 + 团队奖。v0.3：团队奖池从 T 中切 **20%**（8 份池 = T×80%）。v0.4：星级档位按真实价格校准 + **星级透明化与成长可视化**（§4.3.1）。v0.5：**吸引力升级设计**（§4.7，借鉴 Enagic 合法精华）。v0.6：**升级双门槛**——每次升级须业绩分达标 **且** 滚动 12 个月直推有效新用户 ≥1（§4.3）；#12 档位入后台配置、#13/#14 按推荐落地。
 
 ---
 
@@ -196,7 +196,19 @@ CfCommissionService.settle / settleReferrerOnly
 | 五星 | ≥ 140,000 | 带教团队负责人（带 3-5 人团队） | 5 |
 | 六星 | ≥ 250,000 | 顶流团队长（带教团队 + 强推荐） | **6（最多）** |
 
-> **📐 档位推演依据（2026-11-07，按真实业务价格校准）**：以成长规划师 **1对1 咨询 ¥500/次**（`DatabaseInitializer` 商品 seed，`growth planner consult`）为主业务单元，业绩分 = 直接×50% + 团队×40% + 推荐×10%。五个典型画像实测业绩分：兼职新规划师（年 20 次+团队 5 次+推荐 5 千）≈ **6,500**；活跃规划师（80+20+2 万）≈ **26,000**；资深规划师（200+80+5 万）≈ **71,000**；带教团队负责人（300+300+10 万）≈ **145,000**；顶流团队长（400+600+20 万）≈ **240,000**。各档门槛取「对应画像略上方」，保证**跳一跳够得着**；其中**六星（25 万）单靠个人直接服务几乎不可达**（纯咨询需约 1000 次/年），必须是「带教团队 + 强推荐」的团队长级——这正是「团队服务好拿得多、多劳多得」的体现。**门槛均可在 `team_profit.star_tiers` 配置，以上为推荐默认值**；若业务起步期体量小，可整体下调（见 §11 待拍板 #12）。
+> **📐 档位推演依据（2026-11-07，按真实业务价格校准）**：以成长规划师 **1对1 咨询 ¥500/次**（`DatabaseInitializer` 商品 seed，`growth planner consult`）为主业务单元，业绩分 = 直接×50% + 团队×40% + 推荐×10%。五个典型画像实测业绩分：兼职新规划师（年 20 次+团队 5 次+推荐 5 千）≈ **6,500**；活跃规划师（80+20+2 万）≈ **26,000**；资深规划师（200+80+5 万）≈ **71,000**；带教团队负责人（300+300+10 万）≈ **145,000**；顶流团队长（400+600+20 万）≈ **240,000**。各档门槛取「对应画像略上方」，保证**跳一跳够得着**；其中**六星（25 万）单靠个人直接服务几乎不可达**（纯咨询需约 1000 次/年），必须是「带教团队 + 强推荐」的团队长级——这正是「团队服务好拿得多、多劳多得」的体现。**门槛均可在 `team_profit.star_tiers` 后台配置**；若业务起步期体量小，可整体下调（见 §11 #12 已拍板）。
+
+**升级双门槛（主理人意见⑥：每次升级必须直推一个）**
+
+星级升降不仅看业绩分，还需满足「**滚动 12 个月内直推有效新用户 ≥1**」这一带新门槛——保证团队成员持续为平台引入新人，而非只吃老客户红利。升级条件 = **业绩分 ≥ 目标档门槛 AND 本窗口直推有效新用户 ≥ 1**。两个条件缺一不可。
+
+| 指标 | 口径 | 数据来源 |
+|------|------|---------|
+| 业绩分 | 滚动 12 个月加权总分（§4.3 公式） | `service_settlements` × `cf_balance_log(F03a)` × `ppoint_consumption_log` |
+| 直推有效新用户 | 本人 referral_tree level=1 子节点中，近 12 个月完成**首次实付消费**的注册用户数 | `referral_tree` + `product_orders.buyer_id IN (level1 members) AND first_order_at BETWEEN window_start..now`；阈值按 `team_profit.valid_new_ref_min_order_cent` 控制（防白号刷级，默认建议 ≥¥99） |
+| 判定规则 | `score >= tier_threshold AND direct_valid_new_refs >= 1` 才允许升级；两条件均不满足维持当前或降级 | 计算组件 `StarScoreCalculator.isPromotable(userId, targetStar)` |
+
+> ⚠️ 设计备注：**直推门槛随滚动窗口滑出也会消失**（与业绩分同口径）。若某成员曾直推 1 人助其升到 4 星，半年后该直推人退户窗口滑出 → 当次升级周期若没有新的直推有效新用户，业绩分虽够但直推条件不满足 → **无法升级到下一星**（只能维持当前档或自然降级），直到再次直推有效用户进入窗口。这强化「持续带新」导向。
 
 **重评机制**：
 - **周期**：每月 1 日 00:30 定时重评（`team_star_snapshot` 落快照），或按订单支付时**实时计算**（推荐：订单结算时实时算，避免月快照滞后）。
@@ -213,6 +225,7 @@ CfCommissionService.settle / settleReferrerOnly
 
 **① 实时星级看板（用户端小程序「我的星级」页）**
 - 当前星级（大字）+ 业绩分总分 + 距下一星差距（如「距四星还差 12,000 分」）。
+- **升级双门槛进度**（两条件并列展示）：① 业绩分 `72,000 / 70,000` ✓；② 直推有效新用户 `2 / 1` ✓（或 `0 / 1` ✗ 并提示「升级还差 1 个直推新用户」）。两条件**分项打勾**，避免「分够了却升不了」的困惑。
 - 三维构成条：直接服务 / 团队服务 / 推荐消费三条进度条，各自贡献分与占比（如 50,000 / 20,000 / 2,000 = 72,000）。
 - 滚动窗口说明：统计期「近 12 个月」（如 2025-11-08 ~ 2026-11-07）。
 - 星级轨迹：近 12 个月星级曲线（读 `team_star_snapshot` 月度快照），直观看到升降与稳定性。
@@ -604,9 +617,10 @@ profit_pool_order(status=pending)  ← 计算 D/T/8份池/团队奖（幂等）
 | 9 | 保本线口径：用户示例「至少卖 820」为简化口径（800+20）；精确口径含 CF 值 1% 时 ≈809 | 建议采用精确口径 |
 | 10 | F03b 现有上限 20%（CF 值间接销售奖）是否收窄至用户初稿的 10% | 默认不动（沿用 CF 值现状）；如需收窄仅改档位配置 |
 | 11 | 团队邀请落地页：独立新页 vs 复用 `pages/invite/join` | 建议独立页（团队场景信息不同） |
-| 12 | **星级档位推荐值（0 / 8千 / 2.5万 / 7万 / 14万 / 25万）**：已按真实价格校准（¥500/次咨询基准），六星=顶流团队长级（单靠个人直接服务不可达） | 采纳推荐值；业务起步期体量小可整体下调 50%（配置可调） |
-| 13 | **星级透明化范围**：实时看板 + 差距换算 + 月度简报 + 权益可见（§4.3.1）是否全做 | 建议全做（P1：看板+换算必做；P2：简报+权益） |
-| 14 | **吸引力升级范围（§4.7）**：① 收入管道化（会员续费/测评复购/陪跑续订纳入分润）② 星级倍率权重（6星=3.0）③ 带教里程碑奖 ④ 实时可见 | 建议 **①② 必做（P1）** ③④ 随 T7/T8 附带（P2） |
+| 12 | **星级档位推荐值（0 / 8千 / 2.5万 / 7万 / 14万 / 25万）**：已按真实价格校准（¥500/次咨询基准），六星=顶流团队长级 | ✅ 已拍板：**放入后台配置**（`team_profit.star_tiers` 可调，采纳推荐值，起步期可下调） |
+| 13 | **星级透明化范围**：实时看板 + 差距换算 + 月度简报 + 权益可见（§4.3.1） | ✅ 已拍板：**按推荐全做**（P1 看板+换算；P2 简报+权益） |
+| 14 | **吸引力升级范围（§4.7）**：① 收入管道化 ② 星级倍率权重（6星=3.0）③ 带教里程碑奖 ④ 实时可见 | ✅ 已拍板：**按推荐**（①② P1 必做；③④ 随 T7/T8 附带 P2） |
+| 15 | **直推「有效新用户」定义**（升级双门槛配套）：注册即算 vs 注册+首笔实付消费 | 建议「**注册 + 首笔实付 ≥ 产品最低首单阈值**」（防白号刷级），阈值配 `team_profit.valid_new_ref_min_order_cent` |
 
 ---
 
@@ -615,10 +629,10 @@ profit_pool_order(status=pending)  ← 计算 D/T/8份池/团队奖（幂等）
 1. **T1 团队邀请（P0）**：场景 A 注册链路补推荐人绑定钩子 + 场景 B 幂等入团接口 + 落地页/小程序码（参照家庭邀请）。
 2. **T2 后端分润（P0）**：建表（§7.1/7.3/7.4/7.5）+ `ProfitPoolService`（§2 计算）+ `TeamProfitService`（§4 8 份 + 团队奖）+ 配置读取。
 3. **T3 集成（P0）**：6 个订单服务支付成功钩子接入 `ProfitPoolService.settle()`（复用现有 `CfCommissionService.settle` 调用点，同点位并行调用）。
-4. **T4 定时任务（P1）**：冷静期结算、月度星级重评、退款冲正。
-5. **T5 管理端（P2）**：成本价/星级档位/团队门槛/团队奖分档配置 + 分润流水查询与提现审核（复用现有管理端佣金模式）。
+4. **T4 定时任务（P1）**：冷静期结算、月度星级重评（含**升级双门槛校验**：业绩分 + 直推有效新用户 ≥1，见 §4.3）、退款冲正。
+5. **T5 管理端（P2）**：成本价/星级档位（后台配置 #12）/团队门槛/团队奖分档配置 + 分润流水查询与提现审核（复用现有管理端佣金模式）。
 6. **T6 用户端（P3）**：团队成员分润账单、星级展示、团队邀请入口、提现入口。
-7. **T7 星级看板与换算（P1）**：`POST /api/team-star/my-view` + 小程序「我的星级」页（当前星级/三维构成/距下一档差距/三条换算路径/近 12 月轨迹）——§4.3.1 ①②。
+7. **T7 星级看板与换算（P1）**：`POST /api/team-star/my-view` + 小程序「我的星级」页（当前星级/三维构成/距下一档差距/**升级双门槛进度（业绩分✓ + 直推✓）**/三条换算路径/近 12 月轨迹）——§4.3.1 ①②。
 8. **T8 星级简报推送（P2）**：每月 1 日重评后发微信订阅消息（升/降/持平 + 行动建议）——§4.3.1 ③④。
 9. **T9 收入管道化（P1）**：`profit_pool_order` 触发源扩展 membership/subscription/assessment_retest + 续费/复购持续分润——§4.7 杠杆 1。
 10. **T10 星级倍率与里程碑（P1/P2）**：8 份池改星级权重分配（`star_multiplier`）+ 带教里程碑奖（星耀导师）+ 订单完成实时显示本单分润——§4.7 杠杆 2/3/4。