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

Merge branch 'task/S-cfc-299' (S-cfc-299 global.search.query RED 契约单测) into cfclub

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

+ 243 - 0
cfc-backend/src/test/java/com/etotem/cfc/unit/GlobalSearchQueryScP82RestContractTest.java

@@ -0,0 +1,243 @@
+package com.etotem.cfc.unit;
+
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Test;
+
+import java.lang.reflect.Method;
+import java.util.Map;
+
+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 global.search.query},任务号 S-cfc-299,业务域 L)。
+ *
+ * <p><b>需求锚点(SC-P-82)</b>:{@code tests/user-scenarios/应用场景总览.md}
+ * 「SC-P-82 · 全局搜索(报告/方案/任务/商品)」——目标:快速定位;流程:搜 → 结果按类型分流;
+ * 边界:<b>越权结果过滤</b>;<b>空结果不报错</b>。角色:家长(能登录用户)。</p>
+ *
+ * <p><b>设计锚点(API_REFERENCE §4.59.10 契约缺口)</b>:
+ * {@code docs/superpowers/api/API_REFERENCE.md} §4.59.10 明确登记
+ * {@code POST /api/search/global} <b>不存在(无 SearchController)</b>,
+ * SC-P-82 全局搜索(报告/方案/任务/商品)<b>未实现</b>;搜索需求当前分散在
+ * {@code /api/diet/ingredients/search}(食材)、{@code /api/articles/list}(文章)等各自接口,
+ * 无统一的聚合分流入口。待实现时须新建聚合搜索端点并在此登记。</p>
+ *
+ * <p><b>被校验的契约行为(实现方按此落地)</b></p>
+ * <ul>
+ *   <li><b>宿主服务类</b> {@code com.etotem.cfc.service.GlobalSearchService}:
+ *       聚合 报告(HealthReportService) / 方案(GrowthPlanService) / 任务(TaskService) / 商品(ProductService)
+ *       四类结果,按类型分流返回;越权结果按家庭维度过滤;空结果返回空集合而非报错。</li>
+ *   <li><b>REST 端点</b> {@code com.etotem.cfc.controller.search.SearchController}
+ *       (或等价控制器):暴露 {@code POST /api/search/global}(统一 {@code @PostMapping} 约定,
+ *       禁止 GET/PUT/DELETE),请求体含 {@code keyword} + 登录用户家庭上下文。</li>
+ * </ul>
+ *
+ * <p><b>RED 预期</b>:{@code GlobalSearchService} 与 {@code /api/search/global} 端点当前<b>均未落地</b>
+ * (全库 0 引用,无 SearchController、无 GlobalSearchService),本测试以「反射结构契约」探测实现缺失:
+ * 测试能编译、能运行,但在反射探测处断言失败(红),失败原文清晰可贴。
+ * 实现方创建 {@code GlobalSearchService}(含 {@code globalSearch(String keyword, Long userId, Long familyId)}
+ * 入口 + 按类型分流的 4 类结果键)与 {@code SearchController}({@code @PostMapping("/global")})后,
+ * 本测试自动转绿;届时可将结构探测升级为行为级 mock 验证({@code verify(healthReportService)...})。</p>
+ *
+ * <p><b>测试范围</b>:纯契约级单测,反射探测宿主类/方法存在性(无 Spring / 无 DB / 无真实外部服务依赖)。
+ * 与已合入主链的 {@code GlobalSearchScP82ContractTest}(MCP 工具级 search_activities/articles/products)
+ * 互补:本类锚定 <b>REST 端点 /api/search/global 聚合分流</b> 契约(API §4.59.10 登记的未实现端点),
+ * 避免同名,类名取 {@code GlobalSearchQueryScP82RestContractTest}。</p>
+ */
+class GlobalSearchQueryScP82RestContractTest {
+
+    /** 契约宿主服务类(未实现):聚合报告/方案/任务/商品四类搜索,按类型分流 + 越权过滤 + 空结果不报错。 */
+    private static final String HOST_SERVICE = "com.etotem.cfc.service.GlobalSearchService";
+
+    /** 契约宿主控制器类(未实现):暴露 POST /api/search/global。 */
+    private static final String HOST_CONTROLLER = "com.etotem.cfc.controller.search.SearchController";
+
+    /** 契约要求的主入口方法名(实现方须提供)。 */
+    private static final String METHOD_GLOBAL_SEARCH = "globalSearch";
+
+    /** 结果须按类型分流的 4 类键(SC-P-82「结果按类型分流」)。 */
+    private static final String[] RESULT_TYPE_KEYS = {"reports", "plans", "tasks", "products"};
+
+    // ------------------------------------------------------------------
+    // 正常流-1:宿主服务类 GlobalSearchService 应存在
+    // ------------------------------------------------------------------
+
+    @Test
+    @DisplayName("正常流-1:GlobalSearchService 服务类应存在(SC-P-82 聚合搜索宿主)")
+    void globalSearchService_classExists() {
+        Class<?> clazz = loadClass(HOST_SERVICE);
+        assertNotNull(clazz,
+                "[global.search.query] GlobalSearchService 类不存在:契约要求聚合 报告/方案/任务/商品 四类"
+                        + "搜索并按类型分流(SC-P-82),当前实现未落地(API §4.59.10 登记 /api/search/global 不存在)。");
+    }
+
+    // ------------------------------------------------------------------
+    // 正常流-2:globalSearch 主入口方法应存在(keyword + 用户家庭上下文)
+    // ------------------------------------------------------------------
+
+    @Test
+    @DisplayName("正常流-2:GlobalSearchService.globalSearch(keyword, userId, familyId) 入口应存在")
+    void globalSearchService_hasGlobalSearchEntry() {
+        Class<?> clazz = loadClass(HOST_SERVICE);
+        if (clazz == null) {
+            fail("[global.search.query] GlobalSearchService 类不存在,无法验证 globalSearch 入口(SC-P-82)。");
+        }
+        boolean found = false;
+        for (Method m : clazz.getDeclaredMethods()) {
+            if (!METHOD_GLOBAL_SEARCH.equals(m.getName())) {
+                continue;
+            }
+            // 宽松匹配:globalSearch(String keyword, Long userId, Long familyId) 或含 keyword 的多参重载
+            Class<?>[] pts = m.getParameterTypes();
+            if (pts.length >= 1 && String.class.isAssignableFrom(pts[0])) {
+                found = true;
+                break;
+            }
+        }
+        assertTrue(found,
+                "[global.search.query] GlobalSearchService 应提供 globalSearch(String keyword, ...) 方法"
+                        + "作为聚合搜索入口(SC-P-82「搜 → 结果按类型分流」)。");
+    }
+
+    // ------------------------------------------------------------------
+    // 正常流-3:结果应按类型分流的 4 类键(reports/plans/tasks/products)
+    // ------------------------------------------------------------------
+
+    @Test
+    @DisplayName("正常流-3:globalSearch 返回 Map 结果须含 4 类分流键 reports/plans/tasks/products")
+    void globalSearchResult_bundlesFourTypeKeys() {
+        Class<?> clazz = loadClass(HOST_SERVICE);
+        if (clazz == null) {
+            fail("[global.search.query] GlobalSearchService 类不存在,无法验证按类型分流结果结构(SC-P-82)。");
+        }
+        // 定位 globalSearch 方法,检查其返回泛型是否为 Map(含 4 类分流键由实现填充,结构探测 Map 返回类型)
+        Method entry = findGlobalSearchMethod(clazz);
+        if (entry == null) {
+            fail("[global.search.query] GlobalSearchService.globalSearch 入口未实现(SC-P-82)。");
+        }
+        // 结构探测:返回类型应为 Map(4 类分流键 reports/plans/tasks/products 由实现填充)
+        boolean returnsMap = Map.class.isAssignableFrom(entry.getReturnType());
+        assertTrue(returnsMap,
+                "[global.search.query] globalSearch 应返回 Map(按类型分流键 reports/plans/tasks/products,"
+                        + "共 " + RESULT_TYPE_KEYS.length + " 类,见 SC-P-82「结果按类型分流」)。");
+    }
+
+    // ------------------------------------------------------------------
+    // 边界流:空结果不报错(globalSearch 无匹配须返回空集合,不抛异常/null)
+    // ------------------------------------------------------------------
+
+    @Test
+    @DisplayName("边界流-1:空结果不报错——globalSearch 无匹配返回空集合(非 null、不抛异常)")
+    void emptyKeyword_noMatch_returnsEmptyCollections_notError() {
+        Class<?> clazz = loadClass(HOST_SERVICE);
+        if (clazz == null) {
+            fail("[global.search.query] GlobalSearchService 类不存在,无法验证「空结果不报错」边界(SC-P-82)。");
+        }
+        // 结构探测:入口存在即可断言契约(无匹配返回空集合行为级断言待 GREEN 阶段以 mock 升级)
+        Method entry = findGlobalSearchMethod(clazz);
+        assertNotNull(entry,
+                "[global.search.query] globalSearch 入口未实现:契约要求空结果返回空集合而非报错(SC-P-82 边界)。");
+        assertTrue(entry.getReturnType() == Map.class || Map.class.isAssignableFrom(entry.getReturnType()),
+                "空结果不报错:globalSearch 须返回 Map(4 类键各为空 List),而非抛异常或返回 null。");
+    }
+
+    // ------------------------------------------------------------------
+    // 越权结果过滤:globalSearch 须带家庭上下文参数(userId + familyId)做越权过滤
+    // ------------------------------------------------------------------
+
+    @Test
+    @DisplayName("越权流-1:globalSearch 须携带 userId+familyId 上下文做越权结果过滤(SC-P-82 边界)")
+    void permissionFlow_globalSearchCarriesFamilyContext() {
+        Class<?> clazz = loadClass(HOST_SERVICE);
+        if (clazz == null) {
+            fail("[global.search.query] GlobalSearchService 类不存在,无法验证越权过滤上下文(SC-P-82)。");
+        }
+        Method entry = findGlobalSearchMethod(clazz);
+        if (entry == null) {
+            fail("[global.search.query] globalSearch 入口未实现,无法验证越权过滤上下文(SC-P-82)。");
+        }
+        Class<?>[] pts = entry.getParameterTypes();
+        boolean hasLongContext = false;
+        for (Class<?> p : pts) {
+            if (p == Long.class || p == Long.TYPE) {
+                hasLongContext = true;
+                break;
+            }
+        }
+        assertTrue(hasLongContext,
+                "[global.search.query] globalSearch 须含 Long 型上下文参数(userId 或 familyId)"
+                        + "以做越权结果过滤(SC-P-82「越权结果过滤」:跨家庭结果不返回)。");
+    }
+
+    // ------------------------------------------------------------------
+    // 正常流-4:REST 端点 SearchController + POST /api/search/global 应存在
+    // ------------------------------------------------------------------
+
+    @Test
+    @DisplayName("正常流-4:SearchController 控制器类应存在(POST /api/search/global 宿主)")
+    void searchController_classExists() {
+        Class<?> clazz = loadClass(HOST_CONTROLLER);
+        assertNotNull(clazz,
+                "[global.search.query] SearchController 类不存在:契约要求 POST /api/search/global 端点"
+                        + "(统一 @PostMapping 约定,API §4.59.10 登记的未实现端点)。实现未落地。");
+    }
+
+    @Test
+    @DisplayName("正常流-5:SearchController 应暴露 POST /global(即 /api/search/global)")
+    void searchController_exposesPostMappingGlobal() {
+        Class<?> clazz = loadClass(HOST_CONTROLLER);
+        if (clazz == null) {
+            fail("[global.search.query] SearchController 类不存在,无法验证 /api/search/global 端点映射。");
+        }
+        // 探测类级 @RequestMapping(含 "search")+ 方法级 @PostMapping("/global")
+        boolean found = false;
+        for (Method m : clazz.getDeclaredMethods()) {
+            for (java.lang.annotation.Annotation a : m.getAnnotations()) {
+                if (a instanceof org.springframework.web.bind.annotation.PostMapping) {
+                    org.springframework.web.bind.annotation.PostMapping pma =
+                            (org.springframework.web.bind.annotation.PostMapping) a;
+                    String[] paths = pma.value().length == 0 ? pma.path() : pma.value();
+                    for (String p : paths) {
+                        if ("global".equals(p.trim()) || "/global".equals(p.trim())) {
+                            found = true;
+                        }
+                    }
+                }
+            }
+            if (found) {
+                break;
+            }
+        }
+        assertTrue(found,
+                "[global.search.query] SearchController 应含 @PostMapping(\"/global\") 方法映射"
+                        + "(类级 @RequestMapping(\"/api/search\") 组合为 POST /api/search/global,"
+                        + "API §4.59.10 登记的未实现端点;统一 POST 约定)。");
+    }
+
+    // ------------------------------------------------------------------
+    // 反射辅助
+    // ------------------------------------------------------------------
+
+    private Class<?> loadClass(String name) {
+        try {
+            return Class.forName(name, false, Thread.currentThread().getContextClassLoader());
+        } catch (ClassNotFoundException e) {
+            return null;
+        }
+    }
+
+    /** 定位 globalSearch 方法(任一含 String keyword 首参的重载),未实现返回 null。 */
+    private Method findGlobalSearchMethod(Class<?> clazz) {
+        for (Method m : clazz.getDeclaredMethods()) {
+            if (METHOD_GLOBAL_SEARCH.equals(m.getName())) {
+                Class<?>[] pts = m.getParameterTypes();
+                if (pts.length >= 1 && String.class.isAssignableFrom(pts[0])) {
+                    return m;
+                }
+            }
+        }
+        return null;
+    }
+}