Explorar o código

docs(plans): 分润v2设计定稿——4项裁决回写(旧体系彻底废弃/非商品进池成本率50%/亏损照常发/抽成按实付)

Agnes Agent hai 3 días
pai
achega
0183c49be2
Modificáronse 1 ficheiros con 26 adicións e 18 borrados
  1. 26 18
      docs/superpowers/plans/2026-11-14-cf-reward-model-v2-design.md

+ 26 - 18
docs/superpowers/plans/2026-11-14-cf-reward-model-v2-design.md

@@ -2,7 +2,7 @@
 
 > 需求基线:`2026-11-14-cf-reward-model-v2.md`(dc04a6b4c,需求已裁决)
 > 设计基线:`2026-10-24-cf-value-unification-plan.md` + 现行代码实证
-> 产出者:架构师(software-architect)| 状态:**待主理人/产品确认 §9 四项后进入实现**
+> 产出者:架构师(software-architect)| 状态:**§9 四项已裁决(2026-11-14 主理人+廖总拍板),设计定稿,实现待 P0 合入后排期**
 
 ## 0. 重大发现:现存 ProfitPoolService 旧体系须处置(先读)
 
@@ -16,7 +16,7 @@ worktree 中存在**已在产**的旧团队分润体系,与 v2 新团队池口
 | 调用点 | PaymentService:270、ProductOrderService/MembershipService/AssessmentOrderService/MemberSubscriptionService 多处 + TeamProfitCronTask @Scheduled | 由 CfCommissionService.settle 内新方法承载 |
 | 已核实 | ProfitPoolService.java / TeamProfitService / TeamProfitFlowService / StarScoreCalculator / TeamProfitAdminController / TeamProfitCronTask 均在产 | — |
 
-**结论**:v2 落地时旧 ProfitPoolService 应**加开关停用**(配置 `referral_profit.enabled=false`,调用点内部守卫即可灰度停用),避免"毛利池团队奖 + 成本池团队池"双发。此点需产品确认(是否彻底废弃旧团队分润)。
+**结论**:v2 落地时旧 ProfitPoolService **彻底废弃**(2026-11-14 廖总裁决):删除全部调用点(PaymentService/ProductOrderService/MembershipService/AssessmentOrderService/MemberSubscriptionService)+ TeamProfitCronTask + TeamProfitAdminController + StarScoreCalculator/TeamProfitService/TeamProfitFlowService,4 张旧表**归档只读**(不再写入、历史数据保留)。实现期须先废弃旧体系再启用新团队池,避免"毛利池团队奖 + 成本池团队池"双发。
 
 ---
 
@@ -38,11 +38,12 @@ basePpoints = Σ max(0, allocPaid_i − C_i×qty_i)      // allocPaid_i = A × b
 R2'池        = Σ floor(C_i × qty_i × T_bps / 10000)  // 按行成本加总(新增,无分摊歧义)
 R0/R1        = 整单口径(不按行)
 ```
-### 1.3 非商品订单(会员/订阅/测评/套餐)
+### 1.3 非商品订单(会员/订阅/测评/套餐)—— 2026-11-14 裁决:**进团队池,定义成本模型**
 ```
+非商品成本 C' = A × NCD_BPS / 10000        // NCD_BPS = 非商品成本率(新配置 cf.team_pool.non_goods_cost_rate,默认 5000=50%,待运营定)
 R0 = floor(A×TAKE_BPS/10000);R1 不变;
 R2 沿用 calcOrderPpoints 非商品分支(金额×serviceRateBps),不变;
