Преглед изворни кода

Merge branch 'task/S-cfc-250' into cfclub

Sisyphus Agent пре 3 дана
родитељ
комит
5343e77e12
19 измењених фајлова са 5039 додато и 5 уклоњено
  1. 333 0
      cfc-backend/src/test/java/com/etotem/cfc/unit/AiCoachReportAnalyzeContractTest.java
  2. 231 0
      cfc-backend/src/test/java/com/etotem/cfc/unit/AssessmentOrderPayContractTest.java
  3. 303 0
      cfc-backend/src/test/java/com/etotem/cfc/unit/AssessmentPlannerSelectContractTest.java
  4. 465 0
      cfc-backend/src/test/java/com/etotem/cfc/unit/ButlerEscalationContractTest.java
  5. 283 0
      cfc-backend/src/test/java/com/etotem/cfc/unit/ButlerQualityQaContractTest.java
  6. 467 0
      cfc-backend/src/test/java/com/etotem/cfc/unit/ContactGroupImportContractTest.java
  7. 417 0
      cfc-backend/src/test/java/com/etotem/cfc/unit/DietMealPlanAdjustContractTest.java
  8. 374 0
      cfc-backend/src/test/java/com/etotem/cfc/unit/DietMealPlanGenerateContractTest.java
  9. 235 0
      cfc-backend/src/test/java/com/etotem/cfc/unit/EnergyLedgerViewContractTest.java
  10. 327 0
      cfc-backend/src/test/java/com/etotem/cfc/unit/FamilyCreateWithInviteContractTest.java
  11. 413 0
      cfc-backend/src/test/java/com/etotem/cfc/unit/FamilyRelationGraphContractTest.java
  12. 305 0
      cfc-backend/src/test/java/com/etotem/cfc/unit/GrowthPlanTaskListContractTest.java
  13. 322 0
      cfc-backend/src/test/java/com/etotem/cfc/unit/ReportArchiveManageContractTest.java
  14. 469 0
      cfc-backend/src/test/java/com/etotem/cfc/unit/WishCycleManageContractTest.java
  15. 1 1
      cfc-web/.last_build_commit
  16. 2 2
      cfc-web/package-lock.json
  17. 1 1
      cfc-web/package.json
  18. 45 0
      cfc-web/public/CHANGELOG-v1.0.md
  19. 46 1
      cfc-web/public/CHANGELOG.md

+ 333 - 0
cfc-backend/src/test/java/com/etotem/cfc/unit/AiCoachReportAnalyzeContractTest.java

@@ -0,0 +1,333 @@
+package com.etotem.cfc.unit;
+
+import com.etotem.cfc.common.Result;
+import com.etotem.cfc.controller.ai.AIChatController;
+import com.etotem.cfc.entity.User;
+import com.etotem.cfc.service.AIService;
+import com.etotem.cfc.service.FamilyContextService;
+import com.etotem.cfc.service.PortraitService;
+import com.etotem.cfc.service.SelfCheckAnalysisService;
+import com.etotem.cfc.service.TaskParseService;
+import com.etotem.cfc.service.UserService;
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Test;
+import org.springframework.data.redis.core.RedisTemplate;
+
+import java.util.HashMap;
+import java.util.LinkedHashMap;
+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;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.ArgumentMatchers.anyLong;
+import static org.mockito.ArgumentMatchers.anyString;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.when;
+
+/**
+ * 契约级单测:成长报告智能解读(能力键 {@code ai.coach.reportAnalyze},SC-B-04)。
+ *
+ * <p><b>契约来源(TDD-RED 溯源)</b></p>
+ * <ul>
+ *   <li>需求:{@code tests/user-scenarios/应用场景总览.md} SC-B-04(成长报告智能解读:
+ *       报告翻译人话 + 五维关联 + 行动建议);{@code tests/test-cases/butler.md}
+ *       TC-B-04 正常流 / TC-B-04-E 异常流 / TC-B-04-P 权限流</li>
+ *   <li>设计:{@code docs/superpowers/api/API_REFERENCE.md} §4.64.4 ——
+ *       {@code POST /api/ai/report/analyze} 成长报告智能解读(LangGraph 解析;
+ *       不可用时返回「AI服务暂不可用」显式错误)</li>
+ * </ul>
+ *
+ * <p><b>被校验的契约行为(TC-B-04 三类流)</b></p>
+ * <ul>
+ *   <li>正常流(TC-B-04):解读输出应含<b>「通俗解读 + 五维关联 + 行动建议」三段结构</b>,
+ *       五维关联维度与报告实际维度一致;解读引用的数值不超出报告范围(无杜撰指标)</li>
+ *   <li>异常流(TC-B-04-E):无报告提示「请先上传报告」不返回空白解读;报告仍在解析(未入库)
+ *       提示「报告解析中,请稍后」不读半成品;同一孩子两份不同类型报告提示类型不一致不可横向比较;
+ *       输出中姓名/手机号等打码脱敏</li>
+ *   <li>权限流(TC-B-04-P):越权家庭/孩子/规划师请求非本家庭报告解读 → 403,
+ *       不返回报告内容或解读结果</li>
+ * </ul>
+ *
+ * <p><b>实现现状核实(origin/cfclub,2026-11-14)</b>:{@code AIChatController.reportAnalyze}
+ * 端点骨架已存在(参数校验 + FREE Redis 计数 + buildChatInputs + aiService.sendMessage,
+ * 返回自由文本 {@code {answer, conversationId}}),但契约新增行为<b>均未落地</b>:
+ * <ul>
+ *   <li>无结构化三段输出 VO(仅返回自由文本 answer,未解析出通俗解读/五维关联/行动建议)</li>
+ *   <li>无报告归属越权校验({@code FamilyContextService.buildContext} 直查 reportDetail,
+ *       无 canAccessFamily/403 语义;TC-B-04-P 缺失)</li>
+ *   <li>无报告解析中(draftId 草稿未入库)半成品拦截、无报告类型一致性校验、无输出 PII 脱敏
+ *       ({@code TaskParseService.stripTaskMarkers} 仅去标记位)</li>
+ * </ul>
+ * 因此本测试以「行为契约 + 反射结构」断言以上缺失:能编译、能运行、断言失败(红)。</p>
+ *
+ * <p><b>GREEN 升级指引</b>:实现者在 reportAnalyze 成功响应中产出结构化三段
+ * (通俗解读/五维关联/行动建议)并在边界场景返回对应提示、在越权场景返回 403 后,
+ * 本测试相应断言自动转绿。</p>
+ *
+ * <p><b>测试范围</b>:纯 Mockito / 反射注入(仿 {@code CoachButlerNotificationContractTest}),
+ * 无 Spring / 无 DB / 无外部服务。FREE Redis 计数非本键契约点,
+ * 用例统一使用 FAMILY 会员避免触碰 Redis 分支。</p>
+ */
+class AiCoachReportAnalyzeContractTest extends AssessmentPlanContractTestBase {
+
+    private static final Long USER_ID = 1L;
+    private static final String REPORT_ID = "100";
+    private static final String ANSWER_RAW = "孩子的肠道菌群丰度略有下降,建议增加膳食纤维。";
+
+    // ==================== 正常流:解读输出三段结构(TC-B-04) ====================
+
+    @Test
+    @DisplayName("正常流-1:解读输出应含「通俗解读」段")
+    void normalFlow_plainSummarySegment() throws Exception {
+        AIChatController c = newController("FAMILY");
+        Result<Map<String, Object>> r = c.reportAnalyze(USER_ID, paramsReport());
+        assertEqualsCode200(r);
+        Map<String, Object> data = r.getData();
+        assertNotNull(data, "[ai.coach.reportAnalyze] 解读成功响应 data 不应为 null");
+        assertTrue(data.containsKey("plainSummary"),
+                "[ai.coach.reportAnalyze] SC-B-04/TC-B-04 契约要求解读输出含「通俗解读」段"
+                        + "(key=plainSummary,把专业指标翻译成人话)。实现现状仅返回自由文本 answer。");
+    }
+
+    @Test
+    @DisplayName("正常流-2:解读输出应含「五维关联」段")
+    void normalFlow_fiveDimAssociationsSegment() throws Exception {
+        AIChatController c = newController("FAMILY");
+        Result<Map<String, Object>> r = c.reportAnalyze(USER_ID, paramsReport());
+        assertEqualsCode200(r);
+        Map<String, Object> data = r.getData();
+        assertNotNull(data, "[ai.coach.reportAnalyze] 解读成功响应 data 不应为 null");
+        assertTrue(data.containsKey("fiveDimAssociations"),
+                "[ai.coach.reportAnalyze] SC-B-04/TC-B-04 契约要求解读输出含「五维关联」段"
+                        + "(key=fiveDimAssociations,把报告发现关联到身/心/智/行/富五维)。"
+                        + "实现现状未输出。");
+    }
+
+    @Test
+    @DisplayName("正常流-3:解读输出应含「行动建议」段")
+    void normalFlow_actionSuggestionsSegment() throws Exception {
+        AIChatController c = newController("FAMILY");
+        Result<Map<String, Object>> r = c.reportAnalyze(USER_ID, paramsReport());
+        assertEqualsCode200(r);
+        Map<String, Object> data = r.getData();
+        assertNotNull(data, "[ai.coach.reportAnalyze] 解读成功响应 data 不应为 null");
+        assertTrue(data.containsKey("actionSuggestions"),
+                "[ai.coach.reportAnalyze] SC-B-04/TC-B-04 契约要求解读输出含「行动建议」段"
+                        + "(key=actionSuggestions,可被采纳为任务)。实现现状未输出。");
+    }
+
+    @Test
+    @DisplayName("正常流-4:五维关联维度应与报告实际维度一致(身心智行富)")
+    void normalFlow_fiveDimMatchesReportDimensions() throws Exception {
+        AIChatController c = newController("FAMILY");
+        Result<Map<String, Object>> r = c.reportAnalyze(USER_ID, paramsReport());
+        assertEqualsCode200(r);
+        Map<String, Object> data = r.getData();
+        assertNotNull(data, "[ai.coach.reportAnalyze] 解读成功响应 data 不应为 null");
+        Object fiveDim = data.get("fiveDimAssociations");
+        assertNotNull(fiveDim, "[ai.coach.reportAnalyze] 五维关联段(fiveDimAssociations)缺失");
+        if (!(fiveDim instanceof Map)) {
+            fail("[ai.coach.reportAnalyze] fiveDimAssociations 应为 Map<维度,关联说明>");
+        }
+        @SuppressWarnings("unchecked")
+        Map<String, Object> dims = (Map<String, Object>) fiveDim;
+        assertTrue(dims.keySet().containsAll(java.util.Arrays.asList("body", "mind", "intellect", "action", "wealth")),
+                "[ai.coach.reportAnalyze] 五维关联维度应覆盖身/心/智/行/富(body/mind/intellect/action/wealth)"
+                        + "且与报告实际维度一致(TC-B-04)。实际=" + dims.keySet());
+    }
+
+    // ==================== 异常流:边界行为(TC-B-04-E) ====================
+
+    @Test
+    @DisplayName("异常流-1:无报告(reportId 不存在/未上传)应提示「请先上传报告」且不返回解读")
+    void exceptionalFlow_missingReport_promptUploadFirst() throws Exception {
+        AIChatController c = newController("FAMILY");
+        // 契约 AC:无报告不解读,提示「请先上传报告」,不返回空白解读。
+        // reportId 指向不存在/未上传的报告时,实现应拒绝而非继续解读。
+        Result<Map<String, Object>> r = c.reportAnalyze(USER_ID, params("解读一下", "999999", null));
+        boolean blocked = r.getCode() != 200
+                && r.getMessage() != null
+                && r.getMessage().contains("上传");
+        assertTrue(blocked,
+                "[ai.coach.reportAnalyze] SC-B-04-E 契约要求:无报告不解读,提示「请先上传报告」"
+                        + "(code!=200 且提示含「上传」)。实现现状对不存在 reportId 仍返回 200 解读。"
+                        + "实际 code=" + r.getCode() + " message=" + r.getMessage());
+    }
+
+    @Test
+    @DisplayName("异常流-2:报告仍在解析(未入库的 draftId)应提示「报告解析中」不读半成品")
+    void exceptionalFlow_reportParsing_promptRetry() throws Exception {
+        AIChatController c = newController("FAMILY");
+        // TC-B-04-E:报告仍在解析(未入库)时发起 → 提示「报告解析中,请稍后」,不读半成品。
+        // 实现须区分「解析中草稿」与「已解析完成草稿」:后者(report-confirm 页)允许解读,
+        // 前者必须拦截;现状 draftId 一律直接 buildContextFromDraft 读 payload → 缺解析状态门禁。
+        Map<String, String> params = new HashMap<>();
+        params.put("query", "解读草稿");
+        params.put("draftId", "500");
+        Result<Map<String, Object>> r = c.reportAnalyze(USER_ID, params);
+        boolean blocked = r.getCode() != 200
+                && r.getMessage() != null
+                && (r.getMessage().contains("解析中") || r.getMessage().contains("稍后"));
+        assertTrue(blocked,
+                "[ai.coach.reportAnalyze] SC-B-04-E 契约要求:报告仍在解析(未入库)时提示"
+                        + "「报告解析中,请稍后」,不读半成品。实现现状 draftId 未校验解析状态,"
+                        + "直接读草稿 payload 继续解读。实际 code=" + r.getCode() + " message=" + r.getMessage());
+    }
+
+    @Test
+    @DisplayName("异常流-3:不同类型报告先后解读应提示类型不一致、不可横向比较")
+    void exceptionalFlow_typeMismatch_notComparable() throws Exception {
+        AIChatController c = newController("FAMILY");
+        Result<Map<String, Object>> r = c.reportAnalyze(USER_ID, paramsReport());
+        assertEqualsCode200(r);
+        Map<String, Object> data = r.getData();
+        assertNotNull(data, "[ai.coach.reportAnalyze] 解读成功响应 data 不应为 null");
+        Object warning = data.get("typeWarning");
+        boolean warned = warning instanceof Map
+                && ((Map<?, ?>) warning).containsKey("mismatch")
+                && Boolean.TRUE.equals(((Map<?, ?>) warning).get("mismatch"));
+        assertTrue(warned,
+                "[ai.coach.reportAnalyze] SC-B-04-E 契约要求:同一孩子两份不同类型报告先后解读时"
+                        + "提示类型不一致、不可横向比较(响应应含 typeWarning.mismatch 标记)。"
+                        + "实现现状无报告类型一致性校验。");
+    }
+
+    @Test
+    @DisplayName("异常流-4:输出含姓名/手机号等高敏信息应打码脱敏")
+    void exceptionalFlow_highSensitiveInfo_desensitized() throws Exception {
+        AIChatController c = newController("FAMILY");
+        stubbedAnswer(c, "张三的肠道菌群丰度下降,联系电话 13800138000,可联系主治医生。");
+        Result<Map<String, Object>> r = c.reportAnalyze(USER_ID, paramsReport());
+        assertEqualsCode200(r);
+        Map<String, Object> data = r.getData();
+        assertNotNull(data, "[ai.coach.reportAnalyze] 解读成功响应 data 不应为 null");
+        String answer = String.valueOf(data.getOrDefault("answer", ""));
+        boolean masked = !answer.contains("13800138000") && !answer.contains("张三");
+        assertTrue(masked,
+                "[ai.coach.reportAnalyze] SC-B-04-E 契约要求:输出中姓名/手机号等打码脱敏"
+                        + "(不直接回显高敏信息)。实现现状仅 stripTaskMarkers 去任务标记,无 PII 脱敏。"
+                        + "实际 answer=" + answer);
+    }
+
+    // ==================== 权限流:越权 403(TC-B-04-P) ====================
+
+    @Test
+    @DisplayName("权限流-1:家长请求非本家庭报告解读 → 403,不返回报告内容")
+    void permissionFlow_foreignFamilyReport_403() throws Exception {
+        AIChatController c = newController("FAMILY");
+        // 越权:reportId 属于其它家庭(无归属校验场景下仍被解读即视为越权泄露)
+        Result<Map<String, Object>> r = c.reportAnalyze(USER_ID, params("解读他人报告", "777888", null));
+        boolean forbidden = r.getCode() == 403
+                || (r.getMessage() != null && r.getMessage().contains("无权"));
+        assertTrue(forbidden,
+                "[ai.coach.reportAnalyze] SC-B-04-P 契约要求:家长请求非本家庭(F9)报告解读应 403,"
+                        + "不返回报告内容或解读结果。实现现状 reportAnalyze 无报告归属校验(buildContext"
+                        + "直查 reportDetail),越权 reportId 仍返回 200 解读。"
+                        + "实际 code=" + r.getCode() + " message=" + r.getMessage());
+    }
+
+    @Test
+    @DisplayName("权限流-2:孩子/规划师越权请求非绑定家庭报告 → 403")
+    void permissionFlow_otherRoleForeignReport_403() throws Exception {
+        AIChatController c = newController("FAMILY");
+        // 越权角色(孩子 token 请求家长报告 / 规划师请求非绑定家庭报告)均应被拒
+        Result<Map<String, Object>> r = c.reportAnalyze(USER_ID, params("解读他家庭报告", "555666", null));
+        boolean forbidden = r.getCode() == 403
+                || (r.getMessage() != null && r.getMessage().contains("无权"));
+        assertTrue(forbidden,
+                "[ai.coach.reportAnalyze] SC-B-04-P 契约要求:孩子/规划师越权请求非本家庭报告解读应 403。"
+                        + "实现现状无角色/归属门禁,仍返回 200。"
+                        + "实际 code=" + r.getCode() + " message=" + r.getMessage());
+    }
+
+    // ==================== 辅助构造(仿 CoachButlerNotificationContractTest) ====================
+
+    /**
+     * 构造 reportAnalyze 调用链的 controller:FAMILY 会员(避开 FREE Redis 分支),
+     * mock 掉 buildChatInputs 所需的上下文/画像/自检/记忆,sendMessage 返回契约内 answer。
+     */
+    private AIChatController newController(String memberLevel) throws Exception {
+        AIChatController c = new AIChatController();
+
+        UserService userSvc = mock(UserService.class);
+        User u = new User();
+        u.setMemberLevel(memberLevel);
+        when(userSvc.getUserInfo(anyLong())).thenReturn(u);
+        inject(c, "userService", userSvc);
+
+        FamilyContextService ctxSvc = mock(FamilyContextService.class);
+        when(ctxSvc.buildContext(anyLong(), anyLong())).thenReturn(new LinkedHashMap<String, Object>());
+        when(ctxSvc.buildContext(anyLong())).thenReturn(new LinkedHashMap<String, Object>());
+        when(ctxSvc.buildContext(anyLong(), anyLong(), anyLong())).thenReturn(new LinkedHashMap<String, Object>());
+        when(ctxSvc.buildContextFromDraft(anyLong(), anyLong())).thenReturn(new LinkedHashMap<String, Object>());
+        inject(c, "familyContextService", ctxSvc);
+
+        PortraitService portraitSvc = mock(PortraitService.class);
+        when(portraitSvc.buildPortraitPrompt(anyLong(), any())).thenReturn("");
+        inject(c, "portraitService", portraitSvc);
+
+        SelfCheckAnalysisService selfCheckSvc = mock(SelfCheckAnalysisService.class);
+        when(selfCheckSvc.buildLatestSummary(anyLong(), any())).thenReturn(null);
+        inject(c, "selfCheckAnalysisService", selfCheckSvc);
+
+        AIService aiSvc = mock(AIService.class);
+        // buildChatInputs 末尾记忆层注入:原样返回 inputs,避免后续 NPE
+        when(aiSvc.enrichInputsWithMemory(anyLong(), any(), any()))
+                .thenAnswer(inv -> inv.getArgument(2));
+        // 默认 AI 响应成功(answer + conversationId),使断言聚焦契约新增行为而非链路桩件
+        Map<String, Object> aiResp = new LinkedHashMap<>();
+        aiResp.put("answer", ANSWER_RAW);
+        aiResp.put("conversationId", "conv-contract");
+        when(aiSvc.sendMessage(anyString(), anyString(), any(), any(Map.class))).thenReturn(aiResp);
+        inject(c, "aiService", aiSvc);
+
+        TaskParseService tpSvc = mock(TaskParseService.class);
+        when(tpSvc.stripTaskMarkers(anyString())).thenAnswer(inv -> inv.getArgument(0));
+        inject(c, "taskParseService", tpSvc);
+
+        inject(c, "objectMapper", new com.fasterxml.jackson.databind.ObjectMapper());
+        inject(c, "redisTemplate", mock(RedisTemplate.class));
+        return c;
+    }
+
+    /** 覆盖 sendMessage 返回指定 answer(默认 ANSWER_RAW) */
+    private void stubbedAnswer(AIChatController c, String answer) throws Exception {
+        com.etotem.cfc.service.AIService aiSvc =
+                (com.etotem.cfc.service.AIService) field(c, "aiService");
+        Map<String, Object> resp = new LinkedHashMap<>();
+        resp.put("answer", answer);
+        resp.put("conversationId", "conv-contract");
+        when(aiSvc.sendMessage(anyString(), anyString(), any(), any(Map.class))).thenReturn(resp);
+    }
+
+    private Object field(Object target, String fieldName) throws Exception {
+        java.lang.reflect.Field f = target.getClass().getDeclaredField(fieldName);
+        f.setAccessible(true);
+        return f.get(target);
+    }
+
+    private Map<String, String> paramsReport() {
+        return params("请帮我用通俗语言解读这份报告,关联五维并给出行动建议", REPORT_ID, null);
+    }
+
+    private Map<String, String> params(String query, String reportId, String draftId) {
+        Map<String, String> p = new HashMap<>();
+        p.put("query", query);
+        if (reportId != null) {
+            p.put("reportId", reportId);
+        }
+        if (draftId != null) {
+            p.put("draftId", draftId);
+        }
+        return p;
+    }
+
+    private void assertEqualsCode200(Result<?> r) {
+        if (r.getCode() != 200) {
+            fail("[ai.coach.reportAnalyze] 期望 200,实际 code=" + r.getCode()
+                    + " message=" + r.getMessage());
+        }
+    }
+}

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

@@ -0,0 +1,231 @@
+package com.etotem.cfc.unit;
+
+import com.etotem.cfc.entity.AssessmentOrder;
+import com.etotem.cfc.entity.AssessmentQuota;
+import com.etotem.cfc.mapper.AssessmentQuotaMapper;
+import com.etotem.cfc.service.AssessmentOrderService;
+import com.etotem.cfc.service.AssessmentQuotaService;
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Test;
+
+import java.io.InputStream;
+import java.lang.reflect.Field;
+import java.lang.reflect.Method;
+import java.nio.charset.StandardCharsets;
+import java.util.Date;
+import java.util.Scanner;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.when;
+
+/**
+ * 契约级单测:测评订单支付成功生成额度(能力键 {@code assessment.order.pay})。
+ *
+ * <p>契约来源:需求 SC-P-34/SC-P-35(支付成功生成额度、额度过期不可用)+ 设计 docs/superpowers/api/API_REFERENCE.md §4.10 测评模块
+ * (模块:{@code AssessmentOrder} 服务;支付成功生成 {@code AssessmentQuota}(含 expire_time))。</p>
+ *
+ * <p><b>实现现状核实(src/main)</b>:
+ * <ul>
+ *   <li>{@code AssessmentOrderService.paySuccess/payOrder} 已实现订单 pending→paid、佣金结算、
+ *       profitPool 钩子;但<b>未注入 {@code AssessmentQuotaService}、未生成额度</b>。</li>
+ *   <li>{@code AssessmentQuotaService.grantQuota} 仅有 {@code ProductOrder} 入参重载(商城测评商品走)
+ *       与 {@code AssessmentOrder} 之间无桥接;额度实体/schema 的 {@code validity_end}(expire_time)
+ *       与 {@code consumeQuota} 过期拒绝已落地。</li>
+ * </ul>
+ * 因此本测试以「反射结构契约」探测支付→额度落地的缺失钩子:可编译、可运行、断言失败(红),
+ * 且失败断言原文清晰可贴。</p>
+ *
+ * <p><b>GREEN 升级指引</b>:实现者在 {@code AssessmentOrderService} 注入
+ * {@code AssessmentQuotaService}(字段名 {@code assessmentQuotaService})、
+ * 在 {@code AssessmentQuotaService} 增加 {@code AssessmentOrder} 入参的 {@code grantQuota(...)}
+ * 重载(默认 1 次 / 365 天有效,含 expire_time=validityEnd)并在支付成功路径调用后,
+ * 本测试结构探测自动转绿;届时可将 {@link #paySuccess_grantsQuota_behavioralGate} 升级为
+ * 行为级 mock 验证({@code verify(quotaSvc).grantQuota(...)})。</p>
+ *
+ * <p><b>权限流说明</b>:支付成功回调为后端内部链路段,无用户权限校验维度。</p>
+ */
+class AssessmentOrderPayContractTest extends AssessmentPlanContractTestBase {
+
+    private static final String ORDER_SERVICE = "com.etotem.cfc.service.AssessmentOrderService";
+    private static final String QUOTA_SERVICE = "com.etotem.cfc.service.AssessmentQuotaService";
+    private static final String QUOTA_ENTITY = "com.etotem.cfc.entity.AssessmentQuota";
+
+    // ------------------------------------------------------------------
+    // 正常流:支付成功必须触发额度发放(RED 核心)
+    // ------------------------------------------------------------------
+
+    @Test
+    @DisplayName("正常流-1:AssessmentOrderService 应注入 AssessmentQuotaService 钩子")
+    void orderService_injectsAssessmentQuotaServiceHook() {
+        Class<?> clazz = loadClass(ORDER_SERVICE);
+        assertNotNull(clazz, "[assessment.order.pay] AssessmentOrderService 类不存在。");
+        assertTrue(hasFieldOfType(clazz, QUOTA_SERVICE),
+                "[assessment.order.pay] AssessmentOrderService 未注入 AssessmentQuotaService:"
+                        + "契约要求支付成功(pending→paid)后生成 AssessmentQuota(SC-P-34 主流程 / §4.10)。"
+                        + "当前实现 paySuccess/payOrder 仅置 paid + 佣金结算,未生成额度。");
+    }
+
+    @Test
+    @DisplayName("正常流-2:AssessmentQuotaService 应提供 AssessmentOrder 入参的额度发放入口")
+    void quotaService_hasAssessmentOrderGrantQuotaEntry() {
+        Class<?> clazz = loadClass(QUOTA_SERVICE);
+        assertNotNull(clazz, "[assessment.order.pay] AssessmentQuotaService 类不存在。");
+        assertTrue(hasMethodWithParam(clazz, "grantQuota", "com.etotem.cfc.entity.AssessmentOrder"),
+                "[assessment.order.pay] AssessmentQuotaService 缺少 AssessmentOrder 入参的 grantQuota(...):"
+                        + "现仅有 ProductOrder 重载(商城测评商品用),测评订单(assessment_orders)支付成功"
+                        + "后无从生成额度。契约要求支付成功生成 AssessmentQuota(含 expire_time)。");
+    }
+
+    @Test
+    @DisplayName("正常流-3:支付成功路径应调用额度发放(行为门禁,GREEN 后升级为 verify)")
+    void paySuccess_grantsQuota_behavioralGate() {
+        Class<?> clazz = loadClass(ORDER_SERVICE);
+        assertNotNull(clazz, "[assessment.order.pay] AssessmentOrderService 类不存在。");
+        assertTrue(hasFieldOfType(clazz, QUOTA_SERVICE),
+                "[assessment.order.pay] 支付成功(paySuccess/payOrder)后未调用额度发放:"
+                        + "契约要求订单 paid 后同步生成一条 AssessmentQuota(含 expire_time)。"
+                        + "GREEN 升级指引:字段注入后,在此注入 mock AssessmentQuotaService + mock baseMapper,"
+                        + "stub selectOne/updateById,调用 paySuccess 后 verify(quotaSvc).grantQuota(...),断言额度 validityEnd 落在未来。");
+    }
+
+    // ------------------------------------------------------------------
+    // 边界流:额度含有效期 + 过期不可用(已落地,绿,作为契约边界确认)
+    // ------------------------------------------------------------------
+
+    @Test
+    @DisplayName("边界流-1:AssessmentQuota 实体应承载 expire_time(validityEnd)")
+    void quotaEntity_carriesValidityEndExpireTime() {
+        Class<?> clazz = loadClass(QUOTA_ENTITY);
+        assertNotNull(clazz, "[assessment.order.pay] AssessmentQuota 实体不存在。");
+        assertTrue(hasField(clazz, "validityEnd"),
+                "[assessment.order.pay] AssessmentQuota 缺少 validityEnd 字段(对应表 validity_end,"
+                        + "即 expire_time)。契约要求额度含有效期(SC-P-35)。");
+    }
+
+    @Test
+    @DisplayName("边界流-2:schema.sql assessment_quotas 表应落地且含 validity_end 列")
+    void schemaSql_assessmentQuotasCarriesValidityEnd() {
+        String schema = readSchemaSql();
+        assertTrue(schema.contains("assessment_quotas"),
+                "[assessment.order.pay] schema.sql 缺少 assessment_quotas 建表。");
+        assertTrue(schema.contains("validity_end"),
+                "[assessment.order.pay] assessment_quotas 应含 validity_end 列(expire_time),"
+                        + "契约要求额度到账含有效期(SC-P-35)。");
+    }
+
+    @Test
+    @DisplayName("边界流-3:过期额度不可用于预约(consumeQuota 拒绝并置 expired)")
+    void expiredQuota_cannotBeConsumedForAppointment() throws Exception {
+        AssessmentQuotaMapper mapper = mock(AssessmentQuotaMapper.class);
+        AssessmentQuotaService svc = new AssessmentQuotaService();
+        inject(svc, "mapper", mapper);
+
+        AssessmentQuota quota = new AssessmentQuota();
+        quota.setId(5L);
+        quota.setStatus("active");
+        quota.setTotalSessions(2);
+        quota.setRemainingSessions(2);
+        quota.setValidityStart(new Date(System.currentTimeMillis() - 60L * 24 * 3600 * 1000));
+        quota.setValidityEnd(new Date(System.currentTimeMillis() - 30L * 24 * 3600 * 1000)); // 已过期
+        when(mapper.selectById(5L)).thenReturn(quota);
+
+        RuntimeException ex = assertThrows(RuntimeException.class, () -> svc.consumeQuota(5L, 10L));
+        assertTrue(ex.getMessage().contains("已过期"),
+                "[assessment.order.pay] 过期额度应拒绝用于预约(SC-P-35 边界:额度过期不可用于预约)。");
+        assertEquals("expired", quota.getStatus(), "过期额度应被置为 expired");
+    }
+
+    @Test
+    @DisplayName("边界流-4:重复支付幂等——已 paid 订单不得重复生成额度(状态守卫契约)")
+    void paySuccess_repeatPaymentIdempotent_guardContract() {
+        // 契约:重复支付幂等。
+        // 当前 AssessmentOrderService.paySuccess/payOrder 无 paid 状态守卫,重复调用会二次佣金结算 + 潜在重复额度发放。
+        // 结构契约锁定:支付成功入口应依赖额度发放仅一次(GREEN 落地时由 paid 状态守卫 + 额度钩子共同保障)。
+        assertTrue(true, "重复支付幂等由支付入口的 paid 状态守卫 + 额度发放钩子共同保障(GREEN 落地)。");
+    }
+
+    // ------------------------------------------------------------------
+    // 权限流(不适用):后端支付回调内部链路
+    // ------------------------------------------------------------------
+
+    @Test
+    @DisplayName("权限流:本能力为支付成功回调内部链路,无用户权限维度,权限流不适用")
+    void permissionFlow_notApplicable() {
+        assertTrue(true, "权限流不适用:assessment.order.pay 为后端支付成功回调链路段,"
+                + "订单归属家庭/用户已在 createOrder 时落定,回调时刻无用户权限校验维度。");
+    }
+
+    // ------------------------------------------------------------------
+    // 反射辅助
+    // ------------------------------------------------------------------
+
+    private Class<?> loadClass(String name) {
+        try {
+            return Class.forName(name, false, Thread.currentThread().getContextClassLoader());
+        } catch (ClassNotFoundException e) {
+            return null;
+        }
+    }
+
+    /** 沿继承链查找是否存在指定类型的字段(含私有字段) */
+    private boolean hasFieldOfType(Class<?> clazz, String typeName) {
+        Class<?> cur = clazz;
+        while (cur != null) {
+            for (Field f : cur.getDeclaredFields()) {
+                if (typeName.equals(f.getType().getName())) {
+                    return true;
+                }
+            }
+            cur = cur.getSuperclass();
+        }
+        return false;
+    }
+
+    /** 是否存在指定名称的字段(含私有字段) */
+    private boolean hasField(Class<?> clazz, String fieldName) {
+        Class<?> cur = clazz;
+        while (cur != null) {
+            for (Field f : cur.getDeclaredFields()) {
+                if (fieldName.equals(f.getName())) {
+                    return true;
+                }
+            }
+            cur = cur.getSuperclass();
+        }
+        return false;
+    }
+
+    /** 是否存在指定名称的方法且入参含指定类型的声明方法 */
+    private boolean hasMethodWithParam(Class<?> clazz, String methodName, String paramTypeName) {
+        for (Method m : clazz.getDeclaredMethods()) {
+            if (!m.getName().equals(methodName)) {
+                continue;
+            }
+            for (Class<?> p : m.getParameterTypes()) {
+                if (paramTypeName.equals(p.getName())) {
+                    return true;
+                }
+            }
+        }
+        return false;
+    }
+
+    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 "";
+        }
+    }
+}

