Parcourir la source

test: add RED contract test for cf.rewardv2.platformTake (S-cfc-395)

Agnes Agent il y a 3 jours
Parent
commit
78d07f438e

+ 303 - 0
cfc-backend/src/test/java/com/etotem/cfc/unit/CfRewardV2PlatformTakeContractTest.java

@@ -0,0 +1,303 @@
+package com.etotem.cfc.unit;
+
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Test;
+
+import java.lang.reflect.Method;
+import java.lang.reflect.Modifier;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+import static org.junit.jupiter.api.Assertions.fail;
+
+/**
+ * 契约级单测:CF 分润模型 v2 平台抽成记账与可分配额计算(能力键 {@code cf.rewardv2.platformTake},TDD-RED 阶段)。
+ *
+ * <p><b>契约溯源(T03:R0 平台抽成记账 + base 计算)</b></p>
+ * <ul>
+ *   <li>需求:{@code docs/superpowers/plans/2026-11-14-cf-reward-model-v2.md} §3.1(平台抽成 = 实付 × 10%,
+ *       {@code cf.platform.take_rate_bps} 默认 1000,独立入平台流水)+ §5 待实现清单 #2(结算链路分叉)</li>
+ *   <li>设计:{@code docs/superpowers/plans/2026-11-14-cf-reward-model-v2-design.md}
+ *       §6-T03({@code settlePlatformTake} + {@code cf_platform_revenue_log} + {@code calcDistributableBase(A, costCent)})、
+ *       §1.1(账目公式:{@code R0 = floor(A×TAKE_BPS/10000)}、{@code base = A − R0 − R1_等值 − costCent}、
+ *       {@code R1_等值 = floor(A/100)}、{@code base<0 时按 0})、§2.4(cf_platform_revenue_log 表,uk_order 幂等)、
+ *       §3.1(结算顺序:① 平台抽成 → ② 消费返 CF → ③ base 计算 → ④ 直推/间推 → ⑤ 团队池)</li>
+ *   <li>任务编排键:T03 对应 {@code cf.rewardv2.r0.platform-take} / {@code cf.rewardv2.r0.idempotent} /
+ *       {@code cf.rewardv2.base.calc};本测试以任务键 {@code cf.rewardv2.platformTake} 覆盖三者。</li>
+ * </ul>
+ *
+ * <p><b>被校验的契约行为(T03 范围)</b></p>
+ * <ul>
+ *   <li><b>R0 平台抽成记账</b>:{@code CfCommissionService.settlePlatformTake(...)}(§3.1,新增)——按
+ *       {@code floor(实付 × TAKE_BPS / 10000)}(TAKE_BPS=1000 → 10%)写入 {@code cf_platform_revenue_log},
+ *       唯一键 {@code uk_order(order_type, order_id)} 幂等;实付为 null 时回退 orderAmountCent。</li>
+ *   <li><b>可分配额 base 计算</b>:{@code CfCommissionService.calcDistributableBase(A, costCent)}(§3.1,T03 交付)——
+ *       {@code base = A − R0 − R1_等值 − costCent},其中 {@code R1_等值 = floor(A/100)}(消费返 CF 等值成本,1 分=1 CF 参照);
+ *       {@code base < 0} 时返回 0(不得为负)。</li>
+ *   <li><b>口径校验(设计 §8 #10)</b>:base 必须先扣 R0 与 R1,{@code ≠ 原始毛利 (A − costCent)};
+ *       账目示例(200/100 例):{@code base = 78 元}。</li>
+ * </ul>
+ *
+ * <p><b>实现现状</b>:本分支 src/main 中 {@code CfCommissionService} 无 {@code settlePlatformTake} /
+ * {@code calcDistributableBase} 方法、无 {@code TAKE_BPS} 常量(§1.1),{@code CfConfigKeys} 无
+ * {@code cf.platform.take_rate_bps},schema.sql 无 {@code cf_platform_revenue_log} 建表。因此本测试以
+ * 「反射结构契约 + 反射行为契约」探测实现缺失:能编译通过、能运行、断言失败(红),且失败断言原文清晰可贴。</p>
+ *
+ * <p><b>GREEN 升级指引</b>:实现者落地 T03 后({@code CfCommissionService} 新增
+ * {@code settlePlatformTake} 与 {@code calcDistributableBase} 方法、{@code TAKE_BPS=1000} 常量、
+ * 建 {@code cf_platform_revenue_log} 表并同步 schema.sql、{@code CfConfigKeys} 播种
+ * {@code cf.platform.take_rate_bps=1000}),本测试自动转绿。</p>
+ *
+ * <p><b>测试范围</b>:纯契约级单测(反射探测 + 数学校验),无 Spring / 无 DB / 无外部服务。
+ * 权限流不适用(R0 平台抽成为订单结算内部链路,无用户权限维度)。</p>
+ */
+class CfRewardV2PlatformTakeContractTest {
+
+    /** 契约宿主:结算服务(§3.1 主改造点)。 */
+    private static final String HOST_CLASS = "com.etotem.cfc.service.CfCommissionService";
+
+    /** §3.1 R0 平台抽成记账方法名(新增)。 */
+    private static final String METHOD_SETTLE_PLATFORM_TAKE = "settlePlatformTake";
+
+    /** §3.1 / §6-T03 可分配额 base 计算方法名(新增,T03 交付)。 */
+    private static final String METHOD_CALC_BASE = "calcDistributableBase";
+
+    /** §1.1 R0 平台抽成费率常量(TAKE_BPS=1000 → 10%)。 */
+    private static final String CONST_TAKE_BPS = "TAKE_BPS";
+
+    /** §4 配置键:平台抽成费率(bps,默认 1000)。 */
+    private static final String CONFIG_KEY_TAKE_RATE_BPS = "cf.platform.take_rate_bps";
+
+    /** §1.1 默认平台抽成费率(1000bps = 10%)。 */
+    private static final int EXPECT_TAKE_BPS = 1000;
+
+    // ==================== 账目示例锚点(设计 §1.1 / §8 #1、#10;单位:分) ====================
+
+    /** 售价 200 元 = 20000 分。 */
+    private static final int A = 20000;
+    /** 成本 100 元 = 10000 分。 */
+    private static final int COST = 10000;
+
+    /** R0 = floor(20000 × 1000/10000) = 2000 分(20 元)。 */
+    private static final int EXPECT_R0 = 2000;
+    /** R1_等值 = floor(20000/100) = 200 分(2 元,200 CF)。 */
+    private static final int EXPECT_R1_EQUIV = 200;
+    /** base = 20000 − 2000 − 200 − 10000 = 7800 分(78 元)。 */
+    private static final int EXPECT_BASE = 7800;
+    /** 原始毛利 = 20000 − 10000 = 10000 分(100 元)——base 必须先扣 R0/R1,不得等于原始毛利。 */
+    private static final int RAW_GROSS = 10000;
+
+    // ------------------------------------------------------------------
+    // 正常流-1:R0 平台抽成记账入口 settlePlatformTake 应存在(§3.1)
+    // ------------------------------------------------------------------
+
+    @Test
+    @DisplayName("正常流-1:CfCommissionService 应提供 settlePlatformTake 平台抽成记账方法")
+    void commissionService_hasSettlePlatformTake() {
+        Class<?> clazz = loadClass(HOST_CLASS);
+        if (clazz == null) {
+            fail("[cf.rewardv2.platformTake] CfCommissionService 类不存在(§3.1 结算主改造点宿主)。");
+        }
+        boolean found = false;
+        for (Method m : clazz.getDeclaredMethods()) {
+            if (m.getName().equals(METHOD_SETTLE_PLATFORM_TAKE)) {
+                found = true;
+                break;
+            }
+        }
+        assertTrue(found,
+                "[cf.rewardv2.platformTake] CfCommissionService 应提供 " + METHOD_SETTLE_PLATFORM_TAKE
+                        + "(...) 方法:R0 平台抽成 = floor(实付×TAKE_BPS/10000) 写入 cf_platform_revenue_log,"
+                        + "唯一键 uk_order 幂等,实付 null 时用 orderAmountCent(设计 §3.1 / §6-T03)。实现未落地。");
+    }
+
+    // ------------------------------------------------------------------
+    // 正常流-2:可分配额 base 计算 calcDistributableBase 应存在(§3.1 / §6-T03)
+    // ------------------------------------------------------------------
+
+    @Test
+    @DisplayName("正常流-2:CfCommissionService 应提供 calcDistributableBase(A, costCent) 可分配额计算方法")
+    void commissionService_hasCalcDistributableBase() {
+        Class<?> clazz = loadClass(HOST_CLASS);
+        if (clazz == null) {
+            fail("[cf.rewardv2.platformTake] CfCommissionService 类不存在(§3.1 结算主改造点宿主)。");
+        }
+        boolean found = false;
+        for (Method m : clazz.getDeclaredMethods()) {
+            if (m.getName().equals(METHOD_CALC_BASE)) {
+                found = true;
+                break;
+            }
+        }
+        assertTrue(found,
+                "[cf.rewardv2.platformTake] CfCommissionService 应提供 " + METHOD_CALC_BASE
+                        + "(int amountCent, int costCent) 方法:base = A − R0 − R1_等值 − costCent,"
+                        + "R1_等值 = floor(A/100),base<0 按 0(设计 §3.1 / §6-T03 / §1.1)。实现未落地。");
+    }
+
+    // ------------------------------------------------------------------
+    // 正常流-3:R0 费率常量 TAKE_BPS = 1000(§1.1)
+    // ------------------------------------------------------------------
+
+    @Test
+    @DisplayName("正常流-3:CfCommissionService 应声明 TAKE_BPS = 1000 平台抽成费率常量")
+    void commissionService_hasTakeBpsConstant() {
+        Class<?> clazz = loadClass(HOST_CLASS);
+        if (clazz == null) {
+            fail("[cf.rewardv2.platformTake] CfCommissionService 类不存在(§3.1 结算主改造点宿主)。");
+        }
+        try {
+            java.lang.reflect.Field f = clazz.getDeclaredField(CONST_TAKE_BPS);
+            f.setAccessible(true);
+            Object val = f.get(null);
+            assertNotNull(val, CONST_TAKE_BPS + " 常量值不应为 null");
+            int bps = ((Number) val).intValue();
+            assertEquals(EXPECT_TAKE_BPS, bps,
+                    "[cf.rewardv2.platformTake] " + CONST_TAKE_BPS + " 应 = " + EXPECT_TAKE_BPS
+                            + "(1000bps = 10% 平台抽成,设计 §1.1)。实现未落地。");
+        } catch (NoSuchFieldException e) {
+            fail("[cf.rewardv2.platformTake] CfCommissionService 应声明 " + CONST_TAKE_BPS
+                    + " = " + EXPECT_TAKE_BPS + " 常量(R0 平台抽成费率,设计 §1.1 / §4)。实现未落地。");
+        } catch (Exception e) {
+            fail("[cf.rewardv2.platformTake] 读取 " + CONST_TAKE_BPS + " 常量失败:" + e.getMessage());
+        }
+    }
+
+    // ------------------------------------------------------------------
+    // 正常流-4:base 计算数学(§1.1 账目示例 200/100 → base = 78 元)
+    // ------------------------------------------------------------------
+
+    @Test
+    @DisplayName("正常流-4:calcDistributableBase(20000, 10000) 应返回 7800(base=78元,先扣 R0/R1/成本)")
+    void calcDistributableBase_accountingExample_returnsBase() {
+        int base = callCalcBase(A, COST);
+        assertEquals(EXPECT_BASE, base,
+                "[cf.rewardv2.platformTake] base = A − R0 − R1_等值 − costCent = 20000 − 2000 − 200 − 10000"
+                        + " 应 = 7800(78 元,设计 §1.1 账目示例 / §8 #1)。实现未落地。");
+    }
+
+    @Test
+    @DisplayName("正常流-5:base 应先扣 R0/R1,不得等于原始毛利 A − costCent(设计 §8 #10)")
+    void calcDistributableBase_notEqualToRawGross() {
+        int base = callCalcBase(A, COST);
+        assertTrue(base != RAW_GROSS,
+                "[cf.rewardv2.platformTake] base 必须先扣 R0 与 R1 后计算:base = " + base
+                        + " 不得等于原始毛利 " + RAW_GROSS + "(100 元)。设计 §1.1 / §8 #10 口径。实现未落地。");
+    }
+
+    // ------------------------------------------------------------------
+    // 边界流-1:亏损仓 base < 0 → 按 0(不得为负,§1.1 / §1.4)
+    // ------------------------------------------------------------------
+
+    @Test
+    @DisplayName("边界流-1:亏损仓 base<0 应返回 0(不得为负)")
+    void calcDistributableBase_loss_returnsZero() {
+        // A=10000(100元),cost=12000(120元)→ base = 10000−1000−100−12000 = −2100 → 0
+        int base = callCalcBase(10000, 12000);
+        assertEquals(0, base,
+                "[cf.rewardv2.platformTake] 亏损仓 base<0 应按 0(不得为负,设计 §1.1 / §1.4)。实现未落地。");
+    }
+
+    // ------------------------------------------------------------------
+    // 边界流-2:R1_等值 = floor(A/100)(§1.1 先扣项)
+    // ------------------------------------------------------------------
+
+    @Test
+    @DisplayName("边界流-2:base 应先扣 R1 等值 = floor(A/100)(消费返 CF 成本,先扣)")
+    void calcDistributableBase_deductsR1Equivalent() {
+        // A=20000 → R1_等值 = floor(20000/100) = 200 分;若实现未扣 R1,base 会 = 8000(≠7800)
+        int base = callCalcBase(A, COST);
+        assertEquals(EXPECT_R0 + EXPECT_R1_EQUIV + COST + EXPECT_BASE, A,
+                "[cf.rewardv2.platformTake] 守恒校验:A 应 = R0 + R1_等值 + costCent + base"
+                        + "(20000 = 2000 + 200 + 10000 + 7800,设计 §1.1)。实现未落地。");
+    }
+
+    // ------------------------------------------------------------------
+    // 边界流-3:配置键 cf.platform.take_rate_bps 应存在且默认 1000(§4)
+    // ------------------------------------------------------------------
+
+    @Test
+    @DisplayName("边界流-3:CfConfigKeys 应声明 cf.platform.take_rate_bps = 1000 配置键")
+    void cfConfigKeys_hasPlatformTakeRateBps() {
+        try {
+            Class<?> keys = Class.forName("com.etotem.cfc.constant.CfConfigKeys");
+            boolean hasKey = false;
+            for (java.lang.reflect.Field f : keys.getDeclaredFields()) {
+                if (Modifier.isStatic(f.getModifiers()) && f.getType() == String.class) {
+                    f.setAccessible(true);
+                    Object v = f.get(null);
+                    if (CONFIG_KEY_TAKE_RATE_BPS.equals(v)) {
+                        hasKey = true;
+                        break;
+                    }
+                }
+            }
+            assertTrue(hasKey,
+                    "[cf.rewardv2.platformTake] CfConfigKeys 应声明配置键 " + CONFIG_KEY_TAKE_RATE_BPS
+                            + "(R0 平台抽成费率,默认 1000,设计 §4 / §6-T03)。实现未落地。");
+        } catch (ClassNotFoundException e) {
+            fail("[cf.rewardv2.platformTake] CfConfigKeys 类不存在(§4 配置键宿主)。");
+        } catch (Exception e) {
+            fail("[cf.rewardv2.platformTake] 探测 " + CONFIG_KEY_TAKE_RATE_BPS + " 失败:" + e.getMessage());
+        }
+    }
+
+    // ------------------------------------------------------------------
+    // 权限流:R0 平台抽成为订单结算内部链路,无用户权限维度
+    // ------------------------------------------------------------------
+
+    @Test
+    @DisplayName("权限流:R0 平台抽成为结算内部链路,无用户权限维度,权限流不适用")
+    void permissionFlow_notApplicable() {
+        assertTrue(true, "权限流不适用:cf.rewardv2.platformTake 为订单结算内部链路,无用户权限维度。");
+    }
+
+    // ------------------------------------------------------------------
+    // 反射辅助(锚定宿主契约,避免编译期依赖不存在方法)
+    // ------------------------------------------------------------------
+
+    private Class<?> loadClass(String name) {
+        try {
+            return Class.forName(name, false, Thread.currentThread().getContextClassLoader());
+        } catch (ClassNotFoundException e) {
+            return null;
+        }
+    }
+
+    /**
+     * 反射调用 calcDistributableBase(amountCent, costCent)。
+     * 契约方法缺失/宿主缺失时断言失败(红);宿主存在且方法落地后按真实行为断言(绿)。
+     */
+    private int callCalcBase(int amountCent, int costCent) {
+        Class<?> clazz = loadClass(HOST_CLASS);
+        if (clazz == null) {
+            fail("RED[cf.rewardv2.platformTake] 契约宿主 CfCommissionService 未实现(实现未落地):"
+                    + "calcDistributableBase 宿主缺失。");
+        }
+        Method method = null;
+        for (Method m : clazz.getDeclaredMethods()) {
+            if (m.getName().equals(METHOD_CALC_BASE) && m.getParameterCount() == 2) {
+                method = m;
+                break;
+            }
+        }
+        if (method == null) {
+            fail("RED[cf.rewardv2.platformTake] 契约方法 " + HOST_CLASS + "#" + METHOD_CALC_BASE
+                    + "(int,int) 未实现(实现未落地):base = A − R0 − R1_等值 − costCent(设计 §3.1 / §6-T03)。");
+        }
+        try {
+            method.setAccessible(true);
+            Object host = clazz.getDeclaredConstructor().newInstance();
+            Object result = method.invoke(host, amountCent, costCent);
+            if (result instanceof Number) {
+                return ((Number) result).intValue();
+            }
+            fail("契约方法 " + METHOD_CALC_BASE + " 应返回整数,实际 " + result);
+            throw new IllegalStateException("unreachable");
+        } catch (Exception e) {
+            fail("契约方法 " + HOST_CLASS + "#" + METHOD_CALC_BASE + " 调用失败:" + e.getMessage());
+            throw new IllegalStateException("unreachable");
+        }
+    }
+}