docs(分润): v0.6.1 #15团队直推定义拍板——直接邀请加入团队+成交首个服务/商品单=1个直推(载体团队树,首单即算无金额门槛)

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

@@ -1,10 +1,10 @@
 # 推荐人分润 & 团队分润双体系设计
 
-> **版本**：v0.6（新增「升级双门槛：每次升级必须直推一个」+ #12/#13/#14 拍板落地，待评审）
+> **版本**：v0.6.1（#15 团队直推定义拍板落地：直接邀请加入团队 + 成交首个服务/商品单）
 > **日期**：2026-11-07
 > **作者**：研发负责人
 > **状态**：🟡 待评审
-> **修订**：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 按推荐落地。
+> **修订**：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 按推荐落地。v0.6.1：#15 **团队直推定义**拍板——直接邀请加入团队 + 成交首个服务/商品单即算 1 个直推（载体=团队树非推荐人树，首单即算无金额门槛）。
 
 ---
 
@@ -200,15 +200,15 @@ CfCommissionService.settle / settleReferrerOnly
 
 **升级双门槛（主理人意见⑥：每次升级必须直推一个）**
 
-星级升降不仅看业绩分，还需满足「**滚动 12 个月内直推有效新用户 ≥1**」这一带新门槛——保证团队成员持续为平台引入新人，而非只吃老客户红利。升级条件 = **业绩分 ≥ 目标档门槛 AND 本窗口直推有效新用户 ≥ 1**。两个条件缺一不可。
+星级升降不仅看业绩分，还需满足「**滚动 12 个月内团队直推 ≥1**」这一带新门槛——保证团队成员持续为平台引入新人，而非只吃老客户红利。升级条件 = **业绩分 ≥ 目标档门槛 AND 本窗口团队直推 ≥ 1**。两个条件缺一不可。（**团队直推定义**：直接邀请加入团队 + 成交首个服务/商品单 = 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） |
+| 直推有效新用户 | 本人**直接邀请加入团队**（团队树 `distribution_relations` level=1 子节点，§5 团队邀请）中，近 12 个月**成交首个服务或商品单**的成员数 | `distribution_relations`（level=1，邀请人=本人）+ `product_orders`/`service_settlements`（成员**首笔成交**）；**首单即算，无金额门槛**（阈值键 `team_profit.valid_new_ref_min_order_cent` 默认 0，防刷预留） |
 | 判定规则 | `score >= tier_threshold AND direct_valid_new_refs >= 1` 才允许升级；两条件均不满足维持当前或降级 | 计算组件 `StarScoreCalculator.isPromotable(userId, targetStar)` |
 
-> ⚠️ 设计备注：**直推门槛随滚动窗口滑出也会消失**（与业绩分同口径）。若某成员曾直推 1 人助其升到 4 星，半年后该直推人退户窗口滑出 → 当次升级周期若没有新的直推有效新用户，业绩分虽够但直推条件不满足 → **无法升级到下一星**（只能维持当前档或自然降级），直到再次直推有效用户进入窗口。这强化「持续带新」导向。
+> ⚠️ 设计备注：**团队直推门槛随滚动窗口滑出也会消失**（与业绩分同口径）。若某成员曾直推 1 人助其升到 4 星，半年后该直推人退户窗口滑出 → 当次升级周期若没有新的团队直推，业绩分虽够但直推条件不满足 → **无法升级到下一星**（只能维持当前档或自然降级），直到再次直推有效成员进入窗口。这强化「持续带新」导向。
 
 **重评机制**：
 - **周期**：每月 1 日 00:30 定时重评（`team_star_snapshot` 落快照），或按订单支付时**实时计算**（推荐：订单结算时实时算，避免月快照滞后）。
@@ -225,7 +225,7 @@ CfCommissionService.settle / settleReferrerOnly
 
 **① 实时星级看板（用户端小程序「我的星级」页）**
 - 当前星级（大字）+ 业绩分总分 + 距下一星差距（如「距四星还差 12,000 分」）。
-- **升级双门槛进度**（两条件并列展示）：① 业绩分 `72,000 / 70,000` ✓；② 直推有效新用户 `2 / 1` ✓（或 `0 / 1` ✗ 并提示「升级还差 1 个直推新用户」）。两条件**分项打勾**，避免「分够了却升不了」的困惑。
+- **升级双门槛进度**（两条件并列展示）：① 业绩分 `72,000 / 70,000` ✓；② 团队直推 `2 / 1` ✓（或 `0 / 1` ✗ 并提示「升级还差 1 个团队直推，去邀请好友加入团队并完成首单」）。两条件**分项打勾**，避免「分够了却升不了」的困惑。直推口径 = §4.3 团队树首单，**非推荐人树**。
 - 三维构成条：直接服务 / 团队服务 / 推荐消费三条进度条，各自贡献分与占比（如 50,000 / 20,000 / 2,000 = 72,000）。
 - 滚动窗口说明：统计期「近 12 个月」（如 2025-11-08 ~ 2026-11-07）。
 - 星级轨迹：近 12 个月星级曲线（读 `team_star_snapshot` 月度快照），直观看到升降与稳定性。
@@ -620,7 +620,7 @@ profit_pool_order(status=pending)  ← 计算 D/T/8份池/团队奖（幂等）
 | 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` |
+| 15 | **团队直推定义**（升级双门槛配套）：什么算 1 个直推 | ✅ 已拍板：**直接邀请加入团队 + 成交首个服务或商品单**即算 1 个直推（载体=团队树 `distribution_relations` level=1，非推荐人树；**首单即算、无金额门槛**） |
 
 ---
 
@@ -629,7 +629,7 @@ 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）**：冷静期结算、月度星级重评（含**升级双门槛校验**：业绩分 + 直推有效新用户 ≥1，见 §4.3）、退款冲正。
+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 ①②。