+ 303 - 0
cfc-backend/src/test/java/com/etotem/cfc/unit/AssessmentPlannerSelectContractTest.java

@@ -0,0 +1,303 @@
+package com.etotem.cfc.unit;
+
+import com.etotem.cfc.common.Result;
+import com.etotem.cfc.controller.assessment.AssessmentAppointmentController;
+import com.etotem.cfc.controller.family.BindController;
+import com.etotem.cfc.entity.AssessmentAppointment;
+import com.etotem.cfc.entity.AssessmentQuota;
+import com.etotem.cfc.entity.DanAssessmentExecution;
+import com.etotem.cfc.entity.User;
+import com.etotem.cfc.mapper.UserMapper;
+import com.etotem.cfc.service.AssessmentAppointmentService;
+import com.etotem.cfc.service.AssessmentQuotaService;
+import com.etotem.cfc.service.DanAssessmentExecutionService;
+import com.etotem.cfc.service.GuideFamilyAccessGuard;
+import com.etotem.cfc.service.GuideFamilyService;
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Test;
+import org.springframework.web.bind.annotation.PostMapping;
+
+import javax.annotation.Resource;
+import java.io.File;
+import java.lang.reflect.Field;
+import java.lang.reflect.Method;
+import java.nio.charset.StandardCharsets;
+import java.nio.file.Files;
+import java.util.Date;
+import java.util.HashMap;
+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;
+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 assessment.planner.select}(S-cfc-274,TDD-RED)。
+ *
+ * <p><b>契约溯源</b></p>
+ * <ul>
+ *   <li>需求:{@code tests/user-scenarios/应用场景总览.md} SC-P-32(选择规划师)——
+ *       <blockquote>目标:指定服务规划师。流程:测评选规划师 → 绑定的 T 列表。
+ *       边界:未绑定规划师提示先绑定。模块:测评订单。</blockquote></li>
+ *   <li>设计:{@code docs/superpowers/api/API_REFERENCE.md} §4.10 测评
+ *       {@code POST /api/assessment/appointment/create}(预约前需规划师绑定)。</li>
+ * </ul>
+ *
+ * <p><b>能力边界/方向</b>:家长侧选规划师 = 测评预约时,所选规划师(guideId)必须属于
+ * 该家庭<b>已绑定</b>的 T(指导师/规划师)列表;未绑定规划师 → 提示先绑定。
+ * 与 {@code teacher.family.bind}(S-cfc-190,规划师侧接家庭,走
+ * {@link GuideFamilyAccessGuard#checkBinding})方向相反,本能力以家庭维度(familyId)
+ * 反查绑定列表,不引入规划师侧守卫。</p>
+ *
+ * <p><b>实现现状(RED 依据,cfclub 核实)</b>:
+ * <ul>
+ *   <li>{@link AssessmentAppointmentController#createAppointment} 仅参数级校验
+ *       (assessorId/guideId 至少其一),未校验所选规划师 ∈ 家庭绑定列表;家庭未绑定
+ *       规划师时返回泛参数错误「assessorId或guideId必须提供一个」,而非「请先绑定规划师」。</li>
+ *   <li>Controller 未注入 {@link GuideFamilyService}(绑定 T 列表数据源);
+ *       {@link AssessmentAppointmentService} 无「规划师绑定校验」方法。</li>
+ * </ul>
+ * 因此本节测以「反射结构契约 + 源码文本契约 + Mockito 行为契约」探测缺失,编译通过、能运行、
+ * 断言失败(红),失败原文清晰可贴(仿同批 TeamProfitHookContractTest / FamilyJoinValidationRulesContractTest)。
+ * </p>
+ *
+ * <p><b>GREEN 升级指引</b>:创建预约前以家庭维度校验所选规划师:
+ * 复用已有 {@link GuideFamilyService#getGuidesByFamily(Long)} /
+ * {@link GuideFamilyService#isBound(Long, Long)}(家长侧绑定 T 列表数据源,
+ * {@code POST /api/bind/guides} 已提供);未绑定 → 返回含「请先绑定规划师」的业务错误;
+ * guideId 不在绑定列表 → 同口径拒绝。上述结构/文本/行为断言即可转绿。</p>
+ */
+class AssessmentPlannerSelectContractTest extends AssessmentPlanContractTestBase {
+
+    /** §4.10 预约创建端点源码(文本契约锚点) */
+    private static final String APPOINTMENT_CONTROLLER_SOURCE =
+            "src/main/java/com/etotem/cfc/controller/assessment/AssessmentAppointmentController.java";
+
+    /** SC-P-32 / TC-P-32-E 边界提示:未绑定规划师提示先绑定 */
+    private static final String MSG_UNBOUND_PLANNER_PROMPT = "请先绑定规划师";
+
+    // ==================== 正常流:家长侧选规划师 → 绑定的 T 列表 ====================
+
+    @Test
+    @DisplayName("正常流-1:预约 Controller 应注入家庭绑定源 GuideFamilyService(预约前需规划师绑定)")
+    void appointmentController_shouldWireBoundPlannerValidation() {
+        boolean wired = false;
+        for (Field f : AssessmentAppointmentController.class.getDeclaredFields()) {
+            if (GuideFamilyService.class.equals(f.getType())) {
+                wired = true;
+                break;
+            }
+        }
+        assertTrue(wired,
+                "[assessment.planner.select] AssessmentAppointmentController 未注入 GuideFamilyService(家庭绑定 T 列表数据源):"
+                        + "契约要求创建预约前校验所选规划师 ∈ 家庭已绑定列表(API_REFERENCE §4.10『预约前需规划师绑定』,"
+                        + "SC-P-32『测评选规划师 → 绑定的 T 列表』)。实现未落地。");
+    }
+
+    @Test
+    @DisplayName("正常流-2:预约 Service 应提供规划师绑定校验方法(仅绑定规划师可选)")
+    void appointmentService_shouldProvidePlannerBindingValidationMethod() {
+        boolean hasPlannerMethod = false;
+        for (Method m : AssessmentAppointmentService.class.getDeclaredMethods()) {
+            if (m.getName().toLowerCase().contains("planner")) {
+                hasPlannerMethod = true;
+                break;
+            }
+        }
+        assertTrue(hasPlannerMethod,
+                "[assessment.planner.select] AssessmentAppointmentService 缺少规划师绑定校验方法(如 requireBoundPlanner/isPlannerBound):"
+                        + "测评预约只能指定家庭已绑定的规划师(SC-P-32;TC-P-32-E:已解绑 T 不在可选列表,选则拒绝)。实现未落地。");
+    }
+
+    @Test
+    @DisplayName("正常流-3:绑定 T 列表数据源已存在(/api/bind/guides,家长侧;GREEN 复用锚点)")
+    void boundPlannerListSource_bindGuidesEndpointExists() {
+        Class<?> bindController = loadClass(BindController.class.getName());
+        assertNotNull(bindController, "[assessment.planner.select] BindController 应存在(绑定 T 列表入口,SC-P-32)。");
+        boolean hasGetBoundGuides = false;
+        boolean mapsToGuidesPath = false;
+        for (Method m : bindController.getDeclaredMethods()) {
+            if (m.getName().equals("getBoundGuides")) {
+                hasGetBoundGuides = true;
+                PostMapping pm = m.getAnnotation(PostMapping.class);
+                if (pm != null && pm.value().length > 0 && "/guides".equals(pm.value()[0])) {
+                    mapsToGuidesPath = true;
+                }
+            }
+        }
+        assertTrue(hasGetBoundGuides,
+                "[assessment.planner.select] /api/bind/guides 端点(getBoundGuides)应返回家庭已绑定指导师列表,"
+                        + "作为测评选规划师的『绑定的 T 列表』数据源(SC-P-32)。");
+        assertTrue(mapsToGuidesPath,
+                "[assessment.planner.select] getBoundGuides 应映射到 POST /api/bind/guides(家长侧绑定 T 列表)。");
+    }
+
+    // ==================== 异常流:未绑定规划师提示先绑定 ====================
+
+    @Test
+    @DisplayName("异常流-1:预约创建端点源码应包含「请先绑定规划师」提示(SC-P-32 边界)")
+    void createAppointment_shouldContainUnboundPlannerPromptMessage() {
+        String source = readSource(APPOINTMENT_CONTROLLER_SOURCE);
+        assertTrue(source.contains(MSG_UNBOUND_PLANNER_PROMPT),
+                "[assessment.planner.select] AssessmentAppointmentController.createAppointment 缺少「"
+                        + MSG_UNBOUND_PLANNER_PROMPT + "」文案:SC-P-32 边界『未绑定规划师提示先绑定』"
+                        + "(TC-P-32-E:未绑定提示『请先绑定规划师』),当前仅返回泛参数错误"
+                        + "『assessorId或guideId必须提供一个』。实现未落地。(源码路径: " + sourcePathUsed() + ")");
+    }
+
+    @Test
+    @DisplayName("异常流-2:未绑定规划师创建预约 → 应提示先绑定(而非泛参数错误)且不消耗额度")
+    void createAppointment_unboundPlanner_shouldPromptBindFirst_notSilentlyCreate() throws Exception {
+        UserMapper userMapper = mock(UserMapper.class);
+        AssessmentQuotaService quotaSvc = mock(AssessmentQuotaService.class);
+        AssessmentAppointmentService apptSvc = mock(AssessmentAppointmentService.class);
+        DanAssessmentExecutionService execSvc = mock(DanAssessmentExecutionService.class);
+        AssessmentAppointmentController c = new AssessmentAppointmentController();
+        inject(c, "appointmentService", apptSvc);
+        inject(c, "quotaService", quotaSvc);
+        inject(c, "danAssessmentExecutionService", execSvc);
+        inject(c, "userMapper", userMapper);
+
+        User user = new User();
+        user.setId(1L);
+        when(userMapper.selectById(1L)).thenReturn(user);
+
+        // 家庭无绑定规划师:body 未携带 guideId/assessorId
+        Map<String, Object> body = new HashMap<>();
+        body.put("memberId", 10L);
+        body.put("quotaId", 5L);
+
+        Result<Map<String, Object>> r = c.createAppointment(1L, body, null);
+
+        // 契约:未绑定规划师 → 提示先绑定(SC-P-32 边界),不静默创建空预约(TC-B-09-E)
+        assertTrue(r.getMessage() != null && r.getMessage().contains("绑定"),
+                "[assessment.planner.select] 未绑定规划师时 createAppointment 应提示『请先绑定规划师』,"
+                        + "实际返回: " + r.getMessage() + "(当前为泛参数错误『assessorId或guideId必须提供一个』)。实现未落地。");
+        verify(quotaSvc, never()).consumeQuota(anyLong(), anyLong());
+        verify(apptSvc, never()).createAppointment(anyLong(), anyLong(), anyLong(), any(), any(), any(), any(), any());
+    }
+
+    @Test
+    @DisplayName("异常流-3:指定未绑定规划师创建预约 → 应拒绝(预约前需规划师绑定),当前会成功创建(红)")
+    void createAppointment_unboundGuide_shouldRejectInsteadOfSuccess() throws Exception {
+        UserMapper userMapper = mock(UserMapper.class);
+        AssessmentQuotaService quotaSvc = mock(AssessmentQuotaService.class);
+        AssessmentAppointmentService apptSvc = mock(AssessmentAppointmentService.class);
+        DanAssessmentExecutionService execSvc = mock(DanAssessmentExecutionService.class);
+        AssessmentAppointmentController c = new AssessmentAppointmentController();
+        inject(c, "appointmentService", apptSvc);
+        inject(c, "quotaService", quotaSvc);
+        inject(c, "danAssessmentExecutionService", execSvc);
+        inject(c, "userMapper", userMapper);
+
+        User user = new User();
+        user.setId(1L);
+        when(userMapper.selectById(1L)).thenReturn(user);
+        // 模拟当前实现路径:可消耗额度、可创建预约 → 成功响应
+        when(quotaSvc.consumeQuota(5L, 10L)).thenReturn(2);
+        AssessmentQuota quota = new AssessmentQuota();
+        quota.setId(5L);
+        quota.setFamilyId(7L);
+        quota.setProductOrderId(11L);
+        when(quotaSvc.getById(5L)).thenReturn(quota);
+        AssessmentAppointment appt = new AssessmentAppointment();
+        appt.setId(101L);
+        when(apptSvc.createAppointment(anyLong(), anyLong(), anyLong(), any(), any(), any(), any(), any()))
+                .thenReturn(appt);
+        DanAssessmentExecution exec = new DanAssessmentExecution();
+        exec.setId(201L);
+        when(execSvc.createExecution(anyLong(), anyLong(), anyLong(), anyLong(), anyLong(), any(), anyLong()))
+                .thenReturn(exec);
+
+        // 家长指定 guideId=7,但该规划师并未绑定到家庭(家庭维度绑定校验缺失)
+        Map<String, Object> body = new HashMap<>();
+        body.put("memberId", 10L);
+        body.put("guideId", 7L);
+        body.put("quotaId", 5L);
+
+        Result<Map<String, Object>> r = c.createAppointment(1L, body, null);
+
+        // 契约:预约前需规划师绑定(§4.10)→ 未绑定规划师应拒绝,不得成功创建
+        assertTrue(r.getCode() != 200,
+                "[assessment.planner.select] 指定未绑定规划师(guideId=7 不在家庭绑定列表)创建预约竟返回成功(code=200),"
+                        + "违反 API_REFERENCE §4.10『预约前需规划师绑定』(SC-P-32)。"
+                        + "应提示『请先绑定规划师』并拒绝,不消耗额度、不创建预约。实现未落地。");
+        verify(apptSvc, never()).createAppointment(anyLong(), anyLong(), anyLong(), any(), any(), any(), any(), any());
+        verify(quotaSvc, never()).consumeQuota(anyLong(), anyLong());
+    }
+
+    // ==================== 权限流:家长侧 vs 规划师侧(S-cfc-190 区分) ====================
+
+    @Test
+    @DisplayName("权限流-1:家长侧走家庭维度绑定校验,与规划师侧守卫(S-cfc-190)方向区分(锚点)")
+    void permissionFlow_parentSideFamilyDirection_notTeacherSideGuard() {
+        // 规划师侧接家庭守卫已落地(S-cfc-190 teacher.family.bind 方向:guide 维度)
+        assertNotNull(loadClass(GuideFamilyAccessGuard.class.getName()),
+                "[assessment.planner.select] GuideFamilyAccessGuard 应存在(S-cfc-190 规划师侧守卫,作为方向区分的既存物)。");
+        // 家长侧绑定数据源:GuideFamilyService 提供按家庭反查绑定 T 的能力(GREEN 阶段复用)
+        boolean hasFamilyDirection = false;
+        for (Method m : GuideFamilyService.class.getDeclaredMethods()) {
+            if (m.getName().equals("getGuidesByFamily") || m.getName().equals("isBound")) {
+                hasFamilyDirection = true;
+                break;
+            }
+        }
+        assertTrue(hasFamilyDirection,
+                "[assessment.planner.select] GuideFamilyService 应提供家庭维度绑定查询(getGuidesByFamily/isBound),"
+                        + "供家长侧选规划师校验使用(SC-P-32),以区别于规划师侧 checkBinding 方向。");
+        // Controller 注入使用 @Resource(项目 DI 规范),且不依赖规划师侧守卫类型
+        boolean usesResource = false;
+        for (Field f : AssessmentAppointmentController.class.getDeclaredFields()) {
+            if (f.isAnnotationPresent(Resource.class)) {
+                usesResource = true;
+                break;
+            }
+        }
+        assertTrue(usesResource,
+                "[assessment.planner.select] AssessmentAppointmentController 应遵循项目 DI 规范(@Resource 注入字段)。");
+    }
+
+    // ==================== 辅助 ====================
+
+    private Class<?> loadClass(String name) {
+        try {
+            return Class.forName(name, false, Thread.currentThread().getContextClassLoader());
+        } catch (ClassNotFoundException e) {
+            return null;
+        }
+    }
+
+    private String sourcePathUsed = "";
+
+    private String readSource(String relPath) {
+        String[] candidates = {
+                relPath,
+                "cfc-backend/" + relPath,
+                "../" + relPath,
+                "../cfc-backend/" + relPath
+        };
+        for (String p : candidates) {
+            File f = new File(p);
+            if (f.exists()) {
+                try {
+                    sourcePathUsed = f.getCanonicalPath();
+                    byte[] bytes = Files.readAllBytes(f.toPath());
+                    return new String(bytes, StandardCharsets.UTF_8);
+                } catch (Exception e) {
+                    // 忽略读取异常,尝试下一个候选
+                }
+            }
+        }
+        return "";
+    }
+
+    private String sourcePathUsed() {
+        return sourcePathUsed.isEmpty() ? "未找到" : sourcePathUsed;
+    }
+}

+ 465 - 0
cfc-backend/src/test/java/com/etotem/cfc/unit/ButlerEscalationContractTest.java

@@ -0,0 +1,465 @@
+package com.etotem.cfc.unit;
+
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Test;
+
+import java.io.InputStream;
+import java.lang.reflect.Field;
+import java.lang.reflect.Method;
+import java.nio.charset.StandardCharsets;
+import java.util.Arrays;
+import java.util.Scanner;
+
+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 阶段,S-cfc-251):能力键 {@code butler.escalation.handle}(真人管家域,SC-H-01 / SC-H-04)。
+ *
+ * <p>契约溯源:
+ * <ul>
+ *   <li>需求:{@code tests/user-scenarios/应用场景总览.md} SC-H-01(接收 AI 升级并人工介入)、SC-H-04(升级与应急处理);
+ *       {@code tests/test-cases/human-butler.md} TC-H-01 / TC-H-04 三流(正常/异常/权限)。</li>
+ *   <li>设计:{@code docs/superpowers/api/API_REFERENCE.md} §4.13 {@code butler/ButlerController}
+ *       {@code admin/AdminButlerController},但ler 工单/升级 + 工单治理;高风险优先 / 超时升级 / 仅本家庭工单授权。</li>
+ * </ul></p>
+ *
+ * <p><b>契约范围(但ler 升级工单治理,当前 src/main 未落地)</b></p>
+ * <ul>
+ *   <li>宿主服务 {@link com.etotem.cfc.service.ButlerEscalationService} —— 未实现。</li>
+ *   <li>工单实体 {@link com.etotem.cfc.entity.ButlerEscalationOrder}(表 {@code butler_escalation_orders}) —— 未建表/无实体。</li>
+ *   <li>家庭端端点({@code ButlerController})与管理端治理端点({@code AdminButlerController}) —— 未新增。</li>
+ *   <li>核心契约行为:按风险等级优先排序进入工作台;工单上下文(家长诉求 / AI 已给结论 / 风险等级)完整;
+ *       乐观锁领取(一人认领,他人「已被认领」);超时 SLA 触发升级提醒;高风险优先触达并联动应急;
+ *       一级自处 / 二级升级(携带完整上下文);联系动作与复盘留痕;仅本服务家庭可见(403 越界)。</li>
+ * </ul>
+ *
+ * <p><b>RED 预期</b>:宿主 {@code ButlerEscalationService}、实体 {@code ButlerEscalationOrder}、表
+ * {@code butler_escalation_orders}、相关端点均未落地,全部用例在反射探测处失败(红),断言原文为
+ * 「但ler.escalation.handle 契约……未实现」。GREEN 阶段实现宿主后本测试自动转绿。</p>
+ *
+ * <p>测试风格:纯反射锚定契约宿主,无 Spring / 无 DB / 无外部服务,与同批 RED 契约测试(TeamProfitHook /
+ * TeamStarMultiplier / FamilyJoinValidationRules)风格一致。</p>
+ */
+class ButlerEscalationContractTest {
+
+    // ==================== 契约常量 ====================
+
+    /** 契约宿主服务(尚未实现)。 */
+    private static final String SERVICE_CLASS = "com.etotem.cfc.service.ButlerEscalationService";
+    /** 契约工单实体(尚未落地)。 */
+    private static final String ENTITY_CLASS = "com.etotem.cfc.entity.ButlerEscalationOrder";
+    /** 契约建表名。 */
+    private static final String TABLE_NAME = "butler_escalation_orders";
+
+    /** 工单状态枚举值(SC-H-01 流转:待处理→处理中→已闭环;SC-H-04 涉及已升级/已撤回)。 */
+    private static final String[] ORDER_STATUSES = {
+            "PENDING", "PROCESSING", "CLOSED", "WITHDRAWN", "ESCALATED"
+    };
+    /** 风险等级(高风险优先)。 */
+    private static final String[] RISK_LEVELS = {"HIGH", "MEDIUM", "LOW"};
+    /** 联系方式枚举(电话 / 消息 / 站内)。 */
+    private static final String[] CONTACT_TYPES = {"CALL", "MESSAGE", "IN_APP"};
+
+    /** 家庭端契约端点(ButlerController /api/butler/escalation/*)。 */
+    private static final String[] FAMILY_ENDPOINTS = {
+            "/api/butler/escalation/list", "/api/butler/escalation/detail",
+            "/api/butler/escalation/claim", "/api/butler/escalation/log-contact",
+            "/api/butler/escalation/close", "/api/butler/escalation/transfer",
+            "/api/butler/escalation/withdraw"
+    };
+    /** 管理端契约端点(AdminButlerController /api/admin/butler/escalation/*)。 */
+    private static final String[] ADMIN_ENDPOINTS = {
+            "/api/admin/butler/escalation/grade", "/api/admin/butler/escalation/escalate",
+            "/api/admin/butler/escalation/review"
+    };
+
+    // ==================== 正常流:宿主服务与实体存在 ====================
+
+    @Test
+    @DisplayName("正常流-1:ButlerEscalationService 宿主服务应存在")
+    void hostService_exists() {
+        assertNotNull(loadClass(SERVICE_CLASS),
+                "[butler.escalation.handle] ButlerEscalationService 类不存在:契约宿主未落地,"
+                        + "SC-H-01/SC-H-04 工单治理能力缺失。");
+    }
+
+    @Test
+    @DisplayName("正常流-2:ButlerEscalationOrder 实体应存在并承载工单上下文字段")
+    void entity_existsWithContextFields() {
+        Class<?> entity = loadClass(ENTITY_CLASS);
+        if (entity == null) {
+            fail("[butler.escalation.handle] ButlerEscalationOrder 实体不存在:contract 要求承载"
+                    + " 家长诉求 / AI 已给结论 / 风险等级 上下文。");
+        }
+        assertNotNull(findField(entity, "familyId"),
+                "[butler.escalation.handle] ButlerEscalationOrder 应含 familyId 字段(仅本家庭隔离)。");
+        assertNotNull(findField(entity, "riskLevel"),
+                "[butler.escalation.handle] ButlerEscalationOrder 应含 riskLevel 字段(高风险优先排序)。");
+        assertNotNull(findField(entity, "status"),
+                "[butler.escalation.handle] ButlerEscalationOrder 应含 status 字段(待处理/处理中/已闭环流转)。");
+        assertNotNull(findField(entity, "parentDemand"),
+                "[butler.escalation.handle] ButlerEscalationOrder 应含 parentDemand 字段(家长诉求上下文)。");
+        assertNotNull(findField(entity, "aiConclusion"),
+                "[butler.escalation.handle] ButlerEscalationOrder 应含 aiConclusion 字段(AI 已给结论上下文)。");
+    }
+
+    @Test
+    @DisplayName("正常流-3:schema.sql 应落地 butler_escalation_orders 建表")
+    void schemaSql_hasEscalationTable() {
+        String schema = readSchemaSql();
+        assertTrue(schema.contains(TABLE_NAME),
+                "[butler.escalation.handle] schema.sql 缺少 " + TABLE_NAME + " 建表(SC-H-01/SC-H-04 工单治理)。");
+        assertTrue(schema.contains("family_id"),
+                "[butler.escalation.handle] " + TABLE_NAME + " 应含 family_id 列(仅本家庭工单授权)。");
+        assertTrue(schema.contains("risk_level"),
+                "[butler.escalation.handle] " + TABLE_NAME + " 应含 risk_level 列(高风险优先)。");
+        assertTrue(schema.contains("status"),
+                "[butler.escalation.handle] " + TABLE_NAME + " 应含 status 列(工单状态流转)。");
+    }
+
+    // ==================== 正常流:契约方法签名 ====================
+
+    @Test
+    @DisplayName("正常流-4:list(Long butlerUserId) 应存在并返回待认领工单列表")
+    void listMethod_exists() {
+        Class<?> svc = loadClass(SERVICE_CLASS);
+        if (svc == null) {
+            fail("[butler.escalation.handle] ButlerEscalationService 不存在,无法验证 list()(按风险等级优先排序)。");
+        }
+        assertTrue(hasMethod(svc, "list", new Class[]{Long.class}),
+                "[butler.escalation.handle] ButlerEscalationService 应提供 list(Long butlerUserId),"
+                        + "按风险等级优先返回待认领工单(SC-H-01 工作台)。");
+    }
+
+    @Test
+    @DisplayName("正常流-5:detail(Long workorderId, Long userId) 应存在并返回工单详情(仅本家庭)")
+    void detailMethod_exists() {
+        Class<?> svc = loadClass(SERVICE_CLASS);
+        if (svc == null) {
+            fail("[butler.escalation.handle] ButlerEscalationService 不存在,无法验证 detail()。");
+        }
+        assertTrue(hasMethod(svc, "detail", new Class[]{Long.class, Long.class}),
+                "[butler.escalation.handle] ButlerEscalationService 应提供 detail(Long workorderId, Long userId),"
+                        + "返回工单详情且仅本服务家庭可见。");
+    }
+
+    @Test
+    @DisplayName("正常流-6:claim(Long workorderId, Long butlerUserId) 应存在(乐观锁认领)")
+    void claimMethod_exists() {
+        Class<?> svc = loadClass(SERVICE_CLASS);
+        if (svc == null) {
+            fail("[butler.escalation.handle] ButlerEscalationService 不存在,无法验证 claim()。");
+        }
+        assertTrue(hasMethod(svc, "claim", new Class[]{Long.class, Long.class}),
+                "[butler.escalation.handle] ButlerEscalationService 应提供 claim(Long workorderId, Long butlerUserId),"
+                        + "乐观锁认领:同一工单只允许一人认领,他人提示「已被认领」(TC-H-01-E)。");
+    }
+
+    @Test
+    @DisplayName("正常流-7:logContact(...) 应存在并记录联系动作留痕")
+    void logContactMethod_exists() {
+        Class<?> svc = loadClass(SERVICE_CLASS);
+        if (svc == null) {
+            fail("[butler.escalation.handle] ButlerEscalationService 不存在,无法验证 logContact()。");
+        }
+        assertTrue(hasMethod(svc, "logContact",
+                new Class[]{Long.class, String.class, String.class, Long.class}),
+                "[butler.escalation.handle] ButlerEscalationService 应提供 logContact(Long workorderId, String contactType, String content, Long userId),"
+                        + "记录电话/消息/站内联系动作(TC-H-01 步骤 3 联系留痕)。");
+    }
+
+    @Test
+    @DisplayName("正常流-8:resolve(...) 应存在并处置结论/转交规划师,工单闭环留痕")
+    void resolveMethod_exists() {
+        Class<?> svc = loadClass(SERVICE_CLASS);
+        if (svc == null) {
+            fail("[butler.escalation.handle] ButlerEscalationService 不存在,无法验证 resolve()。");
+        }
+        assertTrue(hasMethod(svc, "resolve",
+                new Class[]{Long.class, String.class, Long.class}),
+                "[butler.escalation.handle] ButlerEscalationService 应提供 resolve(Long workorderId, String resolution, Long userId),"
+                        + "给出人工结论并闭环,工单状态 PENDING→PROCESSING→CLOSED 留痕(TC-H-01 步骤 4/5)。");
+    }
+
+    @Test
+    @DisplayName("正常流-9:transferToTeacher(...) 应存在并转交规划师")
+    void transferMethod_exists() {
+        Class<?> svc = loadClass(SERVICE_CLASS);
+        if (svc == null) {
+            fail("[butler.escalation.handle] ButlerEscalationService 不存在,无法验证 transferToTeacher()。");
+        }
+        assertTrue(hasMethod(svc, "transferToTeacher",
+                new Class[]{Long.class, Long.class, Long.class}),
+                "[butler.escalation.handle] ButlerEscalationService 应提供 transferToTeacher(Long workorderId, Long teacherId, Long userId),"
+                        + "转交规划师(SC-H-01 转规划师)。");
+    }
+
+    @Test
+    @DisplayName("正常流-10:grade(...) 应存在并按 SOP 分级(一级自处 / 二级升级)")
+    void gradeMethod_exists() {
+        Class<?> svc = loadClass(SERVICE_CLASS);
+        if (svc == null) {
+            fail("[butler.escalation.handle] ButlerEscalationService 不存在,无法验证 grade()。");
+        }
+        assertTrue(hasMethod(svc, "grade",
+                new Class[]{Long.class, Integer.class, Long.class}),
+                "[butler.escalation.handle] ButlerEscalationService 应提供 grade(Long workorderId, Integer escalationLevel, Long userId),"
+                        + "按 SOP 分级:一级自行处置 / 二级升级至运营/医疗顾问(SC-H-04)。");
+    }
+
+    @Test
+    @DisplayName("正常流-11:escalateLevel2(...) 应存在并携带完整上下文二级升级")
+    void escalateLevel2Method_exists() {
+        Class<?> svc = loadClass(SERVICE_CLASS);
+        if (svc == null) {
+            fail("[butler.escalation.handle] ButlerEscalationService 不存在,无法验证 escalateLevel2()。");
+        }
+        assertTrue(hasMethod(svc, "escalateLevel2",
+                new Class[]{Long.class, String.class, Long.class}),
+                "[butler.escalation.handle] ButlerEscalationService 应提供 escalateLevel2(Long workorderId, String targetRole, Long userId),"
+                        + "二级升级至运营/医疗顾问且携带完整上下文(不丢上下文)。");
+    }
+
+    @Test
+    @DisplayName("正常流-12:recordReview(...) 应存在并生成复盘记录(含时长与结论)")
+    void recordReviewMethod_exists() {
+        Class<?> svc = loadClass(SERVICE_CLASS);
+        if (svc == null) {
+            fail("[butler.escalation.handle] ButlerEscalationService 不存在,无法验证 recordReview()。");
+        }
+        assertTrue(hasMethod(svc, "recordReview",
+                new Class[]{Long.class, Integer.class, String.class, Long.class}),
+                "[butler.escalation.handle] ButlerEscalationService 应提供 recordReview(Long workorderId, Integer durationMinutes, String conclusion, Long userId),"
+                        + "生成复盘记录含处置时长与结论(SC-H-04 复盘)。");
+    }
+
+    // ==================== 边界流:超时升级与乐观锁 ====================
+
+    @Test
+    @DisplayName("边界流-1:checkTimeoutEscalation() 应存在并扫描 SLA 超时工单触发升级提醒")
+    void timeoutScanMethod_exists() {
+        Class<?> svc = loadClass(SERVICE_CLASS);
+        if (svc == null) {
+            fail("[butler.escalation.handle] ButlerEscalationService 不存在,无法验证 checkTimeoutEscalation()。");
+        }
+        assertTrue(hasMethod(svc, "checkTimeoutEscalation", new Class[]{}),
+                "[butler.escalation.handle] ButlerEscalationService 应提供 checkTimeoutEscalation(),扫描超过 SLA 未处理工单触发升级提醒(TC-H-01-E)。");
+    }
+
+    @Test
+    @DisplayName("边界流-2:canHandle(...) 应存在并拒绝非本家庭工单(仅本家庭授权)")
+    void canHandleMethod_exists() {
+        Class<?> svc = loadClass(SERVICE_CLASS);
+        if (svc == null) {
+            fail("[butler.escalation.handle] ButlerEscalationService 不存在,无法验证 canHandle()。");
+        }
+        assertTrue(hasMethod(svc, "canHandle", new Class[]{Long.class, Long.class}),
+                "[butler.escalation.handle] ButlerEscalationService 应提供 canHandle(Long workorderId, Long userId),"
+                        + "仅本服务家庭可见,越界返回 false/403(TC-H-01-P / TC-H-04-P)。");
+    }
+
+    @Test
+    @DisplayName("边界流-3:工单状态应覆盖 PENDING / PROCESSING / CLOSED / WITHDRAWN / ESCALATED")
+    void statusEnum_coversFlowAndEscalation() {
+        Class<?> entity = loadClass(ENTITY_CLASS);
+        if (entity == null) {
+            fail("[butler.escalation.handle] ButlerEscalationOrder 不存在,无法验证状态枚举。");
+        }
+        Field statusField = findField(entity, "status");
+        if (statusField == null) {
+            fail("[butler.escalation.handle] ButlerEscalationOrder 缺少 status 字段。");
+        }
+        Class<?> statusType = statusField.getType();
+        String statusTypeName = statusType.getName();
+        boolean isEnum = statusType.isEnum();
+        boolean isString = String.class.equals(statusType);
+        boolean ok = isEnum || isString;
+        assertTrue(ok,
+                "[butler.escalation.handle] ButlerEscalationOrder.status 应为枚举或 String,用于承载 PENDING/PROCESSING/CLOSED/WITHDRAWN/ESCALATED,实际类型=" + statusTypeName);
+    }
+
+    // ==================== 权限流:控制器端点 ====================
+
+    @Test
+    @DisplayName("权限流-1:ButlerController 应映射家庭端 escalation 端点(@PostMapping)")
+    void familyEndpoints_mapped() {
+        Class<?> ctrl = loadClass("com.etotem.cfc.controller.butler.ButlerController");
+        if (ctrl == null) {
+            fail("[butler.escalation.handle] ButlerController 不存在,无法映射家庭端 escalation 端点。");
+        }
+        String typePrefix = typeRequestMappingPrefix(ctrl);
+        for (String path : FAMILY_ENDPOINTS) {
+            assertTrue(endpointExists(ctrl, "POST", path, typePrefix),
+                    "[butler.escalation.handle] ButlerController 应有 @PostMapping " + path + "(家庭端工单治理,仅本家庭授权)。");
+        }
+    }
+
+    @Test
+    @DisplayName("权限流-2:AdminButlerController 应映射管理端 escalation 端点(@PostMapping)")
+    void adminEndpoints_mapped() {
+        Class<?> ctrl = loadClass("com.etotem.cfc.controller.admin.AdminButlerController");
+        if (ctrl == null) {
+            fail("[butler.escalation.handle] AdminButlerController 不存在,无法映射管理端 escalation 端点。");
+        }
+        String typePrefix = typeRequestMappingPrefix(ctrl);
+        for (String path : ADMIN_ENDPOINTS) {
+            assertTrue(endpointExists(ctrl, "POST", path, typePrefix),
+                    "[butler.escalation.handle] AdminButlerController 应有 @PostMapping " + path + "(工单治理,admin/finance 角色校验)。");
+        }
+    }
+
+    @Test
+    @DisplayName("权限流-3:本能力为但ler 升级与应急处理,三流均适用(权限流不适用标注)")
+    void permissionFlow_applies() {
+        // 说明性用例:但ler.escalation.handle 涉及家庭数据隔离(仅本家庭)与 admin 治理角色,正常/异常/权限三流均适用。
+        assertTrue(true,
+                "权限流适用:但ler.escalation.handle 含家庭工单隔离(仅本家庭)与管理端治理角色,正常/异常/权限三流均适用。");
+    }
+
+    // ==================== 反射辅助(避免编译期依赖不存在类) ====================
+
+    private Class<?> loadClass(String name) {
+        try {
+            return Class.forName(name, false, Thread.currentThread().getContextClassLoader());
+        } catch (ClassNotFoundException e) {
+            return null;
+        } catch (Exception e) {
+            return null;
+        }
+    }
+
+    private Field findField(Class<?> clazz, String name) {
+        Class<?> c = clazz;
+        while (c != null && c != Object.class) {
+            for (Field f : c.getDeclaredFields()) {
+                if (f.getName().equals(name)) {
+                    return f;
+                }
+            }
+            c = c.getSuperclass();
+        }
+        return null;
+    }
+
+    private boolean hasMethod(Class<?> clazz, String name, Class<?>[] paramTypes) {
+        Class<?> c = clazz;
+        while (c != null && c != Object.class) {
+            for (Method m : c.getDeclaredMethods()) {
+                if (m.getName().equals(name) && Arrays.equals(m.getParameterTypes(), paramTypes)) {
+                    return true;
+                }
+            }
+            c = c.getSuperclass();
+        }
+        return false;
+    }
+
+    /** 读取类路径下的 schema.sql 全文。 */
+    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 "";
+        }
+    }
+
+    /**
+     * 检查控制器是否在指定方法(默认 POST)下映射了完整路径(类级前缀 + 方法级 @PostMapping/@RequestMapping)。
+     * 兼容 Spring 4.x @PostMapping(Java 8)。
+     */
+    private boolean endpointExists(Class<?> ctrl, String httpMethod, String expectedPath, String typePrefix) {
+        String fullPath = typePrefix == null || typePrefix.isEmpty()
+                ? expectedPath
+                : (typePrefix.endsWith("/") ? typePrefix + expectedPath.substring(1)
+                : typePrefix + expectedPath);
+        for (Method m : ctrl.getDeclaredMethods()) {
+            // @PostMapping
+            java.lang.annotation.Annotation post = m.getAnnotation(org.springframework.web.bind.annotation.PostMapping.class);
+            if (post != null) {
+                String[] paths = mappingPaths(post);
+                if (pathsContains(paths, expectedPath)) {
+                    return true;
+                }
+            }
+            // 通用 @RequestMapping
+            java.lang.annotation.Annotation rm = m.getAnnotation(org.springframework.web.bind.annotation.RequestMapping.class);
+            if (rm != null) {
+                java.lang.reflect.Method methodAnnotationValue;
+                try {
+                    Method valueM = rm.annotationType().getMethod("value");
+                    String[] paths = (String[]) valueM.invoke(rm);
+                    Method methodM = rm.annotationType().getMethod("method");
+                    Object[] methods = (Object[]) methodM.invoke(rm);
+                    boolean methodMatch = methods.length == 0;
+                    for (Object om : methods) {
+                        if (om instanceof org.springframework.web.bind.annotation.RequestMethod
+                                && ((org.springframework.web.bind.annotation.RequestMethod) om).name()
+                                .equalsIgnoreCase(httpMethod)) {
+                            methodMatch = true;
+                            break;
+                        }
+                    }
+                    if (methodMatch && pathsContains(paths, expectedPath)) {
+                        return true;
+                    }
+                } catch (Exception e) {
+                    // 忽略注解读取异常
+                }
+            }
+        }
+        return false;
+    }
+
+    private String[] mappingPaths(java.lang.annotation.Annotation ann) {
+        try {
+            Method valueM = ann.annotationType().getMethod("value");
+            Object v = valueM.invoke(ann);
+            if (v instanceof String[]) {
+                return (String[]) v;
+            }
+            Method pathM = ann.annotationType().getMethod("path");
+            Object p = pathM.invoke(ann);
+            if (p instanceof String[]) {
+                return (String[]) p;
+            }
+        } catch (Exception e) {
+            // ignore
+        }
+        return new String[0];
+    }
+
+    private boolean pathsContains(String[] paths, String expected) {
+        for (String p : paths) {
+            if (p != null && p.equals(expected)) {
+                return true;
+            }
+        }
+        return false;
+    }
+
+    /** 读取控制器类级 @RequestMapping 的路径前缀(不含 method 限定)。 */
+    private String typeRequestMappingPrefix(Class<?> ctrl) {
+        java.lang.annotation.Annotation rm = ctrl.getAnnotation(org.springframework.web.bind.annotation.RequestMapping.class);
+        if (rm == null) {
+            return "";
+        }
+        try {
+            Method valueM = rm.annotationType().getMethod("value");
+            Object v = valueM.invoke(rm);
+            if (v instanceof String[] && ((String[]) v).length > 0) {
+                return ((String[]) v)[0];
+            }
+        } catch (Exception e) {
+            // ignore
+        }
+        return "";
+    }
+}

+ 283 - 0
cfc-backend/src/test/java/com/etotem/cfc/unit/ButlerQualityQaContractTest.java

@@ -0,0 +1,283 @@
+package com.etotem.cfc.unit;
+
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Test;
+
+import java.io.InputStream;
+import java.lang.reflect.Field;
+import java.lang.reflect.Method;
+import java.nio.charset.StandardCharsets;
+import java.util.Scanner;
+
+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 butler.quality.qa})。
+ *
+ * <p>契约来源(tests/user-scenarios/应用场景总览.md SC-H-07;测试用例 {@code tests/test-cases/human-butler.md}
+ * TC-H-07;设计:{@code ActivityFeedbackController}(活动反馈,仅活动维度)+ {@code AdminSurveyController}
+ * (满意度调研模板)+ 差评触发复盘/回流改进):
+ * <blockquote>
+ *   流程:质检→满意度回访→回流改进。边界:不泄露隐私;差评触发复盘。
+ *   预期行为:
+ *   <ul>
+ *     <li>抽样/全量质检真人管家会话与工单(SLA、合规、态度),质检报告逐项给出通过/不通过与依据;</li>
+ *     <li>向家长发起满意度回访(问卷/评分),家长提交评分并成功;</li>
+ *     <li>质检结果回流至真人管家绩效看板,仅授权角色可见;</li>
+ *     <li>质检报告不展示家长隐私对话原文,仅展示脱敏摘要与判定依据;</li>
+ *     <li>差评自动触发复盘并关联 SC-H-04 升级应急流程;</li>
+ *     <li>同一家长重复提交评分以最后一次为准(幂等,不重复计数)。</li>
+ *   </ul>
+ * </blockquote></p>
+ *
+ * <p><b>实现现状</b>:本分支 src/main 中 {@code ButlerQualityService}、{@code ButlerSatisfactionService}、
+ * {@code ButlerPerformanceService} 及 {@code ButlerQualityInspection}/{@code ButlerSatisfaction} 实体与
+ * {@code butler_quality_inspections}/{@code butler_satisfaction}/{@code butler_performance} 表均未落地(schema.sql
+ * 无对应建表;{@code activity_feedback} 仅覆盖活动评价维度,不满足 butler 服务质检与满意度契约)。
+ * 因此本测试以「反射结构契约」探测实现缺失:能编译通过、能运行、断言失败(红),且失败断言原文
+ * 清晰可贴。</p>
+ *
+ * <p><b>GREEN 升级指引</b>:实现者创建 {@code ButlerQualityService}(含 {@code inspect} 质检入口与
+ * {@code triggerRetrospect} 差评复盘入口)、{@code ButlerSatisfactionService}(含 {@code submitSatisfaction}
+ * 评分提交入口)、{@code ButlerPerformanceService}(绩效看板入口)、相应实体与 3 张表、并在 schema.sql 同步
+ * 建表后,本测试自动转绿;届时可将结构探测升级为行为级 Mockito 验证({@code verify(...)})。</p>
+ *
+ * <p><b>权限流说明</b>:本能力为服务质检与满意度链路,绩效看板权限控制在 Controller 层;
+ * 「权限(适用时)」三流中的权限流以说明性用例标注。</p>
+ */
+class ButlerQualityQaContractTest {
+
+    /** 质检服务类(SC-H-07 质检→回流入口) */
+    private static final String BUTLER_QUALITY_SERVICE = "com.etotem.cfc.service.ButlerQualityService";
+
+    /** 满意度服务类(SC-H-07 满意度回访→评分提交入口) */
+    private static final String BUTLER_SATISFACTION_SERVICE = "com.etotem.cfc.service.ButlerSatisfactionService";
+
+    /** 管家绩效看板服务类(SC-H-07 结果回流入口) */
+    private static final String BUTLER_PERFORMANCE_SERVICE = "com.etotem.cfc.service.ButlerPerformanceService";
+
+    /** 质检记录实体(承载逐项 SLA/合规/态度 通过/不通过+依据) */
+    private static final String QUALITY_INSPECTION_ENTITY = "com.etotem.cfc.entity.ButlerQualityInspection";
+
+    /** 满意度评分实体(承载家长对管家服务的评分与差评触发标记) */
+    private static final String SATISFACTION_ENTITY = "com.etotem.cfc.entity.ButlerSatisfaction";
+
+    /** 质检/满意度/绩效建表(schema.sql 同步落地) */
+    private static final String[] QUALITY_TABLES = {
+            "butler_quality_inspections", "butler_satisfaction", "butler_performance"
+    };
+
+    // ------------------------------------------------------------------
+    // 正常流:质检服务类 + inspect 质检入口应存在
+    // ------------------------------------------------------------------
+
+    @Test
+    @DisplayName("正常流-1:ButlerQualityService 质检服务类应存在")
+    void butlerQualityService_classExists() {
+        assertNotNull(loadClass(BUTLER_QUALITY_SERVICE),
+                "[butler.quality.qa] ButlerQualityService 类不存在:契约要求抽样/全量质检真人管家会话与工单"
+                        + "(SLA、合规、态度),逐项给出通过/不通过与依据(SC-H-07)。实现未落地。");
+    }
+
+    @Test
+    @DisplayName("正常流-2:ButlerQualityService 应提供 inspect 质检入口")
+    void butlerQualityService_hasInspectMethod() {
+        Class<?> clazz = loadClass(BUTLER_QUALITY_SERVICE);
+        if (clazz == null) {
+            fail("[butler.quality.qa] ButlerQualityService 类不存在,无法验证 inspect 质检入口(SC-H-07)。");
+        }
+        boolean hasInspect = false;
+        for (Method m : clazz.getDeclaredMethods()) {
+            if (m.getName().equals("inspect")) {
+                hasInspect = true;
+                break;
+            }
+        }
+        assertTrue(hasInspect,
+                "[butler.quality.qa] ButlerQualityService 应提供 inspect(...) 方法作为质检执行入口(SC-H-07)。");
+    }
+
+    @Test
+    @DisplayName("正常流-3:ButlerSatisfactionService 满意度服务类应存在")
+    void butlerSatisfactionService_classExists() {
+        assertNotNull(loadClass(BUTLER_SATISFACTION_SERVICE),
+                "[butler.quality.qa] ButlerSatisfactionService 类不存在:契约要求向家长发起满意度回访"
+                        + "(问卷/评分),家长提交评分并成功(SC-H-07)。实现未落地。");
+    }
+
+    @Test
+    @DisplayName("正常流-4:ButlerSatisfactionService 应提供 submitSatisfaction 评分提交入口")
+    void butlerSatisfactionService_hasSubmitSatisfactionMethod() {
+        Class<?> clazz = loadClass(BUTLER_SATISFACTION_SERVICE);
+        if (clazz == null) {
+            fail("[butler.quality.qa] ButlerSatisfactionService 类不存在,无法验证 submitSatisfaction 入口(SC-H-07)。");
+        }
+        boolean hasSubmitSatisfaction = false;
+        for (Method m : clazz.getDeclaredMethods()) {
+            if (m.getName().equals("submitSatisfaction")) {
+                hasSubmitSatisfaction = true;
+                break;
+            }
+        }
+        assertTrue(hasSubmitSatisfaction,
+                "[butler.quality.qa] ButlerSatisfactionService 应提供 submitSatisfaction(...) 方法作为满意度评分提交入口(SC-H-07)。");
+    }
+
+    @Test
+    @DisplayName("正常流-5:ButlerPerformanceService 绩效看板服务类应存在")
+    void butlerPerformanceService_classExists() {
+        assertNotNull(loadClass(BUTLER_PERFORMANCE_SERVICE),
+                "[butler.quality.qa] ButlerPerformanceService 类不存在:契约要求质检结果回流至真人管家绩效看板,"
+                        + "仅授权角色可见(SC-H-07)。实现未落地。");
+    }
+
+    @Test
+    @DisplayName("正常流-6:ButlerQualityInspection 质检记录实体应存在并承载逐项质检结果")
+    void butlerQualityInspection_entityExists() {
+        Class<?> entity = loadClass(QUALITY_INSPECTION_ENTITY);
+        if (entity == null) {
+            fail("[butler.quality.qa] ButlerQualityInspection 实体不存在:SC-H-07 要求质检报告逐项给出"
+                    + "通过/不通过与依据,应有 ButlerQualityInspection 实体承载。");
+        }
+        boolean hasInspectionItems = false;
+        for (Field f : entity.getDeclaredFields()) {
+            if (f.getName().equals("inspectionItems")) {
+                hasInspectionItems = true;
+                break;
+            }
+        }
+        assertTrue(hasInspectionItems,
+                "[butler.quality.qa] ButlerQualityInspection 实体应含 inspectionItems 字段,承载逐项质检结果"
+                        + "(通过/不通过与依据,SC-H-07)。");
+    }
+
+    @Test
+    @DisplayName("正常流-7:ButlerSatisfaction 满意度实体应存在并承载评分")
+    void butlerSatisfaction_entityExists() {
+        Class<?> entity = loadClass(SATISFACTION_ENTITY);
+        if (entity == null) {
+            fail("[butler.quality.qa] ButlerSatisfaction 实体不存在:SC-H-07 要求家长提交满意度评分,"
+                    + "应有 ButlerSatisfaction 实体承载评分。");
+        }
+        boolean hasRating = false;
+        for (Field f : entity.getDeclaredFields()) {
+            if (f.getName().equals("rating")) {
+                hasRating = true;
+                break;
+            }
+        }
+        assertTrue(hasRating,
+                "[butler.quality.qa] ButlerSatisfaction 实体应含 rating 字段,承载家长对管家服务的满意度评分(SC-H-07)。");
+    }
+
+    @Test
+    @DisplayName("正常流-8:schema.sql 应含质检/满意度/绩效三张表(SC-H-07 建表落地)")
+    void schemaSql_containsQualityTables() {
+        String schema = readSchemaSql();
+        for (String table : QUALITY_TABLES) {
+            assertTrue(schema.contains(table),
+                    "[butler.quality.qa] schema.sql 缺少 " + table + " 建表(SC-H-07 质检/满意度/绩效表落地)。");
+        }
+    }
+
+    // ------------------------------------------------------------------
+    // 边界流:隐私保护与差评触发复盘(SC-H-07 异常流)
+    // ------------------------------------------------------------------
+
+    @Test
+    @DisplayName("边界流-1:ButlerQualityInspection 应含 desensitizedSummary 字段(质检不泄露对话原文)")
+    void butlerQualityInspection_hasDesensitizedSummary() {
+        Class<?> entity = loadClass(QUALITY_INSPECTION_ENTITY);
+        if (entity == null) {
+            fail("[butler.quality.qa] ButlerQualityInspection 实体不存在,无法验证脱敏摘要字段(SC-H-07)。");
+        }
+        boolean hasDesensitizedSummary = false;
+        for (Field f : entity.getDeclaredFields()) {
+            if (f.getName().equals("desensitizedSummary")) {
+                hasDesensitizedSummary = true;
+                break;
+            }
+        }
+        assertTrue(hasDesensitizedSummary,
+                "[butler.quality.qa] ButlerQualityInspection 实体应含 desensitizedSummary 字段:质检报告不展示"
+                        + "家长隐私对话原文,仅展示脱敏摘要与判定依据(SC-H-07 边界)。");
+    }
+
+    @Test
+    @DisplayName("边界流-2:ButlerQualityService 应提供 triggerRetrospect 差评触发复盘入口(关联 SC-H-04)")
+    void butlerQualityService_hasTriggerRetrospectMethod() {
+        Class<?> clazz = loadClass(BUTLER_QUALITY_SERVICE);
+        if (clazz == null) {
+            fail("[butler.quality.qa] ButlerQualityService 类不存在,无法验证 triggerRetrospect 差评复盘入口(SC-H-07)。");
+        }
+        boolean hasTriggerRetrospect = false;
+        for (Method m : clazz.getDeclaredMethods()) {
+            if (m.getName().equals("triggerRetrospect")) {
+                hasTriggerRetrospect = true;
+                break;
+            }
+        }
+        assertTrue(hasTriggerRetrospect,
+                "[butler.quality.qa] ButlerQualityService 应提供 triggerRetrospect(...) 方法:差评自动触发复盘并"
+                        + "关联 SC-H-04 升级应急流程(SC-H-07 异常流)。");
+    }
+
+    @Test
+    @DisplayName("边界流-3:ButlerSatisfaction 应含 badReviewTriggered 差评触发标记字段")
+    void butlerSatisfaction_hasBadReviewTriggeredField() {
+        Class<?> entity = loadClass(SATISFACTION_ENTITY);
+        if (entity == null) {
+            fail("[butler.quality.qa] ButlerSatisfaction 实体不存在,无法验证差评触发标记字段(SC-H-07)。");
+        }
+        boolean hasBadReviewTriggered = false;
+        for (Field f : entity.getDeclaredFields()) {
+            if (f.getName().equals("badReviewTriggered")) {
+                hasBadReviewTriggered = true;
+                break;
+            }
+        }
+        assertTrue(hasBadReviewTriggered,
+                "[butler.quality.qa] ButlerSatisfaction 实体应含 badReviewTriggered 字段,标记差评是否已触发复盘"
+                        + "(幂等,同一家长重复提交不重复计数,SC-H-07 异常流)。");
+    }
+
+    // ------------------------------------------------------------------
+    // 权限流(不适用):绩效看板权限在 Controller 层,本结构契约不覆盖
+    // ------------------------------------------------------------------
+
+    @Test
+    @DisplayName("权限流:butler.quality.qa 绩效看板权限在 Controller 层手动校验,本结构契约标注不适用")
+    void permissionFlow_notApplicable() {
+        // 说明性用例:SC-H-07 权限流(管家查本人绩效/查同事业绩403/家长查质检原文403/运营查全量质检)
+        // 在 Controller 层按角色手动校验,结构契约层不产生断言失败;仅标注「不适用」。
+        assertTrue(true, "权限流不适用:butler.quality.qa 绩效看板权限控制在 Controller 层(TC-H-07-P)。");
+    }
+
+    // ------------------------------------------------------------------
+    // 反射辅助
+    // ------------------------------------------------------------------
+
+    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 "";
+        }
+    }
+}

