Răsfoiți Sursa

test(S-cfc-272): RED contract test for growth.milestone.mark 成长里程碑标记

TDD-RED 阶段契约级单测(GrowthMilestoneMarkContractTest),预期红:
- 契约宿主 GrowthMilestoneService(markMilestone/isMarked + 重复标幂等)未落地
- GrowthController /api/growth 无 milestone 端点(缺口 G-2)
实测 8 用例 7 失败(宿主缺失 + 端点缺失),权限流不适用用例通过。

溯源:SC-P-51 成长里程碑(系统/手动标里程碑→时间线高亮,重复标幂等);
设计:API_REFERENCE §4.6 /api/growth/*;缺口 G-2(2026-11-07-parent-rest-contract)
E2E Test Bot 1 săptămână în urmă
părinte
comite
fb84460c9a

+ 231 - 0
cfc-backend/src/test/java/com/etotem/cfc/unit/GrowthMilestoneMarkContractTest.java

@@ -0,0 +1,231 @@
+package com.etotem.cfc.unit;
+
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Test;
+
+import java.lang.reflect.Method;
+
+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 growth.milestone.mark},业务域 E 成长记录与档案)。
+ *
+ * <p><b>需求/设计锚点(TDD-RED 阶段,实现未落地)</b></p>
+ * <ul>
+ *   <li>需求:{@code tests/user-scenarios/应用场景总览.md} SC-P-51(成长里程碑)——
+ *       目标:标记关键节点;流程:系统/手动标里程碑 → 时间线高亮;边界:重复标幂等。</li>
+ *   <li>设计:{@code docs/superpowers/api/API_REFERENCE.md} §4.6 成长档案 {@code /api/growth/*}
+ *       (计划/详情)+ §4.7 健康打卡;模块:{@code GrowthController}。</li>
+ *   <li>契约缺口:{@code docs/superpowers/specs/2026-11-07-parent-rest-contract.md} §4 缺口 G-2 ——
+ *       成长「里程碑」无独立端点;成长页里程碑此前为前端聚合计算,缺少后端可追溯标记
+ *       (系统/手动)与幂等保障,无法支撑成长激励闭环。</li>
+ * </ul>
+ *
+ * <p><b>契约宿主(TDD-RED 锚点)</b>:{@code com.etotem.cfc.service.GrowthMilestoneService} ——
+ * 规格 SC-P-51 / 缺口 G-2 规划的成长里程碑服务,当前 src/main <b>尚未实现</b>(实测全库无
+ * {@code GrowthMilestone} / {@code markMilestone} / {@code growth_milestone} 引用)。本测试通过
+ * 反射锚定该宿主契约(避免直接 import 不存在类导致编译失败),运行时宿主类缺失即断言失败(红),
+ * 暴露「实现未落地」这一真实缺陷;GREEN 阶段落地后转为验证真实行为。</p>
+ *
+ * <p><b>契约方法签名(实现方按此落地)</b></p>
+ * <ul>
+ *   <li>{@code Long markMilestone(Long memberId, Long recordId, String milestoneType)} ——
+ *       系统/手动标里程碑:在成长记录上标记关键节点,返回里程碑 ID(时间线高亮依据)。
+ *       {@code milestoneType} 取值 {@code manual}(手动)/ {@code system}(系统)。</li>
+ *   <li>{@code boolean isMarked(Long memberId, Long recordId, String milestoneType)} ——
+ *       该成长记录是否已标该里程碑(时间线高亮判定依据)。</li>
+ * </ul>
+ *
+ * <p><b>端点载体契约</b>:{@code GrowthController /api/growth} 应暴露成长里程碑标记端点
+ * (如 {@code POST /api/growth/milestone/mark})。当前该控制器仅有
+ * {@code recommendations} / {@code articles/ai-classify} / {@code products/ai-classify},
+ * 无任何 milestone 端点 → 端点级断言同样为红。</p>
+ *
+ * <p><b>测试范围</b>:纯契约级单测,无 Spring / 无 DB / 无真实微信,无外部服务依赖。
+ * 表结构与持久化方式(独立里程碑表或成长记录扩展字段)由 GREEN 实现方决定,本测试不作约束。</p>
+ * <p><b>权限流</b>:成长记录里程碑面向家庭内部成员(标记对象为家庭成员的成长记录),
+ * 成员归属校验由 {@code currentMemberId} / JWT 上下文统一承载,本键无独立角色权限分支,
+ * 故权限流以说明性用例标注「不适用」。</p>
+ *
+ * <p><b>RED 预期</b>:宿主 {@code GrowthMilestoneService} 未实现 + {@code GrowthController}
+ * 无里程碑端点,全部用例在反射探测处失败(红),断言原文含「契约宿主
+ * GrowthMilestoneService 未实现」/「GrowthController 无里程碑端点」。</p>
+ */
+class GrowthMilestoneMarkContractTest {
+
+    /** 规格设计宿主类(未实现)。 */
+    private static final String HOST_CLASS = "com.etotem.cfc.service.GrowthMilestoneService";
+
+    /** 成长里程碑端点载体(GrowthController /api/growth)。 */
+    private static final String GROWTH_CONTROLLER_CLASS = "com.etotem.cfc.controller.GrowthController";
+
+    /** milestoneType 允许值:手动标 / 系统标(SC-P-51「系统/手动标里程碑」)。 */
+    private static final String TYPE_MANUAL = "manual";
+    private static final String TYPE_SYSTEM = "system";
+
+    // ==================== 正常流:系统/手动标里程碑 → 返回里程碑 ID(时间线高亮依据) ====================
+
+    @Test
+    @DisplayName("正常流-1:手动标里程碑应返回非空里程碑 ID")
+    void 手动标里程碑_返回非空里程碑Id() {
+        Object host = contractHost();
+        Long id = callLong(host, "markMilestone", 11L, 101L, TYPE_MANUAL);
+        assertNotNull(id, "手动标里程碑应返回里程碑 ID(时间线高亮依据)");
+        assertTrue(id > 0, "里程碑 ID 应为正数,实际=" + id);
+    }
+
+    @Test
+    @DisplayName("正常流-2:系统标里程碑应返回非空里程碑 ID")
+    void 系统标里程碑_返回非空里程碑Id() {
+        Object host = contractHost();
+        Long id = callLong(host, "markMilestone", 11L, 102L, TYPE_SYSTEM);
+        assertNotNull(id, "系统标里程碑应返回里程碑 ID(时间线高亮依据)");
+        assertTrue(id > 0, "里程碑 ID 应为正数,实际=" + id);
+    }
+
+    // ==================== 正常流:标记后时间线高亮判定为已标 ====================
+
+    @Test
+    @DisplayName("正常流-3:标记后时间线高亮判定为已标")
+    void 标记后_时间线高亮判定为已标() {
+        Object host = contractHost();
+        callLong(host, "markMilestone", 11L, 103L, TYPE_MANUAL);
+        assertTrue(callBoolean(host, "isMarked", 11L, 103L, TYPE_MANUAL),
+                "标记后该成长记录里程碑应判定为已标(时间线高亮依据)");
+    }
+
+    // ==================== 边界流:未标记时时间线不高亮 ====================
+
+    @Test
+    @DisplayName("边界流-1:未标记时时间线不高亮")
+    void 未标记时_时间线不高亮() {
+        Object host = contractHost();
+        assertTrue(!callBoolean(host, "isMarked", 11L, 104L, TYPE_MANUAL),
+                "未标记的成长记录里程碑应判定为未标(时间线不高亮)");
+    }
+
+    // ==================== 边界流:重复标幂等(SC-P-51 边界) ====================
+
+    @Test
+    @DisplayName("边界流-2:重复标同一里程碑幂等——返回同一 ID 不重复落库")
+    void 重复标同一里程碑_幂等返回同一Id() {
+        Object host = contractHost();
+        Long first = callLong(host, "markMilestone", 11L, 105L, TYPE_MANUAL);
+        assertNotNull(first, "首次标记应返回里程碑 ID");
+        // 重复标记同一 (memberId, recordId, milestoneType) → 幂等:返回同一 ID,不新增里程碑记录
+        Long second = callLong(host, "markMilestone", 11L, 105L, TYPE_MANUAL);
+        assertNotNull(second, "重复标记应返回里程碑 ID(幂等不返回 null)");
+        assertEquals(first, second,
+                "重复标同一里程碑必须幂等:返回同一里程碑 ID,不得产生重复标记记录(SC-P-51 边界)");
+    }
+
+    @Test
+    @DisplayName("边界流-3:重复标后仍只判定为已标(幂等不翻转状态)")
+    void 重复标后_仍判定为已标() {
+        Object host = contractHost();
+        callLong(host, "markMilestone", 11L, 106L, TYPE_SYSTEM);
+        callLong(host, "markMilestone", 11L, 106L, TYPE_SYSTEM);
+        assertTrue(callBoolean(host, "isMarked", 11L, 106L, TYPE_SYSTEM),
+                "重复标后里程碑仍应判定为已标(幂等,不因重复标记翻转状态)");
+    }
+
+    // ==================== 端点级契约:GrowthController 应暴露里程碑标记端点 ====================
+
+    @Test
+    @DisplayName("端点级:GrowthController 应暴露成长里程碑标记端点")
+    void growthController_暴露里程碑标记端点() {
+        Class<?> controller = loadClass(GROWTH_CONTROLLER_CLASS);
+        if (controller == null) {
+            fail("RED[growth.milestone.mark] GrowthController 类不存在,无法验证里程碑端点(§4.6)。");
+        }
+        boolean hasMilestoneEndpoint = false;
+        for (Method m : controller.getDeclaredMethods()) {
+            if (m.isAnnotationPresent(org.springframework.web.bind.annotation.PostMapping.class)) {
+                String[] paths = m.getAnnotation(org.springframework.web.bind.annotation.PostMapping.class).value();
+                for (String p : paths) {
+                    if (p.toLowerCase().contains("milestone")) {
+                        hasMilestoneEndpoint = true;
+                        break;
+                    }
+                }
+            }
+            if (hasMilestoneEndpoint) {
+                break;
+            }
+        }
+        assertTrue(hasMilestoneEndpoint,
+                "[growth.milestone.mark] GrowthController /api/growth 应暴露成长里程碑标记端点"
+                        + "(如 POST /api/growth/milestone/mark,§4.6/缺口 G-2);当前无任何 milestone 端点。");
+    }
+
+    // ==================== 权限流(不适用):家庭内部成员标记,归属由 JWT/currentMemberId 统一承载 ====================
+
+    @Test
+    @DisplayName("权限流:成长里程碑面向家庭内部成员,无独立角色权限分支,权限流不适用")
+    void 权限流_不适用() {
+        // 说明性用例:标记对象为家庭成员的成长记录,成员归属校验由 currentMemberId / JWT 上下文统一承载。
+        // SC-P-51 契约 AC 聚焦「系统/手动标里程碑→时间线高亮 + 重复标幂等」,无独立角色权限维度。
+        assertTrue(true, "权限流不适用:growth.milestone.mark 无独立角色权限分支。");
+    }
+
+    // ==================== 反射辅助(锚定宿主契约,避免编译期依赖不存在类) ====================
+
+    private Class<?> loadClass(String name) {
+        try {
+            return Class.forName(name, false, Thread.currentThread().getContextClassLoader());
+        } catch (ClassNotFoundException e) {
+            return null;
+        }
+    }
+
+    private Object contractHost() {
+        try {
+            Class<?> clazz = Class.forName(HOST_CLASS);
+            return clazz.getDeclaredConstructor().newInstance();
+        } catch (ClassNotFoundException e) {
+            fail("RED[growth.milestone.mark] 契约宿主 GrowthMilestoneService 未实现(实现未落地):"
+                    + e.getMessage());
+            throw new IllegalStateException("unreachable");
+        } catch (Exception e) {
+            fail("契约宿主 GrowthMilestoneService 实例化失败:" + e.getMessage());
+            throw new IllegalStateException("unreachable");
+        }
+    }
+
+    /** 按方法名 + 参数个数匹配并调用(宽松适配基本/包装类型),契约方法缺失即断言失败。 */
+    private Object call(Object host, String method, Object... args) {
+        for (Method m : host.getClass().getMethods()) {
+            if (m.getName().equals(method) && m.getParameterCount() == args.length) {
+                try {
+                    return m.invoke(host, args);
+                } catch (Exception e) {
+                    fail("契约方法 " + HOST_CLASS + "#" + method + " 调用失败:" + e.getMessage());
+                    throw new IllegalStateException("unreachable");
+                }
+            }
+        }
+        fail("RED[growth.milestone.mark] 契约方法 " + HOST_CLASS + "#" + method + " 未实现");
+        throw new IllegalStateException("unreachable");
+    }
+
+    private long callLong(Object host, String method, Object... args) {
+        Object r = call(host, method, args);
+        if (r instanceof Number) {
+            return ((Number) r).longValue();
+        }
+        fail("契约方法 " + method + " 应返回数值(里程碑 ID),实际 " + r);
+        throw new IllegalStateException("unreachable");
+    }
+
+    private boolean callBoolean(Object host, String method, Object... args) {
+        Object r = call(host, method, args);
+        if (r instanceof Boolean) {
+            return (Boolean) r;
+        }
+        fail("契约方法 " + method + " 应返回布尔,实际 " + r);
+        throw new IllegalStateException("unreachable");
+    }
+}