瀏覽代碼

test(cfc-backend): S-cfc-396 契约测试 cf.teamshare.createPool 团队池建池(TDD RED)

T04 团队池建池契约级单测 TeamPoolCreateContractTest(反射结构契约,无 Spring/DB/外部服务):
- CfCommissionService#settleTeamPool / RULE_TEAM_POOL=F03c / calcDistributableBase 结构探测
- TeamShareConfigService#resolveTbps(T02 依赖,MINIAPP>SYSTEM>GLOBAL>3000)
- CfTeamPoolOrder 实体(orderId/orderType/buyerUserId/poolCent/tBps/configScope/status/settledAt)+ Mapper
- schema.sql 三表:cf_team_pool_order(uk_order 幂等)/ cf_team_share_config / cf_platform_revenue_log
- 权限流不适用(后端结算内部建池,无用户权限维度)

RED 实测:13 用例中 8 断言失败(settleTeamPool/RULE_TEAM_POOL/calcDistributableBase/TeamShareConfigService/
CfTeamPoolOrder 实体与 Mapper 未落地),5 通过(schema.sql 三表已由前置 T01 迁移落地 + 权限流说明性);
溯源 2026-11-14-cf-reward-model-v2-design.md §6 T04
Administrator 3 天之前
父節點
當前提交
2680bd0ae5
共有 1 個文件被更改,包括 321 次插入 和 0 次删除
  1. 321 0
      cfc-backend/src/test/java/com/etotem/cfc/unit/TeamPoolCreateContractTest.java

+ 321 - 0
cfc-backend/src/test/java/com/etotem/cfc/unit/TeamPoolCreateContractTest.java