+ 467 - 0
cfc-backend/src/test/java/com/etotem/cfc/unit/ContactGroupImportContractTest.java

@@ -0,0 +1,467 @@
+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.List;
+import java.util.Map;
+import java.util.Scanner;
+
+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.assertThrows;
+import static org.junit.jupiter.api.Assertions.fail;
+
+/**
+ * 契约级单测:联系人分组/导入(能力键 {@code contact.group.import},单元 contact,S-cfc-284)。
+ *
+ * <p><b>契约溯源</b></p>
+ * <ul>
+ *   <li>需求:{@code tests/user-scenarios/应用场景总览.md} SC-P-62(联系人分组/导入:建分组→
+ *       导入 {@code ContactImport};边界:导入格式错误行跳过并报告);业务域 G 联系人与社交。</li>
+ *   <li>用例:{@code tests/test-cases/parent.md} TC-P-62(建分组→导入,格式错误行跳过并报告)/
+ *       TC-P-62-E(导入 CSV 含格式错误行缺电话→错误行跳过并报告『第 N 行格式错误』;非 CSV 拒绝;
+ *       正确行入库)/ TC-P-62-P(非归属数据访问统一 403/401,横向越权被拒)。</li>
+ *   <li>设计:{@code docs/superpowers/api/API_REFERENCE.md} §4.63.7(联系人/社交)+ §4.63.10
+ *       <b>缺口 G-3</b>——{@code ContactController /api/contact}(list/create/update/delete/
+ *       detail/import-phone/interaction/invite-to-family)仅单条 {@code import-phone},
+ *       <b>分组无端点</b>(ContactGroupController / ContactImportController 均不存在);
+ *       处置:后端新增 {@code POST /api/contact/group/*}(分组 CRUD + contact 分组绑定),
+ *       {@code contacts} 表加 {@code group_id} 分组字段承载。</li>
+ * </ul>
+ *
+ * <p><b>宿主契约(TDD-RED 锚点)</b>:SC-P-62「建分组→导入」规划的类,当前 src/main
+ * <b>全部未实现</b>(全库 0 引用;{@code contacts} 表无 {@code group_id} 列、schema.sql
+ * 无 {@code contact_groups} 建表)。</p>
+ *
+ * <p><b>契约方法签名(实现方按此落地)</b></p>
+ * <ul>
+ *   <li>{@code ContactGroup createGroup(String name, Long userId)} —— 建分组,归属 userId;</li>
+ *   <li>{@code List<ContactGroup> listGroups(Long userId)} —— 仅返回 userId 自身分组(横向隔离);</li>
+ *   <li>{@code List<String> validateCsvLines(String csvContent)} —— <b>纯校验</b>:解析 CSV 文本,
+ *       每条格式错误行产出一条形如『第 N 行格式错误:原因』的报告;合法行不入错误报告;
+ *       非 CSV(null/空/全空白)→ 抛 {@code IllegalArgumentException}(非 CSV 拒绝,TC-P-62-E);</li>
+ *   <li>{@code Map<String,Object> importCsv(Long groupId, Long userId, String csvContent)} ——
+ *       分组导入:合法行入库到 groupId(userId 须为该分组属主);返回 {@code importedCount}
+ *       (成功入库行数)、{@code skippedCount}、{@code skippedRows}(逐条『第 N 行格式错误』);</li>
+ *   <li>{@code boolean isGroupOwner(Long groupId, Long userId)} —— 分组归属判定(越权门禁)。</li>
+ * </ul>
+ *
+ * <p><b>契约端点(controller 结构契约)</b>:{@code com.etotem.cfc.controller.ContactGroupController}
+ * 类级 {@code @RequestMapping("/api/contact/group")},方法级 {@code @PostMapping("/create")}(建分组)、
+ * {@code @PostMapping("/list")}(分组列表)、{@code @PostMapping("/import")}(分组导入),注入
+ * {@code ContactGroupService}。schema.sql 落地 {@code contact_groups} 建表 + {@code contacts}
+ * 表加 {@code group_id} 分组绑定列(缺口 G-3)。</p>
+ *
+ * <p><b>测试范围</b>:纯契约级单测,仅 JUnit + 反射,无 Spring / 无 DB / 无真实微信 / 无外部服务;
+ * 权限流适用(分组归属=横向越权维度),按三类流覆盖。</p>
+ *
+ * <p><b>RED 预期</b>:宿主 {@code ContactGroupService} / {@code ContactImportService} 未实现——
+ * 全部宿主用例在反射探测处失败(红),断言原文「RED[contact.group.import] 契约宿主 … 未实现」;
+ * controller 与 schema.sql 结构用例分别以「契约端点未落地」「schema.sql 缺少 contact_groups」
+ * 独立失败。</p>
+ */
+class ContactGroupImportContractTest {
+
+    /** 契约宿主服务类(未实现)。 */
+    private static final String HOST_GROUP_SERVICE = "com.etotem.cfc.service.ContactGroupService";
+    private static final String HOST_IMPORT_SERVICE = "com.etotem.cfc.service.ContactImportService";
+
+    /** 契约实体与 Mapper(未实现)。 */
+    private static final String ENTITY_CONTACT_GROUP = "com.etotem.cfc.entity.ContactGroup";
+    private static final String MAPPER_CONTACT_GROUP = "com.etotem.cfc.mapper.ContactGroupMapper";
+
+    /** 契约端点 Controller(未实现)。 */
+    private static final String CONTROLLER_CLASS = "com.etotem.cfc.controller.ContactGroupController";
+
+    /** 契约端点类级路径与 schema.sql 分组承载。 */
+    private static final String ENDPOINT_BASE = "/api/contact/group";
+    private static final String GROUP_TABLE = "contact_groups";
+    private static final String CONTACT_GROUP_ID_COLUMN = "group_id";
+
+    // ------------------------------------------------------------------
+    // 测试用 CSV 文本(TC-P-62-E:合法行入库、格式错误行跳过并报告『第 N 行格式错误』)
+    // ------------------------------------------------------------------
+    /** 全合法 CSV:姓名,电话。 */
+    private static final String CSV_ALL_VALID = "张三,13800138000\n李四,13900139000\n王五,13700137000";
+    /** 含格式错误行(第 2 行缺电话)。 */
+    private static final String CSV_MISSING_PHONE = "张三,13800138000\n李四\n王五,13900139000";
+    /** 混合:第 2/3 行缺电话(格式错误),第 1/4 行合法。 */
+    private static final String CSV_MIXED = "张三,13800138000\n李四\n王五\n赵六,13600136000";
+    /** 重复号码(第 2 行与第 1 行号码相同)。 */
+    private static final String CSV_DUPLICATE_PHONE = "张三,13800138000\n李四,13800138000";
+    /** 非 CSV:无分隔结构。 */
+    private static final String CSV_NON_CSV = "this is not a csv content";
+
+    // ==================== 正常流:建分组(分组 CRUD 宿主) ====================
+
+    @Test
+    @DisplayName("正常流-1:ContactGroup 契约实体应已实现")
+    void contactGroup_entityExists() {
+        assertNotNull(loadClass(ENTITY_CONTACT_GROUP),
+                "RED[contact.group.import] ContactGroup 契约实体未实现(实现未落地):"
+                        + "SC-P-62 建分组需 ContactGroup 实体(contact_groups 表)承载分组。");
+    }
+
+    @Test
+    @DisplayName("正常流-2:ContactGroup 实体应含 userId/name 归属字段")
+    void contactGroup_entityCarriesOwnerFields() {
+        Class<?> entity = loadClass(ENTITY_CONTACT_GROUP);
+        if (entity == null) {
+            fail("RED[contact.group.import] ContactGroup 契约实体未实现(实现未落地):"
+                    + "分组归属字段 userId/name 无载体。");
+        }
+        assertTrue(hasField(entity, "userId"), "ContactGroup 应含 userId(分组归属用户)");
+        assertTrue(hasField(entity, "name"), "ContactGroup 应含 name(分组名)");
+    }
+
+    @Test
+    @DisplayName("正常流-3:ContactGroupMapper 契约接口应已实现")
+    void contactGroupMapper_interfaceExists() {
+        Class<?> mapper = loadClass(MAPPER_CONTACT_GROUP);
+        assertNotNull(mapper,
+                "RED[contact.group.import] ContactGroupMapper 契约接口未实现(实现未落地):"
+                        + "contact_groups 表无 Mapper 承载,分组 CRUD 无法落库。");
+        assertTrue(mapper.isInterface(), "ContactGroupMapper 应为接口(MyBatis-Plus BaseMapper 契约)");
+    }
+
+    @Test
+    @DisplayName("正常流-4:ContactGroupService 契约宿主应已实现")
+    void groupService_classExists() {
+        assertNotNull(contractHost(HOST_GROUP_SERVICE),
+                "RED[contact.group.import] 契约宿主 ContactGroupService 未实现(实现未落地):"
+                        + "SC-P-62 建分组→导入 服务未落地,分组 CRUD 契约无法满足。");
+    }
+
+    @Test
+    @DisplayName("正常流-5:ContactGroupService.createGroup 建分组契约方法应存在")
+    void groupService_createGroup_methodExists() {
+        assertMethodExists(HOST_GROUP_SERVICE, "createGroup", 2,
+                "SC-P-62 建分组:createGroup(name, userId) 应建分组并归属 userId。");
+    }
+
+    @Test
+    @DisplayName("正常流-6:ContactGroupService.listGroups 分组列表契约方法应存在(仅本人)")
+    void groupService_listGroups_methodExists() {
+        assertMethodExists(HOST_GROUP_SERVICE, "listGroups", 1,
+                "SC-P-62 分组列表:listGroups(userId) 应仅返回 userId 自身分组(横向隔离)。");
+    }
+
+    // ==================== 边界流:导入校验(TC-P-62-E,纯函数) ====================
+
+    @Test
+    @DisplayName("边界流-7:ContactImportService 契约宿主应已实现")
+    void importService_classExists() {
+        assertNotNull(contractHost(HOST_IMPORT_SERVICE),
+                "RED[contact.group.import] 契约宿主 ContactImportService 未实现(实现未落地):"
+                        + "SC-P-62 导入 ContactImport 服务未落地,分组导入契约无法满足。");
+    }
+
+    @Test
+    @DisplayName("边界流-8:validateCsvLines 格式错误行(缺电话)→ 报告『第 N 行格式错误』")
+    void validateCsvLines_missingPhone_reportsFormatError() {
+        Object host = contractHost(HOST_IMPORT_SERVICE);
+        List<String> errors = callList(host, "validateCsvLines", CSV_MISSING_PHONE);
+        assertNotNull(errors, "validateCsvLines 不得返回 null(逐条格式错误行报告)");
+        assertFalse(errors.isEmpty(), "缺电话格式错误行应产出报告,不得静默跳过");
+        boolean reported = false;
+        for (String msg : errors) {
+            if (msg != null && msg.contains("第 2 行") && msg.contains("格式错误")) {
+                reported = true;
+            }
+        }
+        assertTrue(reported,
+                "缺电话格式错误行应报告『第 2 行格式错误』(TC-P-62-E),实际报告=" + errors);
+    }
+
+    @Test
+    @DisplayName("边界流-9:validateCsvLines 全合法行 → 空报告(无格式错误)")
+    void validateCsvLines_allValid_emptyReport() {
+        Object host = contractHost(HOST_IMPORT_SERVICE);
+        List<String> errors = callList(host, "validateCsvLines", CSV_ALL_VALID);
+        assertNotNull(errors, "validateCsvLines 不得返回 null");
+        assertTrue(errors.isEmpty(),
+                "全合法 CSV(姓名+电话)应无格式错误报告,实际=" + errors);
+    }
+
+    @Test
+    @DisplayName("边界流-10:validateCsvLines 非 CSV/空内容 → 拒绝(IllegalArgumentException)")
+    void validateCsvLines_nonCsv_rejected() {
+        Object host = contractHost(HOST_IMPORT_SERVICE);
+        assertThrows(IllegalArgumentException.class, () -> callRaw(host, "validateCsvLines", (String) null),
+                "null 内容应被拒绝(非 CSV,TC-P-62-E)");
+        assertThrows(IllegalArgumentException.class, () -> callRaw(host, "validateCsvLines", ""),
+                "空内容应被拒绝(非 CSV,TC-P-62-E)");
+        assertThrows(IllegalArgumentException.class, () -> callRaw(host, "validateCsvLines", "   \n  \n "),
+                "全空白内容应被拒绝(非 CSV,TC-P-62-E)");
+    }
+
+    @Test
+    @DisplayName("边界流-11:validateCsvLines 非 CSV 结构(无分隔行)→ 拒绝(非 CSV 拒绝)")
+    void validateCsvLines_nonCsvStructure_rejected() {
+        Object host = contractHost(HOST_IMPORT_SERVICE);
+        assertThrows(IllegalArgumentException.class,
+                () -> callRaw(host, "validateCsvLines", CSV_NON_CSV),
+                "无 CSV 分隔结构的文本应被拒绝(非 CSV 拒绝,TC-P-62-E)");
+    }
+
+    @Test
+    @DisplayName("边界流-12:validateCsvLines 混合行 → 逐条报告错误行,正确行不入错误报告")
+    void validateCsvLines_mixedRows_skipAndReportOnlyBad() {
+        Object host = contractHost(HOST_IMPORT_SERVICE);
+        List<String> errors = callList(host, "validateCsvLines", CSV_MIXED);
+        assertNotNull(errors, "validateCsvLines 不得返回 null");
+        assertEquals(2, errors.size(),
+                "4 行中第 2/3 行缺电话(格式错误)应各报告一条,共 2 条(正确行不入错误报告),实际=" + errors);
+        assertTrue(containsLine(errors, "第 2 行"),
+                "应报告『第 2 行格式错误』(缺电话),实际=" + errors);
+        assertTrue(containsLine(errors, "第 3 行"),
+                "应报告『第 3 行格式错误』(缺电话),实际=" + errors);
+        assertFalse(containsLine(errors, "第 1 行") || containsLine(errors, "第 4 行"),
+                "合法行(第 1/4 行)不得误报为格式错误,实际=" + errors);
+    }
+
+    @Test
+    @DisplayName("边界流-13:validateCsvLines 重复号码 → 去重跳过报告")
+    void validateCsvLines_duplicatePhone_deduped() {
+        Object host = contractHost(HOST_IMPORT_SERVICE);
+        List<String> errors = callList(host, "validateCsvLines", CSV_DUPLICATE_PHONE);
+        assertNotNull(errors, "validateCsvLines 不得返回 null");
+        assertFalse(errors.isEmpty(), "重复号码应被去重跳过并报告(不得静默接受重复导入)");
+    }
+
+    // ==================== 权限流:分组归属/横向越权(TC-P-62-P) ====================
+
+    @Test
+    @DisplayName("权限流-14:isGroupOwner 契约方法应存在且他人分组归属判定为 false")
+    void importService_isGroupOwner_foreignGroup_false() {
+        Object host = contractHost(HOST_IMPORT_SERVICE);
+        Object result = callAllowRejected(host, "isGroupOwner", 500L, 1L);
+        if (result instanceof Boolean) {
+            assertFalse((Boolean) result,
+                    "groupId=500 非 userId=1 所属分组时 isGroupOwner 应返回 false(越权门禁,TC-P-62-P)");
+        }
+    }
+
+    @Test
+    @DisplayName("权限流-15:importCsv 越权分组(非本人)→ importedCount=0(横向越权被拒)")
+    void importCsv_foreignGroup_denied() {
+        Object host = contractHost(HOST_IMPORT_SERVICE);
+        // userId=1 导入到 groupId=500(非本人分组)→ 横向越权统一拒绝(TC-P-62-P:403/不泄露他人数据)
+        Object result = callAllowRejected(host, "importCsv", 500L, 1L, CSV_ALL_VALID);
+        if (result instanceof Map) {
+            Object imported = ((Map<?, ?>) result).get("importedCount");
+            assertFalse(imported != null && toLong(imported) > 0L,
+                    "越权导入非本人分组不得有成功行(横向越权被拒,TC-P-62-P)");
+        }
+    }
+
+    // ==================== 契约端点:controller + schema.sql 分组承载 ====================
+
+    @Test
+    @DisplayName("契约端点-16:ContactGroupController 应落地 /api/contact/group 且提供 create/list/import")
+    void controller_classMappedAndEndpointsExist() {
+        Class<?> clazz = loadClass(CONTROLLER_CLASS);
+        if (clazz == null) {
+            fail("RED[contact.group.import] 契约端点 ContactGroupController 未落地(实现未落地):"
+                    + "SC-P-62 分组无端点(缺口 G-3),需 POST /api/contact/group/* 承载建分组/列表/导入。");
+        }
+        RequestMapping rm = clazz.getAnnotation(RequestMapping.class);
+        assertNotNull(rm, "ContactGroupController 应标注 @RequestMapping");
+        assertEquals(ENDPOINT_BASE, firstValue(rm.value()),
+                "ContactGroupController 类路径应为 " + ENDPOINT_BASE + "(缺口 G-3 处置)");
+        boolean hasCreate = false;
+        boolean hasList = false;
+        boolean hasImport = false;
+        for (Method m : clazz.getDeclaredMethods()) {
+            PostMapping pm = m.getAnnotation(PostMapping.class);
+            if (pm == null) {
+                continue;
+            }
+            for (String path : pm.value()) {
+                if ("/create".equals(path)) {
+                    hasCreate = true;
+                }
+                if ("/list".equals(path)) {
+                    hasList = true;
+                }
+                if ("/import".equals(path)) {
+                    hasImport = true;
+                }
+            }
+        }
+        assertTrue(hasCreate, "应提供 @PostMapping /create(建分组)");
+        assertTrue(hasList, "应提供 @PostMapping /list(分组列表,仅本人)");
+        assertTrue(hasImport, "应提供 @PostMapping /import(分组导入,格式错误行跳过并报告)");
+        boolean injected = false;
+        for (Field f : clazz.getDeclaredFields()) {
+            if (HOST_GROUP_SERVICE.equals(f.getType().getName())) {
+                injected = true;
+                break;
+            }
+        }
+        assertTrue(injected, "ContactGroupController 应通过 @Resource 注入 " + HOST_GROUP_SERVICE);
+    }
+
+    @Test
+    @DisplayName("契约端点-17:schema.sql 应落地 contact_groups 建表 + contacts.group_id 分组绑定列")
+    void schemaSql_contactGroupsTableAndGroupIdColumn() {
+        String schema = readSchemaSql();
+        assertTrue(schema.contains(GROUP_TABLE),
+                "RED[contact.group.import] schema.sql 缺少 " + GROUP_TABLE + " 建表:"
+                        + "SC-P-62 分组承载(缺口 G-3)未落地。");
+        assertTrue(schema.contains(CONTACT_GROUP_ID_COLUMN),
+                "RED[contact.group.import] schema.sql contacts 表缺少 " + CONTACT_GROUP_ID_COLUMN
+                        + " 分组绑定列:ContactImport 导入落分组无字段承载(缺口 G-3)。");
+    }
+
+    // ==================== 反射辅助(锚定宿主契约,避免编译期依赖不存在类) ====================
+
+    private Object contractHost(String className) {
+        try {
+            Class<?> clazz = Class.forName(className);
+            return clazz.getDeclaredConstructor().newInstance();
+        } catch (ClassNotFoundException e) {
+            fail("RED[contact.group.import] 契约宿主 " + simpleName(className)
+                    + " 未实现(实现未落地):" + e.getMessage());
+            throw new IllegalStateException("unreachable");
+        } catch (Exception e) {
+            fail("契约宿主 " + simpleName(className) + " 实例化失败:" + e.getMessage());
+            throw new IllegalStateException("unreachable");
+        }
+    }
+
+    /** 断言契约方法存在(按方法名 + 参数个数匹配),缺失即断言失败(红)。 */
+    private void assertMethodExists(String className, String method, int paramCount, String purpose) {
+        Class<?> clazz = loadClass(className);
+        if (clazz == null) {
+            fail("RED[contact.group.import] 契约宿主 " + simpleName(className)
+                    + " 未实现(实现未落地):无法验证 " + method + " 契约方法。" + purpose);
+        }
+        for (Method m : clazz.getMethods()) {
+            if (m.getName().equals(method) && m.getParameterCount() == paramCount) {
+                return;
+            }
+        }
+        fail("RED[contact.group.import] 契约方法 " + simpleName(className) + "#" + method
+                + "(参数 " + paramCount + " 个)未实现:" + purpose);
+    }
+
+    /** 按方法名 + 参数个数匹配并调用(宽松适配基本/包装类型),契约方法缺失即断言失败。 */
+    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 callRaw(Object host, String method, Object... args) {
+        return callInternal(host, method, true, 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("契约方法 " + simpleName(host.getClass().getName()) + "#" + method
+                                + " 调用失败:" + e.getMessage());
+                        throw new IllegalStateException("unreachable");
+                    }
+                    return null;
+                }
+            }
+        }
+        if (failOnMissing) {
+            fail("RED[contact.group.import] 契约方法 " + simpleName(host.getClass().getName())
+                    + "#" + method + " 未实现");
+            throw new IllegalStateException("unreachable");
+        }
+        return null;
+    }
+
+    @SuppressWarnings("unchecked")
+    private List<String> callList(Object host, String method, Object... args) {
+        Object r = call(host, method, args);
+        if (r instanceof List) {
+            return (List<String>) r;
+        }
+        fail("契约方法 " + method + " 应返回 List<String>,实际 " + r);
+        throw new IllegalStateException("unreachable");
+    }
+
+    private boolean hasField(Class<?> clazz, String field) {
+        try {
+            clazz.getDeclaredField(field);
+            return true;
+        } catch (NoSuchFieldException e) {
+            return false;
+        }
+    }
+
+    private boolean containsLine(List<String> reports, String linePrefix) {
+        for (String msg : reports) {
+            if (msg != null && msg.contains(linePrefix)) {
+                return true;
+            }
+        }
+        return false;
+    }
+
+    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 String simpleName(String fqcn) {
+        int idx = fqcn.lastIndexOf('.');
+        return idx >= 0 ? fqcn.substring(idx + 1) : fqcn;
+    }
+
+    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 "";
+        }
+    }
+}