-R2' = 0(无成本概念,默认不进团队池,需产品确认)
+R2' = floor(C' × T_bps / 10000)             // = A × 50% × 30%,进团队池
 ```
 ### 1.4 边界条件
 | 场景 | 处理 |
@@ -179,21 +180,23 @@ CREATE TABLE IF NOT EXISTS cf_platform_revenue_log (
 - 发放仍走 `CfBalanceService.earnByRule(memberId,"F03c",poolId,{amount:share_cent})`(per_item 由 ctx.amount 驱动)→ 三道闸/幂等自动生效。
 - **单位说明**:R2/R2' 均以 CF 发放(1 分=1 CF 参照,与现状 F03a/b 一致);R0 为货币分入平台账;R1 为 CF。账目示例"金额"在落库语义为分→CF 对照。
 
-### 3.4 旧体系停用(最小侵入)
-- `ProfitPoolService` 加配置 `referral_profit.enabled`(默认 false),所有 settle 入口首行守卫:disabled 时直接 return null(幂等不破坏);CronTask 同样守卫。
-- 调用点(PaymentService:270、ProductOrderService、MembershipService、AssessmentOrderService、MemberSubscriptionService)**不改代码**,仅靠 ProfitPoolService 内部开关灰度停用。
+### 3.4 旧体系废弃(2026-11-14 裁决:彻底废弃)
+- 删除调用点:PaymentService:270、ProductOrderService、MembershipService、AssessmentOrderService、MemberSubscriptionService 中的 ProfitPoolService 注入与调用。
+- 删除 TeamProfitCronTask(@Scheduled)、TeamProfitAdminController、TeamProfitService/TeamProfitFlowService/StarScoreCalculator 及相关 entity/mapper(如无其他引用)。
+- 4 张旧表(profit_pool_order/team_share_record/team_award_record/team_star_snapshot)**归档只读**:不 DROP(历史数据保留),首页面仅可查。
+- 废弃顺序:先删调用点/任务(一次性提交)→ 验证 profit_pool_order 不再新增 → 再删管理端/服务类 → 归档表。
 
 ---
 
 ## 4. 配置键(新增,进 CfConfigKeys + DatabaseInitializer.seedCfServiceConfig)
 | 键 | 默认 | 类型 | 说明 |
 |----|------|------|------|
-| `cf.platform.take_rate_bps` | 1000 | int | R0 平台抽成(成交价 10%) |
+| `cf.platform.take_rate_bps` | 1000 | int | R0 平台抽成(成交价 10%,基数=实付) |
 | `cf.team_pool.enabled` | true | bool | 团队池总开关 |
 | `cf.team_pool.default_t_bps` | 3000 | int | GLOBAL 兜底 T(30%) |
-| `cf.team_pool.on_loss` | payout | string | 亏损仓是否仍发(payout/zero) |
+| `cf.team_pool.on_loss` | payout | string | 亏损仓照常发(2026-11-14 裁决;可选 zero) |
 | `cf.team_pool.max_depth` | 8 | int | 池瓜分最大层级(默认 8) |
-| `referral_profit.enabled` | false | bool | 旧 ProfitPoolService 停用开关 |
+| `cf.team_pool.non_goods_cost_rate` | 5000 | int | 非商品成本率(bps,默认50%),用于非商品订单进池(2026-11-14 裁决) |
 - 播种点:`seedCfServiceConfig()` 内 ensureServiceConfig 追加;CfConfigKeys 静态常量 + FALLBACKS 同步。
 
 ---
@@ -256,13 +259,13 @@ function distributeTeamPool(orderId, orderType, buyerUserId, buyerFamilyId, paid
 
 | 任务 | 内容 | 主要文件 | 依赖 | 能力键(TDD) |
 |------|------|----------|------|----------------|
-| **T01** 配置与迁移(表+键+种子) | 新建 4 表 + F03c 种子 + 6 键播种 + ProfitPoolService 停用开关 | DatabaseInitializer★★、schema.sql★★、CfConfigKeys、CfEarnRuleService 测试 | 无(等 P0 合入) | `cf.rewardv2.config.migrate`、`cf.rewardv2.config.seed` |
+| **T01** 配置与迁移(表+键+种子) | 新建 4 表 + F03c 种子 + 6 键播种(含 non_goods_cost_rate) | DatabaseInitializer★★、schema.sql★★、CfConfigKeys、CfEarnRuleService 测试 | 无(等 P0 合入) | `cf.rewardv2.config.migrate`、`cf.rewardv2.config.seed` |
 | **T02** TeamShareConfigService | 多作用域解析 + 优先级链 + 缓存 | TeamShareConfigService(新)、CfTeamShareConfigMapper(新)、entity.CfTeamShareConfig(新) | T01 | `cf.teamshare.config.resolve`、`cf.teamshare.config.priority` |
 | **T03** R0 平台抽成记账 | settlePlatformTake + cf_platform_revenue_log | CfCommissionService、CfPlatformRevenueLog(新)、PaymentController 依赖不变 | T01 | `cf.rewardv2.r0.platform-take`、`cf.rewardv2.r0.idempotent` |
 | **T04** 团队池建池+结算分叉 | settleTeamPool + 建池幂等 + settle 入口接线 | CfCommissionService、CfTeamPoolOrder(新)、CfTeamPoolOrderMapper(新)、PaymentService★(仅依赖链,无签名变化) | T01,T02 | `cf.teamshare.pool.create`、`cf.teamshare.pool.idempotent` |
 | **T05** 层级树瓜分算法 | distributeTeamPool + share 流水 + 尾差守恒 + 同家庭跳过 | CfCommissionService、CfTeamPoolShare(新)、CfReferralService(复用不改)、CfBalanceServiceImpl(复用不改) | T04 | `cf.teamshare.share.weighted`、`cf.teamshare.share.family-skip`、`cf.teamshare.share.remainder` |
 | **T06** F03c 规则 + 发放接入 | earnByRule("F03c") per_item + 三道闸验证 | CfEarnRuleService、DatabaseInitializer(种子已T01)、CfBalanceServiceImpl(仅验证) | T04 | `cf.rewardv2.f03c.dispatch` |
-| **T07** 旧 ProfitPoolService 停用验证 | enabled=false 灰度、CronTask 守卫、回归 | ProfitPoolService、TeamProfitCronTask、ProfitPoolService 测试 | T01 | `cf.rewardv2.legacy.disable` |
+| **T07** 旧体系废弃清理 | 删除调用点(5处)+CronTask+AdminController+服务类,4旧表归档只读、验证不再新增 | ProfitPoolService、TeamProfitCronTask、TeamProfitAdminController、PaymentService★、ProductOrderService、MembershipService、AssessmentOrderService、MemberSubscriptionService、TeamProfitService/FlowService/StarScoreCalculator | T01 | `cf.rewardv2.legacy.remove`、`cf.rewardv2.legacy.archive` |
 | **T08** 端到端 + 测试矩阵 | 账目示例/多商品/亏损/幂等/回退断言 | CfCommissionServiceTest、PaymentServiceORDRoutingTest★、新 RewardV2E2ETest | T03-T07 | `cf.rewardv2.e2e.example-200-100` 等 |
 
 P0 文件交集标注:T01 与 P0 冲突面最大(DatabaseInitializer/schema.sql)——必须 P0 合入后实现;PaymentService 仅 T04 有依赖引用(不改签名),UserService/application.yml 无交集。
@@ -296,14 +299,19 @@ P0 文件交集标注:T01 与 P0 冲突面最大(DatabaseInitializer/schema.
 | 8 | T=0 / enabled=false | 池不建、不瓜分,R2/R1 照常 |
 | 9 | 尾差守恒 | Σshare_cent == pool_cent(最后一人补齐,无金额蒸发) |
 | 10 | R0 不参与基数 | R0=实付×10% 单列,R2 基数仍为毛利全额(示例中 100 毛利不被抽成 10% 缩小) |
-| 11 | 旧体系停用 | referral_profit.enabled=false 后 ProfitPoolService.settle 返回 null,profit_pool_order 不再新增 |
+| 11 | 旧体系废弃 | 调用点已删、TeamProfitCronTask 已删,profit_pool_order 不再新增;4 旧表数据完整保留可查 |
+| 12 | 非商品订单进池 | 会员/订阅单:池 = 实付 × 50%(non_goods_cost_rate) × 30%,创建 cf_team_pool_order 并瓜分 |
 | 12 | 并发回调 | 两线程同时 settle 同订单,恰一张池单、全部发放一次 |
 
 ---
 
-## 9. 待产品/主理人确认(写入风险,不阻塞设计)
+## 9. 待确认项裁决记录(2026-11-14 已闭环)
 
-1. 旧 ProfitPoolService/团队8份体系是否彻底废弃(默认方案:开关停用、表保留只读)?
-2. 非商品订单是否要进团队池(默认 0)?如需,需定义非商品成本模型。
-3. 亏损仓默认 payout 还是 zero(默认 payout 与"成本切出"语义一致)?
-4. R0 基数"成交价"= 实付还是划线价(默认实付)?
+| # | 待确认项 | 裁决 | 出处 |
+|---|----------|------|------|
+| 1 | 旧 ProfitPoolService/团队8份体系处置 | **彻底废弃**:删调用点+CronTask+管理端+服务类,4 旧表归档只读 | 廖总拍板(本文件 §0/§3.4/T07 已更新) |
+| 2 | 非商品订单是否进团队池 | **进**,成本模型 = 实付 × `cf.team_pool.non_goods_cost_rate`(默认 50%,待运营定) | 廖总拍板(§1.3 已更新) |
+| 3 | 亏损仓团队池发放 | **照常发**(payout,与"从成本切"语义一致) | 廖总拍板 |
+| 4 | R0 平台抽成"成交价"基数 | **实付价**(paidAmountCent,与现状传参一致) | 廖总拍板 |
+
+设计定稿,可进入实现排期(等 P0 合入后另开 `feature/reward-v2` worktree)。