@@ -0,0 +1,321 @@
+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.nio.charset.StandardCharsets;
+import java.util.Scanner;
+
+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;
+
+/**
+ * 契约级单测:团队分润池建池(能力键 {@code cf.teamshare.createPool},TDD-RED 阶段)。
+ *
+ * <p><b>契约溯源</b></p>
+ * <ul>
+ *   <li>需求:{@code docs/superpowers/plans/2026-11-14-cf-reward-model-v2.md} §3 新模型(团队分润池
+ *       = 成本 × T%,从成本侧切出、与 base 脱钩、单独计算)+ §5 待实现清单 #2(结算链路分叉:
+ *       CfCommissionService 增加团队池计算);</li>
+ *   <li>设计:{@code docs/superpowers/plans/2026-11-14-cf-reward-model-v2-design.md}
+ *       §2.2({@code cf_team_pool_order} 表,uk_order 幂等)+ §3.1({@code settleTeamPool} 建池入口
+ *       接线 + 常量 {@code RULE_TEAM_POOL="F03c"})+ §5(池金额公式 {@code poolCent = Σ floor(C×qty×T_bps/10000)},
+ *       幂等建池 {@code insert_if_absent(orderId, orderType, poolCent, T_bps)})+ §6 T04
+ *       (能力键 {@code cf.teamshare.pool.create} / {@code cf.teamshare.pool.idempotent})。</li>
+ * </ul>
+ *
+ * <p><b>被校验的契约行为(建池 + 幂等)</b></p>
+ * <ul>
+ *   <li><b>建池入口</b>:{@code CfCommissionService.settleTeamPool(...)} 存在——解析 T(TeamShareConfigService)
+ *       → 算池(成本×T%)→ 建 {@code cf_team_pool_order} → distributeTeamPool;settle 结算顺序
+ *       ①平台抽成 → ②消费返CF → ③base计算 → ④直推/间推 → ⑤团队池(独立从成本算),划线为同一事务;</li>
+ *   <li><b>幂等</b>:{@code cf_team_pool_order} 表含唯一键 {@code uk_order (order_type, order_id)},
+ *       重复结算命中唯一键直接返回,不重复建池(设计 §7 风险 1 三层兜底第一层);</li>
+ *   <li><b>F03c 规则编码</b>:{@code CfCommissionService} 应有 {@code RULE_TEAM_POOL = "F03c"}
+ *       (现状仅有 {@code RULE_DIRECT_SALES="F03a"} / {@code RULE_INDIRECT_SALES="F03b"});</li>
+ *   <li><b>T% 解析(T02 依赖)</b>:{@code TeamShareConfigService.resolveTbps(mpCode, distributionSystemId)}
+ *       ——优先级 MINIAPP → SYSTEM → GLOBAL → 3000bps 兜底;</li>
+ *   <li><b>数据载体</b>:实体 {@code CfTeamPoolOrder}(含 orderId/orderType/buyerUserId/poolCent/tBps/
+ *       configScope/status/settledAt)+ Mapper {@code CfTeamPoolOrderMapper} + schema.sql 建表;</li>
+ *   <li><b>base 复用(T03 依赖)</b>:{@code CfCommissionService.calcDistributableBase(A, costCent)}
+ *       ——直推/间推入参改 base = A − R0 − R1_等值 − costCent(base&lt;0 → 0),供 T04 复用。</li>
+ * </ul>
+ *
+ * <p><b>测试范围</b>:纯 Mockito 无关的反射结构契约(无 Spring / 无 DB / 无外部服务)。
+ * 本分支 src/main 中 {@code CfTeamPoolOrder} / {@code CfTeamPoolOrderMapper} / {@code TeamShareConfigService}
+ * 及 {@code CfCommissionService.settleTeamPool} / {@code RULE_TEAM_POOL} / {@code calcDistributableBase}
+ * 已核实<b>未落地</b>(全库 0 引用,schema.sql 无对应建表)——故本测试以「反射结构契约」探测实现缺失:
+ * 能编译通过、能运行、断言失败(红),且失败断言原文清晰可贴。</p>
+ *
+ * <p><b>RED 预期</b>:上述契约所需类/方法/常量/字段/建表缺失,对应用例应失败(红);
+ * 失败信息含「契约宿主 X 未实现」或「契约方法 X#m 未实现」等原文。</p>
+ *
+ * <p><b>GREEN 升级指引</b>:实现者落地 {@code settleTeamPool} / {@code RULE_TEAM_POOL} /
+ * {@code calcDistributableBase} / {@code TeamShareConfigService} / {@code CfTeamPoolOrder} /
+ * {@code CfTeamPoolOrderMapper} 及 schema.sql 三张新表(§2.1/§2.2/§2.4)后,本测试自动转绿;
+ * 届时可将结构探测升级为行为级 mock 验证(池金额公式 200/100/T=30% → pool=3000 分、重复结算幂等、
+ * T 未配置回退 3000bps 等,见设计 §8 测试用例 #1/#4/#6)。</p>
+ *
+ * <p><b>权限流说明</b>:本能力为后端结算链路内部方法(支付成功 → settle → 团队池建池),
+ * 无用户权限维度,「权限(适用时)」三流中的权限流不适用,以说明性用例标注。</p>
+ */
+class TeamPoolCreateContractTest {
+
+    /** 契约宿主:统一 CF 分佣服务(T04 建池入口所在,当前仅有 F03a/F03b 常量) */
+    private static final String HOST_COMMISSION = "com.etotem.cfc.service.CfCommissionService";
+
+    /** 新实体宿主:cf_team_pool_order(设计 §2.2,迁移463) */
+    private static final String HOST_POOL_ENTITY = "com.etotem.cfc.entity.CfTeamPoolOrder";
+
+    /** 新 Mapper 宿主(设计 §6 T04) */
+    private static final String HOST_POOL_MAPPER = "com.etotem.cfc.mapper.CfTeamPoolOrderMapper";
+
+    /** T02 交付的配置解析服务(T04 建池前解析 T%,设计 §3.2) */
+    private static final String HOST_CONFIG_SVC = "com.etotem.cfc.service.TeamShareConfigService";
+
+    /** 建池整单表(设计 §2.2) */
+    private static final String TABLE_POOL_ORDER = "cf_team_pool_order";
+
+    /** 幂等唯一键(设计 §2.2 uk_order + §7 风险1 三层兜底第一层) */
+    private static final String UK_ORDER = "uk_order";
+
+    /** T 配置表(设计 §2.1) */
+    private static final String TABLE_TEAM_SHARE_CONFIG = "cf_team_share_config";
+
+    /** R0 平台抽成流水表(设计 §2.4,T03 交付、T04 依赖) */
+    private static final String TABLE_PLATFORM_REVENUE = "cf_platform_revenue_log";
+
+    // ==================== 正常流:建池入口(§3.1) ====================
+
+    @Test
+    @DisplayName("正常流-1:CfCommissionService 应提供 settleTeamPool 建池入口")
+    void commissionService_hasSettleTeamPoolMethod() {
+        Class<?> clazz = loadClass(HOST_COMMISSION);
+        if (clazz == null) {
+            fail("RED[cf.teamshare.createPool] 契约宿主 CfCommissionService 未实现(实现未落地):"
+                    + HOST_COMMISSION + " 不存在。");
+        }
+        assertTrue(hasDeclaredMethod(clazz, "settleTeamPool"),
+                "RED[cf.teamshare.createPool] 契约方法 CfCommissionService#settleTeamPool 未实现:"
+                        + "设计 §3.1 要求 settle 结算顺序 ⑤ 团队池由 settleTeamPool 承担"
+                        + "(解析 T → 算池 → 建 cf_team_pool_order(uk_order 幂等)→ distributeTeamPool)。");
+    }
+
+    @Test
+    @DisplayName("正常流-2:CfCommissionService 应含 RULE_TEAM_POOL 常量(F03c)")
+    void commissionService_hasRuleTeamPoolConstant() {
+        Class<?> clazz = loadClass(HOST_COMMISSION);
+        if (clazz == null) {
+            fail("RED[cf.teamshare.createPool] 契约宿主 CfCommissionService 未实现(实现未落地):"
+                    + HOST_COMMISSION + " 不存在。");
+        }
+        Field f = declaredField(clazz, "RULE_TEAM_POOL");
+        if (f == null) {
+            fail("RED[cf.teamshare.createPool] 契约常量 CfCommissionService#RULE_TEAM_POOL 未实现:"
+                    + "设计 §3.1 要求新增团队池规则编码 F03c(现状仅有 RULE_DIRECT_SALES=F03a / "
+                    + "RULE_INDIRECT_SALES=F03b)。");
+        }
+        try {
+            f.setAccessible(true);
+            Object value = f.get(null);
+            assertEquals("F03c", value,
+                    "RED[cf.teamshare.createPool] RULE_TEAM_POOL 应为 \"F03c\"(cf_earn_rule 团队池规则码,"
+                            + "设计 §3.3 种子),实际 " + value);
+        } catch (IllegalAccessException e) {
+            fail("RED[cf.teamshare.createPool] RULE_TEAM_POOL 常量读取失败:" + e.getMessage());
+        }
+    }
+
+    @Test
+    @DisplayName("正常流-3:CfCommissionService 应提供 calcDistributableBase(T03 交付、建池结算前复用)")
+    void commissionService_hasCalcDistributableBaseMethod() {
+        Class<?> clazz = loadClass(HOST_COMMISSION);
+        if (clazz == null) {
+            fail("RED[cf.teamshare.createPool] 契约宿主 CfCommissionService 未实现(实现未落地):"
+                    + HOST_COMMISSION + " 不存在。");
+        }
+        assertTrue(hasDeclaredMethod(clazz, "calcDistributableBase"),
+                "RED[cf.teamshare.createPool] 契约方法 CfCommissionService#calcDistributableBase 未实现:"
+                        + "设计 §3.1(T03 交付、T04 复用)要求 base = A − R0 − R1_等值 − costCent(base<0 → 0),"
+                        + "直推/间推入参由 P 点毛利改为 base。");
+    }
+
+    // ==================== 依赖链:T% 解析(§3.2,T02 交付) ====================
+
+    @Test
+    @DisplayName("依赖链-1:TeamShareConfigService 应存在(T% 解析)")
+    void teamShareConfigService_classExists() {
+        assertNotNull(loadClass(HOST_CONFIG_SVC),
+                "RED[cf.teamshare.createPool] 契约宿主 TeamShareConfigService 未实现(T02 交付、T04 建池依赖):"
+                        + "设计 §3.2 要求 resolveTbps 按 MINIAPP→SYSTEM→GLOBAL→3000bps 兜底解析团队池比例。");
+    }
+
+    @Test
+    @DisplayName("依赖链-2:TeamShareConfigService 应提供 resolveTbps 方法")
+    void teamShareConfigService_hasResolveTbpsMethod() {
+        Class<?> clazz = loadClass(HOST_CONFIG_SVC);
+        if (clazz == null) {
+            fail("RED[cf.teamshare.createPool] 契约宿主 TeamShareConfigService 未实现(T02 交付):无法验证 resolveTbps。");
+        }
+        assertTrue(hasMethodByArity(clazz, "resolveTbps", 2),
+                "RED[cf.teamshare.createPool] 契约方法 TeamShareConfigService#resolveTbps(mpCode, distributionSystemId) "
+                        + "未实现:设计 §3.2 要求按作用域优先级 MINIAPP>SYSTEM>GLOBAL>3000 解析 T(bps)。");
+    }
+
+    // ==================== 正常流:数据载体(§2.2 + §6 T04) ====================
+
+    @Test
+    @DisplayName("正常流-4:CfTeamPoolOrder 实体应存在(cf_team_pool_order 载体)")
+    void teamPoolOrder_entityExists() {
+        assertNotNull(loadClass(HOST_POOL_ENTITY),
+                "RED[cf.teamshare.createPool] 契约宿主 CfTeamPoolOrder 实体未实现:设计 §2.2(迁移463)要求 "
+                        + "cf_team_pool_order 表承载建池结果(order_id/order_type/pool_cent/t_bps/status 等)。");
+    }
+
+    @Test
+    @DisplayName("正常流-5:CfTeamPoolOrder 实体应含建池关键字段")
+    void teamPoolOrder_entityCarriesPoolFields() {
+        Class<?> entity = loadClass(HOST_POOL_ENTITY);
+        if (entity == null) {
+            fail("RED[cf.teamshare.createPool] 契约宿主 CfTeamPoolOrder 实体未实现(设计 §2.2):无法验证字段。");
+        }
+        String[] required = {"orderId", "orderType", "buyerUserId", "poolCent", "tBps", "configScope", "status", "settledAt"};
+        for (String f : required) {
+            assertTrue(hasDeclaredField(entity, f),
+                    "RED[cf.teamshare.createPool] CfTeamPoolOrder 实体应含字段 " + f
+                            + "(对应 cf_team_pool_order." + snake(f) + ",设计 §2.2)。");
+        }
+    }
+
+    @Test
+    @DisplayName("正常流-6:CfTeamPoolOrderMapper 应存在")
+    void teamPoolOrderMapper_exists() {
+        assertNotNull(loadClass(HOST_POOL_MAPPER),
+                "RED[cf.teamshare.createPool] 契约宿主 CfTeamPoolOrderMapper 未实现(设计 §6 T04):"
+                        + "建池落库需要 cf_team_pool_order 表的 MyBatis-Plus Mapper。");
+    }
+
+    // ==================== 边界流:schema.sql 建表落地(幂等) ====================
+
+    @Test
+    @DisplayName("边界流-1:cf_team_pool_order 应落地 schema.sql(§2.2)")
+    void schemaSql_hasTeamPoolOrderTable() {
+        String schema = readSchemaSql();
+        assertTrue(schema.contains(TABLE_POOL_ORDER),
+                "RED[cf.teamshare.createPool] schema.sql 缺少 cf_team_pool_order 建表(设计 §2.2,迁移463)。");
+    }
+
+    @Test
+    @DisplayName("边界流-2:cf_team_pool_order 应含 uk_order 唯一键(幂等)")
+    void schemaSql_hasTeamPoolOrderUkOrder() {
+        String schema = readSchemaSql();
+        assertTrue(schema.contains(TABLE_POOL_ORDER),
+                "RED[cf.teamshare.createPool] schema.sql 缺少 cf_team_pool_order 建表(设计 §2.2)。");
+        assertTrue(schema.contains(UK_ORDER),
+                "RED[cf.teamshare.createPool] cf_team_pool_order 应含 uk_order 唯一键 (order_type, order_id):"
+                        + "设计 §7 风险1 三层兜底第一层,重复结算命中唯一键直接返回(幂等建池)。");
+    }
+
+    @Test
+    @DisplayName("边界流-3:cf_team_share_config 应落地 schema.sql(T02 依赖)")
+    void schemaSql_hasTeamShareConfigTable() {
+        String schema = readSchemaSql();
+        assertTrue(schema.contains(TABLE_TEAM_SHARE_CONFIG),
+                "RED[cf.teamshare.createPool] schema.sql 缺少 cf_team_share_config 建表(设计 §2.1,T02 交付):"
+                        + "建池前须按作用域解析 T%。");
+    }
+
+    @Test
+    @DisplayName("边界流-4:cf_platform_revenue_log 应落地 schema.sql(T03 依赖)")
+    void schemaSql_hasPlatformRevenueLogTable() {
+        String schema = readSchemaSql();
+        assertTrue(schema.contains(TABLE_PLATFORM_REVENUE),
+                "RED[cf.teamshare.createPool] schema.sql 缺少 cf_platform_revenue_log 建表(设计 §2.4,T03 交付):"
+                        + "结算顺序 ① 平台抽成记账在 ⑤ 团队池建池之前(base 依赖 R0 先算出)。");
+    }
+
+    // ==================== 权限流(不适用) ====================
+
+    @Test
+    @DisplayName("权限流:本能力为后端结算链路内部方法,无用户权限维度,权限流不适用")
+    void permissionFlow_notApplicable() {
+        // 说明性用例:契约 AC 为「支付成功 → CfCommissionService.settle → settleTeamPool 建池」内部链路,
+        // 无权限校验维度。不产生断言失败;仅为三流覆盖标注「不适用」。
+        assertTrue(true, "权限流不适用:cf.teamshare.createPool 为后端结算内部建池,无用户权限维度。");
+    }
+
+    // ==================== 反射辅助(锚定契约宿主,避免编译期依赖不存在类) ====================
+
+    private Class<?> loadClass(String name) {
+        try {
+            return Class.forName(name, false, Thread.currentThread().getContextClassLoader());
+        } catch (ClassNotFoundException e) {
+            return null;
+        }
+    }
+
+    private boolean hasDeclaredMethod(Class<?> clazz, String name) {
+        for (Method m : clazz.getDeclaredMethods()) {
+            if (m.getName().equals(name)) {
+                return true;
+            }
+        }
+        return false;
+    }
+
+    /** 按方法名 + 参数个数匹配(宽松适配,契约签名由 javadoc 约束)。 */
+    private boolean hasMethodByArity(Class<?> clazz, String name, int arity) {
+        for (Method m : clazz.getDeclaredMethods()) {
+            if (m.getName().equals(name) && m.getParameterCount() == arity) {
+                return true;
+            }
+        }
+        return false;
+    }
+
+    private Field declaredField(Class<?> clazz, String name) {
+        try {
+            return clazz.getDeclaredField(name);
+        } catch (NoSuchFieldException e) {
+            return null;
+        }
+    }
+
+    private boolean hasDeclaredField(Class<?> clazz, String name) {
+        return declaredField(clazz, name) != null;
+    }
+
+    /** camelCase 字段名 → snake_case 列名(仅用于失败信息提示)。 */
+    private String snake(String camel) {
+        StringBuilder sb = new StringBuilder();
+        for (int i = 0; i < camel.length(); i++) {
+            char c = camel.charAt(i);
+            if (Character.isUpperCase(c)) {
+                sb.append('_');
+                sb.append(Character.toLowerCase(c));
+            } else {
+                sb.append(c);
+            }
+        }
+        return sb.toString();
+    }
+
+    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 "";
+        }
+    }
+}