+ 417 - 0
cfc-backend/src/test/java/com/etotem/cfc/unit/DietMealPlanAdjustContractTest.java

@@ -0,0 +1,417 @@
+package com.etotem.cfc.unit;
+
+import org.junit.jupiter.api.Test;
+
+import java.lang.reflect.Method;
+import java.util.ArrayList;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+
+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;
+
+/**
+ * 契约级单测:能力键 {@code diet.mealPlan.adjust}(食谱收藏 / 手动微调替换食材 / 营养对齐)。
+ *
+ * <p><b>需求/设计锚点</b></p>
+ * <ul>
+ *   <li>SC-P-29(食谱收藏/调整)— 目标:沉淀常用食谱。流程:收藏食谱 → 手动微调(替换食材)。
+ *       边界:调整不破坏营养目标;重复收藏幂等仅 1 条(TC-P-29 / TC-P-29-E)。</li>
+ *   <li>SC-P-30(食谱与营养目标对齐)— 目标:确保食谱达标。流程:看食谱营养合计 vs 目标。
+ *       边界:超标/不足提示;目标未设时应提示「请先设置营养目标」且不得除零(TC-P-30 / TC-P-30-E)。</li>
+ *   <li>接口溯源:/api/diet/preferences/save(保存饮食偏好)、/api/diet/record/save(饮食记录)、
+ *       /api/health/meal/weekly(营养汇总);业务域 C「五维能量与健康」→ 饮食推荐系统。</li>
+ * </ul>
+ *
+ * <p><b>被校验的契约行为</b></p>
+ * <ul>
+ *   <li><b>收藏 / 取消收藏</b>(TC-P-29 / TC-P-29-E):{@code favorite / unfavorite / getFavoriteList}。
+ *       同一 (mealPlanId, memberId) 重复收藏幂等仅 1 条;按成员视角隔离,防横向越权(TC-P-29-P)。</li>
+ *   <li><b>手动微调替换食材</b>(TC-P-29 「调整不破坏营养目标」):{@code adjustDish} 以新旧食材替换后
+ *       重算聚合营养合计(nutritionSummary),返回替换后的菜单与重算摘要,不允许静默丢失营养键。</li>
+ *   <li><b>营养合计对齐评估</b>(TC-P-30 / TC-P-30-E):{@code alignNutrition} 对比营养合计 vs 目标,
+ *       返回 {status, percent, message};超标明确给出「超出目标 X%」、不足给「低于目标 X%」;
+ *       目标未设 → status="NO_TARGET" + 提示「请先设置营养目标」,percent 不得为 NaN/Infinity(不除零红线)。</li>
+ * </ul>
+ *
+ * <p><b>宿主契约(TDD-RED 锚点)</b>:{@code com.etotem.cfc.service.MealPlanService} ——
+ * SC-P-29/30 的 mealPlan 域在 cfclub 主线(2026-11-14)<b>尚未落地</b>(src/main 无该类、无对应端点;
+ * 「收藏」仅缺口 G-1 登记)。本测试通过反射锚定宿主契约方法(避免直接 import 不存在类导致编译失败),
+ * 运行时宿主类缺失即断言失败(红),暴露「实现未落地」这一真实缺陷;实现落地后转为验证真实行为(GREEN)。</p>
+ *
+ * <p><b>契约方法签名(实现方按此落地)</b></p>
+ * <ul>
+ *   <li>{@code boolean favorite(Long mealPlanId, Long memberId)}
+ *       —— 收藏食谱;新增成功返回 true;已存在(幂等仅 1 条)返回 false,不抛异常。</li>
+ *   <li>{@code boolean unfavorite(Long mealPlanId, Long memberId)}
+ *       —— 取消收藏;存在且移除成功返回 true;不存在返回 false。</li>
+ *   <li>{@code List<Map<String,Object>> getFavoriteList(Long memberId)}
+ *       —— 该成员收藏列表,每项 Map 至少含 {@code mealPlanId};维度须按 memberId 隔离。</li>
+ *   <li>{@code Map<String,Object> adjustDish(Map<String,Object> request)}
+ *       —— request 键:{@code mealPlanId / mealIndex / dishIndex / replacementFoodId /
+ *       replacementFood(Map: foodId,name,calories,protein,fat,carbs…) / menu(menu_json 结构)}。
+ *       返回 {status:"OK", menu(替换后), nutritionSummary(重算聚合)};非法参数 → 抛异常或 status!="OK"。
+ *       menu_json 结构沿用 4.11 登记格式:{meals:[{type,name,dishes:[{name,type,calories,
+ *       ingredients:[{name,amount}]}]}]}。</li>
+ *   <li>{@code Map<String,Object> alignNutrition(Map<String,Number> nutritionActual,
+ *       Map<String,Number> target)}
+ *       —— 营养合计 vs 目标;返回 {status:"ALIGNED"/"OVER"/"UNDER"/"NO_TARGET",
+ *       percent:Number, message:String}。percent = (actual-target)/target×100,取整;
+ *       target == null 或空 → NO_TARGET + 「请先设置营养目标」类 message,percent 仍须为合法 Number(非 NaN)。
+ *       营养键沿用 nutritionSummary 口径(calories/protein/fat/carbs…)。</li>
+ * </ul>
+ *
+ * <p><b>GREEN 升级指引</b>:实现者落地 {@code MealPlanService}(含收藏表或内存态 + adjustDish 纯函数 +
+ * alignNutrition 纯函数)后,全部用例自动转绿;{@link #hostClass_notYetImplemented()}
+ * 为 RED 守卫探针,宿主出现后该探针转红,提示通知编排侧将本键从「契约新增(RED)」登记转为「已实现(GREEN)」。</p>
+ *
+ * <p><b>测试范围</b>:纯契约级单测,无 Spring / 无 DB / 无外部服务,与同批 RED 契约测试
+ * (TeamProfitHookContractTest / TeamStarMultiplierContractTest / TeamProfitPipelineContractTest /
+ * FamilyJoinValidationRulesContractTest)同风格。</p>
+ *
+ * <p><b>RED 预期</b>:宿主 {@code MealPlanService} 未实现,全部用例在反射探测处失败(红),
+ * 断言原文为「契约宿主 com.etotem.cfc.service.MealPlanService 未实现(实现未落地)」。</p>
+ */
+class DietMealPlanAdjustContractTest {
+
+    /** 规格设计宿主类(尚未实现)。 */
+    private static final String HOST_CLASS = "com.etotem.cfc.service.MealPlanService";
+
+    // ==================== 收藏 / 幂等(TC-P-29 / TC-P-29-E) ====================
+
+    @Test
+    void favorite_firstCall_returnsTrue() {
+        Object host = contractHost();
+        assertTrue(callBoolean(host, "favorite", 1001L, 88L),
+                "[diet.mealPlan.adjust] 首次 favorite(1001,88) 应返回 true(新增收藏,TC-P-29 流程)");
+    }
+
+    @Test
+    void favorite_duplicate_idempotent_returnsFalse() {
+        Object host = contractHost();
+        callBoolean(host, "favorite", 1002L, 88L);
+        assertFalse(callBoolean(host, "favorite", 1002L, 88L),
+                "[diet.mealPlan.adjust] 同一 (mealPlanId,memberId) 重复收藏应返回 false(幂等仅 1 条,TC-P-29-E)");
+    }
+
+    @Test
+    void unfavorite_exists_returnsTrue() {
+        Object host = contractHost();
+        callBoolean(host, "favorite", 1003L, 88L);
+        assertTrue(callBoolean(host, "unfavorite", 1003L, 88L),
+                "[diet.mealPlan.adjust] 已收藏后 unfavorite(1003,88) 应返回 true(收藏已被移除,TC-P-29)");
+    }
+
+    @Test
+    void unfavorite_notExists_returnsFalse() {
+        Object host = contractHost();
+        assertFalse(callBoolean(host, "unfavorite", 9999L, 88L),
+                "[diet.mealPlan.adjust] 未收藏的 (9999,88) 取消收藏应返回 false(不抛异常、不产生副作用)");
+    }
+
+    @Test
+    void getFavoriteList_memberScopeIsolated() {
+        Object host = contractHost();
+        // 两个成员分别收藏不同食谱
+        callBoolean(host, "favorite", 1004L, 88L);
+        callBoolean(host, "favorite", 1005L, 77L);
+        List<Map<String, Object>> list = callListMap(host, "getFavoriteList", 88L);
+        assertNotNull(list, "getFavoriteList(88) 应返回列表(不得为 null)");
+        assertEquals(1, list.size(),
+                "[diet.mealPlan.adjust] getFavoriteList(88) 应仅含本人收藏 1 条(memberId 维度隔离,防横向越权 TC-P-29-P)");
+        Map<String, Object> first = list.get(0);
+        assertNotNull(first.get("mealPlanId"),
+                "收藏项 Map 应含 mealPlanId 字段(供前端展示/取消收藏定位)");
+    }
+
+    // ==================== 手动微调替换食材(TC-P-29 调整不破坏营养目标) ====================
+
+    @Test
+    void adjustDish_replacesIngredientAndRecomputesNutritionSummary() {
+        Object host = contractHost();
+        Map<String, Object> request = new HashMap<>();
+        request.put("mealPlanId", 1006L);
+        request.put("mealIndex", 0);
+        request.put("dishIndex", 1);
+        request.put("replacementFoodId", 7001L);
+        request.put("replacementFood", replacementFood());
+        request.put("menu", sampleMenu());
+
+        Map<String, Object> result = callMap(host, "adjustDish", request);
+        assertNotNull(result, "adjustDish 应返回结果 Map");
+        assertEquals("OK", result.get("status"),
+                "adjustDish 替换成功应返回 status='OK'");
+        Object ns = result.get("nutritionSummary");
+        assertNotNull(ns,
+                "[diet.mealPlan.adjust] 替换食材后的 nutritionSummary 不得为 null(TC-P-29『调整不破坏营养目标』:"
+                        + "必须基于替换后菜品集合重算聚合摘要,前端据此校验是否仍达标)");
+        assertTrue(ns instanceof Map && !((Map<?, ?>) ns).isEmpty(),
+                "nutritionSummary 应为非空 Map(含 calories/protein/fat 等聚合键,供对齐评估对齐 Nutrition 目标)");
+    }
+
+    @Test
+    void adjustDish_missingReplacementFood_failsLoudly() {
+        Object host = contractHost();
+        Map<String, Object> request = new HashMap<>();
+        request.put("mealPlanId", 1006L);
+        request.put("mealIndex", 0);
+        request.put("dishIndex", 1);
+        // 缺 replacementFood / replacementFoodId —— 非法载荷
+        request.put("menu", sampleMenu());
+        try {
+            Map<String, Object> result = callMap(host, "adjustDish", request);
+            assertTrue(result == null || !"OK".equals(result.get("status")),
+                    "[diet.mealPlan.adjust] 缺 replacementFood 的非法载荷应失败(抛异常或 status!='OK'),"
+                            + "不允许静默以原食材被 null 顶替(破坏营养目标)");
+        } catch (RuntimeException e) {
+            assertNotNull(e.getMessage(), "抛出的异常必须带可读 message");
+        } catch (Exception e) {
+            fail("adjustDish 非法载荷应抛出可读异常,实际:" + e.getClass().getName());
+        }
+    }
+
+    // ==================== 营养对齐评估(TC-P-30 / TC-P-30-E) ====================
+
+    @Test
+    void alignNutrition_overTarget_statusOver_percentAndHint() {
+        Object host = contractHost();
+        Map<String, Number> actual = numMap("calories", 3000);
+        Map<String, Number> target = numMap("calories", 1000);
+        Map<String, Object> res = callMap(host, "alignNutrition", actual, target);
+        assertEquals("OVER", res.get("status"),
+                "[diet.mealPlan.adjust] 营养合计超目标应 status='OVER'(TC-P-30-E『超标明确标红提示』)");
+        assertEquals(200.0, num(res.get("percent")), 0.001,
+                "percent 应为 (3000-1000)/1000×100=200(TC-P-30-E『超出目标 X%』的 X)");
+        assertNotNull(res.get("message"));
+        assertTrue(String.valueOf(res.get("message")).contains("超出目标")
+                        || String.valueOf(res.get("message")).contains("%"),
+                "message 应含『超出目标』或百分号,满足 TC-P-30-E 文案语义");
+    }
+
+    @Test
+    void alignNutrition_underTarget_statusUnder_hint() {
+        Object host = contractHost();
+        Map<String, Number> actual = numMap("calories", 1000);
+        Map<String, Number> target = numMap("calories", 5000);
+        Map<String, Object> res = callMap(host, "alignNutrition", actual, target);
+        assertEquals("UNDER", res.get("status"),
+                "[diet.mealPlan.adjust] 营养合计低于目标应 status='UNDER'(TC-P-30『不足提示』分支)");
+        assertNotNull(res.get("message"));
+        assertTrue(String.valueOf(res.get("message")).contains("低于目标")
+                        || String.valueOf(res.get("message")).contains("%"),
+                "不足分支 message 应含『低于目标』或百分号");
+    }
+
+    @Test
+    void alignNutrition_noTarget_noDivideByZero_messageSaysSetTarget() {
+        Object host = contractHost();
+        Map<String, Number> actual = numMap("calories", 3000);
+        Map<String, Object> res = callMapWithNullTarget(host, "alignNutrition", actual);
+        assertEquals("NO_TARGET", res.get("status"),
+                "[diet.mealPlan.adjust] target 为 null 应 status='NO_TARGET'(目标未设时不强行计算,TC-P-30-E)");
+        String msg = String.valueOf(res.get("message"));
+        assertTrue(msg.contains("请先设置营养目标") || msg.contains("未设置营养目标")
+                        || msg.contains("未设置"),
+                "message 应提示『请先设置营养目标』类文案(TC-P-30-E 硬性要求),实际:" + msg);
+        Object percent = res.get("percent");
+        assertNotNull(percent,
+                "NO_TARGET 分支 percent 键必须存在(字段语义稳定);取值不参与计算但不除零");
+        double pv = num(percent);
+        assertFalse(Double.isNaN(pv) || Double.isInfinite(pv),
+                "[diet.mealPlan.adjust] NO_TARGET 分支 percent 不得为 NaN/Infinity——契约红线:不除零(TC-P-30-E)。"
+                        + "实际 percent=" + percent);
+    }
+
+    @Test
+    void alignNutrition_alignedWithinTarget_statusAligned() {
+        Object host = contractHost();
+        Map<String, Number> actual = numMap("calories", 1000);
+        Map<String, Number> target = numMap("calories", 1000);
+        Map<String, Object> res = callMap(host, "alignNutrition", actual, target);
+        assertEquals("ALIGNED", res.get("status"),
+                "[diet.mealPlan.adjust] 营养合计等于目标应 status='ALIGNED'(达标态)");
+    }
+
+    // ==================== RED 守卫探针 ====================
+
+    @Test
+    void hostClass_notYetImplemented() {
+        try {
+            Class.forName(HOST_CLASS);
+            fail("[diet.mealPlan.adjust] RED 契约宿主 " + HOST_CLASS
+                    + " 已出现——本键实现已意外落地;请通知编排侧将此键从『契约新增(RED)』转为『实现(GREEN)』,"
+                    + "并删除本探针后重验。");
+        } catch (ClassNotFoundException expected) {
+            // RED 预期:宿主缺失,主用例全部在此路径失败
+        }
+    }
+
+    // ==================== fixture ====================
+
+    /** 替换食材(鸡胸肉)承载营养字段。 */
+    private static Map<String, Object> replacementFood() {
+        Map<String, Object> food = new HashMap<>();
+        food.put("foodId", 7001L);
+        food.put("name", "鸡胸肉");
+        food.put("calories", 165);
+        food.put("protein", 31);
+        food.put("fat", 3.6);
+        food.put("carbs", 0);
+        return food;
+    }
+
+    /** menu_json 结构(4.11 登记格式):meals → dishes → ingredients。 */
+    private static Map<String, Object> sampleMenu() {
+        List<Map<String, Object>> ingredients0 = new ArrayList<>();
+        Map<String, Object> ing0 = new HashMap<>();
+        ing0.put("name", "猪肉");
+        ing0.put("amount", "150g");
+        ingredients0.add(ing0);
+
+        List<Map<String, Object>> ingredients1 = new ArrayList<>();
+        Map<String, Object> ing1 = new HashMap<>();
+        ing1.put("name", "鸡蛋");
+        ing1.put("amount", "2个");
+        ingredients1.add(ing1);
+
+        Map<String, Object> dish0 = new HashMap<>();
+        dish0.put("name", "红烧肉");
+        dish0.put("type", "dish");
+        dish0.put("calories", 450);
+        dish0.put("ingredients", ingredients0);
+
+        Map<String, Object> dish1 = new HashMap<>();
+        dish1.put("name", "番茄炒蛋");
+        dish1.put("type", "dish");
+        dish1.put("calories", 180);
+        dish1.put("ingredients", ingredients1);
+
+        List<Map<String, Object>> dishes = new ArrayList<>();
+        dishes.add(dish0);
+        dishes.add(dish1);
+
+        Map<String, Object> meal = new HashMap<>();
+        meal.put("type", "lunch");
+        meal.put("name", "午餐");
+        meal.put("dishes", dishes);
+
+        List<Map<String, Object>> meals = new ArrayList<>();
+        meals.add(meal);
+
+        Map<String, Object> menu = new HashMap<>();
+        menu.put("meals", meals);
+        return menu;
+    }
+
+    private static Map<String, Number> numMap(String key, int v) {
+        Map<String, Number> m = new HashMap<>();
+        m.put(key, v);
+        return m;
+    }
+
+    private static double num(Object o) {
+        assertTrue(o instanceof Number, "期望 Number,实际 " + (o == null ? "null" : o.getClass().getSimpleName()));
+        return ((Number) o).doubleValue();
+    }
+
+    // ==================== 反射辅助(锚定宿主契约,避免编译期依赖不存在类) ====================
+
+    private Object contractHost() {
+        try {
+            Class<?> clazz = Class.forName(HOST_CLASS);
+            return clazz.getDeclaredConstructor().newInstance();
+        } catch (ClassNotFoundException e) {
+            fail("RED[diet.mealPlan.adjust] 契约宿主 " + HOST_CLASS + " 未实现(实现未落地):" + e.getMessage());
+            throw new IllegalStateException("unreachable");
+        } catch (Exception e) {
+            fail("契约宿主 " + HOST_CLASS + " 实例化失败:" + 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
+                            + "(" + paramTypesDesc(args) + ") 调用失败:" + rootMessage(e));
+                    throw new IllegalStateException("unreachable");
+                }
+            }
+        }
+        fail("RED[diet.mealPlan.adjust] 契约方法 " + HOST_CLASS + "#" + method
+                + "(" + paramTypesDesc(args) + ") 未实现");
+        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 + "(" + typeOf(r) + ")");
+        throw new IllegalStateException("unreachable");
+    }
+
+    @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 + "(" + typeOf(r) + ")");
+        throw new IllegalStateException("unreachable");
+    }
+
+    /** alignNutrition 双参版第二参为 null 时的显式调用(避免 varargs 把 (actual, null) 折叠成 1 参)。 */
+    private Map<String, Object> callMapWithNullTarget(Object host, String method, Object actual) {
+        Object[] args = new Object[]{actual, null};
+        Object r = call(host, method, args);
+        if (r instanceof Map) {
+            return (Map<String, Object>) r;
+        }
+        fail("契约方法 " + method + "() 应返回 Map,实际 " + r + "(" + typeOf(r) + ")");
+        throw new IllegalStateException("unreachable");
+    }
+
+    @SuppressWarnings("unchecked")
+    private List<Map<String, Object>> callListMap(Object host, String method, Object... args) {
+        Object r = call(host, method, args);
+        if (r instanceof List) {
+            return (List<Map<String, Object>>) r;
+        }
+        fail("契约方法 " + method + "() 应返回 List<Map>,实际 " + r + "(" + typeOf(r) + ")");
+        throw new IllegalStateException("unreachable");
+    }
+
+    private static String rootMessage(Throwable t) {
+        Throwable cur = t;
+        while (cur.getCause() != null) {
+            cur = cur.getCause();
+        }
+        return cur.getMessage() == null ? cur.getClass().getSimpleName() : cur.getMessage();
+    }
+
+    private static String typeOf(Object o) {
+        return o == null ? "null" : o.getClass().getSimpleName();
+    }
+
+    private static String paramTypesDesc(Object[] args) {
+        StringBuilder sb = new StringBuilder();
+        for (int i = 0; i < args.length; i++) {
+            if (i > 0) {
+                sb.append(", ");
+            }
+            Object a = args[i];
+            sb.append(a == null ? "null" : a.getClass().getSimpleName());
+        }
+        return sb.toString();
+    }
+}

+ 374 - 0
cfc-backend/src/test/java/com/etotem/cfc/unit/DietMealPlanGenerateContractTest.java

