Merge remote-tracking branch 'origin/cfclub' into cfclub

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

@@ -0,0 +1,473 @@
+# 推荐人分润 & 团队分润双体系设计（真金白银利润分账）
+
+> **版本**：v0.1（设计稿，待主理人拍板后转开发）
+> **日期**：2026-11-07
+> **作者**：研发负责人
+> **状态**：🟡 待评审
+
+---
+
+## 0. TL;DR
+
+本次设计在**现有 CF 值统一账本（F02 / F03a / F03b）之外**，新增一套**真金白银（货币）利润分账体系**，用于把「平台留存的销售利润」分给**推荐人**与**平台服务团队（规划师/测评师等）**。两体系**相互独立**，按固定比例切分同一块利润池：
+
+- **推荐人分润体系**：被推荐人消费时，分**平台留存利润的 70%**；内部再按「直接推荐人 / 间接推荐人 / 平台团队奖池 / 深层分红池」四路分配。
+- **团队分润体系**：团队成员（规划师/测评师等平台人员）产生服务收入时，给其上级团队分润，分**平台留存利润的 30%**；按「8 份制 + 一星至六星」分配。
+
+**核心原则（用户拍板）**：两个体系都支持**下级超越上级、多劳多得**——级别与比例均按**滚动业绩动态计算**，业绩涨则级别/份额涨，业绩跌则降，不固化层级绑定。
+
+> ⚠️ **与 CF 值体系边界**：CF 值（平台积分，1 元=100 CF）是**积分奖励**，走 `cf_balance` 账本；本设计是**货币分润**，走独立账本。两者并行不冲突。CF 值固定成本（消费额 1%）作为平台固定支出从利润池中先行扣除（见 §2）。
+
+---
+
+## 1. 现状核查结论（只读，2026-11-07）
+
+| 资产 | 现状 | 可复用性 |
+|------|------|:--------:|
+| `referral_tree`（推荐树物化，8 层） | 已有，`parent_id/member_id/level/path` | ✅ 直接复用 |
+| `user.referrerId / referralCode` | 已有推荐关系 | ✅ 直接复用 |
+| `cf_direct_sales_tier`（按团队 8 层年度 P 点分档） | 已有，最高 70% | ✅ 借鉴档位模型 |
+| `cf_indirect_sales_tier`（按自身年度 P 点分档） | 已有，最高 20% | ✅ 借鉴档位模型 |
+| `ppoint_consumption_log`（滚动一年 P 点聚合源） | 已有，唯一键 order_type+order_id | ✅ 作业绩统计源 |
+| `products.purchase_price`（成本价，分）+ `profit_rate`（bps） | 已有 | ✅ 商品成本载体 |
+| `supply_system.platform_profit_rate`（平台留利 %） | 已有（供应链） | ⚠️ 参考 |
+| `service_config`（CF 通用配置中心） | 已有 | ✅ 配置载体 |
+| `commission_records` / `service_settlements` | 已有 | ⚠️ 只读历史/服务结算 |
+| 旧货币佣金 `CommissionService.settle/settleTwoLevel`、`CommissionDistService.distribute` | 已废弃（@Deprecated / 410 Gone） | ❌ 不复用 |
+
+**关键结论**：
+1. 现有体系已把「货币佣金」**收口为 CF 值积分**（F02 消费人返 + F03a/F03b 两级销售奖），但那是**积分**，不是**现金分润**。用户本次要求的是**现金利润分账**。
+2. 平台留存利润的**成本载体已具备**：商品用 `products.purchase_price`；**服务（咨询/测评）尚无独立成本价字段**，需扩展（见 §6.4）。
+3. 团队规模/等级的旧机制（`cf_rate_tier`、`promotion_tier` R0-R4）**已废弃**，本次「一星至六星」为**全新等级模型**，不复用旧表，新建表（见 §6）。
+4. 推荐树、滚动一年 P 点统计、档位匹配模式均可直接复用，作为「多劳多得」动态计算的数据底座。
+
+---
+
+## 2. 总账模型：单笔订单的利润漏斗
+
+用户示例（规划师咨询 1000 元）走通全链，作为**数学校验基准**：
+
+```
+售价 S = 1000 元（服务/商品成交价）
+  │
+  ├─ 成本价 C = 800 元（平台为该服务/商品设置的成本价，即平台留存基准）
+  │      → 服务提供者（规划师）实得 S - C = 200 元
+  │
+  └─ 平台留存 P = S - C = 200 元
+       ├─ 平台运营成本 10%        = 20 元   （平台留利，不可分）
+       ├─ CF 值固定成本 1%         = 10 元   （消费者消费额 1% 的 CF 值奖励，固定支出）
+       └─ 可分配利润池 D = 170 元  = P × (100% - 10% - 1%)
+            ├─ 推荐人体系 R = D × 70% = 119 元
+            └─ 团队体系   T = D × 30% = 51 元
+```
+
+> **保本校验**：平台至少卖到保本线才不亏。
+> - **简化口径（用户示例口径）**：`保本线 = C + 10%×P`，C=800 时 `800+20=820`——此时平台留存 P=20 恰好覆盖平台运营 10%，但若按 CF 口径（消费额 1%）需再扣除 8.2，严格意义上 820 仍有微量亏损。
+> - **精确口径（含 CF 值成本）**：`D = P - 10%P - 1%S = 0.9(S-C) - 0.01S = 0` → `S = 1.0112C`，C=800 时保本线 ≈ **809**。
+> - **建议**：以精确口径（含 CF 值 1%）为准，保本线按 `1.0112 × 成本价` 显示给运营；待主理人拍板（§10 第 9 项）。
+
+### 2.1 分配公式（一般化，金额单位：分）
+
+设某订单售价 `S`（分），平台成本价 `C`（分），则：
+
+| 项 | 公式 | 说明 |
+|----|------|------|
+| 平台留存 `P` | `S - C` | 平台毛利 |
+| 平台运营 `O` | `round(P × cfg_platform_ops_rate)` | 默认 10% |
+| CF 值成本 `F` | `round(S × cfg_cf_cost_rate)` | 默认 1%（消费额口径） |
+| 可分配池 `D` | `P - O - F` | `D ≤ 0` 则不触发分润（保本线以下） |
+| 推荐人体系 `R` | `round(D × cfg_referral_share)` | 默认 70% |
+| 团队体系 `T` | `round(D × cfg_team_share)` | 默认 30% |
+
+> `R + T = D`。所有比率入 `service_config`（见 §6.6），允许平台按商品/服务类型单独覆盖。
+
+### 2.2 触发条件
+
+- `D > 0` 才进入分润流程；`D ≤ 0`（售价低于保本线）则整单不产生推荐人/团队分润，仅记录。
+- 支持**按商品/服务维度覆盖**比率（如某商品平台留 0 或负毛利时不发）。
+
+---
+
+## 3. 推荐人分润体系（体系一，占可分配池 70%）
+
+### 3.1 内部四路分配
+
+推荐人体系总额 `R`（示例 119 元）内部拆成**四路**，比例默认值如下（全部可配）：
+
+```
+R = 119 元
+ ├─ ① 直接推荐人（L1）   default 60%，上限 70%
+ ├─ ② 间接推荐人（L2）   default 10%，上限 10%
+ ├─ ③ 平台团队奖池        default 20%（固定留存，转入团队普惠/平台团队基金）
+ └─ ④ 深层分红池          default 10%（保底，给推荐层级 > 3 的所有人）
+```
+
+> **数学校验（对照用户原文）**：用户例「170×70%×70%=93.3」——按 `R=119`，直接上限 70% 应为 `119×70%=83.3`（用户笔误为 93.3，已按自洽口径校正，比例均可配，最终以主理人拍板为准）。间接 `119×10%=11.9` 与用户一致。团队奖池 `119×20%=23.8`。
+
+**「最多拿」语义 = 动态档位上限**（见 3.2），未满档部分自动归入④深层分红池，保证四路恒等于 `R`，不超发。
+
+### 3.2 直接推荐人（L1）—— 动态档位，多劳多得
+
+**比例不是固定 70%，而是按直接推荐人的滚动业绩分档**（这是「下级超越上级」的第一抓手）：
+
+| 档位 | 条件（直接推荐人「团队 8 层内滚动一年累计 P 点」） | L1 比例 |
+|:----:|--------------------------------------------------|:------:|
+| D1 | < 5,000 | 50% |
+| D2 | 5,000 – 19,999 | 55% |
+| D3 | 20,000 – 49,999 | 60%（默认） |
+| D4 | 50,000 – 99,999 | 65% |
+| D5 | ≥ 100,000 | **70%（上限）** |
+
+- **数据源**：直接复用 `CfReferralService.getTeamAnnualPpoints(referrerId, 8)`（滚动一年，团队 8 层）。
+- **动态性**：业绩涨 → 档位涨 → 比例涨；业绩跌（滚动窗口滑出）→ 自动降档。**天然支持下级超越上级**：下级团队业绩超过上级时，下级 L1 比例可高于上级，体现多劳多得。
+- 档位阈值表存 `service_config`（`referral.l1_tiers` JSON），允许平台运营调整。
+
+### 3.3 间接推荐人（L2）—— 动态档位，多劳多得
+
+按间接推荐人**自身滚动一年累计消费 P 点**分档（数据源 `CfReferralService.getSelfAnnualPpoints`），上限 10%：
+
+| 档位 | 条件（自身滚动一年 P 点） | L2 比例 |
+|:----:|------------------------|:------:|
+| I1 | < 2,000 | 0% |
+| I2 | 2,000 – 9,999 | 5% |
+| I3 | ≥ 10,000 | **10%（上限）** |
+
+> L2 为 0% 时（间接推荐人不活跃），其份额自动并入④深层分红池，鼓励激活深层网络。
+
+### 3.4 深层分红池（④）—— 推荐层级 > 3 的所有人
+
+**资格**：订单推荐链上 `referral_tree.level >= 4`（即超过 3 层的所有上游推荐人）。
+
+**分配规则**（用户口径，按贡献而非人头）：
+- 池内金额 `B`（= R 剩余，默认 10%，保底）。
+- 每个合格推荐人 `u` 的权重：
+
+```
+w(u) = ( 个人月消费占比 × 70% ) + ( 团队月消费占比 × 30% )
+个人月消费占比   = u 本月在平台消费额 / 全平台本月消费总额
+团队月消费占比   = u 团队（8 层内）本月消费额 / 全平台所有团队本月消费总额
+```
+
+- `u` 应得 = `B × w(u) / Σw`（归一化）。
+- **意义**：把超出两级销售奖的**深层推荐人**也纳入分红，且**按真实消费/团队贡献**分配，而非层级人头——既不构成「三级计酬」，又鼓励做大团队消费。这是「下级超越上级、多劳多得」的第二抓手。
+
+> **注意（合规）**：④分红池按**消费占比**而非层级固定比例分配，属平台对贡献者的分红激励，非层级计酬。仍需法务确认（见 §9 合规红线）。
+
+### 3.5 推荐人体系完整流程
+
+```
+订单支付成功
+  │
+  ▼
+计算 D、R（§2.1）
+  │
+  ├─ 查买家 referral_tree 全链（level 1..n）
+  ├─ 跳过同家庭（D5 规则：同家庭互推不返，向上上溯）
+  │
+  ├─ L1 = 第 1 个非同家庭推荐人 → 按其团队年度 P 点档位拿 ③(上限70%)
+  ├─ L2 = 第 2 个非同家庭推荐人 → 按其自身年度 P 点档位拿 ②(上限10%)
+  ├─ 平台团队奖池 ③ = R × 20%（固定）
+  └─ 分红池 ④ = R - ①实发 - ②实发 - ③（≥保底）
+         │
+         ▼
+     按 §3.4 权重分给 level≥4 的合格推荐人
+  │
+  ▼
+落库：referral_profit_record（逐人逐单，幂等 ref_type+ref_id）
+```
+
+---
+
+## 4. 团队分润体系（体系二，占可分配池 30%）
+
+### 4.1 概念
+
+团队分润分的是**平台留存利润的 30%**（示例 `T = 51` 元），面向**平台服务团队人员**（规划师/测评师等）——即：平台人员产生服务收入时，给其**上级团队成员**分润，鼓励团队带教与裂变。
+
+**核心机制**：
+- **8 份制**：团队佣金池 `T` 固定切成 **8 份**（示例每份 `51/8 = 6.375 ≈ 6.38` 元）。
+- **星级（一星至六星）**：每个团队成员按**滚动业绩**评星，星级决定其**最多拿 6 份**中的份额（1★=1份 … 6★=6份）。
+- **触发门槛**：团队**年度滚动总服务业绩**达到该团队**单独设定的阈值**时，该团队才进入本次分红（每团队阈值独立配置）。
+
+### 4.2 8 份分配（对照用户示例）
+
+用户示例：6 星成员自服务 → `51×6/8 = 38.25`；其引荐人 1 星 → `51×1/8 = 6.38`；引荐人的引荐人（不论星级）→ `51×1/8 = 6.37`（剩余，因 8 份已分完）。
+
+> **分配链路（自上而下）**：服务提供者本人 → 其引荐人（上级） → 引荐人的引荐人（上上级），**最多三层**，共 8 份封顶：
+> - **第 1 层（服务者本人）**：按本人星级拿 `星级份数`（1★=1份…6★=6份）。
+> - **第 2 层（引荐人）**：按引荐人星级拿 `星级份数`（1★=1份…最多 6 份，但受 8 份总额约束）。
+> - **第 3 层（引荐人的引荐人）**：拿**剩余份额**（8 - 前两层已分），不论星级，封顶 1 份的语义（用户「只能拿剩下的」）。
+
+**一般化规则**：
+```
+剩余份数 = 8
+第1层(服务者本人) 分得 min(本人星级, 剩余)；剩余 -= 已分
+第2层(引荐人)     分得 min(引荐人星级, 剩余)；剩余 -= 已分
+第3层(再上级)     分得 剩余（封顶为剩余全部）
+```
+- 若某层无对应人员（如服务者无引荐人），则该层份额**回流**（并入团队奖池或平台，见 §4.4）。
+- 金额 = `T × 份数 / 8`。
+
+### 4.3 星级定义（多劳多得 + 下级超越上级的第三抓手）
+
+**星级**由**滚动加权业绩分**决定，每自然月/季度重评：
+
+```
+业绩分 = 直接服务收入 × 50%
+       + 团队服务收入 × 40%（仅统计「能拿到推荐奖」的服务订单，防止空转）
+       + 推荐用户平台消费收入 × 10%
+```
+
+| 星级 | 业绩分门槛（示例，可配） |
+|:----:|------------------------|
+| 一星 | ≥ 0 |
+| 二星 | ≥ 5,000 |
+| 三星 | ≥ 20,000 |
+| 四星 | ≥ 50,000 |
+| 五星 | ≥ 100,000 |
+| 六星 | ≥ 200,000 |
+
+> **下级超越上级**：星级按业绩滚动计算，**不绑定层级**。下级业绩好 → 可评 6 星 → 自服务拿 6 份；其上级业绩差 → 只评 1 星 → 引荐人只拿 1 份。**下级拿的可以超过上级**，体现多劳多得。
+
+### 4.4 团队门槛与团队归属
+
+- **团队**：以「平台服务人员（规划师/测评师）」为根节点的**服务团队**，团队成员=其服务推荐链（`referral_tree` 8 层内）中**同为平台服务人员**的子集。
+- **触发门槛**：`team_share_threshold`（每团队独立配置，默认由平台运营设置；也可按团队规模动态给）。
+- **团队年度滚动总服务业绩**：该团队所有成员（含本人）**滚动一年**（按服务订单时间）的服务收入合计，数据源 `service_settlements`（或新表 `service_revenue_log`）。
+- **回流规则**：某层无对应人员/未达门槛时，份额回流至**平台团队奖池**（③）用于普惠或下一周期滚动，不私发。
+
+### 4.5 团队体系完整流程
+
+```
+服务订单完成（服务提供者 X 收入确认）
+  │
+  ▼
+计算 T（§2.1）
+  │
+  ├─ 取 X 所属服务团队（X 为根的服务链）
+  ├─ 校验团队年度滚动总服务业绩 ≥ 团队门槛？
+  │     └─ 否 → 本次不进入团队分红，份额回流平台团队奖池
+  ├─ 评 X 星级（§4.3）→ 份数
+  ├─ 评 X 引荐人星级 → 份数
+  ├─ 评 X 引荐人的引荐人 → 剩余份额
+  │
+  ▼
+落库：team_share_record（逐单逐人，幂等 ref_type+ref_id）
+```
+
+---
+
+## 5. 「下级超越上级、多劳多得」机制汇总
+
+| # | 抓手 | 体系 | 机制 | 效果 |
+|:-:|------|:----:|------|------|
+| 1 | L1 动态档位 | 推荐人 | 按团队年度 P 点分档（50%→70%） | 下级团队业绩高 → 比例超上级 |
+| 2 | L2 动态档位 | 推荐人 | 按自身年度 P 点分档（0%→10%） | 不活跃者 0%，份额让渡 |
+| 3 | 分红池按贡献 | 推荐人 | 按个人/团队消费占比分配 | 深层贡献者多劳多得，非人头 |
+| 4 | 星级滚动重评 | 团队 | 业绩分 50/40/10 加权评 1-6 星 | 下级业绩好可评 6 星，超上级 |
+| 5 | 8 份制封顶 | 团队 | 按星级份数，最多 6 份 | 层级固定但份额动态 |
+| 6 | 滚动窗口滑出 | 两者 | 业绩下跌自动降档/降星 | 不躺在历史功劳簿上 |
+
+> **共同底层**：所有比例/星级都从**滚动业绩**（`ppoint_consumption_log` / 服务收入）实时计算，**不固化层级绑定**。这就是「下级超越上级」的本质——不是靠层级身份，而是靠当期真实贡献。
+
+---
+
+## 6. 数据模型与配置
+
+### 6.1 新表：`profit_pool_order`（每单利润池计算明细，幂等）
+
+```sql
+CREATE TABLE profit_pool_order (
+  id BIGINT PRIMARY KEY AUTO_INCREMENT,
+  order_id BIGINT NOT NULL COMMENT '来源订单ID',
+  order_type VARCHAR(32) NOT NULL COMMENT 'product/service/assessment/package/membership/subscription',
+  product_id BIGINT COMMENT '商品/服务ID',
+  amount_cent INT NOT NULL COMMENT '售价S(分)',
+  cost_cent INT NOT NULL COMMENT '平台成本价C(分)',
+  platform_retain_cent INT NOT NULL COMMENT '平台留存P=S-C(分)',
+  ops_cent INT NOT NULL COMMENT '平台运营O(分)',
+  cf_cost_cent INT NOT NULL COMMENT 'CF值成本F(分)',
+  pool_cent INT NOT NULL COMMENT '可分配池D(分)',
+  referral_share_cent INT NOT NULL COMMENT '推荐人体系R(分)',
+  team_share_cent INT NOT NULL COMMENT '团队体系T(分)',
+  status VARCHAR(16) NOT NULL DEFAULT 'pending' COMMENT 'pending/settled/cancelled',
+  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+  settled_at DATETIME,
+  UNIQUE KEY uk_order (order_type, order_id)
+) COMMENT='单笔订单利润池计算明细';
+```
+
+### 6.2 新表：`referral_profit_record`（推荐人分润流水）
+
+```sql
+CREATE TABLE referral_profit_record (
+  id BIGINT PRIMARY KEY AUTO_INCREMENT,
+  order_id BIGINT NOT NULL,
+  order_type VARCHAR(32) NOT NULL,
+  pool_id BIGINT NOT NULL COMMENT '关联profit_pool_order.id',
+  referrer_user_id BIGINT NOT NULL COMMENT '获得分润的推荐人',
+  level INT NOT NULL COMMENT '1=L1直接 2=L2间接 4+=深层分红池',
+  share_cent INT NOT NULL COMMENT '分润金额(分)',
+  rule_code VARCHAR(20) COMMENT 'L1D1..L1D5 / L2I1..L2I3 / POOL',
+  rate_percent INT COMMENT '实际比例(%)',
+  status VARCHAR(16) DEFAULT 'pending' COMMENT 'pending/settled/cancelled',
+  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+  UNIQUE KEY uk_order_ref (order_id, referrer_user_id, level),
+  KEY idx_referrer (referrer_user_id)
+) COMMENT='推荐人分润流水(货币)';
+```
+
+### 6.3 新表：`team_share_record`（团队分润流水）
+
+```sql
+CREATE TABLE team_share_record (
+  id BIGINT PRIMARY KEY AUTO_INCREMENT,
+  order_id BIGINT NOT NULL,
+  order_type VARCHAR(32) NOT NULL,
+  pool_id BIGINT NOT NULL,
+  provider_user_id BIGINT NOT NULL COMMENT '服务提供者(规划师/测评师)',
+  recipient_user_id BIGINT NOT NULL COMMENT '获得分润的团队成员',
+  layer INT NOT NULL COMMENT '1=服务者本人 2=引荐人 3=引荐人的引荐人',
+  star_level INT COMMENT '该成员当前星级(1-6)',
+  shares INT NOT NULL COMMENT '分得份数(0-8)',
+  share_cent INT NOT NULL COMMENT '分润金额(分)',
+  status VARCHAR(16) DEFAULT 'pending' COMMENT 'pending/settled/cancelled',
+  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+  UNIQUE KEY uk_order_rec (order_id, recipient_user_id, layer),
+  KEY idx_recipient (recipient_user_id)
+) COMMENT='团队分润流水(货币)';
+```
+
+### 6.4 扩展：服务成本价载体
+
+商品已有 `products.purchase_price`。**服务（咨询/测评）**需要成本价字段。建议新增表：
+
+```sql
+CREATE TABLE service_cost_config (
+  id BIGINT PRIMARY KEY AUTO_INCREMENT,
+  service_type VARCHAR(32) NOT NULL COMMENT 'planner_consult/assessor_dan/...',
+  service_name VARCHAR(64),
+  cost_cent INT NOT NULL COMMENT '平台成本价C(分)',
+  enabled TINYINT DEFAULT 1,
+  updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+  UNIQUE KEY uk_service (service_type)
+) COMMENT='平台服务成本价配置(货币分润成本载体)';
+```
+
+### 6.5 新表：`team_star_snapshot`（星级与业绩分快照，重评用）
+
+```sql
+CREATE TABLE team_star_snapshot (
+  id BIGINT PRIMARY KEY AUTO_INCREMENT,
+  user_id BIGINT NOT NULL,
+  team_id BIGINT COMMENT '所属服务团队根节点',
+  star_level INT NOT NULL COMMENT '1-6',
+  score INT NOT NULL COMMENT '加权业绩分',
+  direct_rev_cent INT, team_rev_cent INT, referral_consume_cent INT,
+  period VARCHAR(16) NOT NULL COMMENT 'YYYYMM',
+  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+  UNIQUE KEY uk_user_period (user_id, period)
+) COMMENT='团队成员星级月度快照';
+```
+
+### 6.6 配置项（全部入 `service_config`，`group_key='referral_profit'` / `'team_profit'`）
+
+| config_key | 默认值 | 说明 |
+|-----------|:------:|------|
+| `referral_profit.ops_rate` | 10% | 平台运营成本占 P 比例 |
+| `referral_profit.cf_cost_rate` | 1% | CF 值成本占 S 比例 |
+| `referral_profit.referral_share` | 70% | 推荐人体系占 D 比例 |
+| `referral_profit.team_share` | 30% | 团队体系占 D 比例 |
+| `referral_profit.l1_tiers` | JSON | L1 动态档位表（D1-D5） |
+| `referral_profit.l2_tiers` | JSON | L2 动态档位表（I1-I3） |
+| `referral_profit.team_award_rate` | 20% | ③平台团队奖池占 R 比例 |
+| `referral_profit.pool_min_rate` | 10% | ④深层分红池占 R 保底比例 |
+| `referral_profit.pool_weight` | 70/30 | 分红池个人/团队消费权重 |
+| `team_profit.star_tiers` | JSON | 星级业绩分门槛表 |
+| `team_profit.team_threshold` | JSON | 各服务团队年度业绩阈值（teamId→金额） |
+| `team_profit.share_total` | 8 | 8 份制分母 |
+
+---
+
+## 7. 结算周期与状态机
+
+### 7.1 状态机（推荐人体系 / 团队体系共用）
+
+```
+订单支付成功
+   │
+   ▼
+profit_pool_order(status=pending)  ← 计算 D/R/T，幂等（order_type+order_id 唯一）
+   │
+   ▼
+生成 referral_profit_record / team_share_record (status=pending)
+   │
+   ├── 冷静期（7 天，与退款窗口对齐）
+   │       订单退款 → 全部 status=cancelled，金额回流平台
+   │
+   ▼
+冷静期满 → 定时任务批量置 status=settled，入「可提现余额」（货币账本）
+   │
+   ▼
+用户申请提现 → 后台审核 → 打款（复用现有 withdrawal 流程）
+```
+
+### 7.2 冷静期与退款
+
+- 订单支付后 7 天内退款：对应分润记录全部 `cancelled`，资金不发放。
+- 7 天后自动 `settled`，进入可提现余额。
+- 提现：复用 `withdrawal_requests` + 后台审核（`/api/admin/commission/*` 管理端模式）。
+
+### 7.3 幂等与重试
+
+- 唯一键：`profit_pool_order(uk_order)`、`referral_profit_record(uk_order_ref)`、`team_share_record(uk_order_rec)` —— 重复回调不重复发放。
+- 分润计算失败重试：按唯一键 upsert，先删旧记录再重建（或 INSERT IGNORE + 对账）。
+
+---
+
+## 8. 边界情况
+
+| # | 场景 | 处理 |
+|:-:|------|------|
+| 1 | 买家无推荐人 | ①L1/L2 无人 → 份额入③团队奖池；分红池照发（若有深层） |
+| 2 | 同家庭互推（D5） | 跳过同家庭推荐人，向上上溯（复用现有规则） |
+| 3 | `D ≤ 0`（低于保本线） | 整单不分润，仅落 profit_pool_order 供统计 |
+| 4 | 服务提供者无上级/无团队 | 团队体系该层无人 → 份额回流平台团队奖池 |
+| 5 | 团队未达年度业绩门槛 | 本次不进入团队分红，份额回流 |
+| 6 | 同一商品既有商品属性又有服务属性 | 按订单类型路由（product→purchase_price；service→service_cost_config） |
+| 7 | 退款跨冷静期 | 已 settled 的退款需冲正（负数记录或 cancelled + 余额扣减） |
+| 8 | 星级/档位重评时间点 | 以**支付成功时刻**的档位/星级为准（快照），避免回溯争议 |
+
+---
+
+## 9. 合规红线（⚠ 重要）
+
+1. **三级计酬红线**：推荐人体系 L1/L2 固定层仅到二级；深层分红池按**消费占比**分配（非层级提成），从机制上避免「三级以上按人头/层级计酬」。**上线前须法务确认**（对应既有挂起项「分佣机制过法务」）。
+2. **不设入门费**：本设计不涉及任何「交钱入会」准入，纯消费业绩驱动。
+3. **成本价设置须真实**：`service_cost_config`/`purchase_price` 由平台运营真实填写，不得虚增以制造「高额返利」假象。
+
+---
+
+## 10. 待主理人拍板事项
+
+| # | 事项 | 建议 |
+|:-:|------|------|
+| 1 | 用户示例中「170×70%×70%=93.3」校正确认为 83.3（119×70%）；或按「R 内四路 70/10/20 + 分红另计」重算 | 采纳 83.3 校正口径，比例可配 |
+| 2 | L1 是否从固定 70% 改为动态档位（50%→70%） | **建议：动态**（多劳多得，用户原则） |
+| 3 | 分红池个人/团队消费权重 70/30 的统计口径（本月=自然月？） | 自然月，入配置 |
+| 4 | 星级重评周期（月度/季度） | 建议月度 |
+| 5 | 8 份制中第 3 层是否永远 1 份封顶 | 是（用户口径「只能拿剩下的」） |
+| 6 | 团队年度业绩阈值初始值（各团队单独定） | 平台运营配置，先给默认 |
+| 7 | 分润金额提现走既有 `withdrawal_requests` 还是独立账本 | 建议复用，type 标识分润来源 |
+| 8 | 服务成本价表首批服务类型（planner_consult/assessor_dan/...） | 由运营维护 |
+| 9 | 保本线口径：用户示例「至少卖 820」为简化口径（800+20）；精确口径含 CF 值 1% 时 ≈809 | 建议采用精确口径 |
+
+---
+
+## 11. 落地建议（后续派发）
+
+1. **P0 后端**：建表（§6）+ `ProfitPoolService`（§2 计算）+ `ReferralProfitService`（§3）+ `TeamProfitService`（§4）+ 配置读取。
+2. **P0 集成**：6 个订单服务支付成功钩子接入 `ProfitPoolService.settle()`（复用现有 `CfCommissionService.settle` 调用点，同点位并行调用）。
+3. **P1 定时任务**：冷静期结算、月度星级重评、月度分红池结算、退款冲正。
+4. **P2 管理端**：成本价配置、档位/星级配置、团队阈值配置、分润流水查询与提现审核（复用现有管理端佣金模式）。
+5. **P3 用户端**：推荐人/团队分润账单、星级展示、提现入口。

