Explorar el Código

test(S-cfc-299): global.search.query RED contract test for unimplemented POST /api/search/global (SC-P-82 / API_REFERENCE 4.59.10)

Add GlobalSearchQueryContractTest in cfc-backend/src/test: pure Mockito/reflection, no Spring/DB.
Validates the contract for the aggregate global search endpoint (reports/plans/tasks/products
type buckets, family-scope filtering, empty-result non-error) that is still unimplemented.

Result: 10 tests run, 8 RED (implementation missing), 2 GREEN (status-quo anchors:
existing four source services + dispersed /api/diet/ingredients/search & /api/articles/list).
E2E Test Bot hace 6 días
padre
commit
77a4946254

+ 425 - 0
cfc-backend/src/test/java/com/etotem/cfc/unit/GlobalSearchQueryContractTest.java

@@ -0,0 +1,425 @@
+package com.etotem.cfc.unit;
+
+import com.etotem.cfc.common.Result;
+import com.etotem.cfc.controller.content.ArticleController;
+import com.etotem.cfc.controller.diet.DietIngredientController;
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Test;
+import org.springframework.web.bind.annotation.PostMapping;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RequestAttribute;
+
+import java.lang.reflect.Field;
+import java.lang.reflect.Method;
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.List;
+
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+import static org.junit.jupiter.api.Assertions.fail;
+
+/**
+ * 契约级单测(TDD-RED):能力键 {@code global.search.query}(SC-P-82 全局搜索)。
+ *
+ * <p><b>契约来源</b></p>
+ * <ul>
+ *   <li>需求:{@code tests/user-scenarios/应用场景总览.md} SC-P-82「全局搜索(报告/方案/任务/商品)」
+ *       —— 流程:搜 → 结果按类型分流;边界:越权结果过滤;空结果不报错。</li>
+ *   <li>设计:{@code docs/superpowers/api/API_REFERENCE.md} §4.59.10 契约缺口——
+ *       {@code POST /api/search/global} <b>不存在</b>(无 {@code SearchController}),
+ *       SC-P-82 {@code misc.globalSearch} 全局搜索(报告/方案/任务/商品)<b>未实现</b>;
+ *       搜索需求当前分散:{@code /api/diet/ingredients/search}(食材)、文章/商品搜索各自接口。</li>
+ * </ul>
+ *
+ * <p><b>实现现状(本分支 src/main 核实)</b>:
+ * <ul>
+ *   <li>{@code com.etotem.cfc.controller.SearchController} 类不存在(全库 0 引用);</li>
+ *   <li>{@code /api/search} 路由不存在;聚合搜索服务 {@code SearchService} 不存在;</li>
+ *   <li>唯一已落地的「搜索」实现为 {@code McpToolRegistry} 的 {@code search_activities} /
+ *       {@code search_articles} / {@code search_products} 三个 MCP 工具(见同批
+ *       {@code GlobalSearchScP82ContractTest}),非 {@code /api/search/global} 聚合端点。</li>
+ * </ul></p>
+ *
+ * <p><b>测试形态</b>:与已合入主链的同批 RED 契约测试({@code TeamProfitHookContractTest} /
+ * {@code TeamStarMultiplierContractTest} / {@code TeamProfitPipelineContractTest} /
+ * {@code FamilyJoinValidationRulesContractTest})一致——纯反射结构探测 + 字符串 {@code Class.forName},
+ * 不引用未来类名(保证可编译);无 Spring / 无 DB / 无外部服务。当前实现未落地,故断言失败(红)。</p>
+ *
+ * <p><b>GREEN 升级指引</b>:实现者新增 {@code SearchController}(类级
+ * {@code @RequestMapping("/api/search")} + 方法 {@code @PostMapping("/global")},返回
+ * {@code Result<...>},经 {@code @RequestAttribute("userId")} 取调用者)、聚合搜索服务
+ * {@code SearchService}、以及含「报告/方案/任务/商品」四类结果桶的结果载体后,本测试自动转绿;
+ * 届时可将结构探测升级为行为级 mock 验证(注入 mock 服务、直调 handler 断言四桶与 200 语义)。</p>
+ */
+class GlobalSearchQueryContractTest {
+
+    /** §4.59.10:聚合搜索端点契约路径(/api/search + /global) */
+    private static final String SEARCH_CONTROLLER = "com.etotem.cfc.controller.SearchController";
+    private static final String[] SEARCH_SERVICE_CANDIDATES = {
+            "com.etotem.cfc.service.SearchService",
+            "com.etotem.cfc.service.GlobalSearchService"
+    };
+
+    /** SC-P-82 类型分流四类结果桶(报告/方案/任务/商品) */
+    private static final String[] FOUR_BUCKETS = {"reports", "plans", "tasks", "products"};
+
+    /** 结果载体候选类名(实现落地时命名可能为 VO/Result/DTO,任一命中即可) */
+    private static final String[] RESULT_VO_CANDIDATES = {
+            "com.etotem.cfc.vo.GlobalSearchResult",
+            "com.etotem.cfc.vo.GlobalSearchResultVO",
+            "com.etotem.cfc.vo.SearchResult",
+            "com.etotem.cfc.dto.GlobalSearchResult",
+            "com.etotem.cfc.dto.GlobalSearchResultDTO",
+            "com.etotem.cfc.dto.SearchResult"
+    };
+
+    /** 请求载体候选类名(keyword 可空 + 分页) */
+    private static final String[] QUERY_DTO_CANDIDATES = {
+            "com.etotem.cfc.dto.GlobalSearchQuery",
+            "com.etotem.cfc.dto.GlobalSearchRequest",
+            "com.etotem.cfc.dto.SearchQuery",
+            "com.etotem.cfc.dto.SearchRequest"
+    };
+
+    // ------------------------------------------------------------------
+    // 正常流-1:SearchController 类应存在(§4.59.10 注明「无 SearchController」)
+    // ------------------------------------------------------------------
+
+    @Test
+    @DisplayName("正常流-1:SearchController 类应存在")
+    void searchController_classExists() {
+        assertNotNull(loadClass(SEARCH_CONTROLLER),
+                "[global.search.query] SearchController 类不存在:契约要求新增聚合搜索端点"
+                        + " POST /api/search/global(§4.59.10),覆盖 SC-P-82 报告/方案/任务/商品全局搜索。"
+                        + "实现未落地。");
+    }
+
+    // ------------------------------------------------------------------
+    // 正常流-2:路由 /api/search/global 应存在(类级 /api/search + 方法级 /global)
+    // ------------------------------------------------------------------
+
+    @Test
+    @DisplayName("正常流-2:SearchController 应映射 POST /api/search/global 路由")
+    void searchController_routesGlobalSearch() {
+        Class<?> clazz = loadClass(SEARCH_CONTROLLER);
+        if (clazz == null) {
+            fail("[global.search.query] SearchController 类不存在,无法验证 /api/search/global 路由(§4.59.10)。");
+        }
+        String classPath = classRequestMappingPath(clazz);
+        assertNotNull(classPath,
+                "[global.search.query] SearchController 应以 @RequestMapping(\"/api/search\") 声明类级路由前缀。");
+        assertTrue(classPath.contains("/api/search"),
+                "[global.search.query] SearchController 类级路由应为 /api/search,实际为 " + classPath + "。");
+
+        boolean hasGlobalHandler = false;
+        for (Method m : clazz.getDeclaredMethods()) {
+            PostMapping post = m.getAnnotation(PostMapping.class);
+            if (post == null) {
+                continue;
+            }
+            String[] value = post.value();
+            if (value.length > 0 && value[0].replaceFirst("^/", "").equalsIgnoreCase("global")) {
+                hasGlobalHandler = true;
+                break;
+            }
+        }
+        assertTrue(hasGlobalHandler,
+                "[global.search.query] SearchController 应提供 @PostMapping(\"/global\") 处理器"
+                        + "(组合出 POST /api/search/global,§4.59.10)。");
+    }
+
+    // ------------------------------------------------------------------
+    // 正常流-3:globalSearch handler 应返回统一 Result<T>(项目规范:统一 Result)
+    // ------------------------------------------------------------------
+
+    @Test
+    @DisplayName("正常流-3:/global handler 应返回统一 Result<T> 且取调用者 userId")
+    void globalSearchHandler_returnsResultAndTakesUserId() {
+        Class<?> clazz = loadClass(SEARCH_CONTROLLER);
+        if (clazz == null) {
+            fail("[global.search.query] SearchController 类不存在,无法验证 handler 契约(§4.59.10)。");
+        }
+        Method handler = null;
+        for (Method m : clazz.getDeclaredMethods()) {
+            PostMapping post = m.getAnnotation(PostMapping.class);
+            if (post != null && post.value().length > 0
+                    && post.value()[0].replaceFirst("^/", "").equalsIgnoreCase("global")) {
+                handler = m;
+                break;
+            }
+        }
+        if (handler == null) {
+            fail("[global.search.query] 未找到 /global 处理器方法,无法验证 handler 契约。");
+        }
+        Class<?> returnType = handler.getReturnType();
+        assertTrue(Result.class.isAssignableFrom(returnType),
+                "[global.search.query] /global handler 应返回统一 Result<T>(项目接口规范),实际返回 "
+                        + returnType.getName() + "。");
+
+        boolean takesRequestAttribute = false;
+        for (java.lang.annotation.Annotation[] anns : handler.getParameterAnnotations()) {
+            for (java.lang.annotation.Annotation a : anns) {
+                if (a instanceof RequestAttribute) {
+                    takesRequestAttribute = true;
+                    break;
+                }
+            }
+        }
+        assertTrue(takesRequestAttribute,
+                "[global.search.query] /global handler 应通过 @RequestAttribute 取调用者上下文"
+                        + "(userId;越权结果过滤的数据维度,见 §4.59.10 与 JwtInterceptor 约定)。");
+    }
+
+    // ------------------------------------------------------------------
+    // 正常流-4:聚合搜索服务应存在并注入 SearchController
+    // ------------------------------------------------------------------
+
+    @Test
+    @DisplayName("正常流-4:聚合搜索服务 SearchService/GlobalSearchService 应存在并注入 SearchController")
+    void searchService_classExistsAndInjected() {
+        Class<?> service = null;
+        for (String name : SEARCH_SERVICE_CANDIDATES) {
+            Class<?> c = loadClass(name);
+            if (c != null) {
+                service = c;
+                break;
+            }
+        }
+        assertNotNull(service,
+                "[global.search.query] 聚合搜索服务不存在:契约要求 SearchService(或 GlobalSearchService)"
+                        + "聚合报告/方案/任务/商品四类来源(§4.59.10「新建聚合搜索」)。实现未落地。");
+
+        Class<?> controller = loadClass(SEARCH_CONTROLLER);
+        if (controller == null) {
+            fail("[global.search.query] SearchController 类不存在,无法验证服务注入。");
+        }
+        boolean injected = false;
+        for (Field f : controller.getDeclaredFields()) {
+            if (service.isAssignableFrom(f.getType())) {
+                injected = true;
+                break;
+            }
+        }
+        assertTrue(injected,
+                "[global.search.query] SearchController 未注入聚合搜索服务 " + service.getSimpleName()
+                        + ":应在 /global 链路中调用聚合搜索(§4.59.10)。");
+    }
+
+    // ------------------------------------------------------------------
+    // 正常流-5:结果载体应承载「报告/方案/任务/商品」四类桶(类型分流)
+    // ------------------------------------------------------------------
+
+    @Test
+    @DisplayName("正常流-5:结果载体应含 reports/plans/tasks/products 四类结果桶(类型分流)")
+    void searchResultCarrier_carriesFourTypeBuckets() {
+        Class<?> carrier = null;
+        for (String name : RESULT_VO_CANDIDATES) {
+            Class<?> c = loadClass(name);
+            if (c != null) {
+                carrier = c;
+                break;
+            }
+        }
+        assertNotNull(carrier,
+                "[global.search.query] 全局搜索结果载体不存在:契约要求结果按类型分流(SC-P-82),"
+                        + "结果对象应含报告/方案/任务/商品四类桶(候选类名见 RESULT_VO_CANDIDATES)。实现未落地。");
+
+        List<String> fieldNames = new ArrayList<>();
+        for (Class<?> c = carrier; c != null && c != Object.class; c = c.getSuperclass()) {
+            for (Field f : c.getDeclaredFields()) {
+                fieldNames.add(f.getName());
+            }
+        }
+        List<String> missing = new ArrayList<>();
+        for (String bucket : FOUR_BUCKETS) {
+            if (!fieldNames.contains(bucket)) {
+                missing.add(bucket);
+            }
+        }
+        assertTrue(missing.isEmpty(),
+                "[global.search.query] 结果载体 " + carrier.getSimpleName()
+                        + " 缺少结果桶字段:" + missing + "(SC-P-82 要求报告/方案/任务/商品四类分流)。");
+    }
+
+    // ------------------------------------------------------------------
+    // 边界流-1:空关键词/无匹配 → 空结果不报错(返回 Result.success 语义,非异常/错误码)
+    // ------------------------------------------------------------------
+
+    @Test
+    @DisplayName("边界流-1:聚合搜索入口应返回 Result(空结果以 200 语义承载,不抛错)")
+    void emptyResult_returnsSuccessSemantics_notError() {
+        Class<?> service = null;
+        for (String name : SEARCH_SERVICE_CANDIDATES) {
+            Class<?> c = loadClass(name);
+            if (c != null) {
+                service = c;
+                break;
+            }
+        }
+        if (service == null) {
+            fail("[global.search.query] 聚合搜索服务不存在:SC-P-82「空结果不报错」要求搜索入口以 "
+                    + "Result.success 空桶承载空结果,而非抛异常或返回错误码(§4.59.10)。实现未落地。");
+        }
+        Method search = null;
+        for (Method m : service.getDeclaredMethods()) {
+            if (m.getName().equalsIgnoreCase("search") || m.getName().equalsIgnoreCase("globalSearch")) {
+                search = m;
+                break;
+            }
+        }
+        if (search == null) {
+            fail("[global.search.query] 聚合搜索服务缺少 search/globalSearch 入口方法:"
+                    + "空结果不报错(SC-P-82)要求存在统一聚合搜索入口。实现未落地。");
+        }
+        Class<?> returnType = search.getReturnType();
+        assertTrue(Result.class.isAssignableFrom(returnType),
+                "[global.search.query] 聚合搜索入口 " + service.getSimpleName() + "." + search.getName()
+                        + " 应返回 Result<T>(空结果不报错:以 200 语义返回空桶,SC-P-82),实际返回 "
+                        + returnType.getName() + "。");
+    }
+
+    // ------------------------------------------------------------------
+    // 边界流-2:请求载体应支持可空 keyword 与分页(空关键词不报错、结果可分页)
+    // ------------------------------------------------------------------
+
+    @Test
+    @DisplayName("边界流-2:请求载体应含 keyword(可空)与分页字段 page/pageSize")
+    void searchQueryCarrier_supportsNullableKeywordAndPaging() {
+        Class<?> query = null;
+        for (String name : QUERY_DTO_CANDIDATES) {
+            Class<?> c = loadClass(name);
+            if (c != null) {
+                query = c;
+                break;
+            }
+        }
+        assertNotNull(query,
+                "[global.search.query] 全局搜索请求载体不存在:契约要求请求对象承载 keyword(可空)"
+                        + "与分页 page/pageSize(空关键词不报错、结果可分页,SC-P-82;§4.59.10 POST 体)。实现未落地。");
+
+        List<String> fieldNames = new ArrayList<>();
+        for (Class<?> c = query; c != null && c != Object.class; c = c.getSuperclass()) {
+            for (Field f : c.getDeclaredFields()) {
+                fieldNames.add(f.getName());
+            }
+        }
+        List<String> missing = new ArrayList<>();
+        for (String need : Arrays.asList("keyword", "page", "pageSize")) {
+            if (!fieldNames.contains(need)) {
+                missing.add(need);
+            }
+        }
+        assertTrue(missing.isEmpty(),
+                "[global.search.query] 请求载体 " + query.getSimpleName() + " 缺少字段:" + missing
+                        + "(keyword 可空;page/pageSize 分页)。");
+    }
+
+    // ------------------------------------------------------------------
+    // 权限流-1:聚合入口应携带调用者/家庭维度(越权结果过滤)
+    // ------------------------------------------------------------------
+
+    @Test
+    @DisplayName("权限流-1:聚合搜索入口应携带 userId/familyId/memberId 维度以过滤越权结果")
+    void searchService_entryCarriesFamilyScopeForPrivacyFilter() {
+        Class<?> service = null;
+        for (String name : SEARCH_SERVICE_CANDIDATES) {
+            Class<?> c = loadClass(name);
+            if (c != null) {
+                service = c;
+                break;
+            }
+        }
+        if (service == null) {
+            fail("[global.search.query] 聚合搜索服务不存在:SC-P-82「越权结果过滤」要求搜索入口携带"
+                    + " userId/familyId/memberId 维度,报告/方案/任务桶按调用者家庭/成员范围过滤(§4.59.10)。"
+                    + "实现未落地。");
+        }
+        Method search = null;
+        for (Method m : service.getDeclaredMethods()) {
+            if (m.getName().equalsIgnoreCase("search") || m.getName().equalsIgnoreCase("globalSearch")) {
+                search = m;
+                break;
+            }
+        }
+        if (search == null) {
+            fail("[global.search.query] 聚合搜索服务缺少 search/globalSearch 入口方法:"
+                    + "越权结果过滤(SC-P-82)需在入口参数上体现调用者/家庭维度。实现未落地。");
+        }
+        boolean carriesScope = false;
+        for (Class<?> pt : search.getParameterTypes()) {
+            if (pt == Long.class || pt == long.class) {
+                carriesScope = true;
+                break;
+            }
+        }
+        assertTrue(carriesScope,
+                "[global.search.query] 聚合搜索入口 " + service.getSimpleName() + "." + search.getName()
+                        + " 参数未携带 userId/familyId/memberId(Long)维度:SC-P-82「越权结果过滤」要求"
+                        + "按调用者家庭/成员范围过滤报告/方案/任务结果。");
+    }
+
+    // ------------------------------------------------------------------
+    // 权限流-2:现状锚点——四类桶的自然数据源服务均已存在(供实现复用,非红)
+    // ------------------------------------------------------------------
+
+    @Test
+    @DisplayName("权限流-2:报告/方案/任务/商品四类来源服务现状已存在(复用基础)")
+    void fourSourceServices_alreadyExist_asReuseBasis() {
+        for (String svc : Arrays.asList(
+                "com.etotem.cfc.service.HealthReportService",
+                "com.etotem.cfc.service.GrowthPlanService",
+                "com.etotem.cfc.service.GrowthTaskService",
+                "com.etotem.cfc.service.ProductService")) {
+            assertNotNull(loadClass(svc),
+                    "[global.search.query] 四类搜索来源服务缺失:" + svc + "(实现聚合时应复用现有服务)。");
+        }
+    }
+
+    // ------------------------------------------------------------------
+    // 说明性锚点(GREEN,非红):现状分散搜索入口 /api/diet/ingredients/search 与 /api/articles/list
+    // 均已存在——§4.59.10 记载「搜索需求当前分散」的现状,供 GREEN 实现统一收敛。
+    // ------------------------------------------------------------------
+
+    @Test
+    @DisplayName("锚点:现状分散搜索入口(食材 /api/diet/ingredients/search、文章 /api/articles/list)已存在")
+    void dispersedSearchEntryPoints_currentlyExist() {
+        assertTrue(hasMappingRoute(DietIngredientController.class, "search"),
+                "[global.search.query] 现状锚点失败:DietIngredientController 应已存在 /search(食材搜索)入口。");
+        assertTrue(hasMappingRoute(ArticleController.class, "list"),
+                "[global.search.query] 现状锚点失败:ArticleController 应已存在 /list(文章搜索)入口。");
+    }
+
+    // ------------------------------------------------------------------
+    // 反射辅助
+    // ------------------------------------------------------------------
+
+    private Class<?> loadClass(String name) {
+        try {
+            return Class.forName(name, false, Thread.currentThread().getContextClassLoader());
+        } catch (ClassNotFoundException e) {
+            return null;
+        }
+    }
+
+    /** 取类级 @RequestMapping 的 value[0](无则 null) */
+    private static String classRequestMappingPath(Class<?> clazz) {
+        RequestMapping rm = clazz.getAnnotation(RequestMapping.class);
+        if (rm == null || rm.value().length == 0) {
+            return null;
+        }
+        return rm.value()[0];
+    }
+
+    /** 判断控制器是否已映射某 @PostMapping 子路径(现状锚点用) */
+    private static boolean hasMappingRoute(Class<?> controller, String subPath) {
+        for (Method m : controller.getDeclaredMethods()) {
+            PostMapping post = m.getAnnotation(PostMapping.class);
+            if (post != null && post.value().length > 0
+                    && post.value()[0].replaceFirst("^/", "").equalsIgnoreCase(subPath)) {
+                return true;
+            }
+        }
+        return false;
+    }
+}