Преглед на файлове

docs(cf): 设计定稿 F02 口径裁决 A 落盘(§1.6/§9-7/测试#15 转正,实现阻塞解除)

Agnes Agent преди 2 дни
родител
ревизия
8752c95f6e
променени са 1 файла, в които са добавени 11 реда и са изтрити 13 реда
  1. 11 13
      docs/superpowers/plans/2026-11-14-cf-reward-model-v2-design.md

+ 11 - 13
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-11-14-cf-reward-model-v2.md`(dc04a6b4c,需求已裁决)
 > 设计基线:`2026-10-24-cf-value-unification-plan.md` + 现行代码实证
 > 设计基线:`2026-10-24-cf-value-unification-plan.md` + 现行代码实证
-> 产出者:架构师(software-architect)| 2026-11-14 14:58 主理人+廖总口径修订(分润基数=扣减后可分配额 base;R3 移出分润体系;通道语义命名)| 状态:**§9 第 7 项(F02 实现口径)待用户裁决,实现暂缓**
+> 产出者:架构师(software-architect)| 2026-11-14 14:58 主理人+廖总口径修订(分润基数=扣减后可分配额 base;R3 移出分润体系;通道语义命名);F02 实现口径 2026-11-14 裁决方案 A(比例返利 1%)| 状态:**设计定稿,可进入实现排期**
 
 
 ## 0. 重大发现:现存 ProfitPoolService 旧体系须处置(先读)
 ## 0. 重大发现:现存 ProfitPoolService 旧体系须处置(先读)
 
 
@@ -84,17 +84,15 @@ base = A − R0 − R1_等值 − C'                   // 扣减同理
 | R3 | (非分润) | 分享注册 +20CF/日限10,**已移出分润体系**,不参与订单分账 |
 | R3 | (非分润) | 分享注册 +20CF/日限10,**已移出分润体系**,不参与订单分账 |
 | — | 平台留存 | base 分出后 + 成本侧切池后的余额 |
 | — | 平台留存 | base 分出后 + 成本侧切池后的余额 |
 
 
-### 1.6 ⚠ F02 现状实现校准(**待用户裁决**,阻塞 base 数值落地)
-| 项 | 现状实现 | 本模型要求 |
+### 1.6 F02 现状实现校准(**已裁决方案 A**:改比例返利 1%)
+| 项 | 现状实现(裁决前) | 本模型要求(裁决后) |
 |---|---|---|
 |---|---|---|
-| F02 种子 | `formula = floor(amt)`,`params = {cf_per_yuan:100, amt_unit:cent}` | R1 等值成本 = floor(A/100) 分(实付 200 元 → 200 CF ≈ 2 元) |
-| 换算实现 | `CfBalanceServiceImpl.applyAmountUnitConversion`:`amt(分) × cf_per_yuan/100 = 分→CF 1:1` | 实付 200 元(20000 分)→ **返 200 CF** |
-| 实际结果 | 实付 200 元 → 发放 **20000 CF = 200 元等值**(记账式全额返) | 20000 CF 是要求的 200 CF 的 **100 倍** |
+| F02 种子 | `formula = floor(amt)`,`params = {cf_per_yuan:100, amt_unit:cent}` | `formula = floor(amt × bps/10000)`,`params = {cf_return_bps:100}`(1%) |
+| 换算实现 | `CfBalanceServiceImpl.applyAmountUnitConversion`:`amt(分) × cf_per_yuan/100 = 分→CF 1:1` | 实付 200 元(20000 分)→ **返 200 CF**(2 元等值) |
+| 实际结果 | 实付 200 元 → 发放 **20000 CF = 200 元等值**(记账式全额返,为要求的 100 倍) | R1 等值成本 = floor(A × 100 / 10000) 分 = 2 元 = **200 CF** |
 
 
-**不校准则模型不成立**:若 F02 维持全额等值,base = 200 − 20 − 200 − 100 = **−120 < 0** → 推荐人无奖。
-**建议方案 (A)**:F02 改为**比例返利** —— `formula = floor(amt × bps/10000)`,`params.cf_return_bps = 100`(1%)→ 实付 200 元返 200 CF(2 元等值),base = 78 成立;返利比例由管理端 `CfRuleConfig` 可调(新增 `cf_return_bps` 参数)。
-**连带核对**:F18(代码注释"与 F02 同口径")、F06(1990 CF 口径)是否需同步调整;已发放历史 CF 余额不在本次追溯范围。
-备选 (B):保留 F02 全额等值、base 不扣 R1 → base = 80(与用户 78 口径不符);备选 (C):全额等值 + base 扣 R1 → base<0,不成立。
+**裁决(廖总 2026-11-14)**:采用 **方案 A —— F02 改比例返利**,`cf_return_bps = 100`(1%)→ 实付 200 元返 200 CF(2 元等值),**base = 78 成立**;返利比例由管理端 `CfRuleConfig` 可调(新增 `cf_return_bps` 参数)。备选 B / C 已否决(B:base = 80 与 78 口径不符;C:base = −120 不成立)。
+**连带核对(2026-11-14 已核)**:F18「健康启航计划付费」代码注释明确「与 F02 同口径」→ **须同步改比例返利**(`floor(amt × bps/10000)` + `cf_return_bps=100`),纳入 T05 实现项;F06「菌群健康调研打卡返还」为项目价全额返还语义(19.9 元=1990 CF,退款式),**不受牵连**、维持 `floor(amt)`;基础汇率 `cf.rate.cf_per_yuan=100`(1 元=100 CF)全局不动,仅 F02/F18 公式参数变更;已发放历史 CF 余额不在本次追溯范围。
 
 
 ---
 ---
 
 
@@ -321,7 +319,7 @@ P0 文件交集标注:T01 与 P0 冲突面最大(DatabaseInitializer/schema.
 6. **亏损仓语义**:团队池从成本切出,亏损单仍发池(默认 payout)可能造成商家亏损加倍——配置 on_loss=zero 可关(已裁决 payout)。
 6. **亏损仓语义**:团队池从成本切出,亏损单仍发池(默认 payout)可能造成商家亏损加倍——配置 on_loss=zero 可关(已裁决 payout)。
 7. **单位口径**:直推/间推/团队池以 CF 发放(1 分 = 1 CF 参照)、平台抽成为货币分、消费返 CF 为 CF——财务对账按类型区分,避免把 CF 当货币分合计。
 7. **单位口径**:直推/间推/团队池以 CF 发放(1 分 = 1 CF 参照)、平台抽成为货币分、消费返 CF 为 CF——财务对账按类型区分,避免把 CF 当货币分合计。
 8. **~~"成交价"口径~~(已裁决)**:平台抽成基数 = 实付(paidAmountCent)。
 8. **~~"成交价"口径~~(已裁决)**:平台抽成基数 = 实付(paidAmountCent)。
-9. **⚠ F02 现状口径校准(阻塞项,见 §1.6)**:现状 F02 = floor(实付分) CF(实付 200 元 → 20000 CF = 200 元等值,全额记账式返),与本模型要求的 R1 等值成本 2 元差 100 倍;不改则 base = −120、模型不成立 → 需用户裁决是否改为比例返利(建议 `cf_return_bps=100`,1%)。
+9. **F02 现状口径校准(已裁决方案 A,见 §1.6)**:F02 改为比例返利 `cf_return_bps=100`(1%)→ 实付 200 元返 200 CF,base = 78 成立;F18 同步改 1%(注释「与 F02 同口径」),F06 维持全额返还不动;已发放历史 CF 余额不在追溯范围。
 10. **⚠ 结算顺序与事务一致性(新增)**:base 依赖 R0 与 R1 先算出,若 R1 发放失败必须整体回滚——settle 全链必须同一事务;现状 earnBuyerCf 内部若 try-catch 吞异常(现状存在 log.error 后继续的写法),须改为抛出以触发回滚,否则会出现"已返 CF 但 base 按未返计算"的错账。实现时需核查 earnBuyerCf 的异常处理。
 10. **⚠ 结算顺序与事务一致性(新增)**:base 依赖 R0 与 R1 先算出,若 R1 发放失败必须整体回滚——settle 全链必须同一事务;现状 earnBuyerCf 内部若 try-catch 吞异常(现状存在 log.error 后继续的写法),须改为抛出以触发回滚,否则会出现"已返 CF 但 base 按未返计算"的错账。实现时需核查 earnBuyerCf 的异常处理。
 
 
 ---
 ---
@@ -344,7 +342,7 @@ P0 文件交集标注:T01 与 P0 冲突面最大(DatabaseInitializer/schema.
 | 12 | 非商品订单进池 | 会员/订阅单:池 = 实付 × 50%(non_goods_cost_rate) × 30%,base = 实付 − R0 − R1 − 非商品成本,创建 cf_team_pool_order 并瓜分 |
 | 12 | 非商品订单进池 | 会员/订阅单:池 = 实付 × 50%(non_goods_cost_rate) × 30%,base = 实付 − R0 − R1 − 非商品成本,创建 cf_team_pool_order 并瓜分 |
 | 13 | R3 不参与分账 | 订单 settle 后无 F24 产出;分享注册仅由注册链路独立触发 |
 | 13 | R3 不参与分账 | 订单 settle 后无 F24 产出;分享注册仅由注册链路独立触发 |
 | 14 | 并发回调 | 两线程同时 settle 同订单,恰一张池单、全部发放一次 |
 | 14 | 并发回调 | 两线程同时 settle 同订单,恰一张池单、全部发放一次 |
-| 15 | ⚠ F02 比例返利(待 §1.6 裁决) | 若裁决 A:实付 200 元返 200 CF;断言 cf_earn_rule F02 formula/params 变更后 earnByRule 数量正确 |
+| 15 | F02 比例返利(已裁决 A) | 实付 200 元返 **200 CF**(`cf_return_bps=100`);断言 cf_earn_rule F02 formula/params 变更后 earnByRule 数量正确;F18 同步 1%;F06 维持全额返还不动 |
 
 
 ---
 ---
 
 
@@ -358,6 +356,6 @@ P0 文件交集标注:T01 与 P0 冲突面最大(DatabaseInitializer/schema.
 | 4 | R0 平台抽成"成交价"基数 | **实付价**(paidAmountCent,与现状传参一致) | 廖总拍板 |
 | 4 | R0 平台抽成"成交价"基数 | **实付价**(paidAmountCent,与现状传参一致) | 廖总拍板 |
 | 5 | 分润基数口径 | **扣减后可分配额 base = 实付 − R0 − R1_等值 − 成本**(示例 78,不是毛利 100);平台抽成与消费返 CF 都是先扣成本 | 廖总 2026-11-14 14:58 纠正(§1.1 已更新) |
 | 5 | 分润基数口径 | **扣减后可分配额 base = 实付 − R0 − R1_等值 − 成本**(示例 78,不是毛利 100);平台抽成与消费返 CF 都是先扣成本 | 廖总 2026-11-14 14:58 纠正(§1.1 已更新) |
 | 6 | 分享注册(+20CF)归属 | **移出分润体系**,独立获客激励不参与订单分账 | 廖总 14:58 纠正(测试 #13 已更新) |
 | 6 | 分享注册(+20CF)归属 | **移出分润体系**,独立获客激励不参与订单分账 | 廖总 14:58 纠正(测试 #13 已更新) |
-| 7 | ⚠ F02 消费返 CF 实现口径 | **待裁决**(阻塞):现状 floor(实付分)=全额等值(20000 CF/200元),本模型要求 R1=200 CF(2元)→ 建议改比例返利 `cf_return_bps=100` | 待廖总裁决(§1.6 已列 A/B/C 方案) |
+| 7 | F02 消费返 CF 实现口径 | **已裁决方案 A**(2026-11-14):改比例返利 `cf_return_bps=100`(1%)→ 实付 200 元返 200 CF(2 元),base=78 成立;备选 B(base=80)/ C(base=−120)否决 | 廖总裁决 A(§1.6 已更新) |
 
 
 设计定稿,可进入实现排期(等 P0 合入后另开 `feature/reward-v2` worktree)。
 设计定稿,可进入实现排期(等 P0 合入后另开 `feature/reward-v2` worktree)。