docs/tdd/orchestration/cross-role-kickoff-20261107.md

@@ -0,0 +1,45 @@
+# 跨角色域批次 · 开工包（X 域剩余 8 SC 契约核对）
+
+> 归属：契约补建计划 P0「跨角色域剩余」· 生成 2026-11-07 12:0x（研发负责人 闭环巡检）
+> 数据源：sc-key-map.md（origin/cfclub，O-8 归一后 241 全量登记）· 端点核对：cfc-backend controller 源码（origin/cfclub 工作树）
+> 前置：O-7 裁决（主理人 2026-11-06 23:59 最终确认）契约补建工作流正式生效——契约核对 = 文档核对 + 端点比对（防假 RED），产出契约文档后转测试侧补契约 JUnit + 三类流证据，**渐进而非全量**。
+
+## 批次定位
+
+跨角色域 22 个 SC（SC-X-01~22）中，已由既有开工包覆盖 **13 个**：
+- 测评-方案（EVD-8R）：SC-X-01 / 06 / 09
+- 报告闭环（EVD-7R）：SC-X-02 / 10 / 13
+- 任务-心愿（EVD-3）：SC-X-05
+- 五维能量（EVD-5）：SC-X-19 / 20 / 21
+- 商城-会员（EVD-4）：SC-X-07 / 12
+- 家庭-成员（EVD-2）：SC-X-04
+- CF 值预估（TR-5 独立键）：SC-X-22 已由 `reward.cfEstimate.expectedCf` 实现合入（`f14e46f84`，12 Java 文件）+ 契约合入（`6141c43a2`），**非契约补建批**（测试侧补三类流证据即可）。
+
+**本批 = X 域剩余 8 个 SC（SC-X-03/08/11/14/15/16/17/18）**，端点载体逐条核验，产出契约文档后转测试侧，不建伪实现任务。
+
+## 端点核验（初核候选，会话须逐条核实并回填）
+
+| SC | 场景标题 | 候选端点载体（origin/cfclub 工作树） | 初核 |
+|----|----------|--------------------------------------|------|
+| SC-X-03 | 双角色数据隔离越权 | `family/FamilyMembersController`（成员 CRUD/权限）、`family/TeacherFamilyBindingController`（规划师绑定）、`family/ParentController`（家长视角切换）、`auth/AuthController`（角色切换 switchRole）；越权语义 = 家长/孩子/规划师跨家庭访问须 403 | ✅ |
+| SC-X-08 | 文章发布闭环 | `content/ArticleController` `/api/article/*`（发布/详情）、`content/ArticleCategoryController`（分类）、`content/ArticleCommentController`（评论）、`admin/AdminArticleController` `/api/admin/article/*`（审核）、`admin/ReviewCenterController`（审核中心）；闭环 = 发布→审核→上架→评论 | ✅ |
+| SC-X-11 | 消息通知闭环 | `product/ProductOrderController`（下单通知）、`ActivityOrderController`（报名通知）、`VirtualPayController`（支付通知）、`admin/AdminNotificationTemplateController`（通知模板配置）；闭环 = 事件触发→通知发送→用户已读 | ⚠ 通知发送载体（推送通道）待核实 |
+| SC-X-14 | 解绑/重分配跨角色协同 | `family/BindController`（家庭绑定/解绑）、`family/FamilyInviteController`（邀请重分配）、`CfTransferController`（CF 转移）；协同 = 规划师/成员解绑后数据重分配 | ✅ |
+| SC-X-15 | 注销/数据导出跨角色 | `UserController` `POST /api/user/data-export`（个保法导出，`AccountCleanupService.exportUserData`）+ 注销端点（`AccountCleanupService` 匿名化）；跨角色 = 家长注销后孩子/家庭数据处理 | ✅ |
+| SC-X-16 | 活动名额并发 E2E ⭐ | `ActivityController` `POST /api/activity/register`（名额校验/并发扣减）、`ActivityOrderController`（报名订单）；并发语义 = 同名额多端并发报名须不超发 | ✅ |
+| SC-X-17 | 多端登录会话互斥跨端 | `auth/AuthController` `/api/auth/*`（token 签发/校验）、`auth/WechatWebAuthController`（微信 web 登录）、`JwtInterceptor`（token 互斥/多端单点）；互斥语义 = 同账号多端登录踢下线/互斥 | ⚠ token 互斥实现位置待核实 |
+| SC-X-18 | 推送跨端送达 | `VirtualPayController`（支付结果推送）、微信订阅消息通道（`subscribeMessage`/模板消息，如 `WxTemplateMessageService`/`WeChatSubscribeService`）；跨端 = 小程序/Web/服务端多端送达 | ⚠ 推送通道载体较弱，待核实（可能走 `cfc-langgraph` 或微信开放平台） |
+
+> 注：X-18 初核载体偏弱（仅 VirtualPayController 命中 push 相关），会话须全仓 `grep -rlE "subscribeMessage|templateMessage|pushMessage|sendPush" cfc-backend/src/main/java` + `cfc-langgraph/src` 定位真实推送通道，确无载体的登记为契约缺口（仅登记不实现，回传产品/运维侧确认），不建伪任务。
+
+## 会话要求
+
+1. **端点核对 = 文档核对 + 端点比对**（防假 RED）：逐条用 grep 在 `cfc-backend/src/main/java` 实测定位端点载体，回填上表候选是否成立（✅/⚠/❌），确无载体的登记为契约缺口，不建伪实现任务。⚠ 项须回填实测结论（✅ 成立 / ❌ 缺口 / ⚠ 部分存在）。
+2. **先拉取**：开工前 `git fetch origin cfclub` 并基于 `origin/cfclub` 新建分支 `feature/evd15-cross-role-contract`（独立 worktree，不与主工作树 WIP 冲突）。
+3. **产出 2 文件**：`docs/superpowers/specs/2026-11-07-cross-role-contract.md`（新建）+ `docs/superpowers/api/API_REFERENCE.md` 追加跨角色域契约段（章节号 4.64 起，避开 EVD-9 孩子端 4.61 / EVD-12R2 服务商域 4.62 / EVD-13 家长域 4.63）。
+4. **完成后必须 push**：`git push -u origin feature/evd15-cross-role-contract`，汇报 commit sha 与文件清单。
+5. 不改任何业务代码、不改测试文件、不动 `.tdd/`。
+
+## 交付
+
+契约文档 + API_REFERENCE 增补 + commit sha + 逐 SC 端点核对结论（满足/缺口）。