Explorar o código

test(reward.v2.e2e): S-cfc-400 cf.rewardv2.e2eExample 分润v2 200/100账目示例契约级单测(RED,13红1过)

E2E Test Bot hai 3 días
pai
achega
1e659dbf47

+ 396 - 0
cfc-backend/src/test/java/com/etotem/cfc/unit/RewardV2E2EExampleContractTest.java

@@ -0,0 +1,396 @@
+package com.etotem.cfc.unit;
+
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Test;
+
+import java.io.InputStream;
+import java.lang.reflect.Field;
+import java.lang.reflect.Method;
+import java.lang.reflect.Modifier;
+import java.nio.charset.StandardCharsets;
+import java.util.Scanner;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNotEquals;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+import static org.junit.jupiter.api.Assertions.fail;
+
+/**
+ * 能力键 {@code cf.rewardv2.e2eExample}(任务号 S-cfc-400,TDD-RED 阶段)契约级单测。
+ *
+ * <p>契约溯源:
+ * <ul>
+ *   <li>需求:{@code docs/superpowers/plans/2026-11-14-cf-reward-model-v2.md}
+ *       §3.1 账目示例 + §5-5 测试(200/100 例)+ D4/D5/D8 裁决(base=78、销售奖在 base 上分、
+ *       F02 改比例返利 1%);</li>
+ *   <li>设计:{@code docs/superpowers/plans/2026-11-14-cf-reward-model-v2-design.md}
+ *       §1.1 账目公式 + §5 层级树瓜分 + §6 T08(端到端测试矩阵)+ §8 测试用例 #1(本例)。</li>
+ * </ul>
+ *
+ * <p><b>契约范围</b>:分润 v2 端到端账目验证的 <b>200/100 账目示例</b>(T08 首个矩阵用例)——
+ * 商品售价 200 元({@code A=20000} 分)/ 成本 100 元({@code C=10000} 分)/ 体系
+ * {@code T=30%}(3000bps)/ 直推 70% 档 / 间推 20% 档:</p>
+ * <pre>
+ *   R0  平台抽成   = floor(20000 × 1000 / 10000) = 2000 分 = 20 元
+ *   R1  消费返 CF  = floor(20000 × 100 / 10000)  = 200 CF(等值 200 分 = 2 元,设计 §1.1/§1.6 裁决 A)
+ *   base 可分配额  = 20000 − 2000 − 200 − 10000  = 7800 分 = 78 元   (≠ v1 原始毛利 100 元)
+ *   直推销售奖     = 7800 × 70%  = 5460 分 = 54.6 元
+ *   间推销售奖     = 7800 × 20%  = 1560 分 = 15.6 元
+ *   团队分润池     = floor(10000 × 3000 / 10000) = 3000 分 = 30 元(成本侧切出,不占 base)
+ *   平台留存       = 20000 − 200 − 5460 − 1560 − (10000 − 3000) = 5780 分 = 57.8 元(含 R0)
+ *   校验:R1(200) + 直推(5460) + 间推(1560) + 留存(5780) + 商家自担(7000) = 20000 ✓
+ * </pre>
+ *
+ * <p><b>实现现状</b>:本分支 {@code src/main} 中分润 v2 全部未落地(已核实)——无
+ * {@code calcDistributableBase / settlePlatformTake / settleTeamPool / distributeTeamPool / RULE_TEAM_POOL("F03c")}、
+ * 无 {@code TeamShareConfigService / CfTeamShareConfig / CfTeamPoolOrder / CfTeamPoolShare / CfPlatformRevenueLog}、
+ * {@code schema.sql} 无 4 张 v2 新表、{@code CfConfigKeys} 无 6 个 v2 配置键。因此本测试以
+ * 「反射结构契约」探测实现缺失:能编译、能运行、断言失败(红),且失败断言原文清晰可贴。</p>
+ *
+ * <p><b>GREEN 升级指引</b>:实现者按设计 §6 T01-T07 落地后(T03 交付
+ * {@code calcDistributableBase}、T04 交付 {@code settleTeamPool}、T05 交付
+ * {@code distributeTeamPool}、T01 建表/播种配置键),本测试自动转绿;届时可将
+ * 结构探测升级为行为级 mock 验证(校验账目登账金额)。</p>
+ *
+ * <p><b>权限流说明</b>:本能力为后端内部结算链路(订单支付 → 分润服务),无用户权限维度,
+ * 权限流不适用,以说明性用例标注。</p>
+ */
+class RewardV2E2EExampleContractTest {
+
+    // ---------- 契约目标类 FQCN ----------
+    private static final String CF_COMMISSION_SERVICE = "com.etotem.cfc.service.CfCommissionService";
+    private static final String CF_CONFIG_KEYS = "com.etotem.cfc.constant.CfConfigKeys";
+    private static final String TEAM_SHARE_CONFIG_SERVICE = "com.etotem.cfc.service.TeamShareConfigService";
+    private static final String CF_TEAM_SHARE_CONFIG = "com.etotem.cfc.entity.CfTeamShareConfig";
+    private static final String CF_TEAM_POOL_ORDER = "com.etotem.cfc.entity.CfTeamPoolOrder";
+    private static final String CF_TEAM_POOL_SHARE = "com.etotem.cfc.entity.CfTeamPoolShare";
+    private static final String CF_PLATFORM_REVENUE_LOG = "com.etotem.cfc.entity.CfPlatformRevenueLog";
+
+    // ---------- 200/100 账目示例数学锚点(金额单位:分;CF 单位:CF) ----------
+    /** 实付 200 元(paidAmountCent) */
+    private static final int A = 20000;
+    /** 商品成本 100 元 */
+    private static final int C = 10000;
+    /** R0 平台抽成 = floor(A × 1000 / 10000) = 20 元 */
+    private static final int R0 = 2000;
+    /** R1 消费返 CF = floor(A × 100 / 10000) = 200 CF */
+    private static final int R1_CF = 200;
+    /** R1 等值成本(分) = floor(A / 100) = 2 元 */
+    private static final int R1_CENT = 200;
+    /** base 可分配额 = A − R0 − R1_等值 − C = 78 元(≠ v1 原始毛利 100 元) */
+    private static final int BASE = 7800;
+    /** v1 原始毛利 = A − C = 100 元(base 口径必须与其区分) */
+    private static final int V1_GROSS_MARGIN = 10000;
+    /** 直推销售奖 = base × 70% = 54.6 元 */
+    private static final int DIRECT_CENT = 5460;
+    /** 间推销售奖 = base × 20% = 15.6 元 */
+    private static final int INDIRECT_CENT = 1560;
+    /** 团队分润池 = floor(C × 3000 / 10000) = 30 元 */
+    private static final int POOL_CENT = 3000;
+    /** 平台留存 = A − R1 − 直推 − 间推 − (C − 团队池) = 57.8 元(含 R0) */
+    private static final int RETAIN_CENT = 5780;
+
+    /** 设计 §2/§4 四张 v2 新表 */
+    private static final String[] V2_TABLES = {
+            "cf_team_share_config", "cf_team_pool_order", "cf_team_pool_share", "cf_platform_revenue_log"
+    };
+
+    /** 设计 §4 六个新增配置键(默认值) */
+    private static final String[] V2_CONFIG_KEYS = {
+            "cf.platform.take_rate_bps",      // 1000 = 10%
+            "cf.team_pool.enabled",           // true
+            "cf.team_pool.default_t_bps",     // 3000 = 30%
+            "cf.team_pool.on_loss",           // payout
+            "cf.team_pool.max_depth",         // 8
+            "cf.team_pool.non_goods_cost_rate" // 5000 = 50%
+    };
+
+    // ==================== 正常流:结算入口与结算顺序方法契约(§3.1) ====================
+
+    @Test
+    @DisplayName("正常流-1:CfCommissionService 应提供 v2 结算四入口方法")
+    void cfCommissionService_hasV2SettleMethods() {
+        Class<?> svc = loadClass(CF_COMMISSION_SERVICE);
+        assertTrue(svc != null, "[cf.rewardv2.e2eExample] CfCommissionService 类应存在。");
+
+        // §3.1 T03:base 计算入口(本测试的核心契约锚点)
+        assertTrue(methodExists(svc, "calcDistributableBase", int.class, int.class),
+                "[cf.rewardv2.e2eExample]CfCommissionService 缺少 calcDistributableBase(int A, int costCent):"
+                        + "设计 §3.1 T03 要求 base = A − R0 − R1_等值 − costCent,base<0 按 0。实现未落地。");
+        // §3.1 T03:平台抽成记账入口
+        assertTrue(methodExists(svc, "settlePlatformTake"),
+                "[cf.rewardv2.e2eExample] CfCommissionService 缺少 settlePlatformTake:"
+                        + "设计 §3.1 T03 要求 R0 = floor(A × take_rate_bps / 10000) 写 cf_platform_revenue_log。实现未落地。");
+        // §3.1 T04:团队池建池入口
+        assertTrue(methodExists(svc, "settleTeamPool"),
+                "[cf.rewardv2.e2eExample] CfCommissionService 缺少 settleTeamPool:"
+                        + "设计 §3.1 T04 要求解析 T → 建 cf_team_pool_order(uk_order 幂等)。实现未落地。");
+        // §3.1/§5 T05:层级树瓜分入口
+        assertTrue(methodExists(svc, "distributeTeamPool"),
+                "[cf.rewardv2.e2eExample] CfCommissionService 缺少 distributeTeamPool:"
+                        + "设计 §5 T05 要求层级树+档位权重瓜分(尾差守恒/同家庭跳过)。实现未落地。");
+    }
+
+    @Test
+    @DisplayName("正常流-2:calcDistributableBase(20000, 10000) 应为 78 元(7800 分),≠ v1 毛利 100 元")
+    void calcDistributableBase_200yuan_shouldReturn78yuan() {
+        int base = invokeStatelessInt(CF_COMMISSION_SERVICE, "calcDistributableBase", A, C);
+        assertEquals(BASE, base,
+                "[cf.rewardv2.e2eExample] 200 元实付 / 100 元成本:base 应为 78 元(7800 分)"
+                        + "= A − R0(20元) − R1_等值(2元) − C(100元)(设计 §1.1 公式)。");
+        assertNotEquals(V1_GROSS_MARGIN, base,
+                "[cf.rewardv2.e2eExample] base 不得等于 v1 原始毛利 100 元(10000 分):"
+                        + "分润基数是扣减平台抽成与消费返 CF 后的可分配额,不是毛利(需求 §3.2/设计 §8 用例#10)。");
+    }
+
+    @Test
+    @DisplayName("正常流-3:base 恒等于 A − R0 − R1_等值 − C(R0/R1 先扣口径)")
+    void base_equalsAminusR0minusR1minusC() {
+        assertEquals(A - R0 - R1_CENT - C, BASE,
+                "[cf.rewardv2.e2eExample] 测试锚点自洽性:base 数学锚点须等于 A − R0 − R1_等值 − C。");
+        int base = invokeStatelessInt(CF_COMMISSION_SERVICE, "calcDistributableBase", A, C);
+        assertEquals(A - R0 - R1_CENT - C, base,
+                "[cf.rewardv2.e2eExample] calcDistributableBase 必须按「R0/R1 先扣」口径计算:"
+                        + "R1_等值 = floor(A/100) 分(200 CF ≈ 2 元),平台抽成与消费返 CF 都是先扣成本"
+                        + "(需求 D4/设计 §1.1)。");
+    }
+
+    // ==================== 正常流:团队池通道契约(§3.1/§5) ====================
+
+    @Test
+    @DisplayName("正常流-4:RULE_TEAM_POOL 常量应为 F03c")
+    void ruleTeamPoolConstant_isF03c() {
+        assertTrue(constantValueEquals(CF_COMMISSION_SERVICE, "F03c"),
+                "[cf.rewardv2.e2eExample] CfCommissionService 缺少 RULE_TEAM_POOL = \"F03c\" 常量:"
+                        + "设计 §3.1 要求团队池发放走 earnByRule(memberId, \"F03c\", poolId, {amount})"
+                        + "(cf_earn_rule 新种子,§3.3)。实现未落地。");
+    }
+
+    @Test
+    @DisplayName("正常流-5:团队池两实体应存在并承载 poolCent(金额锚点 30 元)")
+    void teamPoolEntities_carryPoolCent() {
+        Class<?> orderEntity = loadClass(CF_TEAM_POOL_ORDER);
+        assertTrue(orderEntity != null,
+                "[cf.rewardv2.e2eExample] CfTeamPoolOrder 实体不存在:"
+                        + "设计 §2.2 要求 cf_team_pool_order 记录团队池金额(成本×T%,如 30 元)。实现未落地。");
+        assertTrue(fieldExists(orderEntity, "poolCent"),
+                "[cf.rewardv2.e2eExample] CfTeamPoolOrder 应含 poolCent 字段(对应 pool_cent),"
+                        + "承载团队池金额 = floor(C × T_bps / 10000) = 3000 分(30 元)。");
+
+        Class<?> shareEntity = loadClass(CF_TEAM_POOL_SHARE);
+        assertTrue(shareEntity != null,
+                "[cf.rewardv2.e2eExample] CfTeamPoolShare 实体不存在:"
+                        + "设计 §2.3 要求 cf_team_pool_share 记录池内成员瓜分明细(uk_pool_member 幂等)。实现未落地。");
+        assertTrue(fieldExists(shareEntity, "shareCent"),
+                "[cf.rewardv2.e2eExample] CfTeamPoolShare 应含 shareCent 字段(对应 share_cent)。");
+    }
+
+    // ==================== 正常流:平台抽成与新增服务契约(§3.1/§2.4) ====================
+
+    @Test
+    @DisplayName("正常流-6:CfPlatformRevenueLog 应存在并承载 amountCent(R0=20 元)")
+    void platformRevenueLog_carriesAmountCent() {
+        Class<?> entity = loadClass(CF_PLATFORM_REVENUE_LOG);
+        assertTrue(entity != null,
+                "[cf.rewardv2.e2eExample] CfPlatformRevenueLog 实体不存在:"
+                        + "设计 §2.4 要求 cf_platform_revenue_log 单列 R0 平台抽成(uk_order 幂等)。实现未落地。");
+        assertTrue(fieldExists(entity, "amountCent"),
+                "[cf.rewardv2.e2eExample] CfPlatformRevenueLog 应含 amountCent 字段"
+                        + "(对应 amount_cent,200 元实付 → 20 元抽成)。");
+    }
+
+    @Test
+    @DisplayName("正常流-7:TeamShareConfigService 应存在并提供 resolveTbps 解析入口")
+    void teamShareConfigService_resolvesTbps() {
+        Class<?> svc = loadClass(TEAM_SHARE_CONFIG_SERVICE);
+        assertTrue(svc != null,
+                "[cf.rewardv2.e2eExample] TeamShareConfigService 不存在:"
+                        + "设计 §3.2 T02 要求解析 T%(优先级 MINIAPP>SYSTEM>GLOBAL>3000 兜底)。实现未落地。");
+        assertTrue(methodExists(svc, "resolveTbps"),
+                "[cf.rewardv2.e2eExample] TeamShareConfigService 应提供 resolveTbps(...) 解析入口(设计 §3.2)。");
+    }
+
+    @Test
+    @DisplayName("正常流-8:cf_team_share_config 实体类应存在(T 作用域配置承载)")
+    void teamShareConfigEntity_exists() {
+        assertTrue(loadClass(CF_TEAM_SHARE_CONFIG) != null,
+                "[cf.rewardv2.e2eExample] CfTeamShareConfig 实体不存在:"
+                        + "设计 §2.1 T01 要求 cf_team_share_config 承载 GLOBAL/SYSTEM/MINIAPP 三作用域 T 配置。实现未落地。");
+    }
+
+    // ==================== 边界流(§1.4) ====================
+
+    @Test
+    @DisplayName("边界流-1:亏损仓 base 不得为负,按 0 返回")
+    void calcDistributableBase_lossMaking_returnsZero() {
+        // 售价 100 元(10000 分)/ 成本 120 元(12000 分):base = 10000 − 1000 − 100 − 12000 < 0 ⇒ 0
+        int base = invokeStatelessInt(CF_COMMISSION_SERVICE, "calcDistributableBase", 10000, 12000);
+        assertEquals(0, base,
+                "[cf.rewardv2.e2eExample] 亏损仓(A < C)base 必须为 0(不得为负):"
+                        + "直推/间推 = 0,R0/R1 照旧,团队池照发(设计 §1.4/§8 用例#3)。");
+    }
+
+    @Test
+    @DisplayName("边界流-2:实付为 0 时 base 为 0")
+    void calcDistributableBase_zeroPaid_returnsZero() {
+        assertEquals(0, invokeStatelessInt(CF_COMMISSION_SERVICE, "calcDistributableBase", 0, C),
+                "[cf.rewardv2.e2eExample] 实付 = 0:R0=0、R1=0、base=0(设计 §1.4)。");
+    }
+
+    @Test
+    @DisplayName("边界流-3:亏损仓团队池照发配置键 cf.team_pool.on_loss 应播种(默认 payout)")
+    void onLossConfigKey_shouldBeDeclared() {
+        assertTrue(configKeyDeclared(CF_CONFIG_KEYS, "cf.team_pool.on_loss"),
+                "[cf.rewardv2.e2eExample] CfConfigKeys 缺少 cf.team_pool.on_loss 键:"
+                        + "亏损仓团队池按成本×T% 照发(2026-11-14 裁决 payout,设计 §1.4)。实现未落地。");
+    }
+
+    // ==================== 配置流(§2/§4) ====================
+
+    @Test
+    @DisplayName("配置流-1:schema.sql 应包含四张 v2 新表")
+    void schemaSql_containsFourV2Tables() {
+        String schema = readSchemaSql();
+        for (String table : V2_TABLES) {
+            assertTrue(schema.contains(table),
+                    "[cf.rewardv2.e2eExample] schema.sql 缺少 " + table + " 建表"
+                            + "(设计 §2,迁移462-465)。实现未落地。");
+        }
+    }
+
+    @Test
+    @DisplayName("配置流-2:CfConfigKeys 应声明六个 v2 配置键")
+    void configKeys_sixV2KeysDeclared() {
+        for (String key : V2_CONFIG_KEYS) {
+            assertTrue(configKeyDeclared(CF_CONFIG_KEYS, key),
+                    "[cf.rewardv2.e2eExample] CfConfigKeys 缺少配置键 " + key
+                            + "(设计 §4,种子进 seedCfServiceConfig)。实现未落地。");
+        }
+    }
+
+    // ==================== 权限流(不适用) ====================
+
+    @Test
+    @DisplayName("权限流:本能力为后端内部结算链路,无用户权限维度,权限流不适用")
+    void permissionFlow_notApplicable() {
+        // 说明性用例:cf.rewardv2.e2eExample 契约 AC 为「订单支付 → 分润结算」内部链路,
+        // 无请求级权限校验维度。不产生断言失败,仅为三流覆盖标注「不适用」。
+        assertTrue(true, "权限流不适用:cf.rewardv2.e2eExample 为后端内部结算链路,无用户权限维度。");
+    }
+
+    // ==================== 反射辅助 ====================
+
+    private Class<?> loadClass(String name) {
+        try {
+            return Class.forName(name, false, Thread.currentThread().getContextClassLoader());
+        } catch (ClassNotFoundException e) {
+            return null;
+        }
+    }
+
+    private boolean methodExists(Class<?> clazz, String name, Class<?>... params) {
+        try {
+            clazz.getDeclaredMethod(name, params);
+            return true;
+        } catch (NoSuchMethodException e) {
+            return false;
+        }
+    }
+
+    private boolean fieldExists(Class<?> clazz, String name) {
+        try {
+            clazz.getDeclaredField(name);
+            return true;
+        } catch (NoSuchFieldException e) {
+            return false;
+        }
+    }
+
+    /**
+     * 无参构造实例化 + 反射调用静态无副作用契约方法(如 {@code calcDistributableBase(int, int)}),
+     * 返回 int。方法缺失时以契约失败断言结束(RED),GREEN 实现落地后转绿。
+     */
+    private int invokeStatelessInt(String targetClass, String methodName, int arg1, int arg2) {
+        Class<?> clazz = loadClass(targetClass);
+        if (clazz == null) {
+            fail("[cf.rewardv2.e2eExample] 目标类不存在:" + targetClass);
+        }
+        Object instance;
+        try {
+            instance = clazz.getDeclaredConstructor().newInstance();
+        } catch (Exception e) {
+            fail("[cf.rewardv2.e2eExample] 无法实例化 " + targetClass + ":" + e.getClass().getSimpleName()
+                    + "(GREEN 时 calcDistributableBase 应为纯函数,无依赖也可实例化)。");
+            return 0;
+        }
+        try {
+            Method m = clazz.getDeclaredMethod(methodName, int.class, int.class);
+            m.setAccessible(true);
+            Object result = m.invoke(instance, arg1, arg2);
+            return ((Number) result).intValue();
+        } catch (NoSuchMethodException e) {
+            fail("[cf.rewardv2.e2eExample] " + targetClass + " 缺少 " + methodName + "(int, int)"
+                    + "(设计 §3.1 T03 要求交付,实现未落地)。");
+        } catch (Exception e) {
+            fail("[cf.rewardv2.e2eExample] 调用 " + targetClass + "." + methodName + " 失败:"
+                    + e.getCause() == null ? e.toString() : e.getCause().toString());
+        }
+        return 0;
+    }
+
+    /** CfConfigKeys 是否已声明值为 keyValue 的静态 String 常量(不绑定 Java 常量名,防命名漂移) */
+    private boolean configKeyDeclared(String configKeysClass, String keyValue) {
+        Class<?> clazz = loadClass(configKeysClass);
+        if (clazz == null) {
+            return false;
+        }
+        try {
+            for (Field f : clazz.getDeclaredFields()) {
+                if (Modifier.isStatic(f.getModifiers()) && f.getType() == String.class) {
+                    f.setAccessible(true);
+                    if (keyValue.equals(f.get(null))) {
+                        return true;
+                    }
+                }
+            }
+        } catch (Exception e) {
+            return false;
+        }
+        return false;
+    }
+
+    /** 目标类是否存在值为 expected 的静态 String 常量 */
+    private boolean constantValueEquals(String targetClass, String expected) {
+        Class<?> clazz = loadClass(targetClass);
+        if (clazz == null) {
+            return false;
+        }
+        try {
+            for (Field f : clazz.getDeclaredFields()) {
+                if (Modifier.isStatic(f.getModifiers()) && f.getType() == String.class) {
+                    f.setAccessible(true);
+                    if (expected.equals(f.get(null))) {
+                        return true;
+                    }
+                }
+            }
+        } catch (Exception e) {
+            return false;
+        }
+        return false;
+    }
+
+    private String readSchemaSql() {
+        try (InputStream is = getClass().getClassLoader().getResourceAsStream("schema.sql")) {
+            if (is == null) {
+                return "";
+            }
+            try (Scanner scanner = new Scanner(is, StandardCharsets.UTF_8.name())) {
+                scanner.useDelimiter("\\A");
+                return scanner.hasNext() ? scanner.next() : "";
+            }
+        } catch (Exception e) {
+            return "";
+        }
+    }
+}