Sfoglia il codice sorgente

test(S-cfc-248): RED 契约单测 ai.coach.recommend(SC-B-07 推荐与采纳)

契约级单测 CoachRecommendContractTest:AI 教练按五维短板/报告生成任务/心愿/
饮食推荐并一键采纳(分析→推荐→采纳)。宿主 CoachRecommendService 未实现、契约端点
CoachRecommendController 未落地、coach_recommend_log 表缺失 → 13/13 红(预期 RED)。
只新增 cfc-backend/src/test,不改 src/main。GREEN 阶段按 javadoc 契约方法签名落地即可转绿。
Sisyphus 3 giorni fa
parent
commit
60a3344014

+ 449 - 0
cfc-backend/src/test/java/com/etotem/cfc/unit/CoachRecommendContractTest.java

@@ -0,0 +1,449 @@
+package com.etotem.cfc.unit;
+
+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 java.io.InputStream;
+import java.lang.reflect.Field;
+import java.lang.reflect.Method;
+import java.nio.charset.StandardCharsets;
+import java.util.HashSet;
+import java.util.List;
+import java.util.Map;
+import java.util.Scanner;
+import java.util.Set;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+import static org.junit.jupiter.api.Assertions.fail;
+
+/**
+ * 契约级单测:AI 教练个性化任务/饮食推荐与采纳(能力键 {@code ai.coach.recommend},单元 ai.coach)。
+ *
+ * <p><b>契约溯源</b></p>
+ * <ul>
+ *   <li>需求:{@code tests/user-scenarios/应用场景总览.md} SC-B-07(个性化任务/饮食推荐与采纳,
+ *       对应建议能力键 {@code coach.recommend.adopt},见
+ *       {@code docs/tdd/orchestration/task-incentive-kickoff-20261107.md})——按五维短板/报告
+ *       推荐任务、心愿、饮食,并一键采纳为正式任务;边界:无报告降级、过敏/忌口排除、重复推荐幂等。</li>
+ *   <li>设计:{@code docs/superpowers/api/API_REFERENCE.md} §4.11(饮食推荐)/§4.12(内容)/
+ *       §4.64.5(营养/任务推荐与采纳 SC-B-07)+ §3「开工包前置风险」——「采纳→任务写回」规则
+ *       由本契约定义:饮食推荐复用 {@code FoodRecommendController}(食材推荐指数/戒备食材,
+ *       推荐指数 &lt; 0 即忌口/过敏源),采纳写回 {@code TaskController /api/tasks/create}(
+ *       {@code TaskService.createTask})或 {@code WishController /api/wishes/create}。</li>
+ * </ul>
+ *
+ * <p><b>宿主契约(TDD-RED 锚点)</b>:{@code com.etotem.cfc.service.CoachRecommendService} ——
+ * SC-B-07「分析→推荐→采纳」规划的服务类,当前 src/main <b>尚未实现</b>(全库 0 引用;
+ * 无 CoachRecommendService / CoachRecommendController / coach_recommend_log 表)。
+ * 本测试通过反射锚定宿主契约方法(避免直接 import 不存在类导致编译失败),运行时宿主类缺失
+ * 即断言失败(红),暴露「实现未落地」这一真实缺陷;GREEN 落地后转为验证真实行为。</p>
+ *
+ * <p><b>契约方法签名(实现方按此落地)</b></p>
+ * <ul>
+ *   <li>{@code Map<String,Object> analyzeBasis(Long memberId, Long reportId)}
+ *       —— 分析推荐依据:{@code reportAvailable}(Boolean,是否存在成长报告)、
+ *       {@code weakDimensions}(List&lt;String&gt;,五维短板,根码见
+ *       {@code DimensionCodeConstants} body/mind/wisdom/action/wealth)、
+ *       {@code basis}(String:{@code report} | {@code fiveDim} | {@code generic}——
+ *       无报告且无五维数据 → {@code generic} 降级);</li>
+ *   <li>{@code List<Map<String,Object>> recommend(Long memberId, Long reportId)}
+ *       —— 生成推荐清单:每项含 {@code recoId}、{@code type}(task|wish|diet)、
+ *       {@code title}、{@code reason}(其中 diet 项含 {@code foodIds} 且已排除过敏/忌口食材);
+ *       无报告/>无五维数据时不抛异常、不返回 null,降级为通用推荐(依据不足提示);</li>
+ *   <li>{@code Map<String,Object> adopt(Long userId, Long memberId, String type, String recoId)}
+ *       —— 一键采纳:{@code type=task} 经 {@code TaskService.createTask} 写回,{@code type=wish}
+ *       经 {@code WishService} 创建流程写回;返回 {@code targetType}(task|wish)与
+ *       {@code targetId}(新任务/心愿 id);越权(memberId 不在 userId 家庭)拒绝/抛异常;</li>
+ *   <li>{@code List<Long> excludedFoodIds(Long memberId)}
+ *       —— 过敏/忌口排除清单:由 {@code FoodRecommendService} 戒备食材
+ *       (推荐指数 &lt; 0,即 FoodRecommendController 戒備口径)归一;</li>
+ *   <li>{@code Boolean isAdopted(Long memberId, String type, String recoId)}
+ *       —— 幂等留痕:同一 (memberId,type,recoId) 曾采纳 → true(不重复建任务/心愿);</li>
+ *   <li>{@code Boolean hasFamilyAccess(Long userId, Long memberId)}
+ *       —— 权限门禁:memberId 属于 userId 家庭或为 userId 自身 → true。</li>
+ * </ul>
+ *
+ * <p><b>契约端点(controller 结构契约)</b>:{@code com.etotem.cfc.controller.ai.CoachRecommendController}
+ * 类级 {@code @RequestMapping("/api/ai/coach/recommend")},方法级
+ * {@code @PostMapping("/recommend")}(生成推荐)与 {@code @PostMapping("/adopt")}(一键采纳),
+ * 注入 {@code CoachRecommendService};幂等留痕建表 {@code coach_recommend_log}(schema.sql)。</p>
+ *
+ * <p><b>测试范围</b>:纯契约级单测,仅 JUnit + 反射,无 Spring / 无 DB / 无真实微信 / 无外部服务;
+ * 权限流适用(家长代管成员推荐/采纳存在跨家庭越权维度),按三类流覆盖。</p>
+ *
+ * <p><b>RED 预期</b>:宿主 {@code CoachRecommendService} 未实现——全部宿主用例在反射探测处失败(红),
+ * 断言原文「RED[ai.coach.recommend] 契约宿主 CoachRecommendService 未实现」;
+ * controller 与 coach_recommend_log 结构用例分别以「契约端点未落地」「schema.sql 缺少
+ * coach_recommend_log」独立失败。</p>
+ */
+class CoachRecommendContractTest {
+
+    /** 规格设计宿主服务类(未实现)。 */
+    private static final String HOST_CLASS = "com.etotem.cfc.service.CoachRecommendService";
+
+    /** 契约端点 Controller 类(未实现)。 */
+    private static final String CONTROLLER_CLASS = "com.etotem.cfc.controller.ai.CoachRecommendController";
+
+    /** 契约端点类级路径与幂等留痕表。 */
+    private static final String ENDPOINT_BASE = "/api/ai/coach/recommend";
+    private static final String IDEMPOTENT_LOG_TABLE = "coach_recommend_log";
+
+    /** 五维短板根码(DimensionCodeConstants,统一维度体系)。 */
+    private static final String DIM_BODY = "body";
+    private static final String DIM_MIND = "mind";
+    private static final String DIM_WISDOM = "wisdom";
+    private static final String DIM_ACTION = "action";
+    private static final String DIM_WEALTH = "wealth";
+
+    // ==================== 正常流:宿主服务类 + 分析依据 ====================
+
+    @Test
+    @DisplayName("正常流-1:CoachRecommendService 契约宿主应已实现")
+    void hostService_classExists() {
+        assertNotNull(contractHost(),
+                "RED[ai.coach.recommend] 契约宿主 CoachRecommendService 未实现(实现未落地):"
+                        + "SC-B-07 分析→推荐→采纳 服务未落地,契约无法满足。");
+    }
+
+    @Test
+    @DisplayName("正常流-2:有报告时 analyzeBasis 应标记 reportAvailable 且 basis=report")
+    void analyzeBasis_withReport_marksReportAvailable() {
+        Map<String, Object> basis = callMap(contractHost(), "analyzeBasis", 11L, 1001L);
+        assertNotNull(basis, "analyzeBasis 应返回依据 Map");
+        assertEquals(Boolean.TRUE, basis.get("reportAvailable"),
+                "存在成长报告(reportId=1001)时 reportAvailable 必须为 true");
+        assertEquals("report", basis.get("basis"),
+                "有报告时推荐依据以报告为准(basis=report)");
+    }
+
+    @Test
+    @DisplayName("正常流-3:无报告但存在五维数据时 basis=fiveDim 且短板非空")
+    void analyzeBasis_withoutReport_usesFiveDimWeakness() {
+        Map<String, Object> basis = callMap(contractHost(), "analyzeBasis", 11L, null);
+        assertNotNull(basis, "analyzeBasis 应返回依据 Map");
+        assertEquals(Boolean.FALSE, basis.get("reportAvailable"), "无报告时应标记报告不可用");
+        assertEquals("fiveDim", basis.get("basis"), "五维短板数据存在时应以五维为依据");
+        Object weak = basis.get("weakDimensions");
+        assertNotNull(weak, "五维短板列表不得为 null");
+        assertEquals(false, ((List<?>) weak).isEmpty(),
+                "存在五维数据时 weakDimensions 不得为空");
+        for (Object dim : (List<?>) weak) {
+            assertTrue(ROOT_DIMS.contains(String.valueOf(dim)),
+                    "短板维度必须是五维根码之一(body/mind/wisdom/action/wealth),实际=" + dim);
+        }
+    }
+
+    // ==================== 正常流:推荐清单(任务/心愿/饮食) ====================
+
+    @Test
+    @DisplayName("正常流-4:recommend 应返回任务/心愿/饮食三类非空推荐清单")
+    void recommend_withReport_returnsTaskWishDietItems() {
+        List<Map<String, Object>> items = callList(contractHost(), "recommend", 11L, 1001L);
+        assertNotNull(items, "recommend 不得返回 null");
+        assertFalse(items.isEmpty(), "有报告推荐依据时推荐清单不得为空");
+        for (Map<String, Object> item : items) {
+            String type = String.valueOf(item.get("type"));
+            assertTrue("task".equals(type) || "wish".equals(type) || "diet".equals(type),
+                    "推荐项 type 必须为 task|wish|diet,实际=" + type);
+            assertNotNull(item.get("recoId"), "推荐项必须携带 recoId(供一键采纳回引)");
+            assertNotNull(item.get("title"), "推荐项必须携带 title");
+            assertNotNull(item.get("reason"), "推荐项必须携带 reason(推荐依据说明)");
+        }
+    }
+
+    // ==================== 正常流:一键采纳(任务/心愿写回) ====================
+
+    @Test
+    @DisplayName("正常流-5:adopt type=task 应写回正式任务并返回 targetId")
+    void adopt_taskType_writesBackTask() {
+        Map<String, Object> r = callMap(contractHost(), "adopt", 1L, 11L, "task", "reco-task-1");
+        assertNotNull(r, "adopt 必须返回采纳结果");
+        assertEquals("task", String.valueOf(r.get("targetType")),
+                "task 型推荐采纳后应写回任务(TaskService.createTask 语义)");
+        assertTrue(toLong(r.get("targetId")) > 0L,
+                "task 型采纳必须返回新任务 id(targetId>0),落 /api/tasks/create 写回");
+    }
+
+    @Test
+    @DisplayName("正常流-6:adopt type=wish 应写回正式心愿并返回 targetId")
+    void adopt_wishType_writesBackWish() {
+        Map<String, Object> r = callMap(contractHost(), "adopt", 1L, 11L, "wish", "reco-wish-1");
+        assertNotNull(r, "adopt 必须返回采纳结果");
+        assertEquals("wish", String.valueOf(r.get("targetType")),
+                "wish 型推荐采纳后应写回心愿(WishController /api/wishes/create 语义)");
+        assertTrue(toLong(r.get("targetId")) > 0L,
+                "wish 型采纳必须返回新心愿 id(targetId>0)");
+    }
+
+    // ==================== 边界流:无报告降级 / 过敏忌口排除 / 幂等 ====================
+
+    @Test
+    @DisplayName("边界流-7:无报告且无五维数据时降级为通用推荐(不报错、返回非空)")
+    void recommend_noBasis_degradesToGeneric() {
+        Object host = contractHost();
+        Map<String, Object> basis = callMap(host, "analyzeBasis", 11L, null);
+        assertEquals(Boolean.FALSE, basis.get("reportAvailable"), "无报告时应标记报告不可用");
+        assertEquals("generic", basis.get("basis"),
+                "无报告且无五维数据时不得报错/不得返回空——降级为通用推荐(basis=generic,提示依据不足)");
+        List<Map<String, Object>> items = callList(host, "recommend", 11L, null);
+        assertNotNull(items, "降级推荐不得返回 null");
+        assertFalse(items.isEmpty(), "降级推荐仍应返回通用推荐清单(边界:无报告降级而非 500/空)");
+    }
+
+    @Test
+    @DisplayName("边界流-8:diet 推荐项必须排除过敏/忌口食材(FoodRecommendService 戒备口径)")
+    void dietItems_excludeAllergenFoods() {
+        Object host = contractHost();
+        List<Object> excluded = callListObject(host, "excludedFoodIds", 11L);
+        assertNotNull(excluded, "excludedFoodIds 不得返回 null");
+        List<Map<String, Object>> items = callList(host, "recommend", 11L, 1001L);
+        Set<String> excludedKeys = new HashSet<>();
+        for (Object id : excluded) {
+            excludedKeys.add(String.valueOf(id));
+        }
+        for (Map<String, Object> item : items) {
+            if (!"diet".equals(String.valueOf(item.get("type")))) {
+                continue;
+            }
+            Object foods = item.get("foodIds");
+            if (foods == null) {
+                continue;
+            }
+            for (Object foodId : (List<?>) foods) {
+                assertFalse(excludedKeys.contains(String.valueOf(foodId)),
+                        "diet 推荐不得包含过敏/忌口食材(foodId=" + foodId
+                                + ",来源 FoodRecommendService 推荐指数<0 戒备食材)");
+            }
+        }
+        assertTrue(true, "过敏/忌口排除契约断言完成(excludedFoodIds 与 diet.foodIds 无交集)");
+    }
+
+    @Test
+    @DisplayName("边界流-9:同一推荐重复采纳幂等——不重复建任务/心愿")
+    void adopt_duplicateReco_idempotent() {
+        Object host = contractHost();
+        Map<String, Object> first = callMap(host, "adopt", 1L, 11L, "task", "reco-idem-1");
+        long firstId = toLong(first.get("targetId"));
+        Map<String, Object> second = callMap(host, "adopt", 1L, 11L, "task", "reco-idem-1");
+        assertEquals(firstId, toLong(second.get("targetId")),
+                "重复采纳同一 (memberId,type,recoId) 必须返回同一 targetId(coach_recommend_log 留痕幂等)");
+        assertEquals(Boolean.TRUE, callBoolean(host, "isAdopted", 11L, "task", "reco-idem-1"),
+                "已采纳的推荐 isAdopted 必须为 true");
+    }
+
+    // ==================== 权限流:家庭隔离(家长代管成员) ====================
+
+    @Test
+    @DisplayName("权限流-10:同家庭成员 hasFamilyAccess=true 可推荐/采纳")
+    void hasFamilyAccess_ownFamily_true() {
+        assertEquals(Boolean.TRUE, callBoolean(contractHost(), "hasFamilyAccess", 1L, 11L),
+                "memberId=11 属于 userId=1 家庭,代管推荐/采纳应被允许");
+    }
+
+    @Test
+    @DisplayName("权限流-11:跨家庭成员 leaveFamilyAccess=false 且采纳被拒")
+    void adopt_crossFamilyMember_permissionDenied() {
+        Object host = contractHost();
+        assertEquals(Boolean.FALSE, callBoolean(host, "hasFamilyAccess", 1L, 999L),
+                "memberId=999 不属于 userId=1 家庭,不得代管推荐/采纳(家庭隔离)");
+        Object r = callAllowRejected(host, "adopt", 1L, 999L, "task", "reco-other-family");
+        if (r instanceof Map) {
+            Object targetId = ((Map<?, ?>) r).get("targetId");
+            assertFalse(targetId != null && toLong(targetId) > 0L,
+                    "跨家庭采纳不得写回任务(越权 403/拒绝,返回不得含有效 targetId)");
+        }
+    }
+
+    // ==================== 契约端点:controller + 幂等留痕表 ====================
+
+    @Test
+    @DisplayName("契约端点-12:CoachRecommendController 应落地 /api/ai/coach/recommend 且依赖宿主")
+    void controller_classMappedAndDependsOnHost() {
+        Class<?> clazz = loadClass(CONTROLLER_CLASS);
+        if (clazz == null) {
+            fail("RED[ai.coach.recommend] 契约端点 CoachRecommendController 未落地(实现未落地):"
+                    + "SC-B-07 推荐生成/采纳端点缺失。");
+        }
+        RequestMapping rm = clazz.getAnnotation(RequestMapping.class);
+        assertNotNull(rm, "CoachRecommendController 应标注 @RequestMapping");
+        assertEquals(ENDPOINT_BASE, firstValue(rm.value()),
+                "CoachRecommendController 类路径应为 " + ENDPOINT_BASE);
+        boolean hasRecommend = false;
+        boolean hasAdopt = false;
+        for (Method m : clazz.getDeclaredMethods()) {
+            PostMapping pm = m.getAnnotation(PostMapping.class);
+            if (pm == null) {
+                continue;
+            }
+            if (m.getName().equals("recommend")) {
+                hasRecommend = true;
+            }
+            if (m.getName().equals("adopt")) {
+                hasAdopt = true;
+            }
+        }
+        assertTrue(hasRecommend, "应提供 @PostMapping recommend(生成推荐)");
+        assertTrue(hasAdopt, "应提供 @PostMapping adopt(一键采纳)");
+        boolean injected = false;
+        for (Field f : clazz.getDeclaredFields()) {
+            if (HOST_CLASS.equals(f.getType().getName())) {
+                injected = true;
+                break;
+            }
+        }
+        assertTrue(injected, "CoachRecommendController 应通过 @Resource 注入 " + HOST_CLASS);
+    }
+
+    @Test
+    @DisplayName("契约端点-13:schema.sql 应落地 coach_recommend_log(采纳留痕幂等)")
+    void schemaSql_idempotentLogTable() {
+        String schema = readSchemaSql();
+        assertTrue(schema.contains(IDEMPOTENT_LOG_TABLE),
+                "RED[ai.coach.recommend] schema.sql 缺少 " + IDEMPOTENT_LOG_TABLE
+                        + " 建表:一键采纳留痕(重复推荐幂等)未落地。");
+    }
+
+    // ==================== 反射辅助(锚定宿主契约,避免编译期依赖不存在类) ====================
+
+    private static final Set<String> ROOT_DIMS = new HashSet<>();
+    static {
+        ROOT_DIMS.add(DIM_BODY);
+        ROOT_DIMS.add(DIM_MIND);
+        ROOT_DIMS.add(DIM_WISDOM);
+        ROOT_DIMS.add(DIM_ACTION);
+        ROOT_DIMS.add(DIM_WEALTH);
+    }
+
+    private Object contractHost() {
+        try {
+            Class<?> clazz = Class.forName(HOST_CLASS);
+            return clazz.getDeclaredConstructor().newInstance();
+        } catch (ClassNotFoundException e) {
+            fail("RED[ai.coach.recommend] 契约宿主 CoachRecommendService 未实现(实现未落地):"
+                    + e.getMessage());
+            throw new IllegalStateException("unreachable");
+        } catch (Exception e) {
+            fail("契约宿主 CoachRecommendService 实例化失败:" + e.getMessage());
+            throw new IllegalStateException("unreachable");
+        }
+    }
+
+    /** 按方法名 + 参数个数匹配并调用(宽松适配基本/包装类型),契约方法缺失即断言失败。 */
+    private Object call(Object host, String method, Object... args) {
+        return callInternal(host, method, true, args);
+    }
+
+    /** 同 {@link #call},但允许业务拒绝以异常/空表达(权限拒绝用例),不中断失败。 */
+    private Object callAllowRejected(Object host, String method, Object... args) {
+        return callInternal(host, method, false, args);
+    }
+
+    private Object callInternal(Object host, String method, boolean failOnMissing, 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) {
+                    if (failOnMissing) {
+                        fail("契约方法 " + HOST_CLASS + "#" + method + " 调用失败:" + e.getMessage());
+                        throw new IllegalStateException("unreachable");
+                    }
+                    return null;
+                }
+            }
+        }
+        if (failOnMissing) {
+            fail("RED[ai.coach.recommend] 契约方法 " + HOST_CLASS + "#" + method + " 未实现");
+            throw new IllegalStateException("unreachable");
+        }
+        return null;
+    }
+
+    @SuppressWarnings("unchecked")
+    private Map<String, Object> callMap(Object host, String method, Object... args) {
+        Object r = call(host, method, args);
+        if (r instanceof Map) {
+            return (Map<String, Object>) r;
+        }
+        fail("契约方法 " + method + " 应返回 Map,实际 " + r);
+        throw new IllegalStateException("unreachable");
+    }
+
+    @SuppressWarnings("unchecked")
+    private List<Map<String, Object>> callList(Object host, String method, Object... args) {
+        Object r = call(host, method, args);
+        if (r instanceof List) {
+            List<Map<String, Object>> out = new java.util.ArrayList<>();
+            for (Object o : (List<?>) r) {
+                out.add((Map<String, Object>) o);
+            }
+            return out;
+        }
+        fail("契约方法 " + method + " 应返回 List,实际 " + r);
+        throw new IllegalStateException("unreachable");
+    }
+
+    @SuppressWarnings("unchecked")
+    private List<Object> callListObject(Object host, String method, Object... args) {
+        Object r = call(host, method, args);
+        if (r instanceof List) {
+            return (List<Object>) r;
+        }
+        fail("契约方法 " + method + " 应返回 List,实际 " + 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");
+    }
+
+    private long toLong(Object v) {
+        if (v instanceof Number) {
+            return ((Number) v).longValue();
+        }
+        if (v instanceof CharSequence) {
+            try {
+                return Long.parseLong(v.toString().trim());
+            } catch (NumberFormatException ignored) {
+                // fall through
+            }
+        }
+        return -1L;
+    }
+
+    private String firstValue(String[] values) {
+        return values != null && values.length > 0 ? values[0] : null;
+    }
+
+    private Class<?> loadClass(String name) {
+        try {
+            return Class.forName(name, false, Thread.currentThread().getContextClassLoader());
+        } catch (ClassNotFoundException e) {
+            return null;
+        }
+    }
+
+    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 "";
+        }
+    }
+}