@@ -0,0 +1,374 @@
+package com.etotem.cfc.unit;
+
+import com.etotem.cfc.entity.DietPreferences;
+import com.etotem.cfc.mapper.DietPreferencesMapper;
+import com.etotem.cfc.mapper.DietRecommendationMapper;
+import com.etotem.cfc.mapper.FamilyMemberMapper;
+import com.etotem.cfc.mapper.MealConfigMapper;
+import com.etotem.cfc.service.AiGateway;
+import com.etotem.cfc.service.BeijingNutritionService;
+import com.etotem.cfc.service.DietRecommendationService;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Test;
+import org.mockito.InjectMocks;
+import org.mockito.Mock;
+import org.mockito.MockitoAnnotations;
+
+import java.io.File;
+import java.io.IOException;
+import java.lang.reflect.Method;
+import java.nio.charset.StandardCharsets;
+import java.nio.file.Files;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+
+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;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.Mockito.when;
+
+/**
+ * 契约级单测:能力键 {@code diet.mealPlan.generate}(家庭食谱·一日三餐生成),R 系列场景 + 需求 SC-P-27 / SC-P-28。
+ *
+ * <p><b>需求 / 设计溯源</b></p>
+ * <ul>
+ *   <li>需求:{@code tests/user-scenarios/应用场景总览.md} SC-P-27(家庭食谱生成:基于菌群报告 + 营养目标 →
+ *       生成早/午/晚食谱(食材/用量/禁忌标注);边界:<b>无报告降级通用食谱</b>;<b>忌口/过敏自动排除</b>)
+ *       与 SC-P-28(食谱按食材筛选/忌口:设忌口过敏 → <b>食谱重算排除项</b>;边界:<b>忌口冲突时提示</b>);业务域 C;模块:饮食推荐系统 / 家庭食谱</li>
+ *   <li>设计:{@code docs/superpowers/api/API_REFERENCE.md} §4.11 饮食推荐 ——
+ *       {@code /api/diet/meals/config}(餐食配置 {@code participantMemberIds} 共餐人)、
+ *       {@code /api/diet/meals/config/save}(批量格式 {@code configs:{breakfast,lunch,dinner}})、
+ *       {@code /api/diet/recommendation/generate}(单餐次生成 {@code date / meal_type / participant_member_ids})</li>
+ * </ul>
+ *
+ * <p><b>实现现状(src/main 核实)</b>:本分支 src/main 中 {@link DietRecommendationService} 仅提供
+ * {@code generateRecommendation}(单餐次生成)与 {@code getTodayRecommendation};<b>「一日三餐 MealPlan
+ * 聚合生成」能力未落地</b>:无 {@code generateDailyMealPlan}、无参与者忌口/过敏并集解析、
+ * 无「按忌口重算排除项 + 冲突提示」方法,返回层也无 {@code degraded / excludedItems} 契约字段。</p>
+ *
+ * <p><b>契约方法签名(实现方按此落地)</b></p>
+ * <ul>
+ *   <li>{@code Map<String,Object> generateDailyMealPlan(Long familyId, Map<String,Object> request)}
+ *       —— 一日三餐聚合生成(SC-P-27)。request 同 §4.11 {@code /generate} 载荷:{@code date / participant_member_ids /
+ *       nutrition_goals / view_key}。返回 Map 必须含:{@code meals}(键 {@code breakfast/lunch/dinner} 三顿)、
+ *       {@code nutritionSummary}、{@code degraded}(Boolean:无报告降级通用食谱的标志)、{@code excludedItems}
+ *       (List&lt;String&gt;:忌口/过敏自动排除项清单)。</li>
+ *   <li>{@code List<String> resolveParticipantExclusions(List<Long> participantMemberIds)}
+ *       —— 参与者忌口/过敏关键词并集(SC-P-27「忌口/过敏自动排除」+ SC-P-28),来源
+ *       {@code diet_preferences.allergies / absoluteAvoid}(实体 {@link DietPreferences})。</li>
+ *   <li>{@code Map<String,Object> excludeRestrictedFromMenu(Object menuJson, List<String> exclusions)}
+ *       —— 按忌口重算排除项(SC-P-28 主流程)。返回 Map 必须含:{@code menu}(过滤后菜单)、
+ *       {@code excludedItems}(剔除清单)、{@code conflictPrompt}(忌口冲突时提示,无冲突可为空串/**null**)。</li>
+ * </ul>
+ *
+ * <p><b>测试范围</b>:纯契约级单测 —— JUnit5 + Mockito + 反射结构探测,无 Spring / 无 DB / 无真实外部服务
+ * (与同批 RED 契约测试 TeamProfitHookContractTest / TeamStarMultiplierContractTest 同风格)。</p>
+ *
+ * <p><b>RED 预期</b>:三个契约方法在 {@link DietRecommendationService} 中均缺失(实现未落地),
+ * 结构用例在反射探测处断言失败(红);行为用例在方法解析处断言失败(红)。</p>
+ *
+ * <p><b>GREEN 升级指引</b>:实现者按上述签名落地后本测试自动转绿:结构用例直接通过;
+ * 行为用例在方法存在后转为校验真实返回形态(meals 三键 / degraded / excludedItems / conflictPrompt)。</p>
+ */
+class DietMealPlanGenerateContractTest {
+
+    private static final Long FAMILY_ID = 100L;
+    private static final Long MEMBER_A = 11L; // 有忌口/过敏
+    private static final Long MEMBER_B = 12L; // 无忌口/过敏
+
+    @Mock
+    private DietRecommendationMapper dietRecommendationMapper;
+
+    @Mock
+    private BeijingNutritionService beijingNutritionService;
+
+    @Mock
+    private AiGateway aiGateway;
+
+    @Mock
+    private MealConfigMapper mealConfigMapper;
+
+    @Mock
+    private FamilyMemberMapper familyMemberMapper;
+
+    @Mock
+    private DietPreferencesMapper dietPreferencesMapper;
+
+    @InjectMocks
+    private DietRecommendationService service;
+
+    @BeforeEach
+    void setUp() {
+        MockitoAnnotations.openMocks(this);
+    }
+
+    // ==================================================================
+    // 结构契约 A:一日三餐聚合生成 generateDailyMealPlan(SC-P-27)
+    // ==================================================================
+
+    @Test
+    @DisplayName("A1:generateDailyMealPlan(Long, Map) 方法应存在(SC-P-27 一日三餐聚合生成)")
+    void generateDailyMealPlan_methodExists() {
+        Method m = findMethod("generateDailyMealPlan", Long.class, Map.class);
+        assertNotNull(m,
+                "[diet.mealPlan.generate] DietRecommendationService 缺少 generateDailyMealPlan(Long, Map)(SC-P-27):"
+                        + "契约要求基于 participant_member_ids 共餐人 + nutrition_goals 一次生成早/午/晚三餐,"
+                        + "返回 meals(breakfast/lunch/dinner) + degraded + excludedItems。现状仅单餐次 generateRecommendation。");
+    }
+
+    @Test
+    @DisplayName("A2:generateDailyMealPlan 返回类型应为 Map(契约返回形态容器)")
+    void generateDailyMealPlan_returnTypeIsMap() {
+        Method m = findMethod("generateDailyMealPlan", Long.class, Map.class);
+        if (m == null) {
+            fail("[diet.mealPlan.generate] generateDailyMealPlan 未实现,无法校验返回类型(SC-P-27)。");
+        }
+        assertTrue(Map.class.isAssignableFrom(m.getReturnType()),
+                "[diet.mealPlan.generate] generateDailyMealPlan 应返回 Map<String,Object>(含 meals/degraded/excludedItems)。");
+    }
+
+    // ==================================================================
+    // 结构契约 B:忌口/过敏并集解析 resolveParticipantExclusions(SC-P-28)
+    // ==================================================================
+
+    @Test
+    @DisplayName("B1:resolveParticipantExclusions(List) 方法应存在(参与者忌口/过敏并集)")
+    void resolveParticipantExclusions_methodExists() {
+        Method m = findMethod("resolveParticipantExclusions", List.class);
+        assertNotNull(m,
+                "[diet.mealPlan.generate] DietRecommendationService 缺少 resolveParticipantExclusions(List)(SC-P-28):"
+                        + "契约要求聚合各参与者 diet_preferences.allergies/absoluteAvoid 关键词并集,"
+                        + "供生成与重算时自动排除。");
+    }
+
+    @Test
+    @DisplayName("B2:resolveParticipantExclusions 返回类型应为 List(关键词并集)")
+    void resolveParticipantExclusions_returnTypeIsList() {
+        Method m = findMethod("resolveParticipantExclusions", List.class);
+        if (m == null) {
+            fail("[diet.mealPlan.generate] resolveParticipantExclusions 未实现,无法校验返回类型(SC-P-28)。");
+        }
+        assertTrue(List.class.isAssignableFrom(m.getReturnType()),
+                "[diet.mealPlan.generate] resolveParticipantExclusions 应返回 List<String> 关键词并集。");
+    }
+
+    // ==================================================================
+    // 结构契约 C:按忌口重算排除项 excludeRestrictedFromMenu(SC-P-28)
+    // ==================================================================
+
+    @Test
+    @DisplayName("C1:excludeRestrictedFromMenu(Object, List) 方法应存在(按忌口重算排除项)")
+    void excludeRestrictedFromMenu_methodExists() {
+        Method m = findMethod("excludeRestrictedFromMenu", Object.class, List.class);
+        assertNotNull(m,
+                "[diet.mealPlan.generate] DietRecommendationService 缺少 excludeRestrictedFromMenu(Object, List)(SC-P-28):"
+                        + "契约要求设忌口/过敏后对现有菜单重算排除项,返回 menu + excludedItems + conflictPrompt。");
+    }
+
+    @Test
+    @DisplayName("C2:excludeRestrictedFromMenu 返回类型应为 Map(menu/excludedItems/conflictPrompt)")
+    void excludeRestrictedFromMenu_returnTypeIsMap() {
+        Method m = findMethod("excludeRestrictedFromMenu", Object.class, List.class);
+        if (m == null) {
+            fail("[diet.mealPlan.generate] excludeRestrictedFromMenu 未实现,无法校验返回类型(SC-P-28)。");
+        }
+        assertTrue(Map.class.isAssignableFrom(m.getReturnType()),
+                "[diet.mealPlan.generate] excludeRestrictedFromMenu 应返回 Map(menu/excludedItems/conflictPrompt)。");
+    }
+
+    // ==================================================================
+    // 源码锚点:缺失契约字段标记(辅助定位实现未落地)
+    // ==================================================================
+
+    @Test
+    @DisplayName("D1:DietRecommendationService 源码应含 MealPlan 契约标记(degraded/excludedItems)")
+    void source_containsMealPlanContractMarkers() {
+        String src = readMainSource("service/DietRecommendationService.java");
+        assertTrue(src.contains("excludedItems") && src.contains("degraded"),
+                "[diet.mealPlan.generate] DietRecommendationService 源码缺少契约标记 excludedItems / degraded(SC-P-27):"
+                        + "无报告降级通用食谱须以 degraded 标志透出、忌口/过敏自动排除须以 excludedItems 清单透出,"
+                        + "现状源码均未出现。");
+    }
+
+    // ==================================================================
+    // 行为契约 E:一日三餐聚合生成的返回形态(SC-P-27,RED 在方法解析处失败)
+    // ==================================================================
+
+    @Test
+    @DisplayName("E1:generateDailyMealPlan 应返回 meals 三键(breakfast/lunch/dinner)")
+    void generateDailyMealPlan_returnsThreeMeals() {
+        Map<String, Object> request = new HashMap<>();
+        request.put("date", "2026-11-14");
+        request.put("participant_member_ids", "[11,12]");
+
+        Object result = invokeContract("generateDailyMealPlan", FAMILY_ID, request);
+
+        assertNotNull(result, "[diet.mealPlan.generate] generateDailyMealPlan 不应返回 null(SC-P-27)。");
+        Map<?, ?> resultMap = (Map<?, ?>) result;
+        Object meals = resultMap.get("meals");
+        assertNotNull(meals,
+                "[diet.mealPlan.generate] 返回 Map 应含 meals 键(SC-P-27 早/午/晚三餐容器)。");
+        Map<?, ?> mealsMap = (Map<?, ?>) meals;
+        assertTrue(mealsMap.containsKey("breakfast") && mealsMap.containsKey("lunch") && mealsMap.containsKey("dinner"),
+                "[diet.mealPlan.generate] meals 应含 breakfast/lunch/dinner 三键(早/午/晚三餐,SC-P-27)。");
+    }
+
+    @Test
+    @DisplayName("E2:generateDailyMealPlan 应返回 degraded 布尔键(无报告降级通用食谱标志)")
+    void generateDailyMealPlan_returnsDegradedFlag() {
+        Map<String, Object> request = new HashMap<>();
+        request.put("date", "2026-11-14");
+        request.put("participant_member_ids", "[11,12]");
+
+        Object result = invokeContract("generateDailyMealPlan", FAMILY_ID, request);
+
+        Map<?, ?> resultMap = (Map<?, ?>) result;
+        assertTrue(resultMap.containsKey("degraded"),
+                "[diet.mealPlan.generate] 返回 Map 应含 degraded 键(Boolean):无菌群报告时降级通用食谱须置 true(SC-P-27 边界)。");
+    }
+
+    @Test
+    @DisplayName("E3:generateDailyMealPlan 应返回 excludedItems 键(忌口/过敏自动排除清单)")
+    void generateDailyMealPlan_returnsExcludedItems() {
+        Map<String, Object> request = new HashMap<>();
+        request.put("date", "2026-11-14");
+        request.put("participant_member_ids", "[11,12]");
+
+        Object result = invokeContract("generateDailyMealPlan", FAMILY_ID, request);
+
+        Map<?, ?> resultMap = (Map<?, ?>) result;
+        assertTrue(resultMap.containsKey("excludedItems"),
+                "[diet.mealPlan.generate] 返回 Map 应含 excludedItems 键(List<String>):"
+                        + "参与者忌口/过敏须自动排除并透出清单(SC-P-27「忌口/过敏自动排除」)。");
+    }
+
+    // ==================================================================
+    // 行为契约 F:忌口/过敏并集解析(SC-P-28)
+    // ==================================================================
+
+    @Test
+    @DisplayName("F1:resolveParticipantExclusions 应返回非空并集(成员有忌口时)")
+    void resolveParticipantExclusions_unionNonEmpty() {
+        DietPreferences pA = preferences(MEMBER_A, "花生,海鲜", "辣");
+        DietPreferences pB = preferences(MEMBER_B, null, null);
+        when(dietPreferencesMapper.selectList(any())).thenReturn(java.util.Arrays.asList(pA, pB));
+
+        Object result = invokeContract("resolveParticipantExclusions",
+                java.util.Arrays.asList(MEMBER_A, MEMBER_B));
+
+        assertNotNull(result, "[diet.mealPlan.generate] resolveParticipantExclusions 不应返回 null(SC-P-28)。");
+        List<?> exclusions = (List<?>) result;
+        assertTrue(exclusions.contains("花生") && exclusions.contains("海鲜"),
+                "[diet.mealPlan.generate] 成员过敏关键词应并入结果集(allergies:花生、海鲜),实际=" + exclusions);
+    }
+
+    // ==================================================================
+    // 行为契约 G:按忌口重算排除项 + 冲突提示(SC-P-28)
+    // ==================================================================
+
+    @Test
+    @DisplayName("G1:excludeRestrictedFromMenu 应剔除命中忌口的菜品并透出排除清单")
+    void excludeRestrictedFromMenu_filtersHitDishes() {
+        // 菜单含「清蒸鲈鱼」与「葱爆羊肉」,忌口「羊肉」→ 应剔除羊肉菜、保留鲈鱼
+        String menuJson = "{\"meals\":["
+                + "{\"name\":\"清蒸鲈鱼\",\"ingredients\":[\"鲈鱼\",\"姜\"]},"
+                + "{\"name\":\"葱爆羊肉\",\"ingredients\":[\"羊肉\",\"大葱\"]}]}";
+
+        Object result = invokeContract("excludeRestrictedFromMenu", menuJson,
+                java.util.Collections.singletonList("羊肉"));
+
+        assertNotNull(result, "[diet.mealPlan.generate] excludeRestrictedFromMenu 不应返回 null(SC-P-28)。");
+        Map<?, ?> resultMap = (Map<?, ?>) result;
+        assertTrue(resultMap.containsKey("excludedItems"),
+                "[diet.mealPlan.generate] 返回 Map 应含 excludedItems(剔除清单,SC-P-28)。");
+        List<?> excluded = (List<?>) resultMap.get("excludedItems");
+        assertTrue(excluded != null && excluded.contains("羊肉"),
+                "[diet.mealPlan.generate] excludedItems 应含命中忌口「羊肉」,实际=" + excluded);
+        String filtered = String.valueOf(resultMap.get("menu"));
+        assertFalse(filtered.contains("羊肉"),
+                "[diet.mealPlan.generate] 过滤后菜单不应再含「羊肉」菜(设忌口→食谱重算排除项,SC-P-28)。");
+        assertTrue(filtered.contains("鲈鱼"),
+                "[diet.mealPlan.generate] 过滤后菜单应保留未命中忌口的菜(清蒸鲈鱼)。");
+    }
+
+    @Test
+    @DisplayName("G2:excludeRestrictedFromMenu 忌口冲突时应透出 conflictPrompt 提示")
+    void excludeRestrictedFromMenu_conflictPrompts() {
+        // 边界 SC-P-28:全部菜品均命中忌口(全被剔除)→ 忌口冲突提示
+        String menuJson = "{\"meals\":["
+                + "{\"name\":\"羊肉串\",\"ingredients\":[\"羊肉\"]},"
+                + "{\"name\":\"羊排\",\"ingredients\":[\"羊排\"]}]}";
+
+        Object result = invokeContract("excludeRestrictedFromMenu", menuJson,
+                java.util.Collections.singletonList("羊肉"));
+
+        assertNotNull(result, "[diet.mealPlan.generate] excludeRestrictedFromMenu 不应返回 null(SC-P-28 边界)。");
+        Map<?, ?> resultMap = (Map<?, ?>) result;
+        assertTrue(resultMap.containsKey("conflictPrompt"),
+                "[diet.mealPlan.generate] 返回 Map 应含 conflictPrompt 键(忌口冲突时提示,SC-P-28 边界)。");
+        String prompt = resultMap.get("conflictPrompt") == null ? "" : String.valueOf(resultMap.get("conflictPrompt"));
+        assertFalse(prompt.trim().isEmpty(),
+                "[diet.mealPlan.generate] 全部菜品命中忌口时应返回非空 conflictPrompt(忌口冲突提示),实际为空。");
+    }
+
+    // ==================================================================
+    // 反射辅助(锚定宿主契约,避免编译期依赖不存在方法)
+    // ==================================================================
+
+    private Method findMethod(String name, Class<?>... paramTypes) {
+        try {
+            return DietRecommendationService.class.getDeclaredMethod(name, paramTypes);
+        } catch (NoSuchMethodException e) {
+            return null;
+        }
+    }
+
+    /** 按方法名 + 参数个数匹配并调用(宽松适配基本/包装类型),契约方法缺失即断言失败(红)。 */
+    private Object invokeContract(String method, Object... args) {
+        for (Method m : DietRecommendationService.class.getDeclaredMethods()) {
+            if (m.getName().equals(method) && m.getParameterCount() == args.length) {
+                try {
+                    m.setAccessible(true);
+                    return m.invoke(service, args);
+                } catch (Exception e) {
+                    fail("[diet.mealPlan.generate] 契约方法 " + method + " 调用失败:" + e.getMessage());
+                    throw new IllegalStateException("unreachable");
+                }
+            }
+        }
+        fail("RED[diet.mealPlan.generate] 契约方法 DietRecommendationService#" + method + " 未实现(实现未落地)");
+        throw new IllegalStateException("unreachable");
+    }
+
+    private DietPreferences preferences(Long memberId, String allergies, String absoluteAvoid) {
+        DietPreferences p = new DietPreferences();
+        p.setFamilyMemberId(memberId);
+        p.setAllergies(allergies);
+        p.setAbsoluteAvoid(absoluteAvoid);
+        return p;
+    }
+
+    /** 读取 src/main 源码文件(surefire 工作目录 = cfc-backend 模块目录),找不到返回空串 */
+    private String readMainSource(String relative) {
+        String[] candidates = {
+                "src/main/java/com/etotem/cfc/" + relative,
+                "cfc-backend/src/main/java/com/etotem/cfc/" + relative,
+                "../cfc-backend/src/main/java/com/etotem/cfc/" + relative
+        };
+        for (String candidate : candidates) {
+            File file = new File(candidate);
+            if (file.isFile()) {
+                try {
+                    return new String(Files.readAllBytes(file.toPath()), StandardCharsets.UTF_8);
+                } catch (IOException e) {
+                    return "";
+                }
+            }
+        }
+        return "";
+    }
+}

+ 235 - 0
cfc-backend/src/test/java/com/etotem/cfc/unit/EnergyLedgerViewContractTest.java

@@ -0,0 +1,235 @@
+package com.etotem.cfc.unit;
+
+import com.baomidou.mybatisplus.extension.plugins.pagination.Page;
+import com.etotem.cfc.common.Result;
+import com.etotem.cfc.controller.EnergyController;
+import com.etotem.cfc.entity.EnergyDimension;
+import com.etotem.cfc.entity.EnergyLog;
+import com.etotem.cfc.mapper.EnergyDimensionMapper;
+import com.etotem.cfc.mapper.EnergyLogMapper;
+import com.etotem.cfc.service.EnergyService;
+import com.fasterxml.jackson.annotation.JsonFormat;
+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.util.Arrays;
+import java.util.HashMap;
+import java.util.Map;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.when;
+
+/**
+ * 契约测试:能力键 {@code energy.ledger.view}(SC-P-18 能量流水查看,业务域 C 五维能量与健康)。
+ *
+ * <p><b>契约锚点</b></p>
+ * <ul>
+ *   <li>需求:{@code tests/user-scenarios/应用场景总览.md} SC-P-18 —— 目标:追溯能量来源;流程:能量明细(任务/打卡/测评);边界:时间格式统一。模块:{@code EnergyController}。</li>
+ *   <li>设计:{@code docs/superpowers/api/API_REFERENCE.md} §4.5 —— {@code POST /api/energy/logs} 能量流水。</li>
+ *   <li>职责边界:本键 = 查看流水(view);{@code energy.ledger.guard}(S-cfc-225)= 账本一致性守卫。二者互补不重复:guard 校验 {@code balanceAfter==prev+amount},view 校验 <b>展示口径</b>(来源可读名 + 时间格式)。</li>
+ * </ul>
+ *
+ * <p><b>被校验的契约行为(展示口径,TDD-RED)</b></p>
+ * <ul>
+ *   <li><b>来源溯源可读</b>:每条流水必须暴露可读来源名 {@code sourceName}("task"→"完成任务"、"health_checkin"→"健康打卡"、"assessment"→"测评"等),而非仅原始 {@code sourceType} 码;未映射来源回退原始码,不得抛错。</li>
+ *   <li><b>维度代码</b>:每条流水需暴露 {@code dimensionCode}(如 "body"/"mind"),使前端无需再查维度表即可按维度着色/筛选。</li>
+ *   <li><b>时间格式统一</b>:{@code createdAt} 响应须以 {@code yyyy-MM-dd'T'HH:mm:ss}(ISO 8601)字符串暴露,而非裸 {@code java.util.Date}(Jackson 默认序列化为 epoch 毫秒)。与项目时间显示规范一致(后端统一 ISO 8601,前端按需格式化)。</li>
+ * </ul>
+ *
+ * <p><b>测试范围</b>:{@link EnergyController#getEnergyLogs} + {@link EnergyService#getLogs} 的展示口径。仅用 Mockito(无 Spring / 无 DB),不依赖真实外部服务。</p>
+ *
+ * <p><b>读取策略</b>:{@code sourceName}/{@code dimensionCode} 为待落地的展示字段,{@code EnergyLog} 实体当前没有,
+ * 故用反射 {@link #readField} 读取(字段缺失即抛异常 = 契约失败),使本测试可编译、失败发生在测试阶段(运行期红)而非编译期红,
+ * 与同批 RED 契约测试风格一致。{@code createdAt} 的 ISO 8601 契约用 {@code @JsonFormat} 注解存在性断言。</p>
+ *
+ * <p><b>RED 预期</b>:{@code EnergyLog} 实体当前只有 {@code sourceType}/{@code sourceId}/{@code dimensionId}/{@code Date createdAt},
+ * 无 {@code sourceName}/{@code dimensionCode} 展示字段,{@code createdAt} 亦无 {@code @JsonFormat} —— 本契约展示口径未落地,
+ * 三条用例在 GREEN 补齐前应失败(红)。</p>
+ */
+class EnergyLedgerViewContractTest extends EnergyContractTestBase {
+
+    private static final String MSG_NO_MEMBER = "memberId不能为空";
+
+    private EnergyService service;
+    private EnergyDimensionMapper dimensionMapper;
+    private EnergyLogMapper logMapper;
+    private EnergyController controller;
+
+    @BeforeEach
+    void setUp() throws Exception {
+        service = new EnergyService();
+        dimensionMapper = mock(EnergyDimensionMapper.class);
+        logMapper = mock(EnergyLogMapper.class);
+        inject(service, "energyDimensionMapper", dimensionMapper);
+        inject(service, "energyLogMapper", logMapper);
+        inject(service, "energyBalanceMapper", mock(com.etotem.cfc.mapper.EnergyBalanceMapper.class));
+        inject(service, "energySourceConfigMapper", mock(com.etotem.cfc.mapper.EnergySourceConfigMapper.class));
+        inject(service, "energyBehaviorConfigMapper", mock(com.etotem.cfc.mapper.EnergyBehaviorConfigMapper.class));
+        inject(service, "wishMapper", mock(com.etotem.cfc.mapper.WishMapper.class));
+        inject(service, "familyMemberMapper", mock(com.etotem.cfc.mapper.FamilyMemberMapper.class));
+        inject(service, "notificationDispatchService", mock(com.etotem.cfc.service.NotificationDispatchService.class));
+
+        controller = new EnergyController();
+        inject(controller, "energyService", service);
+        inject(controller, "fiveDimensionScoreService", mock(com.etotem.cfc.service.FiveDimensionScoreService.class));
+        inject(controller, "userMapper", mock(com.etotem.cfc.mapper.UserMapper.class));
+        inject(controller, "unlockGateService", mock(com.etotem.cfc.service.UnlockGateService.class));
+
+        initTable(EnergyLog.class);
+        initTable(EnergyDimension.class);
+    }
+
+    private void seedDims() {
+        when(dimensionMapper.selectList(any())).thenReturn(Arrays.asList(fiveDims()));
+    }
+
+    private void seedPage(EnergyLog... logs) {
+        when(logMapper.selectPage(any(Page.class), any())).thenAnswer(inv -> {
+            Page<EnergyLog> p = inv.getArgument(0);
+            p.setRecords(Arrays.asList(logs));
+            p.setTotal(logs.length);
+            return p;
+        });
+    }
+
+    /** 通过 controller 入口取回流水 Page(走 memberId/familyId 门禁 + service.getLogs) */
+    private Page<EnergyLog> invokeLogs() {
+        Map<String, Object> params = new HashMap<>();
+        params.put("memberId", 50L);
+        Result<Page<EnergyLog>> r = controller.getEnergyLogs(params, 1L, 50L);
+        assertEquals(200, r.getCode(), "入口应返回 200");
+        assertNotNull(r.getData());
+        return r.getData();
+    }
+
+    /** 反射读取实体字段(沿类层次向上查找);字段缺失即抛 IllegalStateException = 契约失败 */
+    private static Object readField(Object target, String fieldName) {
+        Class<?> cls = target.getClass();
+        Field f = null;
+        while (cls != null && f == null) {
+            try {
+                f = cls.getDeclaredField(fieldName);
+            } catch (NoSuchFieldException e) {
+                cls = cls.getSuperclass();
+            }
+        }
+        if (f == null) {
+            throw new IllegalStateException(
+                    "EnergyLog 缺少契约展示字段 '" + fieldName + "'(SC-P-18 能量流水查看:展示口径未落地)");
+        }
+        f.setAccessible(true);
+        try {
+            return f.get(target);
+        } catch (IllegalAccessException e) {
+            throw new IllegalStateException("无法读取字段 " + fieldName, e);
+        }
+    }
+
+    // ==================== 契约 AC-1:来源溯源可读(task / health_checkin / assessment) ====================
+
+    @Test
+    @DisplayName("SC-P-18 契约:task 流水暴露可读来源名 sourceName=完成任务")
+    void 契约_任务流水_来源可读名() {
+        seedDims();
+        seedPage(energyLog(1L, 50L, 5L, 10, 30, "task", 100L));
+
+        Page<EnergyLog> page = invokeLogs();
+        EnergyLog log = page.getRecords().get(0);
+        assertEquals("task", log.getSourceType(), "原始来源码应为 task");
+        assertEquals("完成任务", readField(log, "sourceName"), "task 应映射为可读来源名「完成任务」");
+    }
+
+    @Test
+    @DisplayName("SC-P-18 契约:health_checkin 流水暴露可读来源名 sourceName=健康打卡")
+    void 契约_打卡流水_来源可读名() {
+        seedDims();
+        seedPage(energyLog(2L, 50L, 4L, 5, 25, "health_checkin", 200L));
+
+        Page<EnergyLog> page = invokeLogs();
+        EnergyLog log = page.getRecords().get(0);
+        assertEquals("health_checkin", log.getSourceType(), "原始来源码应为 health_checkin");
+        assertEquals("健康打卡", readField(log, "sourceName"), "health_checkin 应映射为「健康打卡」");
+    }
+
+    @Test
+    @DisplayName("SC-P-18 契约:assessment 流水暴露可读来源名 sourceName=测评")
+    void 契约_测评流水_来源可读名() {
+        seedDims();
+        seedPage(energyLog(3L, 50L, 1L, 8, 18, "assessment", 300L));
+
+        Page<EnergyLog> page = invokeLogs();
+        EnergyLog log = page.getRecords().get(0);
+        assertEquals("assessment", log.getSourceType(), "原始来源码应为 assessment");
+        assertEquals("测评", readField(log, "sourceName"), "assessment 应映射为「测评」");
+    }
+
+    @Test
+    @DisplayName("SC-P-18 契约:未映射来源码回退原始码,不抛错")
+    void 契约_未映射来源_回退原始码() {
+        seedDims();
+        seedPage(energyLog(4L, 50L, 3L, 6, 6, "unknown_source", 400L));
+
+        Page<EnergyLog> page = invokeLogs();
+        EnergyLog log = page.getRecords().get(0);
+        assertEquals("unknown_source", readField(log, "sourceName"), "未映射来源应回退原始码,且不抛错");
+    }
+
+    // ==================== 契约 AC-2:维度代码暴露 ====================
+
+    @Test
+    @DisplayName("SC-P-18 契约:流水暴露 dimensionCode(如 body)供前端维度着色/筛选")
+    void 契约_流水暴露维度代码() {
+        seedDims();
+        seedPage(energyLog(5L, 50L, 5L, 10, 10, "task", 500L));
+
+        Page<EnergyLog> page = invokeLogs();
+        EnergyLog log = page.getRecords().get(0);
+        assertEquals(5L, log.getDimensionId(), "前置:维度 ID=5 应为 body");
+        assertEquals("body", readField(log, "dimensionCode"), "应按 dimensionId 暴露 dimensionCode");
+    }
+
+    // ==================== 契约 AC-3:时间格式统一(yyyy-MM-dd'T'HH:mm:ss) ====================
+
+    @Test
+    @DisplayName("SC-P-18 契约:createdAt 以 ISO 8601 序列化(@JsonFormat yyyy-MM-dd'T'HH:mm:ss)")
+    void 契约_时间格式ISO8601() throws Exception {
+        seedDims();
+        seedPage(energyLog(6L, 50L, 5L, 10, 10, "task", 600L));
+
+        Page<EnergyLog> page = invokeLogs();
+        EnergyLog log = page.getRecords().get(0);
+        assertNotNull(log.getCreatedAt(), "前置:createdAt 非空");
+
+        Field createdAtField = EnergyLog.class.getDeclaredField("createdAt");
+        JsonFormat ann = createdAtField.getAnnotation(JsonFormat.class);
+        assertNotNull(ann,
+                "EnergyLog.createdAt 需 @JsonFormat(pattern=\"yyyy-MM-dd'T'HH:mm:ss\"),否则 Jackson 序列化为 epoch 毫秒,时间格式不统一");
+        assertEquals("yyyy-MM-dd'T'HH:mm:ss", ann.pattern(), "时间格式必须统一为 yyyy-MM-dd'T'HH:mm:ss");
+    }
+
+    // ==================== 既有门禁回归:view 与 guard 职责不互斥 ====================
+
+    @Test
+    @DisplayName("SC-P-18 回归:无 memberId 仍返回业务提示(view 不破坏既有门禁)")
+    void 回归_无memberId_业务提示() {
+        Map<String, Object> params = new HashMap<>();
+        params.put("dimensionCode", "body");
+        Result<Page<EnergyLog>> r = controller.getEnergyLogs(params, 1L, null);
+        assertEquals(500, r.getCode());
+        assertEquals(MSG_NO_MEMBER, r.getMessage());
+    }
+
+    @Test
+    @DisplayName("SC-P-18 回归:无 familyId 返回 5001(view 不破坏既有权限门禁)")
+    void 回归_无familyId_5001() {
+        Map<String, Object> params = new HashMap<>();
+        params.put("memberId", 50L);
+        Result<Page<EnergyLog>> r = controller.getEnergyLogs(params, null, 50L);
+        assertEquals(5001, r.getCode());
+    }
+}

+ 327 - 0
cfc-backend/src/test/java/com/etotem/cfc/unit/FamilyCreateWithInviteContractTest.java

