Просмотр исходного кода

test(S-cfc-293): RED 契约级单测 shop.coupon.claim(SC-P-75 领券→入卡包/库存为0拦截/重复领幂等·流水口径·原子扣减)

Agnes Agent 1 день назад
Родитель
Сommit
e51ec6fc3b

+ 310 - 0
cfc-backend/src/test/java/com/etotem/cfc/unit/CouponClaimScP75ContractTest.java

@@ -0,0 +1,310 @@
+package com.etotem.cfc.unit;
+
+import com.baomidou.mybatisplus.core.conditions.Wrapper;
+import com.etotem.cfc.entity.Coupon;
+import com.etotem.cfc.entity.FamilyCoupon;
+import com.etotem.cfc.entity.User;
+import com.etotem.cfc.mapper.CouponMapper;
+import com.etotem.cfc.mapper.FamilyCouponGrantLogMapper;
+import com.etotem.cfc.mapper.FamilyCouponMapper;
+import com.etotem.cfc.mapper.UserMapper;
+import com.etotem.cfc.service.CouponService;
+import com.etotem.cfc.service.MembershipService;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Test;
+
+import java.lang.reflect.Field;
+import java.lang.reflect.Method;
+import java.util.Date;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+import static org.junit.jupiter.api.Assertions.fail;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.ArgumentMatchers.anyLong;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.never;
+import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.when;
+
+/**
+ * 契约级单测:能力键 {@code shop.coupon.claim}(S-cfc-293,TDD-RED 阶段,预期失败)。
+ *
+ * <p><b>溯源·需求</b>:tests/user-scenarios/应用场景总览.md SC-P-75「优惠券领取(活动/分享)」
+ * (业务域 K 营销/活动/优惠):流程「领券 → 入卡包」;边界「库存为 0/已领拦截;重复领幂等」。
+ * 验收条款(派生):</p>
+ * <ul>
+ *   <li><b>AC-1 入卡包(正常流)</b>:领取成功须写入家庭券实例 {@code family_coupon}(家庭卡包),
+ *       且落发券流水 {@code family_coupon_grant_log}(grantType=CLAIM,用于「已领拦截」的防重口径)。</li>
+ *   <li><b>AC-2 库存拦截(异常流)</b>:{@code used_count >= total_count}(含 used_count 为 0 上限场景)
+ *       → 拒绝「优惠券已领完」;且失败路径<b>不产生副作用</b>——不写 family_coupon、不写流水。</li>
+ *   <li><b>AC-3 已领/重复领幂等(边界流)</b>:本家庭已有 family_coupon 记录 → 不重复发券、
+ *       used_count 不再 +1(幂等);已领拦截须以<b>发券流水(任意 grant_type)</b>为判定口径,
+ *       保证 JOIN/POPULATION/PERIODIC/CF_EXCHANGE 等自动发放链路发过券的家庭,
+ *       手动 /claim 同券不会二次发放(SC-P-75「已领拦截」+ COUPON-C3 去重口径)。</li>
+ * </ul>
+ *
+ * <p><b>溯源·设计</b>:docs/superpowers/api/API_REFERENCE.md §4.32 优惠券
+ * {@code POST /api/coupon/claim}(领取优惠券,发到家庭);领券 vs 使用({@code /apply},
+ * 能力键 shop.coupon.apply,S-cfc-167)区分:本键只覆盖「领取」侧,不涉及结算抵扣。
+ * {@code /available-templates}(COUPON-C3)与 /claim 去重口径对齐——以 family_coupon
+ * 任意状态有记录即视为已领取。流水表 {@code family_coupon_grant_log} 的
+ * {@code uk_family_grant} 唯一键(grant_type+family_id+coupon_id+period)为重复领幂等的 DB 层防线。</p>
+ *
+ * <p><b>RED 依据(契约未落地)</b>:src/main 现状 {@link CouponService#claim} 领取成功路径
+ * 仅写 family_coupon + used_count+1,<b>不落 grant log</b>;已领判定仅查 family_coupon 记录数,
+ * 与 grant log 口径脱节(自动发放渠道发过、家庭手动再领的窗口无流水可查);
+ * 库存为 0/已领失败路径无「无副作用」契约。实现落地后(GREEN 阶段)本测试应全绿;
+ * 若意外全绿,说明实现已超前,交编排侧转测试登记,不私改实现。</p>
+ *
+ * <p><b>参考风格</b>:同批 RED 契约测试(TeamProfitHookContractTest / TeamStarMultiplierContractTest /
+ * TeamProfitPipelineContractTest / FamilyJoinValidationRulesContractTest)——纯 Mockito/反射、
+ * 无 Spring 上下文、无 DB、无外部服务。同领域已绿参照:CouponUseScP57ScP75ContractTest(S-cfc-12)。</p>
+ */
+class CouponClaimScP75ContractTest {
+
+    private static final String GRANT_TYPE_CLAIM = "CLAIM";
+
+    private CouponService service;
+    private UserMapper userMapper;
+    private CouponMapper couponMapper;
+    private FamilyCouponMapper familyCouponMapper;
+    private FamilyCouponGrantLogMapper familyCouponGrantLogMapper;
+    private MembershipService membershipService;
+
+    @BeforeEach
+    void setUp() throws Exception {
+        service = new CouponService();
+        userMapper = mock(UserMapper.class);
+        couponMapper = mock(CouponMapper.class);
+        familyCouponMapper = mock(FamilyCouponMapper.class);
+        familyCouponGrantLogMapper = mock(FamilyCouponGrantLogMapper.class);
+        membershipService = mock(MembershipService.class);
+
+        inject(service, "userMapper", userMapper);
+        inject(service, "couponMapper", couponMapper);
+        inject(service, "familyCouponMapper", familyCouponMapper);
+        inject(service, "familyCouponGrantLogMapper", familyCouponGrantLogMapper);
+        inject(service, "membershipService", membershipService);
+        when(familyCouponGrantLogMapper.insert(any())).thenReturn(1);
+        when(familyCouponMapper.selectCount(any(Wrapper.class))).thenReturn(0L);
+    }
+
+    private static void inject(Object target, String field, Object value) throws Exception {
+        Field f = target.getClass().getDeclaredField(field);
+        f.setAccessible(true);
+        f.set(target, value);
+    }
+
+    private void stubUserFamily(Long familyId) {
+        User user = new User();
+        user.setId(1L);
+        user.setFamilyId(familyId);
+        when(userMapper.selectById(1L)).thenReturn(user);
+    }
+
+    /** 可领取的 ACTIVE 全平台券模板(非自动发放、有效期内、库存充足) */
+    private Coupon claimableCoupon() {
+        Coupon c = new Coupon();
+        c.setId(100L);
+        c.setName("满100减10");
+        c.setType("CASH");
+        c.setValue(1000);
+        c.setMinSpend(0);
+        c.setStatus("ACTIVE");
+        c.setApplicableTo("ALL");
+        c.setValidFrom(new Date(System.currentTimeMillis() - 86_400_000L));
+        c.setValidUntil(new Date(System.currentTimeMillis() + 30L * 86_400_000L));
+        c.setTotalCount(100);
+        c.setUsedCount(50);
+        return c;
+    }
+
+    // ==================================================================
+    // AC-1 入卡包(正常流):领取成功须写 family_coupon 并落发券流水
+    // ==================================================================
+
+    @Test
+    @DisplayName("正常流(AC-1 入卡包):领取成功 → 家庭卡包写入 + 发券流水落库(grantType=CLAIM)")
+    void 正常流_领取成功_入卡包并落发券流水() {
+        stubUserFamily(5L);
+        Coupon coupon = claimableCoupon();
+        when(couponMapper.selectById(100L)).thenReturn(coupon);
+        when(familyCouponMapper.insert(any(FamilyCoupon.class))).thenAnswer(inv -> {
+            FamilyCoupon fc = inv.getArgument(0);
+            fc.setId(500L);
+            return 1;
+        });
+
+        String result = service.claim(1L, 100L);
+
+        assertEquals("领取成功", result);
+        // 入卡包:family_coupon 实例必须写入(AC-1)
+        verify(familyCouponMapper).insert(any(FamilyCoupon.class));
+        assertEquals(51, coupon.getUsedCount().intValue(), "used_count 应 +1");
+        verify(couponMapper).updateById(coupon);
+        // AC-1 契约缺口:发券流水(grantType=CLAIM)应落 family_coupon_grant_log,
+        // 供 AC-3「已领拦截」以流水为口径判定;现状实现未落流水 → 红
+        verify(familyCouponGrantLogMapper).insert(any());
+    }
+
+    @Test
+    @DisplayName("正常流(AC-1 入卡包·结构契约):CouponService 应持有发券流水 Mapper(family_coupon_grant_log)")
+    void 结构契约_couponService注入grantLogMapper() {
+        boolean injected = false;
+        for (Field f : CouponService.class.getDeclaredFields()) {
+            if ("com.etotem.cfc.mapper.FamilyCouponGrantLogMapper".equals(f.getType().getName())) {
+                injected = true;
+                break;
+            }
+        }
+        if (!injected) {
+            fail("[shop.coupon.claim] AC-1 契约缺口:CouponService 未注入 FamilyCouponGrantLogMapper,"
+                    + "领取成功无法落发券流水 family_coupon_grant_log(grantType=CLAIM)。实现未落地。");
+        }
+    }
+
+    // ==================================================================
+    // AC-2 库存拦截(异常流):库存为 0/已领完 → 拒绝且无副作用
+    // ==================================================================
+
+    @Test
+    @DisplayName("异常流(AC-2 库存拦截):库存为 0(used_count >= total_count)→ 拒绝且不写卡包/不写流水")
+    void 异常流_库存为0_拦截且无副作用() {
+        stubUserFamily(5L);
+        Coupon coupon = claimableCoupon();
+        coupon.setTotalCount(100);
+        coupon.setUsedCount(100);
+        when(couponMapper.selectById(100L)).thenReturn(coupon);
+
+        String result = service.claim(1L, 100L);
+
+        assertEquals("优惠券已领完", result, "库存为 0 应拦截(SC-P-75 边界:库存为 0/已领拦截)");
+        // 无副作用契约(AC-2):失败路径不得写入卡包/流水/used_count
+        verify(familyCouponMapper, never()).insert(any(FamilyCoupon.class));
+        verify(familyCouponGrantLogMapper, never()).insert(any());
+        verify(couponMapper, never()).updateById(any(Coupon.class));
+    }
+
+    // ==================================================================
+    // AC-3 已领/重复领幂等(边界流)
+    // ==================================================================
+
+    @Test
+    @DisplayName("边界流(AC-3 幂等):本家庭已有 family_coupon 记录 → 重复领不重复发券、used_count 不再 +1")
+    void 边界流_重复领取_幂等不重复发券() {
+        stubUserFamily(5L);
+        Coupon coupon = claimableCoupon();
+        when(couponMapper.selectById(100L)).thenReturn(coupon);
+        when(familyCouponMapper.selectCount(any(Wrapper.class))).thenReturn(1L);
+
+        String result = service.claim(1L, 100L);
+
+        assertEquals("已领取过该优惠券", result, "同家庭同券重复领取应幂等拦截(SC-P-75 边界:重复领幂等)");
+        verify(familyCouponMapper, never()).insert(any(FamilyCoupon.class));
+        verify(couponMapper, never()).updateById(any(Coupon.class));
+        assertEquals(50, coupon.getUsedCount().intValue(), "重复领不得使 used_count 再次 +1");
+    }
+
+    @Test
+    @DisplayName("边界流(AC-3 已领拦截口径):仅自动发放流水存在(无 family_coupon 记录)时,"
+            + "claim 须以发券流水为口径拦截重复发放")
+    void 边界流_已领拦截_须覆盖发券流水口径() throws Exception {
+        // 现状实现仅以 family_coupon 记录数判定「已领取过」:
+        // 当 JOIN/POPULATION/PERIODIC/CF_EXCHANGE 等自动发放渠道已发券、
+        // 但 family_coupon 侧查不到该 couponId 记录时,/claim 仍会二次发放。
+        // 契约要求:已领拦截须扩展为「family_coupon 记录 ∪ 发券流水(任意 grant_type)」判定,
+        // 与 COUPON-C3 去重口径对齐。
+        stubUserFamily(5L);
+        Coupon coupon = claimableCoupon();
+        when(couponMapper.selectById(100L)).thenReturn(coupon);
+        // family_coupon 侧无该券记录(现状实现的判定输入 → 会误判为「可领取」)
+        when(familyCouponMapper.selectCount(any(Wrapper.class))).thenReturn(0L);
+        // 发券流水侧存在本家庭同券记录(自动发放渠道已发)
+        when(familyCouponGrantLogMapper.selectCount(any(Wrapper.class))).thenReturn(1L);
+        when(familyCouponMapper.insert(any(FamilyCoupon.class))).thenAnswer(inv -> {
+            FamilyCoupon fc = inv.getArgument(0);
+            fc.setId(501L);
+            return 1;
+        });
+
+        String result = service.claim(1L, 100L);
+
+        if ("领取成功".equals(result)) {
+            fail("[shop.coupon.claim] AC-3 契约缺口:发券流水已存在(family_coupon_grant_log 有本家庭同券记录)"
+                    + "时 /claim 仍二次发放,「已领拦截」未覆盖流水口径。实现未落地。");
+        }
+        assertEquals("已领取过该优惠券", result, "已领拦截须以发券流水为口径(COUPON-C3 对齐)");
+        verify(familyCouponMapper, never()).insert(any(FamilyCoupon.class));
+        verify(couponMapper, never()).updateById(any(Coupon.class));
+    }
+
+    @Test
+    @DisplayName("边界流(AC-3 幂等·DB 防线):family_coupon_grant_log 建表应含 uk_family_grant 唯一键"
+            + "(family_id+coupon_id+grant_type+period,PERIODIC 防重用)")
+    void 边界流_幂等_DB唯一键ukFamilyGrant() {
+        String schema = readSchemaSql();
+        assertTrue(schema.contains("uk_family_grant"),
+                "[shop.coupon.claim] schema.sql 缺少 family_coupon_grant_log 的 uk_family_grant 唯一键:"
+                        + "重复领幂等的 DB 层防线(grant_type+family_id+coupon_id+period 防重,PERIODIC 周期防重用)。");
+    }
+
+    @Test
+    @DisplayName("边界流(AC-3 幂等·DB 防线):CouponMapper 应提供 claim 幂等原子扣减(used_count+1 且不超发)")
+    void 边界流_幂等_mapper原子扣减契约() throws Exception {
+        boolean hasAtomicClaim = false;
+        for (Method m : CouponMapper.class.getDeclaredMethods()) {
+            if (m.getName().toLowerCase().contains("claim")
+                    || m.getName().contains("incrementUsedCount")
+                    || m.getName().contains("tryClaim")) {
+                hasAtomicClaim = true;
+                break;
+            }
+        }
+        assertTrue(hasAtomicClaim,
+                "[shop.coupon.claim] CouponMapper 缺少 claim 侧原子扣减方法(used_count+1 且 total_count 上限判定):"
+                        + "现状 claim() 走 selectById + updateById 非原子路径,并发下可超发库存,"
+                        + "与「库存为 0 拦截」契约冲突。实现未落地。");
+    }
+
+    // ==================================================================
+    // 权限流:未登录/未加入家庭 → 拒绝且不写卡包
+    // ==================================================================
+
+    @Test
+    @DisplayName("权限流:未加入家庭 → 拒绝且不写卡包/不写流水")
+    void 权限流_未加入家庭_拒绝() {
+        User user = new User();
+        user.setId(1L);
+        user.setFamilyId(null);
+        when(userMapper.selectById(1L)).thenReturn(user);
+
+        String result = service.claim(1L, 100L);
+
+        assertEquals("未加入家庭", result);
+        verify(familyCouponMapper, never()).insert(any(FamilyCoupon.class));
+        verify(familyCouponGrantLogMapper, never()).insert(any());
+        verify(couponMapper, never()).selectById(anyLong());
+    }
+
+    // ==================================================================
+    // 资源辅助
+    // ==================================================================
+
+    private String readSchemaSql() {
+        try (java.io.InputStream is =
+                     getClass().getClassLoader().getResourceAsStream("schema.sql")) {
+            if (is == null) {
+                return "";
+            }
+            java.util.Scanner scanner = new java.util.Scanner(is, "UTF-8");
+            scanner.useDelimiter("\\A");
+            String content = scanner.hasNext() ? scanner.next() : "";
+            scanner.close();
+            return content;
+        } catch (Exception e) {
+            return "";
+        }
+    }
+}