@@ -0,0 +1,327 @@
+package com.etotem.cfc.unit;
+
+import com.etotem.cfc.config.GlobalExceptionHandler;
+import com.etotem.cfc.config.JwtInterceptor;
+import com.etotem.cfc.controller.family.FamilyUserController;
+import com.etotem.cfc.entity.Family;
+import com.etotem.cfc.entity.FamilyMember;
+import com.etotem.cfc.entity.User;
+import com.etotem.cfc.mapper.FamilyMapper;
+import com.etotem.cfc.mapper.FamilyMemberMapper;
+import com.etotem.cfc.mapper.UserMapper;
+import com.etotem.cfc.service.UserService;
+import com.jayway.jsonpath.JsonPath;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Test;
+import org.mockito.ArgumentCaptor;
+import org.mockito.Mock;
+import org.mockito.MockitoAnnotations;
+import org.springframework.http.MediaType;
+import org.springframework.mock.web.MockHttpServletRequest;
+import org.springframework.mock.web.MockHttpServletResponse;
+import org.springframework.test.util.ReflectionTestUtils;
+import org.springframework.test.web.servlet.MockMvc;
+import org.springframework.test.web.servlet.MvcResult;
+import org.springframework.test.web.servlet.setup.MockMvcBuilders;
+
+import javax.servlet.http.HttpServletResponse;
+
+import static org.hamcrest.Matchers.containsString;
+import static org.junit.jupiter.api.Assertions.assertDoesNotThrow;
+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.assertThrows;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.Mockito.never;
+import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.when;
+import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.post;
+import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.jsonPath;
+import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
+
+/**
+ * 契约测试:能力键 {@code family.family.createWithInvite}(S-cfc-256,SC-P-01)。
+ *
+ * <p><b>需求溯源(tests/user-scenarios/应用场景总览.md SC-P-01 · tests/test-cases/parent.md TC-P-01/TC-P-01-E/TC-P-01-P)</b></p>
+ * <ul>
+ *   <li>TC-P-01 正常流:创建家庭(名称「测试家庭1」) → 家庭创建成功;生成唯一邀请码+二维码(令牌+落地页);角色变家庭管理员。</li>
+ *   <li>TC-P-01-E 异常流:家庭名称传空 / 超长(>30 字符) / 含 {@code <script>} 注入 → 名称空或超长返回 400 且 message 含
+ *       『家庭名称』校验项;HTML/SQL 注入被转义,库内不落恶意串;不抛 500、不泄露堆栈。</li>
+ *   <li>TC-P-01-P 权限流:非归属数据访问统一 403/401——本类落地为「建家庭为写操作,无 token 匿名一律 401」。</li>
+ * </ul>
+ *
+ * <p><b>设计锚点(docs/superpowers/api/API_REFERENCE.md §4.2 家庭与成员 /
+ *     cfc-backend controller/family/FamilyInviteController(创建/邀请码/二维码落地页)+ FamilyController)</b></p>
+ * <ul>
+ *   <li>当前「建家庭」入口为 {@code POST /api/family/user/create-family}
+ *       ({@link FamilyUserController#createFamily} → {@link UserService#createFamilyForUser}),
+ *       契约要求该链路同步完成:创建家庭(唯一邀请码)→ 创建者成为家庭管理员 → 名称校验(空/超长/注入)→
+ *       邀请材料(令牌+二维码落地页,复用 {@code FamilyInvitationService.generateInvitation} + 小程序码语义)产出。</li>
+ *   <li>管理员语义先例:{@code UserService.createUserAndFamily}(L1534)/ {@code ensureUserHasFamily}(L1569)均已
+ *        {@code user.setIsFamilyAdmin(true)};{@code createFamilyForUser} 路径缺失该回写 → RED。</li>
+ *   <li>400 语义:{@link GlobalExceptionHandler} 将 {@link IllegalArgumentException} 映射为
+ *       {@code Result.error(400, message)};控制层也可直接返回 {@code Result.badRequest(...)}。</li>
+ *   <li>同类 RED 先例:family.family.autoCreateForPurchase(S-cfc-188)、family.invite.joinValidationGate/Rules(S-cfc-58/59)。</li>
+ * </ul>
+ *
+ * <p><b>RED 预期</b>(当前实现均未落地 → 断言红):</p>
+ * <ol>
+ *   <li>创建者未回写 {@code isFamilyAdmin=true}(SC-P-01「成为管理员」缺失);</li>
+ *   <li>空名/超长名无校验、HTML 注入原样落库(TC-P-01-E 校验/转义缺失);</li>
+ *   <li>控制层无空名/超长名 400 守卫(TC-P-01-E「返回 400 且 message 含『家庭名称』」缺失);</li>
+ *   <li>{@code /api/family/user/create-family} 未入 {@code JwtInterceptor.LOGIN_REQUIRED_PATHS},匿名(userId=-1)被放行
+ *       (写操作必须登录,TC-P-01-P 缺失)。</li>
+ * </ol>
+ *
+ * <p><b>测试范围</b>:纯 Mockito + Spring Test(MockMvc standalone + ReflectionTestUtils),
+ * 无 Spring 容器 / 无 DB / 无真实微信;风格与同批 CONTRACT 测试(FamilyAutoCreateForPurchaseContractTest /
+ * FamilyJoinValidationRulesContractTest / TeamInvitationCreateContractTest)一致。</p>
+ */
+public class FamilyCreateWithInviteContractTest {
+
+    private static final String KEY = "[family.family.createWithInvite]";
+    private static final Long CREATOR_USER_ID = 1L;
+    private static final String CREATE_FAMILY_URL = "/api/family/user/create-family";
+    private static final String INJECTION_NAME = "<script>alert('xss')</script>";
+
+    @Mock
+    private UserMapper userMapper;
+
+    @Mock
+    private FamilyMapper familyMapper;
+
+    @Mock
+    private FamilyMemberMapper familyMemberMapper;
+
+    /** 服务段:真实 UserService + 注入 mock mappers —— 验证 service 层契约 */
+    private UserService realService;
+
+    /** 控制段:真实 FamilyUserController + 注入 realService —— 验证 API 层契约 */
+    private FamilyUserController controller;
+
+    private MockMvc mockMvc;
+
+    @BeforeEach
+    void setUp() {
+        MockitoAnnotations.openMocks(this);
+
+        realService = new UserService();
+        ReflectionTestUtils.setField(realService, "userMapper", userMapper);
+        ReflectionTestUtils.setField(realService, "familyMapper", familyMapper);
+        ReflectionTestUtils.setField(realService, "familyMemberMapper", familyMemberMapper);
+
+        controller = new FamilyUserController();
+        ReflectionTestUtils.setField(controller, "userService", realService);
+
+        mockMvc = MockMvcBuilders.standaloneSetup(controller)
+                .setControllerAdvice(new GlobalExceptionHandler())
+                .build();
+
+        // 公共桩:当前用户存在;创建者在目标家庭尚无成员记录(addCreatorAsMember 幂等查不命中)
+        User current = new User();
+        current.setId(CREATOR_USER_ID);
+        when(userMapper.selectById(CREATOR_USER_ID)).thenReturn(current);
+        when(familyMemberMapper.selectCount(any())).thenReturn(0L);
+    }
+
+    // ====================================================================
+    // 服务层契约(UserService.createFamilyForUser)
+    // ====================================================================
+
+    @Test
+    @DisplayName("【服务-正常锚点】合法名称创建成功:唯一邀请码 + creatorId + 创建人入成员表(GREEN 锚点)")
+    void service_createFamily_success_anchor_唯一邀请码与创建者关系() {
+        realService.createFamilyForUser(CREATOR_USER_ID, "测试家庭1");
+
+        ArgumentCaptor<Family> famCap = ArgumentCaptor.forClass(Family.class);
+        verify(familyMapper).insert(famCap.capture());
+        Family family = famCap.getValue();
+        assertNotNull(family.getInviteCode(), KEY + " 创建家庭必须生成唯一邀请码");
+        assertEquals(CREATOR_USER_ID, family.getCreatorId(), KEY + " creatorId 须等于当前用户 ID");
+        assertEquals("测试家庭1", family.getName(), KEY + " 家庭名称应原样入库");
+
+        ArgumentCaptor<User> userCap = ArgumentCaptor.forClass(User.class);
+        verify(userMapper).updateById(userCap.capture());
+        assertEquals(CREATOR_USER_ID, userCap.getValue().getId(), KEY + " 回写用户应为创建者本人");
+
+        verify(familyMemberMapper).insert(any(FamilyMember.class));
+    }
+
+    @Test
+    @DisplayName("【服务-正常流·管理员】createFamilyForUser 创建后必须回写 isFamilyAdmin=true → RED(当前缺失)")
+    void service_createFamily_mustSetCreatorAdminFlag() {
+        realService.createFamilyForUser(CREATOR_USER_ID, "测试家庭1");
+
+        ArgumentCaptor<User> cap = ArgumentCaptor.forClass(User.class);
+        verify(userMapper).updateById(cap.capture());
+        assertEquals(Boolean.TRUE, cap.getValue().getIsFamilyAdmin(),
+                KEY + " 创建者应成为家庭管理员;当前 createFamilyForUser 未回写 isFamilyAdmin=true"
+                        + "(对照 createUserAndFamily / ensureUserHasFamily 均已实现该语义)");
+    }
+
+    @Test
+    @DisplayName("【服务-异常流·空名】空字符串应被拒绝且 message 含『家庭名称』,不落库 → RED(当前直接建家庭成功)")
+    void service_emptyName_mustBeRejected_notPersisted() {
+        RuntimeException ex = assertThrows(RuntimeException.class,
+                () -> realService.createFamilyForUser(CREATOR_USER_ID, ""),
+                KEY + " 契约要求空名拒绝,当前直接建家庭成功");
+        assertTrue(ex.getMessage() != null && ex.getMessage().contains("家庭名称"),
+                KEY + " message 应含『家庭名称』校验项;实际: " + ex.getMessage());
+        verify(familyMapper, never()).insert(any(Family.class));
+        verify(userMapper, never()).updateById(any(User.class));
+        verify(familyMemberMapper, never()).insert(any(FamilyMember.class));
+    }
+
+    @Test
+    @DisplayName("【服务-异常流·超长名】超过 30 字符应被拒绝且 message 含『家庭名称』,不落库 → RED(当前不校验)")
+    void service_nameOverMaxLength_mustBeRejected_notPersisted() {
+        String longName = repeat("测", 31); // 契约上限 30 字符
+
+        RuntimeException ex = assertThrows(RuntimeException.class,
+                () -> realService.createFamilyForUser(CREATOR_USER_ID, longName),
+                KEY + " 契约要求 >30 字符拒绝,当前直接建家庭成功");
+        assertTrue(ex.getMessage() != null && ex.getMessage().contains("家庭名称"),
+                KEY + " message 应含『家庭名称』校验项;实际: " + ex.getMessage());
+        verify(familyMapper, never()).insert(any(Family.class));
+        verify(userMapper, never()).updateById(any(User.class));
+        verify(familyMemberMapper, never()).insert(any(FamilyMember.class));
+    }
+
+    @Test
+    @DisplayName("【服务-异常流·注入】含 HTML 注入串的名称必须被拒绝或转义,库内不落恶意串 → RED(当前原样落库)")
+    void service_injectionName_mustNotBeStoredRaw() {
+        try {
+            realService.createFamilyForUser(CREATOR_USER_ID, INJECTION_NAME);
+        } catch (RuntimeException rejected) {
+            // 契约允许「拒绝注入串」:此时不得落库
+            verify(familyMapper, never()).insert(any(Family.class));
+            return;
+        }
+
+        ArgumentCaptor<Family> famCap = ArgumentCaptor.forClass(Family.class);
+        verify(familyMapper).insert(famCap.capture());
+        String stored = famCap.getValue().getName();
+        assertFalse(stored.contains("<script>") && stored.contains("</script>"),
+                KEY + " 库内不应原样存储 HTML 注入串(应转义/净化);当前原样落库");
+    }
+
+    @Test
+    @DisplayName("【服务-边界锚点】恰好 30 字符不触发拒绝,名称原样入库(GREEN 锚点)")
+    void service_nameAtMaxLengthBoundary_passes() {
+        String boundaryName = repeat("测", 30);
+
+        assertDoesNotThrow(() -> realService.createFamilyForUser(CREATOR_USER_ID, boundaryName),
+                KEY + " 恰好 30 字符应为合法边界");
+
+        ArgumentCaptor<Family> famCap = ArgumentCaptor.forClass(Family.class);
+        verify(familyMapper).insert(famCap.capture());
+        assertEquals(boundaryName, famCap.getValue().getName(), KEY + " 边界名应原样入库");
+    }
+
+    // ====================================================================
+    // 控制器层契约(POST /api/family/user/create-family)
+    // ====================================================================
+
+    @Test
+    @DisplayName("【控制-异常流·空名】name=\"\" 应返回 code=400 且 message 含『家庭名称』 → RED(当前透传建家庭 200)")
+    void ctrl_emptyName_returns400_withFamilyNameMessage() throws Exception {
+        mockMvc.perform(post(CREATE_FAMILY_URL)
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content("{\"name\":\"\"}")
+                        .requestAttr("userId", CREATOR_USER_ID))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.code").value(400))
+                .andExpect(jsonPath("$.message").value(containsString("家庭名称")));
+    }
+
+    @Test
+    @DisplayName("【控制-异常流·超长名】name 超过 30 字符应返回 code=400 且 message 含『家庭名称』 → RED(当前透传建家庭 200)")
+    void ctrl_nameOverMaxLength_returns400_withFamilyNameMessage() throws Exception {
+        String longName = repeat("测", 31);
+        mockMvc.perform(post(CREATE_FAMILY_URL)
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content("{\"name\":\"" + longName + "\"}")
+                        .requestAttr("userId", CREATOR_USER_ID))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.code").value(400))
+                .andExpect(jsonPath("$.message").value(containsString("家庭名称")));
+    }
+
+    @Test
+    @DisplayName("【控制-异常流·注入】含 HTML 注入串的名称不得原样落库(拒绝 400 或转义后入库)→ RED(当前 200 原样落库)")
+    void ctrl_injectionName_notStoredRaw() throws Exception {
+        MvcResult result = mockMvc.perform(post(CREATE_FAMILY_URL)
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content("{\"name\":\"" + INJECTION_NAME + "\"}")
+                        .requestAttr("userId", CREATOR_USER_ID))
+                .andExpect(status().isOk())
+                .andReturn();
+
+        Integer code = JsonPath.read(result.getResponse().getContentAsString(), "$.code");
+        if (Integer.valueOf(200).equals(code)) {
+            // 未拒绝 → 必须已转义,库内不落恶意串
+            ArgumentCaptor<Family> famCap = ArgumentCaptor.forClass(Family.class);
+            verify(familyMapper).insert(famCap.capture());
+            String stored = famCap.getValue().getName();
+            assertFalse(stored.contains("<script>") && stored.contains("</script>"),
+                    KEY + " 库内不应原样存储 HTML 注入串(应转义/净化);当前原样落库");
+        } else {
+            assertEquals(Integer.valueOf(400), code,
+                    KEY + " 若拒绝注入名称,应返回 code=400(实际 " + code + ")");
+        }
+    }
+
+    @Test
+    @DisplayName("【控制-正常锚点】合法 name → code=200,家庭落库且名称正确(GREEN 锚点)")
+    void ctrl_validName_createsFamily_andStoresName() throws Exception {
+        mockMvc.perform(post(CREATE_FAMILY_URL)
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content("{\"name\":\"测试家庭1\"}")
+                        .requestAttr("userId", CREATOR_USER_ID))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.code").value(200));
+
+        ArgumentCaptor<Family> famCap = ArgumentCaptor.forClass(Family.class);
+        verify(familyMapper).insert(famCap.capture());
+        assertEquals("测试家庭1", famCap.getValue().getName(),
+                KEY + " 家庭名称须按提交值入库");
+    }
+
+    // ====================================================================
+    // 权限流契约(TC-P-01-P:写操作必须登录)
+    // ====================================================================
+
+    @Test
+    @DisplayName("【权限流·建家庭】无 token 匿名访问 create-family 必须 401(写操作不得匿名放行)→ RED(当前未入 LOGIN_REQUIRED_PATHS,匿名 userId=-1 放行)")
+    void permission_createFamily_anonymousMustBe401() throws Exception {
+        JwtInterceptor interceptor = new JwtInterceptor();
+        MockHttpServletRequest request = new MockHttpServletRequest();
+        request.setMethod("POST");
+        request.setRequestURI(CREATE_FAMILY_URL);
+        MockHttpServletResponse response = new MockHttpServletResponse();
+
+        boolean allowed = interceptor.preHandle(request, response, null);
+
+        assertFalse(allowed,
+                KEY + " 建家庭/生成邀请为写操作,无 token 不得匿名放行;当前 create-family 未在 LOGIN_REQUIRED_PATHS"
+                        + "(对照 /api/family/member/ 等私写端点)→ 匿名 userId=-1 直达 controller");
+        assertEquals(HttpServletResponse.SC_UNAUTHORIZED, response.getStatus(),
+                KEY + " 未登录访问建家庭应返回 HTTP 401");
+    }
+
+    // ====================================================================
+    // 辅助
+    // ====================================================================
+
+    /** Java 8 兼容拼接(避免依赖 String.repeat,Java 11+ API) */
+    private String repeat(String s, int n) {
+        StringBuilder sb = new StringBuilder(s.length() * n);
+        for (int i = 0; i < n; i++) {
+            sb.append(s);
+        }
+        return sb.toString();
+    }
+}

+ 413 - 0
cfc-backend/src/test/java/com/etotem/cfc/unit/FamilyRelationGraphContractTest.java

@@ -0,0 +1,413 @@
+package com.etotem.cfc.unit;
+
+import com.etotem.cfc.dto.FamilyMemberVO;
+import com.etotem.cfc.entity.FamilyMember;
+import com.etotem.cfc.entity.FamilyRelationship;
+import com.etotem.cfc.mapper.FamilyMemberAttributesMapper;
+import com.etotem.cfc.mapper.FamilyMemberMapper;
+import com.etotem.cfc.service.FamilyRelationshipService;
+import com.etotem.cfc.service.RelationshipQualityService;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Test;
+import org.mockito.InjectMocks;
+import org.mockito.Mock;
+import org.mockito.MockitoAnnotations;
+
+import java.lang.reflect.Field;
+import java.lang.reflect.Method;
+import java.lang.reflect.ParameterizedType;
+import java.lang.reflect.Type;
+import java.math.BigDecimal;
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.List;
+
+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.assertThrows;
+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.Mockito.when;
+
+/**
+ * 契约级单测:家庭关系图查看(能力键 {@code family.family.relationGraph})。
+ *
+ * <p><b>需求/设计溯源</b></p>
+ * <ul>
+ *   <li>需求:{@code tests/user-scenarios/应用场景总览.md} SC-P-07 家庭关系图查看 ——
+ *       流程「打开关系图 → 节点 + 关系标签渲染」;边界「关系缺失的节点降级展示」。</li>
+ *   <li>设计:{@code docs/superpowers/api/API_REFERENCE.md} §4.2 家庭与成员 +
+ *       §4.20 家庭成员关系质量 —— {@code RelationshipQualityController}
+ *       {@code POST /api/family/relationship/pairwise}(以指定成员为中心的所有成员关系),
+ *       返回 {@code Result<List<FamilyMemberVO>>},每行承载关系图节点渲染所需字段
+ *       (id/nickname/gender/effectiveRole/memberType/relationship/relativeLabel + 三项评分)。</li>
+ *   <li>前端契约:关系图节点渲染({@code components/FamilyRelationGraph.vue})消费
+ *       {@code memberType}(节点形状 parent/child)与 {@code relativeLabel}(关系标签),
+ *       关系缺失时需有可渲染的降级展示({@code components/MemberSelector.vue} 的 pairwise 加载)。</li>
+ * </ul>
+ *
+ * <p><b>被校验的契约行为</b></p>
+ * <ul>
+ *   <li>正常流:pairwise 返回全家庭成员节点行(含中心行),每行携带节点渲染字段;中心行关系标签「我」;
+ *       有关系行成员标签取关系表 relationshipKey;无 relationshipKey 时依辈分差推断标签;
+ *       配偶关系取 3 参重载「丈夫/妻子」;每行携带节点形状字段 memberType(parent/child,非空)。</li>
+ *   <li>边界流:关系缺失成员三项评分降级为 0(不 null、不 500);关系缺失成员
+ *       {@code relationship}/{@code relativeLabel} 必须有非空降级标签(节点可渲染);
+ *       中心成员不存在则拒绝。</li>
+ *   <li>权限流:中心成员不属于查看者家庭则拒绝(仅本家庭成员可见);
+ *       查看者家庭归属不可核验(familyId 缺位)时 fail-closed,不得静默回退中心成员家庭。</li>
+ * </ul>
+ *
+ * <p><b>测试范围</b>:纯 Mockito + 反射,无 Spring / 无 DB / 无外部服务。</p>
+ *
+ * <p><b>RED 预期</b>(实现未落地的契约缺口,GREEN 阶段补齐后转绿):</p>
+ * <ul>
+ *   <li>pairwise VO 未设置 {@code memberType}(节点形状字段缺失,前端全部节点退化为 child 圆形)。</li>
+ *   <li>关系缺失成员 {@code relationship}/{@code relativeLabel} 为 null(降级展示标签未实现)。</li>
+ *   <li>配偶关系未走 3 参重载({@code computeRelationshipLabel(generationValue, gender, relationType)}),
+ *       辈分差 0 时被解析为「兄弟/姐妹」而非「丈夫/妻子」。</li>
+ *   <li>familyId 缺位时静默回退中心成员家庭返回数据(越权 fail-open,非 fail-closed)。</li>
+ * </ul>
+ *
+ * <p>已落地部分(本测试同时固化):pairwise 端点/入口存在、全成员节点行、中心行「我」标签、
+ * relationshipKey 标签、辈分差推断标签、关系缺失评分降级 0、跨家庭拒绝。</p>
+ */
+@DisplayName("契约级单测:family.family.relationGraph(SC-P-07 家庭关系图查看)")
+class FamilyRelationGraphContractTest {
+
+    /** 契约端点控制器(API_REFERENCE §4.20)。 */
+    private static final String CONTROLLER_CLASS = "com.etotem.cfc.controller.family.RelationshipQualityController";
+
+    /** 契约数据供给服务(pairwise)。 */
+    private static final String SERVICE_CLASS = "com.etotem.cfc.service.RelationshipQualityService";
+
+    /** 家庭/查看者标识。 */
+    private static final Long FAMILY_ID = 888L;
+    private static final Long CENTER_ID = 11L;
+
+    @Mock
+    private FamilyMemberMapper familyMemberMapper;
+
+    @Mock
+    private FamilyMemberAttributesMapper familyMemberAttributesMapper;
+
+    @Mock
+    private FamilyRelationshipService familyRelationshipService;
+
+    @InjectMocks
+    private RelationshipQualityService service;
+
+    @BeforeEach
+    void setUp() {
+        MockitoAnnotations.openMocks(this);
+        FamilyMember center = member(CENTER_ID, "爸爸", "male", 0, false);
+        when(familyMemberMapper.selectById(CENTER_ID)).thenReturn(center);
+        when(familyMemberMapper.selectList(any())).thenReturn(new ArrayList<>(baselineMembers()));
+        // 默认:中心成员无任何关系行(各用例按需再覆盖)
+        when(familyRelationshipService.getRelationsForMember(CENTER_ID))
+                .thenReturn(new ArrayList<>());
+    }
+
+    // ==================== 契约锚点:端点与服务入口存在(反射结构探测) ====================
+
+    @Test
+    @DisplayName("正常流:pairwise 端点应以 POST 提供于 /api/family/relationship/pairwise")
+    void 端点_pairwise以POST映射存在() {
+        Class<?> controller = loadClass(CONTROLLER_CLASS);
+        assertNotNull(controller, "[family.family.relationGraph] RelationshipQualityController 不存在(API_REFERENCE §4.20)。");
+        boolean found = false;
+        for (Method m : controller.getDeclaredMethods()) {
+            String path = postMappingPath(m);
+            if ("/pairwise".equals(path)) {
+                found = true;
+                break;
+            }
+        }
+        assertTrue(found, "[family.family.relationGraph] RelationshipQualityController 应提供 "
+                + "@PostMapping(\"/pairwise\") 端点(API_REFERENCE §4.20 pairwise)。");
+    }
+
+    @Test
+    @DisplayName("正常流:服务应提供 getPairwiseRelationships 入口,返回 List<FamilyMemberVO>")
+    void 服务_提供pairwise入口_返回FamilyMemberVO列表() {
+        Class<?> clazz = loadClass(SERVICE_CLASS);
+        assertNotNull(clazz, "[family.family.relationGraph] RelationshipQualityService 不存在。");
+        for (Method m : clazz.getMethods()) {
+            if (!"getPairwiseRelationships".equals(m.getName())) {
+                continue;
+            }
+            if (m.getParameterCount() != 2) {
+                continue;
+            }
+            Type genericReturn = m.getGenericReturnType();
+            if (genericReturn instanceof ParameterizedType) {
+                Type[] args = ((ParameterizedType) genericReturn).getActualTypeArguments();
+                for (Type arg : args) {
+                    if ("com.etotem.cfc.dto.FamilyMemberVO".equals(arg.getTypeName())) {
+                        return;
+                    }
+                }
+            }
+        }
+        fail("[family.family.relationGraph] RelationshipQualityService.getPairwiseRelationships(...) "
+                + "应存在且返回 List<FamilyMemberVO>(关系图节点渲染数据源)。");
+    }
+
+    // ==================== 正常流:节点 + 关系标签渲染数据供给 ====================
+
+    @Test
+    @DisplayName("正常流:pairwise 返回全家庭成员节点行(含中心行),节点字段齐全")
+    void pairwise_返回全部家庭成员节点行_含中心行() {
+        List<FamilyMemberVO> rows = service.getPairwiseRelationships(CENTER_ID, FAMILY_ID);
+
+        assertNotNull(rows, "pairwise 应返回成员节点行列表");
+        assertEquals(5, rows.size(), "家庭 5 名成员应全部返回(含中心成员)");
+        boolean centerPresent = false;
+        for (FamilyMemberVO vo : rows) {
+            assertNotNull(vo.getId(), "节点行应有 id(节点键)");
+            assertNotNull(vo.getNickname(), "节点行应有 nickname(节点显示)");
+            assertNotNull(vo.getEffectiveRole(), "节点行应有 effectiveRole(角色渲染)");
+            assertNotNull(vo.getIsSelf(), "节点行应有 isSelf(中心节点标记)");
+            if (CENTER_ID.equals(vo.getId())) {
+                centerPresent = true;
+            }
+        }
+        assertTrue(centerPresent, "返回节点行应包含中心成员(isSelf 行)");
+    }
+
+    @Test
+    @DisplayName("正常流:中心成员行关系标签应为「我」,isSelf=true")
+    void pairwise_中心成员行_关系标签为我_isSelf() {
+        List<FamilyMemberVO> rows = service.getPairwiseRelationships(CENTER_ID, FAMILY_ID);
+
+        FamilyMemberVO center = findRow(rows, CENTER_ID);
+        assertEquals("我", center.getRelationship(), "中心行 relationship 应为「我」");
+        assertEquals("我", center.getRelativeLabel(), "中心行 relativeLabel 应为「我」");
+        assertTrue(center.getIsSelf(), "中心行 isSelf 应为 true");
+    }
+
+    @Test
+    @DisplayName("正常流:有关系行成员,关系标签应取关系表 relationshipKey")
+    void pairwise_有关系行成员_标签取relationshipKey() {
+        FamilyRelationship rel = relationship(22L, null, "妈妈", -1, 90, 80, 70);
+        stubRelations(rel);
+
+        FamilyMemberVO row = findRow(service.getPairwiseRelationships(CENTER_ID, FAMILY_ID), 22L);
+        assertEquals("妈妈", row.getRelationship(), "有关系行成员标签应优先取 relationshipKey");
+        assertEquals("妈妈", row.getRelativeLabel(), "relativeLabel 应与 relationshipKey 一致");
+        assertEquals(new BigDecimal("90"), row.getTrustScore(), "三项评分应来自关系行");
+    }
+
+    @Test
+    @DisplayName("正常流:无 relationshipKey 时,依辈分差推断标签(generationValue=1 男→儿子)")
+    void pairwise_无relationshipKey_依辈分差推断标签() {
+        // 关系行指向 member 33(男,辈分差 1),relationshipKey 为空 → 依辈分差推断「儿子」
+        FamilyRelationship rel = relationship(33L, null, null, 1, 60, 50, 40);
+        stubRelations(rel);
+        when(familyRelationshipService.computeRelationshipLabel(1, "male")).thenReturn("儿子");
+
+        FamilyMemberVO row = findRow(service.getPairwiseRelationships(CENTER_ID, FAMILY_ID), 33L);
+        assertEquals("儿子", row.getRelationship(),
+                "无 relationshipKey 应依辈分差推断标签(computeRelationshipLabel(generationValue, gender))");
+    }
+
+    @Test
+    @DisplayName("正常流:每行应携带节点形状字段 memberType(parent/child,非空)")
+    void pairwise_每行节点形状字段memberType_非空白() {
+        List<FamilyMemberVO> rows = service.getPairwiseRelationships(CENTER_ID, FAMILY_ID);
+
+        for (FamilyMemberVO vo : rows) {
+            assertNotNull(vo.getMemberType(), "[family.family.relationGraph] pairwise 节点行未携带 memberType:"
+                    + "关系图节点形状渲染依赖 memberType(parent/child),缺失时前端全部节点退化为 child 圆形"
+                    + "(SC-P-07 节点渲染 / FamilyMemberVO.memberType)。id=" + vo.getId());
+            assertTrue("parent".equals(vo.getMemberType()) || "child".equals(vo.getMemberType()),
+                    "[family.family.relationGraph] pairwise 节点行 memberType 应为 parent/child,实际="
+                            + vo.getMemberType() + ",id=" + vo.getId());
+        }
+    }
+
+    @Test
+    @DisplayName("正常流:配偶关系(relationType=spouse)应取 3 参重载标签「妻子」")
+    void pairwise_配偶关系_无relationshipKey时应取丈夫妻子() {
+        FamilyRelationship rel = relationship(22L, "spouse", null, 0, 0, 0, 0);
+        stubRelations(rel);
+        // 2 参(辈分差 0,女)真实行为为「姐妹」;3 参 spouse 重载为「妻子」
+        when(familyRelationshipService.computeRelationshipLabel(0, "female")).thenReturn("姐妹");
+        when(familyRelationshipService.computeRelationshipLabel(0, "female", "spouse")).thenReturn("妻子");
+
+        FamilyMemberVO row = findRow(service.getPairwiseRelationships(CENTER_ID, FAMILY_ID), 22L);
+        assertEquals("妻子", row.getRelationship(),
+                "[family.family.relationGraph] 配偶关系应走 computeRelationshipLabel(generationValue, gender, "
+                        + "relationType) 3 参重载,辈分差 0 时输出「妻子」而非「姐妹」"
+                        + "(FamilyRelationshipService.computeRelationshipLabel(R4))。");
+    }
+
+    // ==================== 边界流:关系缺失的节点降级展示 ====================
+
+    @Test
+    @DisplayName("边界流:中心成员不存在 → 拒绝(「成员不存在或不属于该家庭」)")
+    void pairwise_中心成员不存在_拒绝() {
+        when(familyMemberMapper.selectById(999L)).thenReturn(null);
+
+        RuntimeException ex = assertThrows(RuntimeException.class,
+                () -> service.getPairwiseRelationships(999L, FAMILY_ID));
+        assertNotNull(ex.getMessage());
+        assertTrue(ex.getMessage().contains("成员不存在"),
+                "中心成员不存在应拒绝并提示成员不存在,实际=" + ex.getMessage());
+    }
+
+    @Test
+    @DisplayName("边界流:关系缺失成员三项评分降级为 0(不 null、不 500)")
+    void pairwise_关系缺失成员_评分降级为零() {
+        List<FamilyMemberVO> rows = service.getPairwiseRelationships(CENTER_ID, FAMILY_ID);
+
+        // 女儿(44)无关系行,非中心 → 评分应降级为 0
+        FamilyMemberVO row = findRow(rows, 44L);
+        assertNotNull(row.getTrustScore(), "关系缺失成员 trustScore 应降级为 0(非 null)");
+        assertEquals(BigDecimal.ZERO.compareTo(row.getTrustScore()), 0,
+                "关系缺失成员 trustScore 应降级为 0(SC-P-07 边界:关系缺失的节点降级展示)");
+        assertEquals(BigDecimal.ZERO.compareTo(row.getIntimacyScore()), 0,
+                "关系缺失成员 intimacyScore 应降级为 0");
+        assertEquals(BigDecimal.ZERO.compareTo(row.getCommunicationScore()), 0,
+                "关系缺失成员 communicationScore 应降级为 0");
+    }
+
+    @Test
+    @DisplayName("边界流:关系缺失成员 relationship 应有非空降级标签(不得 null)")
+    void pairwise_关系缺失成员_relationship降级标签非空白() {
+        List<FamilyMemberVO> rows = service.getPairwiseRelationships(CENTER_ID, FAMILY_ID);
+
+        FamilyMemberVO row = findRow(rows, 44L);
+        assertNotNull(row.getRelationship(), "[family.family.relationGraph] 关系缺失成员 relationship 为 null:"
+                + "SC-P-07 边界「关系缺失的节点降级展示」要求节点仍可渲染关系标签(至少降级为通用「家人」类标签),"
+                + "当前实现未设置降级标签。id=" + row.getId());
+        assertFalse(row.getRelationship().isEmpty(),
+                "[family.family.relationGraph] 关系缺失成员 relationship 降级标签不得为空白,id=" + row.getId());
+    }
+
+    @Test
+    @DisplayName("边界流:关系缺失成员 relativeLabel 应非空白,节点可渲染")
+    void pairwise_关系缺失成员_relativeLabel非空白_节点可渲染() {
+        List<FamilyMemberVO> rows = service.getPairwiseRelationships(CENTER_ID, FAMILY_ID);
+
+        FamilyMemberVO row = findRow(rows, 44L);
+        assertNotNull(row.getRelativeLabel(), "[family.family.relationGraph] 关系缺失成员 relativeLabel 为 null:"
+                + "前端关系图节点按 relativeLabel 渲染关系标签,缺失时节点降级展示标签未落地(SC-P-07 边界)。"
+                + "id=" + row.getId());
+        assertFalse(row.getRelativeLabel().isEmpty(),
+                "[family.family.relationGraph] 关系缺失成员 relativeLabel 降级标签不得为空白,id=" + row.getId());
+    }
+
+    @Test
+    @DisplayName("边界流:单人家庭(仅中心成员)→ 至少返回中心行,不空、不 500")
+    void pairwise_单人家庭_仅中心行不空不500() {
+        when(familyMemberMapper.selectList(any())).thenReturn(
+                Collections.singletonList(member(CENTER_ID, "爸爸", "male", 0, false)));
+
+        List<FamilyMemberVO> rows = service.getPairwiseRelationships(CENTER_ID, FAMILY_ID);
+
+        assertNotNull(rows, "单人家庭 pairwise 不应返回空");
+        assertEquals(1, rows.size(), "单人家庭应仅返回中心行");
+        assertEquals("我", rows.get(0).getRelationship(), "仅中心行关系标签应为「我」");
+    }
+
+    // ==================== 权限流:仅本家庭成员可见 ====================
+
+    @Test
+    @DisplayName("权限流:中心成员不属于传入家庭 → 拒绝(跨家庭不可见)")
+    void pairwise_中心成员不属于传入家庭_拒绝() {
+        // center 属家庭 888,传入 familyId=999(其他家庭)→ 应拒绝
+        RuntimeException ex = assertThrows(RuntimeException.class,
+                () -> service.getPairwiseRelationships(CENTER_ID, 999L));
+        assertNotNull(ex.getMessage());
+        assertTrue(ex.getMessage().contains("不属于该家庭"),
+                "跨家庭 pairwise 应拒绝并提示不属于该家庭(仅本家庭成员可见),实际=" + ex.getMessage());
+    }
+
+    @Test
+    @DisplayName("权限流:查看者家庭归属不可核验(familyId 缺位)→ fail-closed 拒绝,不得回退中心家庭")
+    void pairwise_viewer家庭核验缺位familyId空_应拒绝() {
+        // familyId=null 表示查看者家庭归属不可核验(controller 侧 userId→familyId 解析缺位);
+        // 按「仅本家庭成员可见」fail-closed,应拒绝而非静默回退 center.getFamilyId() 返回数据。
+        RuntimeException ex = assertThrows(RuntimeException.class,
+                () -> service.getPairwiseRelationships(CENTER_ID, null));
+        assertNotNull(ex.getMessage(),
+                "[family.family.relationGraph] 查看者家庭归属不可核验(familyId 缺位)时应拒绝(fail-closed):"
+                        + "当前实现在 familyId=null 时静默回退 center.getFamilyId() 返回数据,"
+                        + "属越权 fail-open(SC-P-07 边界:仅本家庭成员可见)。");
+    }
+
+    // ==================== 辅助:契约反射/实体构造/桩 ====================
+
+    private Class<?> loadClass(String name) {
+        try {
+            return Class.forName(name, false, Thread.currentThread().getContextClassLoader());
+        } catch (ClassNotFoundException e) {
+            return null;
+        }
+    }
+
+    private String postMappingPath(Method m) {
+        org.springframework.web.bind.annotation.PostMapping ann =
+                m.getAnnotation(org.springframework.web.bind.annotation.PostMapping.class);
+        if (ann == null || ann.value().length == 0) {
+            return null;
+        }
+        return ann.value()[0];
+    }
+
+    private FamilyMemberVO findRow(List<FamilyMemberVO> rows, Long id) {
+        for (FamilyMemberVO vo : rows) {
+            if (id.equals(vo.getId())) {
+                return vo;
+            }
+        }
+        fail("节点行未找到 id=" + id);
+        throw new IllegalStateException("unreachable");
+    }
+
+    /** 基线家庭成员(家庭 888):中心 11(父)、妈妈 22、儿子 33、女儿 44(无关系)、哥哥 55(无关系)。 */
+    private List<FamilyMember> baselineMembers() {
+        List<FamilyMember> list = new ArrayList<>();
+        list.add(member(CENTER_ID, "爸爸", "male", 0, false));
+        list.add(member(22L, "妈妈", "female", -1, true));
+        list.add(member(33L, "儿子", "male", 1, false));
+        list.add(member(44L, "女儿", "female", 1, false));
+        list.add(member(55L, "哥哥", "male", 0, false));
+        return list;
+    }
+
+    private FamilyMember member(Long id, String nickname, String gender, Integer generation, boolean spouse) {
+        FamilyMember fm = new FamilyMember();
+        fm.setId(id);
+        fm.setFamilyId(FAMILY_ID);
+        fm.setNickname(nickname);
+        fm.setGender(gender);
+        fm.setGeneration(generation);
+        fm.setIsSpouse(spouse);
+        return fm;
+    }
+
+    private FamilyRelationship relationship(Long toMemberId, String relationType, String relationshipKey,
+                                            Integer generationValue,
+                                            int trust, int intimacy, int communication) {
+        FamilyRelationship rel = new FamilyRelationship();
+        rel.setFromMemberId(CENTER_ID);
+        rel.setToMemberId(toMemberId);
+        rel.setGenerationValue(generationValue);
+        rel.setRelationType(relationType);
+        rel.setRelationshipKey(relationshipKey);
+        rel.setTrustScore(BigDecimal.valueOf(trust));
+        rel.setIntimacyScore(BigDecimal.valueOf(intimacy));
+        rel.setCommunicationScore(BigDecimal.valueOf(communication));
+        return rel;
+    }
+
+    private void stubRelations(FamilyRelationship rel) {
+        when(familyRelationshipService.getRelationsForMember(CENTER_ID))
+                .thenReturn(Collections.singletonList(rel));
+    }
+}

+ 305 - 0
cfc-backend/src/test/java/com/etotem/cfc/unit/GrowthPlanTaskListContractTest.java

@@ -0,0 +1,305 @@
+package com.etotem.cfc.unit;
+
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Test;
+
+import java.lang.reflect.Method;
+import java.lang.reflect.ParameterizedType;
+import java.lang.reflect.Type;
+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 plan.task.list})。
+ *
+ * <p>契约来源(TDD-RED 阶段契约新增能力,SC-P-47 方案任务列表,业务域 D):
+ * <blockquote>
+ *   SC-P-47 · 查看方案下任务列表 — 目标:跟踪执行。流程:方案 → 关联任务列表(状态/进度)。
+ *   边界:任务增删与方案同步。模块:{@code GrowthPlanController} + {@code TaskController}。
+ * </blockquote></p>
+ *
+ * <p><b>与 task.* 能力的区分</b>:{@code task.parent.createTask} / {@code task.parent.review}
+ * (S-cfc-12/13)面向通用任务的创建与审批;本键 {@code plan.task.list} 面向
+ * <b>方案维度的任务清单视图</b>(读侧聚合:列表 + 状态/进度 + 增删同步)。</p>
+ *
+ * <p><b>实现现状(src/main 核实)</b>:
+ * <ul>
+ *   <li>{@code GrowthPlanController}(/{@code api/growth/plan})现有端点:create / child/{memberId} /
+ *       child/{memberId}/active / {id} / update / {id}/review / list(管理端分页);
+ *       <b>无方案任务列表视图端点</b>。</li>
+ *   <li>{@code GrowthPlanService} 无 {@code planTaskList}/{@code getPlanTasks}/{@code planTasks}
+ *       等任务清单方法;{@code GrowthPlan} 实体无任务关联字段、无进度聚合。</li>
+ *   <li>任务实体 {@code Task} 尚无成长方案关联维度(无 growthPlanId/planId),
+ *       「任务增删与方案同步」无落点。</li>
+ * </ul>
+ * 因此本测试以「反射结构契约」探测实现缺失:
+ * <b>能编译通过、能运行、断言失败(红)</b>,且失败断言原文清晰可贴。</p>
+ *
+ * <p><b>GREEN 升级指引</b>:实现者在 {@code GrowthPlanController} 暴露方案任务列表视图
+ * (契约路由 {@code POST /api/growth/plan/task/list},body {planId} 或 {memberId}),
+ * 由 {@code GrowthPlanService} 提供任务清单(返回含 status/progress 的任务项),
+ * 并打通任务增删与方案的同步后,本测试自动转绿;
+ * 届时可把结构探测升级为行为级 Mockito 验证。</p>
+ *
+ * <p><b>三流覆盖</b>:
+ * <ul>
+ *   <li>正常流:视图端点存在 + 任务清单方法存在 + 状态/进度字段 + 方案关联字段;</li>
+ *   <li>异常流:缺 planId/memberId 参数守卫;</li>
+ *   <li>权限流:非本家庭不可见(IDOR 防护,familyId 归属校验)。</li>
+ * </ul></p>
+ *
+ * <p><b>测试范围</b>:仅反射探测结构契约(无 Spring / 无 DB / 无外部服务),断言不依赖真实数据。</p>
+ */
+class GrowthPlanTaskListContractTest {
+
+    /** 契约要求的方案任务列表视图端点所在控制器(growth 子包) */
+    private static final String GROWTH_PLAN_CONTROLLER = "com.etotem.cfc.controller.growth.GrowthPlanController";
+
+    /** 契约要求的方案任务清单服务 */
+    private static final String GROWTH_PLAN_SERVICE = "com.etotem.cfc.service.GrowthPlanService";
+
+    /** 任务实体(现有,用于进度/关联字段探测) */
+    private static final String TASK_ENTITY = "com.etotem.cfc.entity.Task";
+
+    /** 契约路由:POST /api/growth/plan/task/list(方案任务列表视图,SC-P-47) */
+    private static final String CONTRACT_ROUTE = "/api/growth/plan/task/list";
+
+    /** 契约 GATE 接口方法名候选(任务清单视图入口 / 任务清单服务方法) */
+    private static final String[] PLAN_TASK_METHODS = {"planTaskList", "getPlanTasks", "planTasks"};
+
+    // ------------------------------------------------------------------
+    // 正常流-1:GrowthPlanController 应暴露方案任务列表视图端点
+    // ------------------------------------------------------------------
+
+    @Test
+    @DisplayName("正常流-1:GrowthPlanController 应暴露 /api/growth/plan/task/list 方案任务列表端点")
+    void growthPlanController_exposesPlanTaskListRoute() {
+        Class<?> clazz = loadClass(GROWTH_PLAN_CONTROLLER);
+        assertNotNull(clazz, "[plan.task.list] GrowthPlanController 类不存在(" + GROWTH_PLAN_CONTROLLER + ")。");
+        assertTrue(hasRoutePrefix(clazz, "/api/growth/plan"),
+                "[plan.task.list] GrowthPlanController 应映射 /api/growth/plan 前缀。");
+        assertTrue(hasRoute(clazz, CONTRACT_ROUTE),
+                "[plan.task.list] " + simpleName(GROWTH_PLAN_CONTROLLER)
+                        + " 未暴露 POST " + CONTRACT_ROUTE
+                        + " 方案任务列表视图端点(SC-P-47:方案 → 关联任务列表(状态/进度))。实现未落地。");
+    }
+
+    // ------------------------------------------------------------------
+    // 正常流-2:任务清单应含「状态/进度」两个契约字段
+    // ------------------------------------------------------------------
+
+    @Test
+    @DisplayName("正常流-2:任务清单 Item 应含 status/progress 字段(状态/进度)")
+    void planTaskListItem_carriesStatusAndProgress() {
+        Class<?> taskClazz = loadClass(TASK_ENTITY);
+        assertNotNull(taskClazz, "[plan.task.list] Task 实体不存在(" + TASK_ENTITY + ")。");
+        boolean hasStatus = hasField(taskClazz, "status");
+        boolean hasProgress = hasField(taskClazz, "progress") || hasField(taskClazz, "todayDone");
+        assertTrue(hasStatus && hasProgress,
+                "[plan.task.list] 任务 Item 应含 status(状态)与 progress/todayDone(进度)字段"
+                        + "(当前 status=" + hasStatus + ", progress=" + hasProgress + ")。");
+    }
+
+    // ------------------------------------------------------------------
+    // 正常流-3:任务增删与方案同步(方案维度关联)
+    // ------------------------------------------------------------------
+
+    @Test
+    @DisplayName("正常流-3:任务应支持方案维度关联(任务增删与方案同步)")
+    void task_supportsPlanAssociation() {
+        Class<?> taskClazz = loadClass(TASK_ENTITY);
+        assertNotNull(taskClazz, "[plan.task.list] Task 实体不存在(" + TASK_ENTITY + ")。");
+        boolean hasPlanAssoc = hasField(taskClazz, "growthPlanId")
+                || hasField(taskClazz, "planId");
+        assertTrue(hasPlanAssoc,
+                "[plan.task.list] 任务应含 growthPlanId/planId 方案关联字段,"
+                        + "保证「任务增删与方案同步」(SC-P-47 边界)。当前缺失。");
+    }
+
+    // ------------------------------------------------------------------
+    // 正常流-4:GrowthPlanService 应提供方案任务清单方法
+    // ------------------------------------------------------------------
+
+    @Test
+    @DisplayName("正常流-4:GrowthPlanService 应提供方案任务清单方法")
+    void growthPlanService_hasPlanTaskListMethod() {
+        Class<?> clazz = loadClass(GROWTH_PLAN_SERVICE);
+        assertNotNull(clazz, "[plan.task.list] GrowthPlanService 类不存在(" + GROWTH_PLAN_SERVICE + ")。");
+        StringBuilder found = new StringBuilder();
+        for (String m : PLAN_TASK_METHODS) {
+            for (Method method : clazz.getDeclaredMethods()) {
+                if (method.getName().equals(m)) {
+                    found.append(m).append("(").append(method.getParameterCount()).append(") ");
+                    break;
+                }
+            }
+            if (found.length() > 0) {
+                break;
+            }
+        }
+        assertTrue(found.length() > 0,
+                "[plan.task.list] GrowthPlanService 应提供 " + String.join("/", PLAN_TASK_METHODS)
+                        + " 方案任务清单方法(返回任务列表,含状态/进度)。实现未落地。");
+    }
+
+    // ------------------------------------------------------------------
+    // 异常流-1:缺 planId/memberId 参数守卫
+    // ------------------------------------------------------------------
+
+    @Test
+    @DisplayName("异常流-1:方案任务列表入参应含 planId/memberId(缺参守卫)")
+    void planTaskList_requiresPlanIdOrMemberId() {
+        Class<?> clazz = loadClass(GROWTH_PLAN_SERVICE);
+        if (clazz == null) {
+            fail("[plan.task.list] GrowthPlanService 不存在,无法校验入参守卫(异常流)。");
+        }
+        boolean methodFound = false;
+        for (Method method : clazz.getDeclaredMethods()) {
+            if (!isPlanTaskMethod(method)) {
+                continue;
+            }
+            methodFound = true;
+            boolean hasPlanParam = false;
+            for (Type t : method.getGenericParameterTypes()) {
+                String typeName = typeSimpleName(t);
+                if (typeName.equals("Long") || typeName.equals("Map")) {
+                    hasPlanParam = true;
+                }
+            }
+            assertTrue(hasPlanParam,
+                    "[plan.task.list] " + method.getName() + " 应接收 planId/memberId 参数(缺参守卫要求)。");
+        }
+        if (!methodFound) {
+            fail("[plan.task.list] 异常流:方案任务清单方法未落地,无法验证缺参守卫。实现未落地。");
+        }
+    }
+
+    // ------------------------------------------------------------------
+    // 权限流-1:非本家庭不可见(IDOR 防护)
+    // ------------------------------------------------------------------
+
+    @Test
+    @DisplayName("权限流-1:方案任务列表视图应校验家庭归属(IDOR 防护)")
+    void planTaskList_guardsFamilyScope() {
+        Class<?> clazz = loadClass(GROWTH_PLAN_CONTROLLER);
+        if (clazz == null) {
+            fail("[plan.task.list] GrowthPlanController 不存在,无法校验家庭归属守卫(权限流)。");
+        }
+        boolean methodFound = false;
+        for (Method method : clazz.getDeclaredMethods()) {
+            if (!method.getName().equals("planTaskList") && !method.getName().equals("planTasks")) {
+                continue;
+            }
+            methodFound = true;
+            boolean hasFamilyParam = false;
+            for (Type t : method.getGenericParameterTypes()) {
+                if (typeSimpleName(t).equals("Long")) {
+                    hasFamilyParam = true;
+                }
+            }
+            assertTrue(hasFamilyParam,
+                    "[plan.task.list] 方案任务列表视图端点应携带 familyId 校验家庭归属"
+                            + "(非本家庭不可见,IDOR 防护)。实现未落地。");
+        }
+        if (!methodFound) {
+            fail("[plan.task.list] 权限流:方案任务列表视图端点未落地,无法验证家庭归属守卫。实现未落地。");
+        }
+    }
+
+    // ------------------------------------------------------------------
+    // 反射辅助
+    // ------------------------------------------------------------------
+
+    private Class<?> loadClass(String name) {
+        try {
+            return Class.forName(name, false, Thread.currentThread().getContextClassLoader());
+        } catch (ClassNotFoundException e) {
+            return null;
+        }
+    }
+
+    private boolean isPlanTaskMethod(Method method) {
+        for (String m : PLAN_TASK_METHODS) {
+            if (method.getName().equals(m)) {
+                return true;
+            }
+        }
+        return false;
+    }
+
+    private boolean hasField(Class<?> clazz, String fieldName) {
+        try {
+            clazz.getDeclaredField(fieldName);
+            return true;
+        } catch (NoSuchFieldException e) {
+            return false;
+        }
+    }
+
+    /**
+     * 探测契约路由 {@code /api/growth/plan/task/list} 是否已暴露。
+     * <p>严格按「路径段」匹配,避免把管理端的 {@code /list}({@code /api/growth/plan/list})
+     * 误判为契约的 {@code /task/list}:方法级相对路径必须完整等于 {@code task/list}
+     * (或以 {@code /task/list} 形式声明)。</p>
+     */
+    private boolean hasRoute(Class<?> clazz, String route) {
+        // 类级 @RequestMapping 直接拼完整路由(无子包前缀时)
+        org.springframework.web.bind.annotation.RequestMapping rm =
+                clazz.getAnnotation(org.springframework.web.bind.annotation.RequestMapping.class);
+        if (rm != null) {
+            for (String v : rm.value()) {
+                if (route.equals(v)) {
+                    return true;
+                }
+            }
+        }
+        // 方法级:契约相对路径段 = "task/list"
+        final String contractRelative = "task/list";
+        for (Method m : clazz.getDeclaredMethods()) {
+            org.springframework.web.bind.annotation.PostMapping pm =
+                    m.getAnnotation(org.springframework.web.bind.annotation.PostMapping.class);
+            if (pm == null) {
+                continue;
+            }
+            for (String v : pm.value()) {
+                String normalized = v.startsWith("/") ? v.substring(1) : v;
+                if (normalized.equals(contractRelative)) {
+                    return true;
+                }
+            }
+        }
+        return false;
+    }
+
+    private boolean hasRoutePrefix(Class<?> clazz, String prefix) {
+        org.springframework.web.bind.annotation.RequestMapping rm =
+                clazz.getAnnotation(org.springframework.web.bind.annotation.RequestMapping.class);
+        if (rm == null) {
+            return false;
+        }
+        for (String v : rm.value()) {
+            if (prefix.equals(v)) {
+                return true;
+            }
+        }
+        return false;
+    }
+
+    private String typeSimpleName(Type t) {
+        if (t instanceof Class) {
+            return ((Class<?>) t).getSimpleName();
+        }
+        if (t instanceof ParameterizedType) {
+            return typeSimpleName(((ParameterizedType) t).getRawType());
+        }
+        return String.valueOf(t);
+    }
+
+    private String simpleName(String fqcn) {
+        int idx = fqcn.lastIndexOf('.');
+        return idx >= 0 ? fqcn.substring(idx + 1) : fqcn;
+    }
+}

+ 322 - 0
cfc-backend/src/test/java/com/etotem/cfc/unit/ReportArchiveManageContractTest.java

@@ -0,0 +1,322 @@
+package com.etotem.cfc.unit;
+
+import com.etotem.cfc.entity.HealthReport;
+import com.etotem.cfc.service.FamilyMemberNutritionProfileService;
+import com.etotem.cfc.service.HealthReportService;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Test;
+import org.mockito.InjectMocks;
+import org.mockito.Mock;
+import org.mockito.MockitoAnnotations;
+
+import java.lang.reflect.Field;
+import java.lang.reflect.Method;
+import java.text.SimpleDateFormat;
+import java.util.Collections;
+import java.util.Date;
+import java.util.List;
+import java.util.Map;
+
+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;
+import static org.mockito.Mockito.when;
+
+/**
+ * 契约级单测:报告档案管理(能力键 {@code report.archive.manage},TDD-RED 阶段)。
+ *
+ * <p><b>契约溯源</b></p>
+ * <ul>
+ *   <li>需求:{@code tests/user-scenarios/应用场景总览.md}
+ *       <ul>
+ *         <li><b>SC-P-24 多报告管理/对比</b>(业务域 C,模块 报告管理)—— 流程:报告列表 → 查看/删除/对比;
+ *             边界:<b>删除有关联方案时提示</b>。对应测试用例 TC-P-24 / TC-P-24-E / TC-P-24-P:
+ *             <ul>
+ *               <li>TC-P-24:删除有关联方案时提示;对比展示差异</li>
+ *               <li>TC-P-24-E:有方案时提示<b>「请先解除关联方案」</b>再删;不存在 id 返回 404 不崩</li>
+ *               <li>TC-P-24-P:非归属数据访问(报告)统一 403/401,横向越权被拒</li>
+ *             </ul></li>
+ *         <li><b>SC-P-25 报告趋势查看</b>(业务域 C,模块 报告/成长)—— 流程:同类型报告时间序列 → 趋势图;
+ *             边界:<b>单报告无趋势</b>;时间轴正确。对应 TC-P-25 / TC-P-25-E:
+ *             <ul>
+ *               <li>TC-P-25:同类型报告时间序列趋势图;单报告无趋势提示;时间轴按真实时间升序</li>
+ *               <li>TC-P-25-E:仅 1 份同类型报告 → 提示<b>「至少需要 2 份报告才能看趋势」</b>;
+ *                   两份报告时间倒挂时按真实时间升序不倒挂</li>
+ *             </ul></li>
+ *       </ul></li>
+ *   <li>设计:{@code docs/superpowers/api/API_REFERENCE.md}
+ *       <ul>
+ *         <li>§4.10 测评({@code POST /api/assessment/history} 测评历史、
+ *             {@code POST /api/assessment/latest-result} 最新结果)—— 成长档案 / 报告管理锚点</li>
+ *         <li>§4.59.10 契约缺口:<b>未实现端点</b> {@code /api/health/report/{compare,trend,...}}
+ *             (即报告对比 / 报告趋势契约新增,实现未落地)</li>
+ *       </ul></li>
+ * </ul>
+ *
+ * <p><b>实现现状(2026-11-14,本分支 src/main 核实)</b>:以下契约行为<b>均未落地</b>,本测试逐一探测缺失:</p>
+ * <ol>
+ *   <li><b>删除守卫缺失</b>:{@code HealthReportService.deleteReport(Long)} 无条件逻辑删除(status=deleted +
+ *       清理关联数据),<b>不检测报告关联成长方案</b>——服务内无 {@code GrowthPlanMapper} /
+ *       {@code hasLinkedPlan} / {@code assertNotLinkedToPlan} 入口,无法在删除前提示「请先解除关联方案」。</li>
+ *   <li><b>单报告趋势未拦</b>:{@code FamilyMemberNutritionProfileService.getReportTrendData(memberId)}
+ *       对 1 份报告仍返回单点序列(dates/scores 各 1 项),<b>不标记无趋势、不提示</b>「至少需要 2 份报告才能看趋势」。</li>
+ *   <li><b>趋势未按同类型过滤</b>:{@code getReportTrendData} 仅 1 参(memberId),无 {@code reportType}
+ *       入参,无法只取「同类型报告」时间序列(SC-P-25 口径)。</li>
+ *   <li><b>报告对比缺失</b>:契约宿主 {@code ReportArchiveCompareService} 未落地;{@code HealthReportController}
+ *       无 {@code POST /api/health/report/compare} 端点(对比展示差异 / 类型一致才可比对均无载体)。</li>
+ *   <li><b>删除归属未校验</b>:{@code HealthReportController.deleteReport} 仅收 {@code @RequestBody Map},
+ *       无 {@code userId}/{@code memberId} 归属校验,横向越权删除他人报告不被拒(TC-P-24-P)。</li>
+ * </ol>
+ *
+ * <p><b>测试范围</b>:纯 Mockito / 反射,无 Spring 上下文、无 DB、无外部服务、无真实微信。
+ * 能编译、能运行、断言失败(红),失败断言原文清晰可贴;实现落地后转绿。</p>
+ *
+ * <p><b>GREEN 升级指引</b>:实现者按本契约补齐——
+ * (1) {@code HealthReportService} 注入 {@code GrowthPlanMapper} 并提供 {@code hasLinkedPlan(Long)}/
+ * {@code assertNotLinkedToPlan(Long)},删除前命中则抛 {@code MSG_LINKED_PLAN};
+ * (2) {@code FamilyMemberNutritionProfileService.getReportTrendData} 增 {@code reportType} 同类型过滤,
+ * 单报告(同类型 &lt;2)时返回 {@code trendAvailable=false} + 提示 {@code MSG_SINGLE_REPORT_TREND};
+ * (3) 落地 {@code ReportArchiveCompareService.compareReports(reportAId, reportBId)}(类型一致才可比对,返回差异标注)
+ * 及 {@code HealthReportController} 的 {@code POST /api/health/report/compare} 端点;
+ * (4) {@code HealthReportController.deleteReport} 增 {@code @RequestAttribute("userId")} 归属校验,
+ * 非归属返回 403/401。</p>
+ */
+class ReportArchiveManageContractTest {
+
+    // ==================== 契约文案(TC-P-24-E / TC-P-25-E 原文) ====================
+
+    /** 删除有关联方案时的提示(TC-P-24-E「请先解除关联方案」) */
+    private static final String MSG_LINKED_PLAN = "该报告已关联成长方案,请先解除关联方案后再删除";
+
+    /** 单报告无趋势提示(TC-P-25-E「至少需要 2 份报告才能看趋势」) */
+    private static final String MSG_SINGLE_REPORT_TREND = "至少需要 2 份报告才能看趋势";
+
+    /** 报告对比契约宿主(§4.59.10 未实现端点 /api/health/report/compare 的服务层载体) */
+    private static final String HOST_REPORT_COMPARE = "com.etotem.cfc.service.ReportArchiveCompareService";
+
+    // ==================== Mockito:趋势行为探测(SC-P-25) ====================
+
+    @Mock
+    private HealthReportService healthReportService;
+
+    @InjectMocks
+    private FamilyMemberNutritionProfileService trendService;
+
+    @BeforeEach
+    void setUp() {
+        MockitoAnnotations.openMocks(this);
+    }
+
+    // ==================== A. 删除守卫(关联方案)— SC-P-24 / TC-P-24-E ====================
+
+    @Test
+    @DisplayName("删除守卫:HealthReportService 应提供关联方案检测入口(hasLinkedPlan/assertNotLinkedToPlan)")
+    void deleteReport_应提供关联方案检测入口() {
+        Class<?> svc = loadClass("com.etotem.cfc.service.HealthReportService");
+        assertNotNull(svc, "[report.archive.manage] HealthReportService 类不存在,无法探测删除守卫入口。");
+
+        // 守卫入口:方法 hasLinkedPlan(Long) / assertNotLinkedToPlan(Long),或注入 GrowthPlanMapper 字段
+        boolean hasGuardMethod = false;
+        for (Method m : svc.getDeclaredMethods()) {
+            String n = m.getName();
+            if (("hasLinkedPlan".equals(n) || "assertNotLinkedToPlan".equals(n))
+                    && m.getParameterCount() == 1) {
+                hasGuardMethod = true;
+                break;
+            }
+        }
+        boolean hasGrowthPlanMapper = false;
+        for (Field f : svc.getDeclaredFields()) {
+            if (f.getType().getName().endsWith("GrowthPlanMapper")) {
+                hasGrowthPlanMapper = true;
+                break;
+            }
+        }
+
+        assertTrue(hasGuardMethod || hasGrowthPlanMapper,
+                "[report.archive.manage] HealthReportService 缺少关联方案检测入口:删除前应检测报告是否关联"
+                        + "成长方案(hasLinkedPlan/assertNotLinkedToPlan 或 GrowthPlanMapper),"
+                        + "命中则提示「" + MSG_LINKED_PLAN + "」(SC-P-24 / TC-P-24-E)。实现未落地。");
+    }
+
+    @Test
+    @DisplayName("删除守卫:删除关联方案报告应被拒并提示「请先解除关联方案」,不落删除")
+    void deleteReport_关联方案报告_应拒绝并提示_不删除() {
+        Class<?> svc = loadClass("com.etotem.cfc.service.HealthReportService");
+        assertNotNull(svc, "[report.archive.manage] HealthReportService 类不存在。");
+
+        // 行为探测:定位删除守卫入口(GREEN 后在此反射调用并断言抛 MSG_LINKED_PLAN + 不执行删除)
+        Method guard = null;
+        for (Method m : svc.getDeclaredMethods()) {
+            String n = m.getName();
+            if (("hasLinkedPlan".equals(n) || "assertNotLinkedToPlan".equals(n))
+                    && m.getParameterCount() == 1) {
+                guard = m;
+                break;
+            }
+        }
+        if (guard == null) {
+            // 契约入口缺失即红:无法表达「关联方案报告删除被拒」这一行为(TC-P-24-E)
+            fail("[report.archive.manage] 删除守卫入口缺失:无 hasLinkedPlan/assertNotLinkedToPlan,"
+                    + "删除关联方案报告时无法提示「" + MSG_LINKED_PLAN + "」,会无条件删除(SC-P-24)。");
+        }
+        // 守卫入口已存在(GREEN 阶段补行为级断言:反射调用抛 MSG_LINKED_PLAN)
+        assertNotNull(guard, "[report.archive.manage] 删除守卫入口应存在(SC-P-24)。");
+    }
+
+    // ==================== B. 趋势守卫(单报告 / 同类型)— SC-P-25 / TC-P-25-E ====================
+
+    @Test
+    @DisplayName("趋势:单报告应标记无趋势并提示「至少需要 2 份报告才能看趋势」")
+    void 趋势_单报告_应标记无趋势并提示() {
+        HealthReport only = report("gut_flora", "2026-10-01", 72);
+
+        when(healthReportService.getMemberReports(1L)).thenReturn(Collections.singletonList(only));
+
+        Map<String, Object> trend = trendService.getReportTrendData(1L);
+        assertNotNull(trend, "[report.archive.manage] 趋势数据不应为 null(SC-P-25)。");
+
+        // 契约:单报告(同类型 <2)→ trendAvailable=false + 提示文案(TC-P-25-E)
+        assertFalse(Boolean.TRUE.equals(trend.get("trendAvailable")),
+                "[report.archive.manage] 单报告应标记 trendAvailable=false(无趋势),"
+                        + "当前仅 1 份报告仍返回单点序列(dates/scores 各 1 项)。SC-P-25 边界未落地。");
+        assertTrue(trend.containsKey("message") && trend.get("message") != null
+                        && trend.get("message").toString().contains(MSG_SINGLE_REPORT_TREND),
+                "[report.archive.manage] 单报告趋势应返回提示「" + MSG_SINGLE_REPORT_TREND
+                        + "」(TC-P-25-E),当前 response 无 message 字段。实现未落地。");
+    }
+
+    @Test
+    @DisplayName("趋势:应提供 reportType 同类型过滤入参(同类型报告时间序列)")
+    void 趋势_应提供reportType同类型过滤入参() {
+        Class<?> svc = loadClass("com.etotem.cfc.service.FamilyMemberNutritionProfileService");
+        assertNotNull(svc, "[report.archive.manage] FamilyMemberNutritionProfileService 类不存在。");
+
+        boolean hasTypedOverload = false;
+        for (Method m : svc.getDeclaredMethods()) {
+            if (m.getName().equals("getReportTrendData") && m.getParameterCount() == 2) {
+                hasTypedOverload = true;
+                break;
+            }
+        }
+        assertTrue(hasTypedOverload,
+                "[report.archive.manage] getReportTrendData 缺少 reportType 入参:SC-P-25 口径为"
+                        + "「同类型报告时间序列」→趋势图,需按 reportType 过滤;当前仅 1 参(memberId),"
+                        + "无法只取同类型报告。实现未落地。");
+    }
+
+    // ==================== C. 报告对比(SC-P-24 对比展示差异)— 正常流 ====================
+
+    @Test
+    @DisplayName("报告对比:应提供 ReportArchiveCompareService 宿主")
+    void 报告对比_应提供ReportArchiveCompareService宿主() {
+        Class<?> host = loadClass(HOST_REPORT_COMPARE);
+        assertNotNull(host,
+                "[report.archive.manage] ReportArchiveCompareService 未落地:SC-P-24「对比展示差异」"
+                        + "(TC-P-24)契约宿主缺失,报告档案对比无载体(§4.59.10 未实现端点 /api/health/report/compare)。");
+    }
+
+    @Test
+    @DisplayName("报告对比:宿主应提供 compareReports(reportAId, reportBId) 契约方法")
+    void 报告对比_宿主应提供compareReports方法() {
+        Class<?> host = loadClass(HOST_REPORT_COMPARE);
+        if (host == null) {
+            fail("[report.archive.manage] ReportArchiveCompareService 未落地,无法验证 compareReports "
+                    + "契约方法(SC-P-24 / TC-P-24)。");
+        }
+        boolean hasCompare = false;
+        for (Method m : host.getDeclaredMethods()) {
+            if (m.getName().equals("compareReports") && m.getParameterCount() == 2) {
+                hasCompare = true;
+                break;
+            }
+        }
+        assertTrue(hasCompare,
+                "[report.archive.manage] ReportArchiveCompareService 应提供 compareReports(reportAId, reportBId),"
+                        + "报告类型一致才可比对、差异清晰标注(SC-P-24 / TC-T-21)。");
+    }
+
+    @Test
+    @DisplayName("报告对比:HealthReportController 应暴露 POST /api/health/report/compare 端点")
+    void 报告对比_应暴露report_compare端点() {
+        Class<?> controller = loadClass("com.etotem.cfc.controller.HealthReportController");
+        assertNotNull(controller, "[report.archive.manage] HealthReportController 类不存在。");
+
+        boolean exposed = false;
+        for (Method m : controller.getDeclaredMethods()) {
+            org.springframework.web.bind.annotation.PostMapping post =
+                    m.getAnnotation(org.springframework.web.bind.annotation.PostMapping.class);
+            if (post != null) {
+                for (String v : post.value()) {
+                    if ("/report/compare".equals(v)) {
+                        exposed = true;
+                        break;
+                    }
+                }
+            }
+            if (exposed) break;
+        }
+        assertTrue(exposed,
+                "[report.archive.manage] HealthReportController 缺少 POST /api/health/report/compare 端点:"
+                        + "报告档案对比(SC-P-24 / TC-P-24,§4.59.10 未实现端点)无接口载体。实现未落地。");
+    }
+
+    // ==================== D. 权限流(SC-P-24-P 归属校验) ====================
+
+    @Test
+    @DisplayName("权限流:删除报告应校验归属,非归属数据访问统一 403/401")
+    void 删除报告_应校验归属_非归属越权被拒() {
+        Class<?> controller = loadClass("com.etotem.cfc.controller.HealthReportController");
+        assertNotNull(controller, "[report.archive.manage] HealthReportController 类不存在。");
+
+        Method del = null;
+        for (Method m : controller.getDeclaredMethods()) {
+            if (m.getName().equals("deleteReport")) {
+                del = m;
+                break;
+            }
+        }
+        assertNotNull(del, "[report.archive.manage] HealthReportController.deleteReport 方法不存在。");
+
+        boolean hasOwnerArg = false;
+        for (java.lang.reflect.Parameter p : del.getParameters()) {
+            for (java.lang.annotation.Annotation a : p.getAnnotations()) {
+                String at = a.annotationType().getName();
+                // 归属校验载体:@RequestAttribute("userId"/"memberId") 或 @RequestAttribute("familyId")
+                if (at.endsWith("RequestAttribute")) {
+                    hasOwnerArg = true;
+                }
+            }
+        }
+        assertTrue(hasOwnerArg,
+                "[report.archive.manage] HealthReportController.deleteReport 缺少归属校验参数"
+                        + "(@RequestAttribute userId/memberId/familyId):当前仅收 @RequestBody Map,"
+                        + "无法拦截横向越权删除他人报告(SC-P-24-P / TC-P-24-P,非归属统一 403/401)。实现未落地。");
+    }
+
+    // ==================== 反射 / 测试辅助 ====================
+
+    private HealthReport report(String reportType, String reportDate, int overallScore) {
+        HealthReport r = new HealthReport();
+        r.setId(9001L);
+        r.setReportType(reportType);
+        try {
+            Date d = new SimpleDateFormat("yyyy-MM-dd").parse(reportDate);
+            r.setReportDate(d);
+        } catch (Exception ignored) {
+            // 契约探针不依赖真实日期解析
+        }
+        r.setOverallScore(overallScore);
+        return r;
+    }
+
+    private Class<?> loadClass(String name) {
+        try {
+            return Class.forName(name, false, Thread.currentThread().getContextClassLoader());
+        } catch (ClassNotFoundException e) {
+            return null;
+        }
+    }
+}

+ 469 - 0
cfc-backend/src/test/java/com/etotem/cfc/unit/WishCycleManageContractTest.java

@@ -0,0 +1,469 @@
+package com.etotem.cfc.unit;
+
+import com.etotem.cfc.common.Result;
+import com.etotem.cfc.controller.wish.WishController;
+import com.etotem.cfc.dto.CreateWishDTO;
+import com.etotem.cfc.dto.WishDTO;
+import com.etotem.cfc.entity.FamilyMember;
+import com.etotem.cfc.entity.User;
+import com.etotem.cfc.entity.Wish;
+import com.etotem.cfc.mapper.FamilyMemberMapper;
+import com.etotem.cfc.mapper.UserMapper;
+import com.etotem.cfc.mapper.WishMapper;
+import com.etotem.cfc.service.CfSpendDispatchService;
+import com.etotem.cfc.service.WishService;
+import org.junit.jupiter.api.BeforeEach;
+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.RequestBody;
+import org.springframework.web.bind.annotation.RequestMapping;
+
+import java.lang.annotation.Annotation;
+import java.lang.reflect.Field;
+import java.lang.reflect.Method;
+import java.lang.reflect.Parameter;
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.HashSet;
+import java.util.List;
+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.assertThrows;
+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.Mockito.mock;
+import static org.mockito.Mockito.never;
+import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.when;
+
+/**
+ * 契约级单测:能力键 {@code wish.cycle.manage}(SC-P-13 心愿创建-审批-兑换闭环 / SC-P-14 心愿驳回/失效处理)。
+ *
+ * <p><b>溯源·需求</b>:{@code tests/user-scenarios/应用场景总览.md}
+ * <ul>
+ *   <li>SC-P-13:B 建心愿 → 家长待审批 → 通过扣积分兑换 / 驳回失效;边界:积分不足拦截;驳回后不可再兑。</li>
+ *   <li>SC-P-14:驳回 → 心愿失效 → 可重新提;边界:已兑换不可驳回。</li>
+ * </ul></p>
+ *
+ * <p><b>溯源·设计</b>:{@code API_REFERENCE.md} §4.4 心愿({@code /api/wishes})create / set-price /
+ * reject / exchange / approve-exchange / fulfill / confirm / cancel / list / pending / {id};
+ * §4.61.6 商城/心愿/积分(SC-C-04/C-22)list 请求体契约 {@code {memberId?, status?, page?, size?}} → {@code Wish[]}。
+ * 模块:{@link WishController} + 奖励域 {@code RewardController}(奖励模板/兑换,本键聚焦 wish 域闭环)。</p>
+ *
+ * <p><b>编排溯源</b>:{@code docs/tdd/orchestration/sc-key-map.md} SC-P-13 / SC-P-14 → 键
+ * {@code wish.cycle.manage} → 任务 <b>S-cfc-261</b>(RED 阶段)。</p>
+ *
+ * <p><b>测试范围与 RED 判定</b>:纯 Mockito / 反射,无 Spring / 无 DB / 无外部服务(同批
+ * {@code WishFlowScP13ContractTest} / {@code ChildWishManageContractTest} 风格)。</p>
+ * <ul>
+ *   <li><b>核心闭环(A–E 段)</b>:心愿 create→定价→申请兑换→批准扣积分→兑现→确认 的状态机、
+ *       驳回/失效/重新提、积分不足拦截、已兑换不可驳回、越权拒绝——这些为 SC-P-13/14 契约本体。</li>
+ *   <li><b>契约缺口(F 段,预期红)</b>:{@code /api/wishes/list} 的 §4.61.6 契约
+ *       (请求体 body 传参 {@code {memberId, status}} + 分页 {@code page}/{@code size} + {@code status} 过滤生效)
+ *       未落地——现有 {@code WishController.getWishes} 用 {@code @RequestParam} 读参、
+ *       无 page/size 分页、且 status 参数被完全忽略(按 notIn(cancelled) 硬编码返回全部非取消心愿)。
+ *       F 段断言契约所需行为缺失,预期失败(红),GREEN 阶段补齐 list 契约后转绿。</li>
+ * </ul>
+ */
+class WishCycleManageContractTest {
+
+    // ==================== 契约锚点常量(API_REFERENCE §4.4) ====================
+
+    /** §4.4 心愿契约端点(11 条) */
+    private static final String[] WISH_CONTRACT_PATHS = {
+            "/create", "/{id}/set-price", "/{id}/reject", "/{id}/exchange",
+            "/{id}/approve-exchange", "/{id}/fulfill", "/{id}/confirm",
+            "/{id}/cancel", "/list", "/pending", "/{id}"
+    };
+
+    /** 心愿兑换扣账 refType(cf_balance 统一账本口径,§10.25 cf 单一真源) */
+    private static final String WISH_EXCHANGE_REF_TYPE = "wish_exchange";
+
+    private WishService service;
+    private WishMapper wishMapper;
+    private FamilyMemberMapper familyMemberMapper;
+    private UserMapper userMapper;
+    private CfSpendDispatchService cfSpendDispatchService;
+
+    /** 捕获 DB 中已插入/更新的心愿(模拟 wish 表) */
+    private final List<Wish> wishStore = new ArrayList<>();
+    private long idSeq = 5000L;
+
+    @BeforeEach
+    void setUp() throws Exception {
+        service = new WishService();
+        wishMapper = mock(WishMapper.class);
+        familyMemberMapper = mock(FamilyMemberMapper.class);
+        userMapper = mock(UserMapper.class);
+        cfSpendDispatchService = mock(CfSpendDispatchService.class);
+
+        inject(service, "wishMapper", wishMapper);
+        inject(service, "familyMemberMapper", familyMemberMapper);
+        inject(service, "userMapper", userMapper);
+        inject(service, "cfSpendDispatchService", cfSpendDispatchService);
+
+        // insert 捕获并回填主键
+        when(wishMapper.insert(any(Wish.class))).thenAnswer(inv -> {
+            Wish w = inv.getArgument(0);
+            if (w.getId() == null) w.setId(++idSeq);
+            wishStore.add(w);
+            return 1;
+        });
+        // selectById 主键查询
+        when(wishMapper.selectById(any(Long.class))).thenAnswer(inv -> {
+            Long id = inv.getArgument(0);
+            return wishStore.stream().filter(w -> w.getId().equals(id)).findFirst().orElse(null);
+        });
+        // updateById 覆盖 store 中同 id
+        when(wishMapper.updateById(any(Wish.class))).thenAnswer(inv -> {
+            Wish w = inv.getArgument(0);
+            for (int i = 0; i < wishStore.size(); i++) {
+                if (wishStore.get(i).getId().equals(w.getId())) wishStore.set(i, w);
+            }
+            return 1;
+        });
+        // selectList 返回 store 快照(供 list 契约 F 段验证 status 过滤)
+        when(wishMapper.selectList(any())).thenAnswer(inv -> new ArrayList<>(wishStore));
+        when(wishMapper.selectCount(any())).thenReturn(0L);
+
+        // 默认:家庭1、家长 user(1,1)、成员B member(100,1,1)、CF 余额 1000
+        when(userMapper.selectById(1L)).thenReturn(user(1L, 1L));
+        when(familyMemberMapper.selectById(100L)).thenReturn(member(100L, 1L, 1L, "小明"));
+        when(cfSpendDispatchService.getAvailableForMember(100L)).thenReturn(1000);
+    }
+
+    // =====================================================================
+    // A. 端点路由契约(反射):§4.4 /api/wishes 11 条端点
+    // =====================================================================
+
+    @Test
+    @DisplayName("端点契约:WishController /api/wishes 暴露 §4.4 全部 11 条契约端点")
+    void wishController_exposesContractEndpoints() {
+        Class<?> clazz = WishController.class;
+        RequestMapping classMapping = clazz.getAnnotation(RequestMapping.class);
+        assertNotNull(classMapping, "WishController 应声明类级 @RequestMapping");
+        assertTrue(Arrays.asList(classMapping.value()).contains("/api/wishes"),
+                "WishController 类级路由应为 /api/wishes,实际: " + Arrays.toString(classMapping.value()));
+
+        Set<String> postPaths = postMappingPaths(clazz);
+        for (String path : WISH_CONTRACT_PATHS) {
+            assertTrue(postPaths.contains(path),
+                    "契约端点 POST /api/wishes" + path + " 应已注册(API_REFERENCE §4.4),实际已注册: " + postPaths);
+        }
+    }
+
+    // =====================================================================
+    // B. SC-P-13 心愿创建-审批-兑换闭环(正常流)
+    // =====================================================================
+
+    @Test
+    @DisplayName("SC-P-13 正常流:孩子建心愿→家长定价→孩子申请兑换→家长批准扣积分→兑现→确认收货")
+    void p13_闭环_创建_定价_兑换_批准扣积分_兑现_确认() {
+        // 1) B 建心愿 → draft(进家长待审批)
+        Long id = service.createByChild(100L, childWish("买乐高"));
+        assertEquals("draft", current(id).getStatus(), "孩子建心愿初始为 draft(待家长定价审批)");
+        assertEquals("child", current(id).getCreatorType());
+
+        // 2) 家长定价 draft→active
+        assertTrue(service.setPrice(id, 1L, 300), "家长定价应成功");
+        assertEquals("active", current(id).getStatus(), "定价后 active");
+        assertEquals(300, current(id).getPointsRequired().intValue());
+
+        // 3) B 申请兑换 active→pending_exchange
+        assertTrue(service.requestExchange(id, 100L), "申请兑换应成功");
+        assertEquals("pending_exchange", current(id).getStatus());
+
+        // 4) 家长批准兑换 pending_exchange→approved,扣 cf_balance
+        assertTrue(service.approveExchange(id, 1L, true), "家长批准兑换应成功");
+        assertEquals("approved", current(id).getStatus(), "批准后 approved");
+        verify(cfSpendDispatchService).spendForMember(100L, 300, WISH_EXCHANGE_REF_TYPE, id, "兑换心愿: 买乐高");
+
+        // 5) 家长标记已购买 approved→exchanging
+        assertTrue(service.markFulfilled(id, 1L), "标记已购买应成功");
+        assertEquals("exchanging", current(id).getStatus());
+
+        // 6) B 确认收货 exchanging→fulfilled
+        assertTrue(service.confirmReceived(id, 100L), "确认收货应成功");
+        assertEquals("fulfilled", current(id).getStatus(), "闭环终点 fulfilled");
+    }
+
+    @Test
+    @DisplayName("SC-P-13 正常流:家长可直接建 active 心愿并进入兑换链")
+    void p13_闭环_家长直接建active心愿_孩子兑换_批准() {
+        Long id = service.createByParent(1L, parentWish(100L, 300, "乐高"));
+        assertEquals("active", current(id).getStatus(), "家长建心愿应直接 active(已定价)");
+
+        assertTrue(service.requestExchange(id, 100L));
+        assertEquals("pending_exchange", current(id).getStatus());
+
+        assertTrue(service.approveExchange(id, 1L, true));
+        assertEquals("approved", current(id).getStatus());
+        verify(cfSpendDispatchService).spendForMember(100L, 300, WISH_EXCHANGE_REF_TYPE, id, "兑换心愿: 乐高");
+    }
+
+    // =====================================================================
+    // C. SC-P-13 异常流:积分不足拦截 / 非 active 不可兑 / 重复兑拦截
+    // =====================================================================
+
+    @Test
+    @DisplayName("SC-P-13 异常流:积分不足申请兑换被拦截,状态保持 active")
+    void p13_异常_积分不足_拦截_不改状态() {
+        when(cfSpendDispatchService.getAvailableForMember(100L)).thenReturn(10); // 余额 < 价
+        Long id = service.createByParent(1L, parentWish(100L, 300, "高价心愿"));
+
+        RuntimeException e = assertThrows(RuntimeException.class, () -> service.requestExchange(id, 100L));
+        assertTrue(e.getMessage().contains("积分不足"), "实际: " + e.getMessage());
+        assertEquals("active", current(id).getStatus(), "积分不足不应改状态");
+        verify(cfSpendDispatchService, never()).spendForMember(any(), any(Integer.class), any(), any(), any());
+    }
+
+    @Test
+    @DisplayName("SC-P-13 异常流:draft 状态申请兑换被拒(未定价不可兑)")
+    void p13_异常_draft不可申请兑换() {
+        Long id = service.createByChild(100L, childWish("draft心愿"));
+        assertFalse(service.requestExchange(id, 100L), "draft 未定价不可申请兑换");
+    }
+
+    @Test
+    @DisplayName("SC-P-13 异常流:已兑换(approved)不可再次申请兑换")
+    void p13_异常_已兑换不可重复申请() {
+        Long id = service.createByParent(1L, parentWish(100L, 20, "再兑心愿"));
+        service.requestExchange(id, 100L);
+        service.approveExchange(id, 1L, true); // approved
+
+        assertFalse(service.requestExchange(id, 100L), "approved 非 active,不可再次申请兑换");
+    }
+
+    // =====================================================================
+    // D. SC-P-14 心愿驳回/失效处理 + 已兑换不可驳回
+    // =====================================================================
+
+    @Test
+    @DisplayName("SC-P-14 正常流:家长驳回 draft 心愿→rejected(失效),记 rejectCount")
+    void p14_正常_驳回draft_失效() {
+        Long id = service.createByChild(100L, childWish("异常心愿"));
+        assertTrue(service.rejectWish(id, 1L, "积分超额"), "驳回应成功");
+        assertEquals("rejected", current(id).getStatus(), "驳回后失效 rejected");
+        assertEquals(1, current(id).getRejectCount().intValue(), "rejectCount 应 +1");
+    }
+
+    @Test
+    @DisplayName("SC-P-14 正常流:驳回后不可再兑(rejected 非 active)")
+    void p14_正常_驳回后不可兑() {
+        Long id = service.createByChild(100L, childWish("被驳回心愿"));
+        service.rejectWish(id, 1L, "积分超额");
+
+        assertFalse(service.requestExchange(id, 100L), "被驳回心愿不可再申请兑换(驳回后不可再兑)");
+    }
+
+    @Test
+    @DisplayName("SC-P-14 正常流:驳回→失效→可重新提(member 重新建新心愿为 draft)")
+    void p14_正常_驳回后可重新提_新心愿draft() {
+        Long first = service.createByChild(100L, childWish("被驳回心愿"));
+        service.rejectWish(first, 1L, "积分超额");
+        assertEquals("rejected", current(first).getStatus());
+
+        // 可重新提:member 重新建新心愿,仍走 draft 待审批
+        Long second = service.createByChild(100L, childWish("重新提的心愿"));
+        assertNotNull(second, "重新提应成功(新建心愿)");
+        assertEquals("draft", current(second).getStatus(), "重新提的心愿应为 draft(待审批)");
+        assertEquals("child", current(second).getCreatorType());
+    }
+
+    @Test
+    @DisplayName("SC-P-14 正常流:取消 active 心愿→cancelled(失效)")
+    void p14_正常_取消active_失效() {
+        Long id = service.createByParent(1L, parentWish(100L, 10, "取消心愿"));
+        assertTrue(service.cancelWish(id, 1L, "孩子不要了"), "取消应成功");
+        assertEquals("cancelled", current(id).getStatus(), "取消后失效 cancelled");
+    }
+
+    @Test
+    @DisplayName("SC-P-14 异常流:已兑换(approved)不可驳回")
+    void p14_异常_已兑换不可驳回() {
+        Long id = service.createByParent(1L, parentWish(100L, 20, "已兑换心愿"));
+        service.requestExchange(id, 100L);
+        service.approveExchange(id, 1L, true); // approved
+
+        assertFalse(service.rejectWish(id, 1L, "驳回"), "已兑换心愿不可驳回(rejectWish 仅允许 draft)");
+    }
+
+    @Test
+    @DisplayName("SC-P-14 异常流:已确认收货(fulfilled)不可驳回")
+    void p14_异常_已兑现不可驳回() {
+        Long id = service.createByParent(1L, parentWish(100L, 20, "已兑现心愿"));
+        service.requestExchange(id, 100L);
+        service.approveExchange(id, 1L, true);
+        service.markFulfilled(id, 1L);
+        service.confirmReceived(id, 100L); // fulfilled
+
+        assertFalse(service.rejectWish(id, 1L, "驳回"), "已兑现心愿不可驳回");
+    }
+
+    // =====================================================================
+    // E. 权限流:跨家庭家长定价/驳回/审批被拒;非归属成员兑换被拒
+    // =====================================================================
+
+    @Test
+    @DisplayName("权限流:跨家庭家长为孩子定价被拒")
+    void 权限_跨家庭家长定价_拒绝() {
+        Long id = service.createByChild(100L, childWish("本家心愿"));
+        when(userMapper.selectById(99L)).thenReturn(user(99L, 999L));
+
+        assertFalse(service.setPrice(id, 99L, 100), "非本家庭家长定价应失败");
+    }
+
+    @Test
+    @DisplayName("权限流:跨家庭家长为孩子建 active 心愿被拒(成员不属于该家庭)")
+    void 权限_跨家庭家长建心愿_拒绝() {
+        when(userMapper.selectById(99L)).thenReturn(user(99L, 999L));
+
+        RuntimeException e = assertThrows(RuntimeException.class,
+                () -> service.createByParent(99L, parentWish(100L, 100, "越权心愿")));
+        assertTrue(e.getMessage().contains("不属于该家庭"), "实际: " + e.getMessage());
+    }
+
+    @Test
+    @DisplayName("权限流:非心愿归属成员申请兑换被拒")
+    void 权限_非归属成员兑换_拒绝() {
+        Long id = service.createByParent(1L, parentWish(100L, 10, "他人心愿"));
+
+        assertFalse(service.requestExchange(id, 200L), "非归属成员申请兑换应被拒");
+        verify(cfSpendDispatchService, never()).spendForMember(any(), any(Integer.class), any(), any(), any());
+    }
+
+    // =====================================================================
+    // F. 契约缺口(预期红):/api/wishes/list §4.61.6 契约未落地
+    // =====================================================================
+
+    @Test
+    @DisplayName("F1 契约缺口:list 应按契约从请求体 body 读 {memberId, status, page, size}")
+    void f1_list_应支持body传参_契约缺口_预期红() {
+        // §4.61.6:POST /api/wishes/list 请求体 {memberId?, status?, page?, size?}
+        // 现状 getWishes 用 @RequestParam(query 参数)读 memberId/familyId/status,
+        // 与契约「请求体 body」不符 → 无任何 @RequestBody 参数 → 断言失败(红)
+        Method m = findMethod(WishController.class, "getWishes");
+        boolean hasRequestBody = false;
+        for (Parameter p : m.getParameters()) {
+            for (Annotation a : p.getAnnotations()) {
+                if (a.annotationType() == RequestBody.class) {
+                    hasRequestBody = true;
+                }
+            }
+        }
+        assertTrue(hasRequestBody,
+                "[wish.cycle.manage] POST /api/wishes/list 契约要求请求体 body {memberId?, status?, page?, size?}(§4.61.6),"
+                        + "但 WishController.getWishes 未声明 @RequestBody 参数(现状用 @RequestParam 读参)。契约缺口,预期红。");
+    }
+
+    @Test
+    @DisplayName("F2 契约缺口:list 应支持 page/size 分页(契约 body.page/size)")
+    void f2_list_应支持分页_契约缺口_预期红() {
+        // 契约含 page?/size? 分页;现状 getWishes 仅 (userId, role, memberId, familyId, status) 5 参,无分页槽位
+        // → 参数总数 5 < 7(userId/role/memberId/familyId/status + page/size)→ 断言失败(红)
+        Method m = findMethod(WishController.class, "getWishes");
+        int paramCount = m.getParameterCount();
+        assertTrue(paramCount >= 7,
+                "[wish.cycle.manage] POST /api/wishes/list 契约要求支持 page/size 分页(§4.61.6 body.page/size),"
+                        + "但 WishController.getWishes 参数数=" + paramCount
+                        + "(仅 userId/role/memberId/familyId/status),无分页槽位。契约缺口,预期红。");
+    }
+
+    @Test
+    @DisplayName("F3 契约缺口:list 应按 status 过滤(契约 body.status)")
+    void f3_list_应按status过滤_契约缺口_预期红() throws Exception {
+        // 成员 B 有 2 条心愿:一条 active、一条 fulfilled(已确认收货)
+        service.createByParent(1L, parentWish(100L, 300, "A_active"));
+        Long doneId = service.createByParent(1L, parentWish(100L, 20, "B_fulfilled"));
+        service.requestExchange(doneId, 100L);
+        service.approveExchange(doneId, 1L, true);
+        service.markFulfilled(doneId, 1L);
+        service.confirmReceived(doneId, 100L); // fulfilled
+
+        WishController controller = new WishController();
+        inject(controller, "wishService", service);
+
+        // 契约:body.status=active → 仅返回 active(1 条)
+        Result<List<WishDTO>> result = controller.getWishes(1L, "parent", 100L, null, "active");
+        List<WishDTO> data = result.getData();
+        assertNotNull(data);
+        // 现状:status 参数被完全忽略(getChildWishes 仅 notIn(cancelled)),active+fulfilled 全返回(2 条)
+        assertEquals(1, data.size(),
+                "[wish.cycle.manage] POST /api/wishes/list 契约要求按 body.status 过滤(§4.61.6),"
+                        + "status=active 应仅返回 active 心愿;现状忽略 status,返回 " + data.size()
+                        + " 条(active+fulfilled 全部)。契约缺口,预期红。");
+    }
+
+    // =====================================================================
+    // 辅助构造
+    // =====================================================================
+
+    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 static User user(Long id, Long familyId) {
+        User u = new User();
+        u.setId(id);
+        u.setFamilyId(familyId);
+        return u;
+    }
+
+    private static FamilyMember member(Long id, Long familyId, Long userId, String nickname) {
+        FamilyMember m = new FamilyMember();
+        m.setId(id);
+        m.setFamilyId(familyId);
+        m.setUserId(userId);
+        m.setNickname(nickname);
+        return m;
+    }
+
+    private static CreateWishDTO childWish(String title) {
+        CreateWishDTO dto = new CreateWishDTO();
+        dto.setTitle(title);
+        return dto;
+    }
+
+    private static CreateWishDTO parentWish(Long memberId, Integer points, String title) {
+        CreateWishDTO dto = new CreateWishDTO();
+        dto.setTitle(title);
+        dto.setMemberId(memberId);
+        dto.setPointsRequired(points);
+        return dto;
+    }
+
+    /** 在 store 中检索指定 id 的当前心愿对象 */
+    private Wish current(Long id) {
+        return wishStore.stream().filter(w -> w.getId().equals(id)).findFirst().orElse(null);
+    }
+
+    /** 收集类上所有 @PostMapping 的 value 路径 */
+    private static Set<String> postMappingPaths(Class<?> clazz) {
+        Set<String> paths = new HashSet<>();
+        for (Method m : clazz.getDeclaredMethods()) {
+            PostMapping pm = m.getAnnotation(PostMapping.class);
+            if (pm != null) {
+                paths.addAll(Arrays.asList(pm.value()));
+            }
+        }
+        return paths;
+    }
+
+    /** 按名称查找无参/任意参方法(用于反射断言) */
+    private static Method findMethod(Class<?> clazz, String name) {
+        for (Method m : clazz.getDeclaredMethods()) {
+            if (m.getName().equals(name)) {
+                return m;
+            }
+        }
+        fail("方法 " + clazz.getSimpleName() + "." + name + " 不存在");
+        return null;
+    }
+}

+ 1 - 1
cfc-web/.last_build_commit

@@ -1 +1 @@
-da78baefa72d0f86d383f9d252ed7b1bf353ccab
+9cf9bfa4907ad4a55423c1b97696d61168c461bb

+ 2 - 2
cfc-web/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "cfc-web",
-  "version": "1.0.2461",
+  "version": "1.0.2463",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "cfc-web",
-      "version": "1.0.2461",
+      "version": "1.0.2463",
       "dependencies": {
         "@wangeditor/editor": "^5.1.23",
         "@wangeditor/editor-for-vue": "^1.0.2",

+ 1 - 1
cfc-web/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cfc-web",
-  "version": "1.0.2462",
+  "version": "1.0.2464",
   "private": true,
   "scripts": {
     "dev": "vue-cli-service serve",

+ 45 - 0
cfc-web/public/CHANGELOG-v1.0.md

@@ -4,6 +4,51 @@
 
 ---
 
+## v1.0.2464 (2026-11-13)
+
+### 测试
+- family.family.relationGraph TDD-RED 契约单测(SC-P-07 家庭关系图节点+关系标签渲染/关系缺失降级,15 用例 5 红)
+- add RED contract test for SC-P-13/14 wish cycle (S-cfc-261)
+- S-cfc-254 butler.quality.qa 服务质检与满意度 契约级单测 12例全红
+- S-cfc-246 ai.coach.reportAnalyze 成长报告智能解读 契约级单测10例全红
+
+### 其他
+- 新增纯 Mockito/反射契约测试 WishCycleManageContractTest(18 用例):
+- - A 段:/api/wishes §4.4 全部 11 条端点路由(反射)
+- - B/C 段:create→定价→申请兑换→批准扣 cf_balance→兑现→确认 闭环 + 积分不足/非 active 拦截
+- - D 段:驳回→失效→可重新提、取消失效、已兑换不可驳回
+- - E 段:跨家庭定价/建心愿/非归属成员兑换越权拒绝
+- - F 段(预期红):/api/wishes/list 的 §4.61.6 契约缺口——应支持 body 传参
+-   {memberId,status,page,size} + 分页 + status 过滤,现状 @RequestParam 读参且忽略 status
+- 红测结果:Tests run 18, Failures 3(F1/F2/F3 list 契约缺口), 15 通过(核心闭环已落地)。
+- GREEN 阶段补齐 list 契约后 F 段转绿。
+- 
+- 契约来源:tests/user-scenarios/应用场景总览.md SC-H-07(服务质检与满意度)
+- ;API_REFERENCE ActivityFeedbackController + AdminSurveyController + 差评触发复盘/回流改进
+- RED 预期:但lerQualityService/ButlerSatisfactionService/ButlerPerformanceService 及 ButlerQualityInspection/ButlerSatisfaction 实体与 3 张建表均未落地,结构探测断言失败(11 例失败,权限流 1 例标注不适用),断言原文清晰可贴,待 GREEN 阶段实现后自动转绿。
+- 禁止改 src/main 实现;仅新增测试文件。
+- 
+- - 设计锚点:API_REFERENCE 4.64.4 POST /api/ai/report/analyze(报告翻译人话+五维关联+行动建议)
+- - 实现现状核实(origin/cfclub):reportAnalyze 端点骨架存在,但契约新增行为未落地
+-   (三段结构化输出 VO / 报告归属越权403 / 解析中拦截 / 类型不一致 / PII脱敏)
+- - 10 用例全红(Errors:0 纯断言失败):正常流4(plainSummary/fiveDimAssociations/actionSuggestions/五维一致)
+-   + 异常流4(无报告请先上传/解析中提示/类型不一致/高敏脱敏)+ 权限流2(越权403)
+- - 纯 Mockito/反射注入,无 Spring/DB/外部服务(仿 CoachButlerNotificationContractTest)
+- 
+
+
+## v1.0.2463 (2026-11-13)
+
+### 测试
+- RED 契约单测 ai.coach.recommend(SC-B-07 推荐与采纳)
+
+### 其他
+- 饮食推荐并一键采纳(分析→推荐→采纳)。宿主 CoachRecommendService 未实现、契约端点
+- CoachRecommendController 未落地、coach_recommend_log 表缺失 → 13/13 红(预期 RED)。
+- 只新增 cfc-backend/src/test,不改 src/main。GREEN 阶段按 javadoc 契约方法签名落地即可转绿。
+- 
+
+
 ## v1.0.2462 (2026-11-13)
 
 ### 测试

+ 46 - 1
cfc-web/public/CHANGELOG.md

@@ -1,6 +1,6 @@
 # 更新日志
 
-> 当前版本: v1.0.2462
+> 当前版本: v1.0.2464
 
 ## 历史版本
 
@@ -8,6 +8,51 @@
 
 ---
 
+## v1.0.2464 (2026-11-13)
+
+### 测试
+- family.family.relationGraph TDD-RED 契约单测(SC-P-07 家庭关系图节点+关系标签渲染/关系缺失降级,15 用例 5 红)
+- add RED contract test for SC-P-13/14 wish cycle (S-cfc-261)
+- S-cfc-254 butler.quality.qa 服务质检与满意度 契约级单测 12例全红
+- S-cfc-246 ai.coach.reportAnalyze 成长报告智能解读 契约级单测10例全红
+
+### 其他
+- 新增纯 Mockito/反射契约测试 WishCycleManageContractTest(18 用例):
+- - A 段:/api/wishes §4.4 全部 11 条端点路由(反射)
+- - B/C 段:create→定价→申请兑换→批准扣 cf_balance→兑现→确认 闭环 + 积分不足/非 active 拦截
+- - D 段:驳回→失效→可重新提、取消失效、已兑换不可驳回
+- - E 段:跨家庭定价/建心愿/非归属成员兑换越权拒绝
+- - F 段(预期红):/api/wishes/list 的 §4.61.6 契约缺口——应支持 body 传参
+-   {memberId,status,page,size} + 分页 + status 过滤,现状 @RequestParam 读参且忽略 status
+- 红测结果:Tests run 18, Failures 3(F1/F2/F3 list 契约缺口), 15 通过(核心闭环已落地)。
+- GREEN 阶段补齐 list 契约后 F 段转绿。
+- 
+- 契约来源:tests/user-scenarios/应用场景总览.md SC-H-07(服务质检与满意度)
+- ;API_REFERENCE ActivityFeedbackController + AdminSurveyController + 差评触发复盘/回流改进
+- RED 预期:但lerQualityService/ButlerSatisfactionService/ButlerPerformanceService 及 ButlerQualityInspection/ButlerSatisfaction 实体与 3 张建表均未落地,结构探测断言失败(11 例失败,权限流 1 例标注不适用),断言原文清晰可贴,待 GREEN 阶段实现后自动转绿。
+- 禁止改 src/main 实现;仅新增测试文件。
+- 
+- - 设计锚点:API_REFERENCE 4.64.4 POST /api/ai/report/analyze(报告翻译人话+五维关联+行动建议)
+- - 实现现状核实(origin/cfclub):reportAnalyze 端点骨架存在,但契约新增行为未落地
+-   (三段结构化输出 VO / 报告归属越权403 / 解析中拦截 / 类型不一致 / PII脱敏)
+- - 10 用例全红(Errors:0 纯断言失败):正常流4(plainSummary/fiveDimAssociations/actionSuggestions/五维一致)
+-   + 异常流4(无报告请先上传/解析中提示/类型不一致/高敏脱敏)+ 权限流2(越权403)
+- - 纯 Mockito/反射注入,无 Spring/DB/外部服务(仿 CoachButlerNotificationContractTest)
+- 
+
+
+## v1.0.2463 (2026-11-13)
+
+### 测试
+- RED 契约单测 ai.coach.recommend(SC-B-07 推荐与采纳)
+
+### 其他
+- 饮食推荐并一键采纳(分析→推荐→采纳)。宿主 CoachRecommendService 未实现、契约端点
+- CoachRecommendController 未落地、coach_recommend_log 表缺失 → 13/13 红(预期 RED)。
+- 只新增 cfc-backend/src/test,不改 src/main。GREEN 阶段按 javadoc 契约方法签名落地即可转绿。
+- 
+
+
 ## v1.0.2462 (2026-11-13)
 
 ### 测试