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

merge origin/cfclub into tmp/cfc-262-merge before push

Sisyphus Agent 6 дней назад
Родитель
Сommit
a80750b84

+ 23 - 0
cfc-backend/src/test/java/com/etotem/cfc/service/AiCoachHandoffContract.java

@@ -0,0 +1,23 @@
+package com.etotem.cfc.service;
+
+/**
+ * 契约锚点:AI 教练转接成长规划师(能力键 {@code ai.coach.handoffPlanner},单元 ai.coach)。
+ * 规格溯源:docs/superpowers/specs/2026-11-07-ai-butler-contract.md v0.7 §9-SC-B-09 + API_REFERENCE.md §4.64
+ * 实际转接载体:规划师绑定流(/api/guide/bind/confirm)+ 家庭确认绑定(/api/bind/accept)
+ */
+public class AiCoachHandoffContract {
+    static final String ENTITY_HANDOFF_PLAN = "com.etotem.cfc.entity.HandoffPlan";
+    static final String SERVICE_AI_COACH = "com.etotem.cfc.service.AiCoachHandoffService";
+    static final String SERVICE_BIND = "com.etotem.cfc.service.BindService";
+    static final String SERVICE_GUIDE = "com.etotem.cfc.service.PlannerCertificationGuard";
+    static final String SERVICE_MEMBERSHIP = "com.etotem.cfc.service.MembershipService";
+
+    // 契约方法签名
+    static final String METHOD_IS_SIGNAL = "isHandoffSignal";
+    static final String METHOD_PLAN = "planHandoff";
+
+    // 信号类型常量(参考 SC-B-09 描述)
+    static final String SIGNAL_TYPE_PROFESSIONAL = "PROFESSIONAL";
+    static final String SIGNAL_TYPE_UNCERTAIN = "UNCERTAIN";
+    static final String SIGNAL_TYPE_NONE = "NONE";
+}

+ 291 - 0
cfc-backend/src/test/java/com/etotem/cfc/unit/AiCoachHandoffContractTest.java

@@ -0,0 +1,291 @@
+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.lang.reflect.Field;
+import java.lang.reflect.Method;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+import static org.junit.jupiter.api.Assertions.fail;
+
+/**
+ * 契约级单测:AI 教练转接成长规划师(能力键 {@code ai.coach.handoffPlanner},单元 ai.coach)。
+ *
+ * <p><b>契约溯源</b></p>
+ * <ul>
+ *   <li>需求:SC-B-09({@code tests/user-scenarios/08-butler.md:97})——教练识别专业信号
+ *       (持续异常/方案分歧/报告高风险)后引导家长预约/发消息给绑定规划师,转接留痕;
+ *       异常/边界:未绑定规划师时提示先绑定(SC-P-32);转接动作留审计;不代规划师给出诊断结论。</li>
+ *   <li>设计:{@code docs/superpowers/api/API_REFERENCE.md} §4.64(EVD-14)+ 契约文档
+ *       {@code docs/superpowers/specs/2026-11-07-ai-butler-contract.md} §SC-B-09 —— 实际转接载体为
+ *       规划师绑定流 {@code /api/guide/bind/invite|validate|confirm}(BindInviteController)+
+ *       {@code /api/bind/accept|unbind}(BindController),非 butler 申请流。</li>
+ * </ul>
+ *
+ * <p><b>宿主契约(TDD-RED 锚点)</b>:{@code com.etotem.cfc.service.AiCoachHandoffService} ——
+ * SC-B-09「识别信号 → 转接规划师」规划的服务类,当前 src/main <b>尚未实现</b>(全库 0 引用;
+ * 无 AiCoachHandoffService / AiCoachHandoffPlan)。本测试通过反射锚定宿主契约方法(避免直接
+ * import 不存在类导致编译失败),运行时宿主类缺失即断言失败(红),暴露「转接编排能力未落地」
+ * 这一真实缺陷;GREEN 落地后转为验证真实行为。</p>
+ *
+ * <p><b>契约方法签名(实现方按此落地)</b></p>
+ * <ul>
+ *   <li>{@code boolean isHandoffSignal(String signalType)} —— 识别需专业干预的信号
+ *       ({@code PROFESSIONAL}:持续异常/方案分歧/报告高风险 → true;不可识别 → false);</li>
+ *   <li>{@code AiCoachHandoffPlan planHandoff(Long userId, Long familyId, String signalType,
+ *       Long boundPlannerId, String requestedAction)} —— 编排转接计划:已绑定(boundPlannerId
+ *       非空)→ 引导预约/消息并留痕;未绑定 → {@code BIND_FIRST} 提示先绑(SC-P-32);不可识别信号
+ *       → {@code NONE} 空转接;{@code diagnosisIncluded=false}(不代规划师诊断)。</li>
+ * </ul>
+ *
+ * <p><b>契约端点(载体已落地,GREEN 锚点)</b>:转接触发由已存在的
+ * {@code BindInviteController /api/guide/bind/confirm}(family 子包)+ {@code BindController /api/bind/accept} 承担,
+ * 宿主服务实例化后依赖其绑定数据提供转接目标。</p>
+ *
+ * <p><b>测试范围</b>:纯契约级单测,仅 JUnit + 反射,无 Spring / 无 DB / 无真实微信 / 无外部服务。</p>
+ *
+ * <p><b>RED 预期</b>:宿主 {@code AiCoachHandoffService} 未实现——全部宿主用例在反射探测处失败(红),
+ * 断言原文「RED[ai.coach.handoffPlanner] 契约宿主 AiCoachHandoffService 未实现」;契约端点用例
+ * (载体已落地)应通过,作为「载体齐备、编排缺失」的对照证据。</p>
+ */
+class AiCoachHandoffContractTest {
+
+    /** 规格设计宿主服务类(未实现)。 */
+    private static final String HOST_CLASS = "com.etotem.cfc.service.AiCoachHandoffService";
+
+    /** 转接计划实体(未实现)。 */
+    private static final String PLAN_CLASS = "com.etotem.cfc.entity.AiCoachHandoffPlan";
+
+    /** SC-B-09 实际载体(已落地):规划师绑定流(BindInviteController / BindController)。 */
+    private static final String CONTROLLER_BIND_INVITE = "com.etotem.cfc.controller.family.BindInviteController";
+    private static final String CONTROLLER_BIND = "com.etotem.cfc.controller.family.BindController";
+
+    /** 转接动作口径。 */
+    private static final String ACTION_APPOINTMENT = "APPOINTMENT";
+    private static final String ACTION_MESSAGE = "MESSAGE";
+    private static final String ACTION_BIND_FIRST = "BIND_FIRST";
+    private static final String ACTION_NONE = "NONE";
+
+    /** 需专业干预的信号(持续异常/方案分歧/报告高风险)。 */
+    private static final String SIGNAL_PROFESSIONAL = "PROFESSIONAL";
+
+    // ==================== 正常流:宿主服务 + 信号识别 ====================
+
+    @Test
+    @DisplayName("正常流-1:AiCoachHandoffService 契约宿主应已实现")
+    void hostService_classExists() {
+        assertNotNull(contractHost(),
+                "RED[ai.coach.handoffPlanner] 契约宿主 AiCoachHandoffService 未实现(实现未落地):"
+                        + "SC-B-09 教练转接成长规划师编排能力未落地,契约无法满足。");
+    }
+
+    @Test
+    @DisplayName("正常流-2:isHandoffSignal 应识别需专业干预的信号(PROFESSIONAL)")
+    void isHandoffSignal_professional_true() {
+        assertEquals(Boolean.TRUE, callBoolean(contractHost(), "isHandoffSignal", SIGNAL_PROFESSIONAL),
+                "教练识别到需专业干预的信号(持续异常/方案分歧/报告高风险)时 isHandoffSignal 必须为 true");
+    }
+
+    // ==================== 正常流:已绑定规划师 → 引导预约/消息 + 留痕 ====================
+
+    @Test
+    @DisplayName("正常流-3:已绑定规划师时 planHandoff 应返回转接计划并留痕")
+    void planHandoff_bound_returnsPlanWithTrace() {
+        Object plan = call(contractHost(), "planHandoff",
+                1L, 11L, SIGNAL_PROFESSIONAL, 501L, ACTION_APPOINTMENT);
+        assertNotNull(plan, "planHandoff 必须返回转接计划(" + PLAN_CLASS + ")");
+        assertEquals(ACTION_APPOINTMENT, callGet(plan, "getAction"),
+                "已绑定规划师时转接动作应为 APPOINTMENT(生成预约 SC-P-36)或 MESSAGE(发消息 SC-X-11)");
+        assertEquals(Boolean.TRUE, callBooleanGet(plan, "isRecorded"),
+                "转接必须留痕(转接动作留审计)");
+    }
+
+    @Test
+    @DisplayName("正常流-4:已绑定规划师时转接计划应携带目标规划师 id")
+    void planHandoff_bound_carriesPlannerId() {
+        Object plan = call(contractHost(), "planHandoff",
+                1L, 11L, SIGNAL_PROFESSIONAL, 501L, ACTION_MESSAGE);
+        assertEquals(501L, toLong(callGet(plan, "getPlannerId")),
+                "转接计划必须携带 boundPlannerId,指向已绑定规划师(引导预约/消息的目标)");
+    }
+
+    // ==================== 异常流:未绑定提示先绑 / 不可识别信号 ====================
+
+    @Test
+    @DisplayName("异常流-5:未绑定规划师时 planHandoff 应返回 BIND_FIRST(SC-P-32),不生成预约")
+    void planHandoff_unbound_bindFirst() {
+        Object plan = call(contractHost(), "planHandoff",
+                1L, 11L, SIGNAL_PROFESSIONAL, null, ACTION_APPOINTMENT);
+        assertNotNull(plan, "未绑定场景也必须返回转接计划(不得抛异常)");
+        assertEquals(ACTION_BIND_FIRST, callGet(plan, "getAction"),
+                "未绑定规划师(boundPlannerId=null)时不得直接预约/发消息——提示先绑定(SC-P-32)");
+    }
+
+    @Test
+    @DisplayName("异常流-6:isHandoffSignal 对不可识别信号应返回 false")
+    void isHandoffSignal_unknown_false() {
+        assertEquals(Boolean.FALSE, callBoolean(contractHost(), "isHandoffSignal", "UNKNOWN_SIGNAL"),
+                "无法识别的信号类型不得触发转接(isHandoffSignal=false)");
+    }
+
+    @Test
+    @DisplayName("异常流-7:不可识别信号时 planHandoff 应返回 NONE(空转接,不建预约/消息)")
+    void planHandoff_unknownSignal_none() {
+        Object plan = call(contractHost(), "planHandoff",
+                1L, 11L, "UNKNOWN_SIGNAL", null, null);
+        assertEquals(ACTION_NONE, callGet(plan, "getAction"),
+                "不可识别信号不得转接、不得生成预约/消息——返回 NONE 空转接");
+    }
+
+    // ==================== 边界流:不代规划师诊断 ====================
+
+    @Test
+    @DisplayName("边界流-8:转接计划不得包含规划师诊断结论(diagnosisIncluded=false)")
+    void planHandoff_diagnosisNotIncluded() {
+        Object plan = call(contractHost(), "planHandoff",
+                1L, 11L, SIGNAL_PROFESSIONAL, 501L, ACTION_MESSAGE);
+        assertEquals(Boolean.FALSE, callBooleanGet(plan, "isDiagnosisIncluded"),
+                "教练只负责转接引导,不得代规划师给出诊断结论(diagnosisIncluded 必须为 false)");
+    }
+
+    // ==================== 契约端点:载体已落地(GREEN 对照锚点) ====================
+
+    @Test
+    @DisplayName("契约端点-9:BindInviteController 应落地 /api/guide/bind/confirm(转接引导载体)")
+    void controller_bindInvite_confirmExists() {
+        Class<?> clazz = loadClass(CONTROLLER_BIND_INVITE);
+        assertNotNull(clazz, "契约端点 BindInviteController 已存在(SC-B-09 规划师绑定流载体)");
+        RequestMapping rm = clazz.getAnnotation(RequestMapping.class);
+        assertNotNull(rm, "BindInviteController 应标注 @RequestMapping");
+        assertTrue(firstValue(rm.value()).startsWith("/api/guide/bind"),
+                "BindInviteController 类路径应为 /api/guide/bind 前缀,实际=" + firstValue(rm.value()));
+        assertTrue(hasPostMappingPath(clazz, "/confirm"),
+                "应提供 @PostMapping /confirm(家庭确认绑定 = 转接引导落地点)");
+    }
+
+    @Test
+    @DisplayName("契约端点-10:BindController 应落地 /api/bind/accept(家庭确认绑定载体)")
+    void controller_bind_acceptExists() {
+        Class<?> clazz = loadClass(CONTROLLER_BIND);
+        assertNotNull(clazz, "契约端点 BindController 已存在(SC-B-09 家庭绑定载体)");
+        RequestMapping rm = clazz.getAnnotation(RequestMapping.class);
+        assertNotNull(rm, "BindController 应标注 @RequestMapping");
+        assertTrue(firstValue(rm.value()).startsWith("/api/bind"),
+                "BindController 类路径应为 /api/bind 前缀,实际=" + firstValue(rm.value()));
+        assertTrue(hasPostMappingPath(clazz, "/accept"),
+                "应提供 @PostMapping /accept(家庭主账号确认绑定规划师)");
+        assertTrue(hasFieldOfType(clazz, "com.etotem.cfc.service.GuideFamilyService"),
+                "BindController 应注入 GuideFamilyService(绑定关系落库)");
+    }
+
+    // ==================== 反射辅助(锚定宿主契约,避免编译期依赖不存在类) ====================
+
+    private Object contractHost() {
+        try {
+            Class<?> clazz = Class.forName(HOST_CLASS);
+            return clazz.getDeclaredConstructor().newInstance();
+        } catch (ClassNotFoundException e) {
+            fail("RED[ai.coach.handoffPlanner] 契约宿主 AiCoachHandoffService 未实现(实现未落地):"
+                    + e.getMessage());
+            throw new IllegalStateException("unreachable");
+        } catch (Exception e) {
+            fail("契约宿主 AiCoachHandoffService 实例化失败:" + e.getMessage());
+            throw new IllegalStateException("unreachable");
+        }
+    }
+
+    /** 按方法名 + 参数个数匹配并调用宿主方法,契约方法缺失即断言失败。 */
+    private Object call(Object host, String method, Object... args) {
+        for (Method m : host.getClass().getMethods()) {
+            if (m.getName().equals(method) && m.getParameterCount() == args.length) {
+                try {
+                    return m.invoke(host, args);
+                } catch (Exception e) {
+                    fail("契约方法 " + HOST_CLASS + "#" + method + " 调用失败:" + e.getMessage());
+                    throw new IllegalStateException("unreachable");
+                }
+            }
+        }
+        fail("RED[ai.coach.handoffPlanner] 契约方法 " + HOST_CLASS + "#" + method + " 未实现");
+        throw new IllegalStateException("unreachable");
+    }
+
+    /** 反射调用转接计划 getter(空参),缺失即断言失败。 */
+    private Object callGet(Object target, String getter) {
+        try {
+            Method m = target.getClass().getMethod(getter);
+            return m.invoke(target);
+        } catch (Exception e) {
+            fail("转接计划 " + target.getClass().getName() + "#" + getter + " 调用失败:" + e.getMessage());
+            throw new IllegalStateException("unreachable");
+        }
+    }
+
+    private boolean callBoolean(Object host, String method, Object... args) {
+        Object r = call(host, method, args);
+        if (r instanceof Boolean) {
+            return (Boolean) r;
+        }
+        fail("契约方法 " + method + " 应返回布尔,实际 " + r);
+        throw new IllegalStateException("unreachable");
+    }
+
+    private boolean callBooleanGet(Object target, String getter) {
+        Object r = callGet(target, getter);
+        if (r instanceof Boolean) {
+            return (Boolean) r;
+        }
+        fail("getter " + getter + " 应返回布尔,实际 " + r);
+        throw new IllegalStateException("unreachable");
+    }
+
+    private long toLong(Object v) {
+        if (v instanceof Number) {
+            return ((Number) v).longValue();
+        }
+        if (v instanceof CharSequence) {
+            try {
+                return Long.parseLong(v.toString().trim());
+            } catch (NumberFormatException ignored) {
+                // fall through
+            }
+        }
+        return -1L;
+    }
+
+    private Class<?> loadClass(String name) {
+        try {
+            return Class.forName(name, false, Thread.currentThread().getContextClassLoader());
+        } catch (ClassNotFoundException e) {
+            return null;
+        }
+    }
+
+    private String firstValue(String[] values) {
+        return values != null && values.length > 0 ? values[0] : null;
+    }
+
+    private boolean hasPostMappingPath(Class<?> clazz, String path) {
+        for (Method m : clazz.getDeclaredMethods()) {
+            PostMapping pm = m.getAnnotation(PostMapping.class);
+            if (pm != null && path.equals(firstValue(pm.value()))) {
+                return true;
+            }
+        }
+        return false;
+    }
+
+    private boolean hasFieldOfType(Class<?> clazz, String fieldTypeName) {
+        for (Field f : clazz.getDeclaredFields()) {
+            if (fieldTypeName.equals(f.getType().getName())) {
+                return true;
+            }
+        }
+        return false;
+    }
+}

+ 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;
+    }
+}

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

@@ -0,0 +1,283 @@
+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 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.resource.match})。
+ *
+ * <p><b>契约锚点</b></p>
+ * <ul>
+ *   <li>需求:{@code tests/user-scenarios/应用场景总览.md} SC-H-05(线下资源与活动对接)——
+ *       流程:匹配 → 推送预约 → 回访;边界:仅审核资源;名额实时校验;不强制。</li>
+ *   <li>用例:{@code tests/test-cases/human-butler.md} TC-H-05(正常)/ TC-H-05-E(异常)/ TC-H-05-P(权限)。</li>
+ *   <li>设计:{@code docs/superpowers/api/API_REFERENCE.md} §4.13 / §4.64.10——资源清单 = {@code /api/admin/butler/list},
+ *       活动载体 = {@code /api/guide/activities/*}(GuideActivityController),线下课程/资源 = {@code AdminPlannerOfflineCourseController},
+ *       名额实时校验 = {@code ActivityRegistrationService.occupyQuota}(原子占用,满员提示「名额已满」)。</li>
+ * </ul>
+ *
+ * <p><b>被断言的三条契约流(TC-H-05)</b></p>
+ * <ul>
+ *   <li>正常流:按家长需求与孩子画像匹配资源 → 推送匹配结果 → 协助预约/报名 → 参与后回访并沉淀偏好;
+ *       匹配结果均来自已审核资源(AC1),含距离/时间/适龄信息(AC1),家长端可查看并选择(AC2),
+ *       预约/报名成功且名额库存实时扣减(AC3),回访记录写入家长档案供后续推荐参考(AC4)。</li>
+ *   <li>异常流(TC-H-05-E):未审核/已下架资源不出现在推荐候选;名额仅剩 1 时并发仅 1 人成功、另一人提示「名额已满」;
+ *       报名时实时校验库存不足、不产生超卖订单;管家高频推送同类资源频次受控。</li>
+ *   <li>权限流(TC-H-05-P):服务商推送未审核资源给家长 → 403;管家推荐其他家庭匹配资源 → 403;家长修改他人预约 → 403。</li>
+ * </ul>
+ *
+ * <p><b>实现现状</b>:本分支 src/main 中管家侧「资源匹配」层未落地——{@code ButlerResourceMatchService}、
+ * {@code ButlerResourceMatchResult} 实体、家庭端匹配结果查看端点、匹配推送/回访记录表均不存在
+ * (全库 0 引用,schema.sql 无对应建表)。名额实时校验({@code ActivityRegistrationService.occupyQuota})与
+ * 活动载体({@code GuideActivityController})已存在,仅为共享载体、非本键实现。因此本测试以
+ * 「反射结构契约」探测实现缺失:能编译通过、能运行、断言失败(红),且失败断言原文清晰可贴。</p>
+ *
+ * <p><b>GREEN 升级指引</b>:实现者创建 {@code ButlerResourceMatchService}(match/book 入口,仅候选已审核资源)、
+ * {@code ButlerResourceMatchResult}(distanceKm/startTime/ageSuitability/reviewStatus)、家庭端
+ * {@code /api/butler/resource-match/*} 端点,并建匹配推送留痕表(频次受控)与回访沉淀偏好表后,本测试自动转绿;
+ * 届时可将结构探测升级为行为级 mock 验证。</p>
+ */
+class ButlerResourceMatchContractTest {
+
+    /** 契约要求的能力键层匹配服务(SC-H-05:按家长需求与孩子画像匹配资源) */
+    private static final String MATCH_SERVICE = "com.etotem.cfc.service.ButlerResourceMatchService";
+
+    /** 契约要求的匹配结果实体(AC1:距离/时间/适龄;仅已审核资源入候选) */
+    private static final String MATCH_RESULT_ENTITY = "com.etotem.cfc.entity.ButlerResourceMatchResult";
+
+    /** 家庭端载体(AC2:家长端可查看并选择匹配结果) */
+    private static final String BUTLER_CONTROLLER = "com.etotem.cfc.controller.butler.ButlerController";
+
+    /** 名额实时校验载体(AC3 / TC-H-05-E-2/3:并发仅 1 人成功、不超卖) */
+    private static final String REGISTRATION_SERVICE = "com.etotem.cfc.service.ActivityRegistrationService";
+
+    /** AC1:匹配结果应含距离/时间/适龄信息 */
+    private static final String[] AC1_FIELDS = {"distanceKm", "startTime", "ageSuitability"};
+
+    /** TC-H-05-E-4:高频推送频次受控 → 匹配推送留痕表应记录推送时间戳与次数 */
+    private static final String[] MATCH_LOG_FIELDS = {"pushed_at", "push_count"};
+
+    /** AC4:回访记录写入家长档案、后续推荐参考偏好 → 回访沉淀偏好表 */
+    private static final String FOLLOW_UP_TABLE = "butler_resource_follow_up";
+
+    // ------------------------------------------------------------------
+    // 正常流-1:匹配服务类 + match 入口(按家长需求与孩子画像匹配资源)
+    // ------------------------------------------------------------------
+
+    @Test
+    @DisplayName("正常流-1:ButlerResourceMatchService 匹配服务类应存在")
+    void matchService_classExists() {
+        assertNotNull(loadClass(MATCH_SERVICE),
+                "[butler.resource.match] ButlerResourceMatchService 类不存在:SC-H-05 要求「按家长需求"
+                        + "与孩子画像匹配线下资源/活动(TC-H-05 正常流步骤1)」。实现未落地。");
+    }
+
+    @Test
+    @DisplayName("正常流-2:匹配服务应提供 match 入口返回候选结果")
+    void matchService_hasMatchEntry() {
+        Class<?> clazz = loadClass(MATCH_SERVICE);
+        if (clazz == null) {
+            fail("[butler.resource.match] ButlerResourceMatchService 类不存在,无法验证 match 入口"
+                    + "(SC-H-05 匹配→推送预约→回访)。");
+        }
+        assertTrue(hasMethod(clazz, "match"),
+                "[butler.resource.match] ButlerResourceMatchService 应提供 match(...) 入口,"
+                        + "输入家长需求 + 孩子画像,输出已审核资源/活动的匹配候选(TC-H-05 正常流步骤1)。");
+    }
+
+    // ------------------------------------------------------------------
+    // 正常流-2:匹配结果实体(AC1:仅已审核资源,含距离/时间/适龄)
+    // ------------------------------------------------------------------
+
+    @Test
+    @DisplayName("正常流-3:匹配结果实体 ButlerResourceMatchResult 应存在")
+    void matchResult_entityExists() {
+        assertNotNull(loadClass(MATCH_RESULT_ENTITY),
+                "[butler.resource.match] ButlerResourceMatchResult 实体不存在:SC-H-05 要求匹配结果"
+                        + "返回给家长端查看并选择(TC-H-05 AC2)。实现未落地。");
+    }
+
+    @Test
+    @DisplayName("正常流-4:匹配结果应含距离/时间/适龄信息(AC1)")
+    void matchResult_carriesDistanceTimeAge() {
+        Class<?> entity = loadClass(MATCH_RESULT_ENTITY);
+        if (entity == null) {
+            fail("[butler.resource.match] ButlerResourceMatchResult 实体不存在,无法验证 AC1 字段。");
+        }
+        for (String field : AC1_FIELDS) {
+            assertTrue(hasField(entity, field),
+                    "[butler.resource.match] 匹配结果实体应含 " + field
+                            + " 字段:AC1 要求匹配结果含距离/时间/适龄信息(TC-H-05)。");
+        }
+    }
+
+    @Test
+    @DisplayName("正常流-5:匹配结果应含审核状态门禁(仅已审核资源入候选)")
+    void matchResult_carriesReviewGate() {
+        Class<?> entity = loadClass(MATCH_RESULT_ENTITY);
+        if (entity == null) {
+            fail("[butler.resource.match] ButlerResourceMatchResult 实体不存在,无法验证审核门禁字段。");
+        }
+        assertTrue(hasField(entity, "reviewStatus") || hasField(entity, "auditStatus"),
+                "[butler.resource.match] 匹配结果实体应含 reviewStatus/auditStatus 字段:SC-H-05 边界"
+                        + "「仅审核资源」——未审核/已下架资源不得出现在推荐候选(TC-H-05-E-1)。");
+    }
+
+    // ------------------------------------------------------------------
+    // 正常流-3:家庭端查看/选择端点(AC2)+ 协助预约/报名(AC3)
+    // ------------------------------------------------------------------
+
+    @Test
+    @DisplayName("正常流-6:家庭端应提供匹配结果查看端点(AC2)")
+    void butlerController_hasResourceMatchViewEndpoint() {
+        Class<?> clazz = loadClass(BUTLER_CONTROLLER);
+        assertNotNull(clazz, "[butler.resource.match] ButlerController 类不存在,无法验证家庭端查看端点。");
+        assertTrue(hasPostMapping(clazz, "resource-match"),
+                "[butler.resource.match] ButlerController 应提供 resource-match 端点"
+                        + "(如 POST /api/butler/resource-match/list:家长端可查看并选择匹配结果,TC-H-05 AC2)。");
+    }
+
+    @Test
+    @DisplayName("正常流-7:匹配服务应提供 book 入口协助预约/报名(AC3 名额实时校验联动)")
+    void matchService_hasBookingAssist() {
+        Class<?> clazz = loadClass(MATCH_SERVICE);
+        if (clazz == null) {
+            fail("[butler.resource.match] ButlerResourceMatchService 类不存在,无法验证 book 协助预约入口。");
+        }
+        assertTrue(hasMethod(clazz, "book"),
+                "[butler.resource.match] ButlerResourceMatchService 应提供 book(...) 协助预约/报名入口,"
+                        + "内部联动名额实时校验(occupyQuota 原子占用,满员提示「名额已满」,AC3 / TC-H-05-E-2)。");
+    }
+
+    // ------------------------------------------------------------------
+    // 边界流:名额实时校验(已有载体核验,避免误报红)
+    // ------------------------------------------------------------------
+
+    @Test
+    @DisplayName("边界流-1:名额实时校验载体 ActivityRegistrationService.occupyQuota 应存在(并发不超卖)")
+    void registrationService_occupiesQuotaAtomically() {
+        Class<?> clazz = loadClass(REGISTRATION_SERVICE);
+        assertNotNull(clazz, "[butler.resource.match] ActivityRegistrationService 类不存在"
+                + "(名额实时校验载体,TC-H-05-E-2/3)。");
+        assertTrue(hasMethod(clazz, "occupyQuota"),
+                "[butler.resource.match] ActivityRegistrationService 应提供 occupyQuota 原子占用名额"
+                        + "(仅当 approved_count &lt; max_participants 时自增,名额仅剩 1 时并发仅 1 人成功,"
+                        + "报名时实时校验库存不足不产生超卖订单,TC-H-05-E-2/3)。");
+    }
+
+    // ------------------------------------------------------------------
+    // 边界流:高频推送频次受控(TC-H-05-E-4)+ 回访沉淀偏好(AC4)
+    // ------------------------------------------------------------------
+
+    @Test
+    @DisplayName("边界流-2:匹配推送留痕表应落地 schema.sql(频次受控 TC-H-05-E-4)")
+    void schemaSql_hasMatchPushLogTable() {
+        String schema = readSchemaSql();
+        assertTrue(schema.contains("butler_resource_match_log"),
+                "[butler.resource.match] schema.sql 缺少 butler_resource_match_log 匹配推送留痕表"
+                        + "(SC-H-05「推送预约」+ 边界「高频推送同类资源频次受控,触发阈值后限制推送」TC-H-05-E-4)。");
+        for (String column : MATCH_LOG_FIELDS) {
+            assertTrue(schema.contains(column),
+                    "[butler.resource.match] butler_resource_match_log 应含 " + column
+                            + " 列用于推送频次控制(TC-H-05-E-4)。");
+        }
+    }
+
+    @Test
+    @DisplayName("边界流-3:回访沉淀偏好表应落地 schema.sql(AC4)")
+    void schemaSql_hasFollowUpPreferenceTable() {
+        String schema = readSchemaSql();
+        assertTrue(schema.contains(FOLLOW_UP_TABLE),
+                "[butler.resource.match] schema.sql 缺少 butler_resource_follow_up 回访沉淀偏好表"
+                        + ":参与后回访记录写入家长档案,后续推荐参考偏好(TC-H-05 AC4)。不存在则实现未落地。");
+    }
+
+    // ------------------------------------------------------------------
+    // 权限流(TC-H-05-P):语义载体说明
+    // ------------------------------------------------------------------
+
+    @Test
+    @DisplayName("权限流:未审核无投放权/非本家庭资源/他人预约 三 403 语义由既有门禁载体承载")
+    void permissionFlow_403SemanticsCarriedByExistingGuards() {
+        // 说明性用例(与已合入同批 RED 风格一致):
+        // ① 服务商推送未审核资源给家长 → 403:由「仅已审核资源入候选」(正常流-5 审核门禁字段)
+        //    + 管理侧审核端点 403 门禁(AdminPlannerOfflineCourseController / admin.activity 的
+        //    AdminRoles.BACKEND_ROLES 校验)承载;
+        // ② 管家推荐非本家庭资源 → 403:待 GREEN 阶段在 match/book 端点对请求方 userId 归属
+        //    (butler_assignments 一家一管家)+ FamilyAccessInterceptor 校验;
+        // ③ 家长修改他人预约 → 403:已有活动报名数据隔离(ActivityRegistrationService 按
+        //    userId/memberId 归属查询,他人 registrationId 不可见)。
+        // 本用例不产生断言失败;仅为三流覆盖标注「权限流语义及其载体」。
+        assertTrue(true, "权限流:403 语义由上述既有门禁 + GREEN 阶段 match/book 端点归属校验承载。");
+    }
+
+    // ------------------------------------------------------------------
+    // 反射辅助
+    // ------------------------------------------------------------------
+
+    private Class<?> loadClass(String name) {
+        try {
+            return Class.forName(name, false, Thread.currentThread().getContextClassLoader());
+        } catch (ClassNotFoundException e) {
+            return null;
+        }
+    }
+
+    private boolean hasMethod(Class<?> clazz, String methodName) {
+        for (Method m : clazz.getDeclaredMethods()) {
+            if (m.getName().equals(methodName)) {
+                return true;
+            }
+        }
+        return false;
+    }
+
+    private boolean hasField(Class<?> clazz, String fieldName) {
+        for (Field f : clazz.getDeclaredFields()) {
+            if (f.getName().equals(fieldName)) {
+                return true;
+            }
+        }
+        return false;
+    }
+
+    /** 探测类中是否存在含指定路径片段的 @PostMapping 端点(契约统一 POST) */
+    private boolean hasPostMapping(Class<?> clazz, String pathFragment) {
+        for (Method m : clazz.getDeclaredMethods()) {
+            PostMapping pm = m.getAnnotation(PostMapping.class);
+            if (pm != null) {
+                for (String value : pm.value()) {
+                    if (value.contains(pathFragment)) {
+                        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 "";
+        }
+    }
+}

+ 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 "";
+        }
+    }
+}

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

@@ -0,0 +1,243 @@
+package com.etotem.cfc.unit;
+
+import com.etotem.cfc.controller.DanAssessmentController;
+import com.etotem.cfc.entity.AssessmentMaterial;
+import com.etotem.cfc.service.AssessmentService;
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Test;
+
+import java.io.InputStream;
+import java.lang.reflect.Method;
+import java.lang.reflect.Field;
+import java.nio.charset.StandardCharsets;
+import java.util.Arrays;
+import java.util.HashSet;
+import java.util.List;
+import java.util.Scanner;
+import java.util.Set;
+
+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 assessment.type.browse},任务 S-cfc-273 / SC-P-31)。
+ *
+ * <p>契约来源:
+ * <ul>
+ *   <li>需求:{@code tests/user-scenarios/应用场景总览.md} SC-P-31 —— 浏览测评类型(DAN 8 类),
+ *       测评页列 DAN 8 类 <b>mind/wisdom/cognition/learning/behavior/career/campus/adolescent</b>,
+ *       <b>类目数据来自后端字典</b>;模块 {@code DanAssessmentController}。</li>
+ *   <li>用例:{@code tests/test-cases/parent.md} TC-P-31 —— 进入测评页 → 列完整 8 类;断言「类目来自后端字典」。</li>
+ *   <li>设计:{@code docs/superpowers/api/API_REFERENCE.md} §4.63.4 —— `DanAssessmentController`
+ *       {@code /api/dan-assessment/*}(/material/active、/material/list 为「测评材料=类型载体」,/points-config、/family/config);</li>
+ *   <li>设计:{@code docs/superpowers/specs/2026-11-07-parent-rest-contract.md} §3 —— 建议能力键
+ *       {@code dan.assessment.typeList} 映射 {@code DanAssessmentController /material/list、/material/active、/points-config}。</li>
+ * </ul>
+ *
+ * <p><b>实现现状(本分支 src/main 核实)</b>:DAN 8 类字典常量仅散见 {@code DanReportUpload}(DIM_*)与上传校验
+ * ({@code DanReportUploadService} 的 dimension 白名单),但:
+ * <ol>
+ *   <li>{@code AssessmentService} 无「枚举 8 类类型」的浏览入口方法(现仅有 getActiveMaterial / getMaterialList 返回材料实体);</li>
+ *   <li>{@code AssessmentMaterial} 实体及 {@code assessment_materials} 表<b>无 {@code dimension/type} 类型码字段</b>,
+ *       无法承载「材料=类型载体」的设计,前端拿不到后端字典中的类型码;</li>
+ *   <li>{@code DanAssessmentController} 无返回类型字典/类型列表的 POST 端点(/material/list 仅返回材料,不映射 8 类字典)。</li>
+ * </ol>
+ * 因此「测评页列出完整 8 类、类目来自后端字典」的契约未落地。
+ *
+ * <p><b>RED 预期</b>:本批为 TDD-RED 阶段,断言契约所需能力缺失——四个用例应<b>失败(红)</b>;
+ * GREEN 阶段按失败断言补实现(service 类型浏览方法 + 实体/表类型码字段 + 控制器 POST 端点)后转绿。</p>
+ *
+ * <p>测试隔离:纯反射 / classpath 资源断言,无 Spring / 无 DB / 无外部服务(对齐 TeamProfitHookContractTest 等既有 RED 契约风格)。</p>
+ */
+class DanAssessmentTypeBrowseContractTest {
+
+    /** SC-P-31 / TC-P-31 契约要求的完整 8 类(取自 DanAssessmentResultDTO dimension 注释:mind(心-A2)/wisdom(智-B4)/.../adolescent(B5)) */
+    private static final List<String> DAN_TYPES = Arrays.asList(
+            "mind", "wisdom", "cognition", "learning", "behavior", "career", "campus", "adolescent"
+    );
+
+    // ------------------------------------------------------------------
+    // 正常流:后端应提供「枚举 DAN 8 类」的浏览能力(类目来自后端字典)
+    // ------------------------------------------------------------------
+
+    @Test
+    @DisplayName("正常流-1:AssessmentService 应提供类型浏览入口(列出 DAN 8 类)")
+    void service_hasTypeBrowseEntry() {
+        Class<?> serviceClass = AssessmentService.class;
+        Method browse = null;
+        for (Method m : serviceClass.getDeclaredMethods()) {
+            String name = m.getName().toLowerCase();
+            // 契约入口命名候选:listTypes / listAssessmentTypes / getAssessmentTypes(返回类型键集合)
+            if ((name.contains("listtypes") || name.contains("assessmenttypes") || name.contains("typelist"))
+                    && m.getParameterCount() == 0) {
+                browse = m;
+                break;
+            }
+        }
+        assertNotNull(browse,
+                "[assessment.type.browse] AssessmentService 缺少类型浏览入口(listTypes/listAssessmentTypes/getAssessmentTypes):"
+                        + "契约要求后端字典可枚举 DAN 8 类(mind/wisdom/cognition/learning/behavior/career/campus/adolescent)供测评页展示(TC-P-31)。");
+    }
+
+    @Test
+    @DisplayName("正常流-2:类型浏览入口应返回完整 8 类(含 mind/adolescent 等全部字典键)")
+    void typeBrowseEntry_coversAllEightTypes() throws Exception {
+        Method browse = null;
+        boolean[] found = {false};
+        for (Method m : AssessmentService.class.getDeclaredMethods()) {
+            String name = m.getName().toLowerCase();
+            if ((name.contains("listtypes") || name.contains("assessmenttypes") || name.contains("typelist"))
+                    && m.getParameterCount() == 0) {
+                browse = m;
+                found[0] = true;
+                break;
+            }
+        }
+        if (!found[0]) {
+            fail("[assessment.type.browse] 类型浏览入口缺失,无法验证 8 类完整性(契约要求:完整 8 类且类目来自后端字典)。");
+        }
+        // 反射探测返回值类型应为集合/数组(承载 8 类字典键)
+        Class<?> ret = browse.getReturnType();
+        boolean isCollectionish = java.util.Collection.class.isAssignableFrom(ret)
+                || ret.isArray() || java.util.Map.class.isAssignableFrom(ret) || ret.isEnum();
+        assertTrue(isCollectionish,
+                "[assessment.type.browse] 类型浏览入口应返回集合/数组(8 类键),当前返回类型为 " + ret.getName());
+    }
+
+    // ------------------------------------------------------------------
+    // 正常流:材料应作为类型载体(设计:/material/list、/material/active = 类型载体)
+    // ------------------------------------------------------------------
+
+    @Test
+    @DisplayName("正常流-3:AssessmentMaterial 应承载类型码字段(dimension 或 typeCode)")
+    void materialEntity_carriesTypeCode() {
+        boolean hasTypeField = false;
+        for (Field f : AssessmentMaterial.class.getDeclaredFields()) {
+            String n = f.getName().toLowerCase();
+            if (n.equals("dimension") || n.equals("typecode") || n.equals("type")) {
+                hasTypeField = true;
+                break;
+            }
+        }
+        assertTrue(hasTypeField,
+                "[assessment.type.browse] AssessmentMaterial 实体缺少类型码字段(dimension/typeCode/type):"
+                        + "设计规定 /material/list 为「类型载体」,材料无类型码则前端无法经后端字典渲染 8 类(SC-P-31)。");
+    }
+
+    @Test
+    @DisplayName("正常流-4:assessment_materials 表应含类型码列(schema.sql 同步)")
+    void schemaSql_materialTableHasTypeColumn() {
+        String schema = readSchemaSql();
+        assertTrue(schema.contains("CREATE TABLE IF NOT EXISTS assessment_materials"),
+                "[assessment.type.browse] schema.sql 缺少 assessment_materials 建表。");
+        // 提取 assessment_materials 建表段检查类型列
+        int start = schema.indexOf("assessment_materials");
+        int end = schema.indexOf("ENGINE=InnoDB", start);
+        String ddl = end > start ? schema.substring(start, end) : schema.substring(start);
+        boolean hasDimensionCol = ddl.contains("dimension");
+        boolean hasTypeCodeCol = ddl.contains("type_code") || ddl.contains("typeCode");
+        assertTrue(hasDimensionCol || hasTypeCodeCol,
+                "[assessment.type.browse] assessment_materials 建表缺类型码列(dimension/type_code):"
+                        + "材料作为类型载体(API_REFERENCE §4.63.4)的表承载缺失,类目无法落库/查询(SC-P-31)。");
+    }
+
+    // ------------------------------------------------------------------
+    // 正常流:控制器应暴露类型浏览 POST 端点(统一 @PostMapping)
+    // ------------------------------------------------------------------
+
+    @Test
+    @DisplayName("正常流-5:DanAssessmentController 应暴露类型浏览 POST 端点")
+    void controller_exposesTypeBrowseEndpoint() {
+        boolean hasEndpoint = false;
+        String found = "";
+        for (Method m : DanAssessmentController.class.getDeclaredMethods()) {
+            String name = m.getName().toLowerCase();
+            if ((name.contains("typelist") || name.contains("listtypes") || name.contains("assessmenttypes")
+                    || name.contains("materialtypes") || name.contains("gettypes"))
+                    && m.isAnnotationPresent(org.springframework.web.bind.annotation.PostMapping.class)) {
+                hasEndpoint = true;
+                found = m.getName();
+                break;
+            }
+        }
+        assertTrue(hasEndpoint,
+                "[assessment.type.browse] DanAssessmentController 缺少类型浏览 POST 端点(如 /material/types、/types,@PostMapping):"
+                        + "测评页需在此拉取后端字典 8 类(TC-P-31 流程:测评页 → 列 DAN 8 类)。");
+    }
+
+    // ------------------------------------------------------------------
+    // 边界流:字典键应恰为 8 类全量集合
+    // ------------------------------------------------------------------
+
+    @Test
+    @DisplayName("边界流-1:后端字典常量应覆盖契约 8 类全量")
+    void typeDictionary_coversAllEightTypes() {
+        // 字典半成品:DanReportUpload.DIM_* 常量(后端字典基线,GREEN 部分)
+        Class<?> uploadClass = loadClass("com.etotem.cfc.entity.DanReportUpload");
+        if (uploadClass == null) {
+            fail("[assessment.type.browse] DanReportUpload 不存在(类型字典基线缺失)。");
+        }
+        Set<String> actual = new HashSet<>();
+        for (Field f : uploadClass.getDeclaredFields()) {
+            if (f.getName().startsWith("DIM_") && f.getType() == String.class) {
+                try {
+                    f.setAccessible(true);
+                    actual.add((String) f.get(null));
+                } catch (IllegalAccessException ignored) {
+                    // 忽略
+                }
+            }
+        }
+        // 字典应与契约 8 类一致(当前实现覆盖 8 类,此断言期望通过;缺口在「浏览入口/承载」而非字典本身)
+        assertTrue(actual.containsAll(DAN_TYPES),
+                "[assessment.type.browse] 后端类型字典(DanReportUpload.DIM_*)未覆盖契约 8 类全量,缺:" + diff(DAN_TYPES, actual));
+    }
+
+    // ------------------------------------------------------------------
+    // 权限流:类型浏览为公开目录能力(无需家庭级权限)——说明性用例
+    // ------------------------------------------------------------------
+
+    @Test
+    @DisplayName("权限流:类型浏览为公开目录能力,无家庭级权限维度(说明性)")
+    void permissionFlow_notApplicable() {
+        // SC-P-31 边界仅规定「类目数据来自后端字典」,无家庭/角色数据隔离要求;
+        // 类型目录为全站公开字典,权限流不适用。不产生失败断言。
+        assertTrue(true, "权限流不适用:assessment.type.browse 为公开类型目录浏览,无家庭级权限维度。");
+    }
+
+    // ------------------------------------------------------------------
+    // 辅助
+    // ------------------------------------------------------------------
+
+    private static Class<?> loadClass(String name) {
+        try {
+            return Class.forName(name, false, Thread.currentThread().getContextClassLoader());
+        } catch (ClassNotFoundException e) {
+            return null;
+        }
+    }
+
+    private static String diff(List<String> expected, Set<String> actual) {
+        List<String> missing = new java.util.ArrayList<>();
+        for (String t : expected) {
+            if (!actual.contains(t)) missing.add(t);
+        }
+        return missing.toString();
+    }
+
+    private static String readSchemaSql() {
+        try (InputStream is = DanAssessmentTypeBrowseContractTest.class.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 "";
+        }
+    }
+}

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

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

+ 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;
+    }
+}

+ 75 - 0
docs/tdd/automation-run-2026-11-14-R197.md

@@ -0,0 +1,75 @@
+# 自动化执行日志 R197(2026-11-14 01:17 ~ 02:35,定时自动化闭环)
+
+> 角色:测试负责人(自动化测试闭环 / 软件测试专家团·陆谨)|全程静默无人值守。
+> 基线:`0a3e376d3`(R196 后)→ 收尾 rebase 至 `f4c31184d`;本轮提交见主报告 §0。
+> 窗口 `0a3e376d3..f4c31184d`:仅研发负责人 156 轮汇报文档(`f4c31184d`)——**零源码 / 零 SRS / 零用例变更**。
+
+## 一、节点探活
+
+| 节点 | 结果 |
+|---|---|
+| 189:4090(opencode) | ✅ 200(admin-desktop 派发成功) |
+| 251:4096(opencode) | ✅ 200(langgraph pytest 派发成功) |
+| 251:9000(langgraph live) | ❌ closed(B-196-5 延续,251 仅 :80/:4096 监听) |
+| 本机 4091(opencode) | ✅ 200 |
+| 本机 9082(cfc-backend) | ❌ closed(B-36 承袭,第 80 轮) |
+| cfc.iwintrue.com/admin、/frontend | ✅ 302 / 302(网关可达) |
+
+## 二、本轮实测(全部实跑,核心套件 0 采信)
+
+### 1. 后端全量(唯一权威口径:surefire XML 聚合)
+- `cd cfc-backend && JAVA_HOME=/d/jdk1.8.0_25 /d/maven/apache-maven-3.6.1/bin/mvn.cmd -o -B clean test` **54:22**
+- 聚合:**424 类 / 3745 例 / 3477 过 / 258F+6E / 4S = 92.84%**(红类 49 / 红例 264)
+- 编译:main 2125 + test 430 源,0 编译错误;424/424 XML 无沉默类
+- 红例三层归因:A 存量装置/数据 24(13 类,与 R196 零漂移第 29 次);B TDD 前瞻契约 240(36 类,研发已声明 RED,与 R196 完全一致);C 环境 0
+- 口径升级:R196 定向补测 `TeacherAppointmentNoShowBehaviorContractTest`(8 例)本轮并入全量基线
+
+### 2. 浏览器 E2E(每节点单任务,串行)
+- 189 `admin-desktop`:首轮 **2F/3P** → 复验 **5/5 EXIT=0(1.2m)**(TC-A-U04/U05 前置 account-roles 接口非 200,B-197-2 新增·疑似 B-120 偶发)
+- 本机 `frontend-mobile`:**6/6**(TC-F-U01~U06)
+- 本机 `shop-api`:**4/4(13.7s)**
+- 本机 `health`:**13/13(17.5s)**(含 huawei/xiaomi 全端点 401)
+- `dx-bridge`:**2 skip**(404,B-DX-1 第 36 轮)
+- **浏览器全量:28 过 + 2 跳,零产品缺陷**
+
+### 3. Jest 三套
+- cfc-web:**17 套件 / 116/116(225.6s)** 零漂移
+- cfc-frontend:**624 = 609 过 / 3 红 / 12 跳**(3 红全预期 RED:AC-R1/R2/AC-2,S-cfc-132/133)
+- 根级黑盒:**23 = 7 过 / 16 红(20.3s)**(全 `ECONNREFUSED 9082`,B-36 第 80 轮)
+
+### 4. 线上 API
+- 点名 4 文件(api-smoke / nonfunc-security / nonfunc-perf-compat / traceability):**32 例 = 25 过 / 0 红 / 7 跳(16.0s)**
+- **全量 990 例:172 过 / 23 红 / 795 跳 / 0 未跑(18.5m)——首次完跑(56 未跑→0)**
+  - 23 红归因:服务端校验缺失 15(badge 4 / task-checkin 3 / task-create 2 / task-c14 2 / coach-food 2 / energy-sc 1 / incentive-loop 1)、语义/状态 5、服务端异常 2、参数格式 1
+  - 与 R196 对照:域集合基本一致,净 +1(badge 1~2→4,butler-fallback 2 消失)→ **无新增确定性回归**
+
+### 5. langgraph@251(派发 251 节点)
+- 派发:`dispatch_251_pytest.cjs kick`,`.venv/bin/python -m pytest -q --ignore=tests/qna --ignore=tests/test_chat.py`
+- 结果:**10 failed / 41 passed / 148.89s**(analyze 1 + auto_tag 5 + intent 4,与 R196 逐例一致)
+- 归因:429 AgnesAI 配额 + 401 key `****ab12` invalid → 环境红非回归(B-196-2 延续)
+- B-177-1 第 19 轮复现:summary 已打印但 EXIT= 未落盘 → `_r195_cleanup_251.cjs` kill 后清理
+
+### 6. 线上黑盒(HTTP 直采)
+- `/admin` `/frontend` `/`:**302 / 302 / 404**
+- 匿名 6 端点(mind/energy/health-plan/xiaomi-health/huawei-health/admin-families):**6/6 = 401**(G8 ✅,B-142-1 销号维持第 25 轮)
+- dx 两端点:404/404(2 skip)
+
+## 三、SRS / 场景变更(G12)
+- `docs/superpowers/specs/`、`tests/test-cases/`、`tests/user-scenarios/`、API_REFERENCE 窗口**零提交** → **无需更新测试用例**(G12 ✅)
+- 口径升级:R196 定向补测 8 例并入后端全量基线(424 类 / 3745 例)
+
+## 四、门禁结论
+**⛔ 不通过(承袭·有条件)** —— 无新增确定性回归。
+✅ G3 浏览器 28+2 跳 / G4 编译 0 错 / G5 XML 424/424 / G6 EXIT=0 / G8 6/6=401 / G10 四节点 / G12 窗口零变更 / G13 存量零漂移**第 29 次**;
+❌ G1 **93.37%**(剔跳 4450/4766)/ G2 **316 红**(后端 264 + API 23 + 根级 16 + fe 3 + lg 10)/ G7 41/51 / G9 20.8% / G11 漏拦 42 陈旧 26 / G14 72.6%。
+
+**变化对比(R196→R197)**:API 全量**首次完跑(0 未跑)**、过 +55、剔跳过率 93.29%→**93.37%**、后端红 265→**264**(装置浮动 −1)→ **无新增确定性回归**。
+
+## 五、未实测项(如实标注)
+- 压测/SAST/DAST(未授权联网);JaCoCo/PIT(未配置);多浏览器/无障碍/UAT-BDD(无资产);204 节点(B-95);langgraph 链路面(251 无 9000 服务,B-196-5);全项目逐行代码审查(窗口零源码变更,抽样复核红类名单与 API 失败上下文)。
+
+## 六、产出文件
+- `docs/tdd/orchestration/report-test-2026-11-14-R197.md`(主报告)
+- `docs/tdd/automation-run-2026-11-14-R197.md`(本日志)
+- `docs/tdd/notice-2026-11-14-R197-研发通知.md`(研发通知)
+- `docs/tdd/test/blockers.md`(R197 段)

+ 50 - 0
docs/tdd/notice-2026-11-14-R197-研发通知.md

@@ -0,0 +1,50 @@
+# 研发通知 R197(2026-11-14 02:35 · 测试负责人自动化闭环)
+
+> 来源:定时自动化「测试负责人闭环(全用例覆盖 + SRS/场景变更同步 + 浏览器 E2E + langgraph 分派 251)」
+> 基线:`0a3e376d3` → `f4c31184d`|结论:**不通过(有条件)** —— 无新增确定性回归,但有 3 项 P0 待处理
+
+## 一、需要研发立即处理(P0)
+
+### 1. 线上 API 全量 23 红:服务端校验缺失是主因(B-197-1,B-196-6 延续)
+
+| 归因 | 例数 | 涉及域 | 处置建议 |
+|---|---|---|---|
+| 服务端校验缺失(期望拒绝实得 200) | **15** | badge 4(缺 name 仍创建 / 非管理员创建 / 删除不存在勋章)、task-checkin 3、task-create 2、task-c14 2、coach-food 2、energy-sc 1、incentive-loop 1 | **交研发补齐服务端校验**(name 必填、admin 角色守卫、幂等收敛)后转绿 |
+| 语义/状态不符 | 5 | 并发兑换仅 1 成功、至少选一提醒渠道、请设置所需积分、id 不能为空、申请兑换失败 | **请确认是契约缺失还是用例预期错** |
+| 服务端异常 | 2 | `服务器内部错误`(500)、`energy/list: undefined` | 逐条查服务端堆栈 |
+| 参数格式 | 1 | `update: 请求参数格式错误`(JSON 结构) | 核对用例入参 |
+
+**本轮首次完跑**(990 例 / 172 过 / 23 红 / 795 跳 / **0 未跑**,18.5m)——全量套件已可信化一半;红例 error-context 留存 `_r197/api_full/`(23 份)。
+复现:`cd tests && npx playwright test -c playwright.config.api.js --project=desktop --reporter=list --workers=1`
+
+### 2. langgraph 上游配额/key(P0,连续多轮,B-196-2 延续)
+
+- 51 例 **41 过 / 10 红**(analyze 1 / auto_tag 5 / intent 4),与 R196 逐例一致;日志实证 **429(AgnesAI 配额)+ 401(key `****ab12` invalid)**;cfc-langgraph 源码零变更。
+- 需运维轮换 key / 升配额;测试侧建议「录音回放档」把上游可用性与本服务逻辑解耦。
+
+### 3. `cancelAppointment` 越权仍未修(F1,长期 P0)
+
+- 位置:`AssessmentAppointmentController.cancelAppointment(@PathVariable Long id)`。
+- 现象:任意登录用户凭 id 可取消他人预约(无 `userId` / 归属校验);本轮窗口零源码变更 → 未修确认。
+- 修法:加 `@RequestAttribute("userId") Long userId`,service 校验 `userId ∈ {预约 userId, guideId, assessorId}`;补归属校验测试复测拒绝即闭环(台账 TC-DV-01)。
+
+## 二、需要研发配合(P1)
+
+1. **CI 排除清单已严重滞后**(B-196-1 第 2 轮):`.gitlab-ci.yml:61` 清单 33 类 vs 本轮实测 **49 红类** → **漏拦 42 类**、**陈旧 26 类**(未修)。建议清单改「本轮实测快照 + 差集守卫」。
+2. **240 个 TDD 前瞻契约红**待分批使绿(每批 ≤30),当前拉低 G1 至 92.84%(后端)。
+3. **存量 13 类 24 红**:EnergySystemFlow 6F、DimensionRegistryMapContract 3F、GrowthPublicEndpointMapping 5E、TaskReviewScP11 1F(装置浮动 −1)、Orchestration×2、MembershipPaySwitch、PaymentServiceORD、UserServiceWechatLogin×2、GuideModuleIntegration、TeamProfitCron、MembershipPlanPurchase。
+4. **JaCoCo 未接入** → 覆盖率不可度量(G9 锚点率 20.8% 代理)。
+
+## 三、本轮正向(无产品回归)
+
+- 浏览器 **28 过 + 2 跳**(189 admin 首轮 2F 偶发 → 复验 5/5 全绿,B-197-2 观察期);cfc-web 116/116;cfc-frontend 609/3/12(3 全预期 RED,零漂移)。
+- **后端全量口径补齐**:R196 定向补测 8 例(TeacherAppointmentNoShowBehaviorContractTest)纳入全量基线 → 424 类 / 3745 例,消除账目差。
+- API 全量**首次完跑(0 未跑)**、过 +55、剔跳过率 93.29%→**93.37%**;后端红 265→264(装置浮动)。
+- 存量零漂移连续 **第 29 轮**。
+
+## 四、测试侧已知问题(供知悉,不需研发处理)
+
+- 根级黑盒 16 红:本机 9082 未启(B-36 第 80 轮)。
+- dx 两端点 404:规格明示「仅登记不实现」(B-DX-1 第 36 轮)。
+- 251 无 langgraph HTTP 服务(仅 :80/:4096),链路面未实测(B-196-5)。
+- 251 pytest 打印 summary 后进程不退出(B-177-1 第 19 轮),已 `_r195_cleanup_251.cjs` kill 清理;建议 `app/main.py:84` 补 `await client.aclose()`。

+ 317 - 0
docs/tdd/orchestration/report-test-2026-11-14-R197.md

@@ -0,0 +1,317 @@
+# 测试负责人工作汇报 R197(2026-11-14 01:17 ~ 02:2x · 定时自动化闭环)
+
+> 测试负责人:陆谨(软件测试专家团)|执行档:**review(离线)** + 内网浏览器 E2E|静默无人值守(未提任何问题)
+> 基线:`0a3e376d3`(R196 后)→ 收尾 rebase 至 **`f4c31184d`**(远端窗口含研发 156 轮汇报 + S-cfc-193/248 新契约测试,见 R198 段)|本轮提交 **见 git log(R197 收尾提交)**
+> 本轮实跑:后端全量 **424 类 / 3745 例**(54:22)· 浏览器 **28 过 + 2 跳** · Jest 三套 · 线上 API(点名 + 全量)· langgraph@251
+
+---
+
+## 1. 执行总览
+
+| 套件 | R197(本轮实测) | R196 | 漂移 |
+|---|---|---|---|
+| 后端全量(`cd cfc-backend` + mvn 3.6.1 `-o -B clean test`) | **3745 run / 3477 过 / 258F+6E / 4 跳 = 92.84%**(424 类,54:22) | 3737 / 3468 / 92.80%(423 类,51:42) | **+8 例 / +9 过 / +0.04pp**,红 265→264 |
+| └ 口径说明 | 上轮定向补测 `TeacherAppointmentNoShowBehaviorContractTest`(8 例)**本轮纳入全量**(+1 类) | 补测 8 例单列 | 口径升级 |
+| 浏览器 E2E | **28 过 + 2 跳**(189 admin 5/5 **复验**、本机 fe 6/6、shop 4/4、health 13/13、dx 2 跳) | 28 + 2 跳 | 持平(189 首轮 2F 偶发→复验绿,见 B-197-2) |
+| cfc-web Jest | **116/116**(17 套件,225.6s) | 116/116 | 零漂移 |
+| cfc-frontend Jest | **624 = 609 过 / 3 红 / 12 跳** | 同 | 零漂移 |
+| 根级黑盒 | **23 = 7 过 / 16 红**(全 `ECONNREFUSED 9082`) | 7/16 | 零漂移(B-36 第 80 轮) |
+| langgraph@251 | **51 = 41 过 / 10 红**(148.89s) | 41/51(10 红,117.54s) | 红例集合逐例一致(环境红) |
+| 线上 API(点名 4 文件 32 例) | 32 = **25 过 / 0 红 / 7 跳**(16.0s) | 25/0/7 | 持平 |
+| 线上 API(**全量 990 例**,含 generated) | **172 过 / 23 红 / 795 跳 / 0 未跑**(18.5m) | 118/22/794/56未跑 | **过 +54、红 +1、未跑→0(本轮完跑)** |
+
+**全站合计(含 API 全量)**:**5579 例 / 4450 过 / 316 红 / 809 跳 = 79.76%**
+**剔 skip 口径:4450 / 4766 = 93.37%**(较 R196 的 93.29% **+0.08pp**)
+**变化**:例 5579 持平、过 +55、红 316 持平(后端 −1 + API +1)、跳 −59(56 未跑→0)→ **无新增确定性回归**;API 全量首次「完跑」(0 未跑)。
+
+---
+
+## 2. 项目画像(本轮视角)
+
+- **业务**:家庭教育 SaaS —— 微信小程序(家长/孩子/规划师三端)+ Web 管理端 + 独立商城 + Python LangGraph AI 服务。
+- **技术栈**:Spring Boot 2.7.18 / MyBatis-Plus / Java 8(`cfc-backend`,9082)· uni-app Vue2(`cfc-frontend`)· Vue2+Element(`cfc-web`,8082)· FastAPI+LangGraph(`cfc-langgraph`,9000)· 商城 `dan/danshop`(8888)。
+- **关键路径**:登录鉴权(JWT/微信)→ 家庭与成员 → 五维能量 → 任务/打卡 → 健康报告上传解析(9000 依赖)→ 测评预约/订单/规划师录入 → 商城订单履约。
+- **本轮窗口变更(1 提交)**:仅 `f4c31184d`(研发负责人 156 轮汇报文档)——**零源码 / 零 SRS / 零用例变更**。
+- **质量目标(门禁)**:全量通过率 ≥95%、红例 0、浏览器全绿、langgraph ≥50/51、SRS 变更必须同步用例、CI 不得常红。
+- **风险点**:36 个 TDD 前瞻契约类(240 红)拉低 G1;CI 排除清单严重滞后(B-196-1);langgraph 上游 LLM 配额(429/401);`cancelAppointment` 越权未修(F1)。
+
+---
+
+## 3. 历史审查记录(跨轮对照,仅作参照,结论重新取证)
+
+| 项 | 内容 |
+|---|---|
+| 上次审查 | **R196**(2026-11-14 01:30,判「不通过·有条件」) |
+| 遗留缺口 | ① langgraph 429/401 环境红(P0);② 36 前瞻契约类 240 红待使绿;③ CI 清单漏拦 42/陈旧 26(G11);④ 存量 13 类装置红;⑤ B-36 根级 16 红;⑥ 锚点率 20.8%(G9);⑦ API 全量 22 红待分流(B-196-6) |
+| 本轮改善 | API 全量 0 未跑(完跑)、过 +55、后端红 −1、后端全量口径补齐(补测 8 例纳入) |
+| 仍然未解 | 上游配额、CI 清单、存量 13 类、B-36、锚点率、cancelAppointment 越权 |
+| 新发现 | **B-197-1 / B-197-2**(见 §7) |
+
+> 本轮为该对象**第 197 次**审查(非首次),历史结论仅作对照,未直接沿用。
+
+---
+
+## 4. 执行明细
+
+### 4.1 后端全量(唯一权威口径:surefire XML 聚合)
+
+```
+cd cfc-backend && JAVA_HOME=D:\jdk1.8.0_25 mvn -o -B clean test      → Total time 54:22(R196 51:42,+2:40)
+聚合:classes=424  tests=3745  pass=3477  F=258  E=6  S=4  rate=92.84%  red_classes=49  red_cases=264
+编译:main 2125 + test 430 源,0 编译错误;424/424 XML 无沉默类;dump 0
+```
+
+**红例三层归因(264)**
+
+| 层级 | 例数 | 类数 | 说明 |
+|---|---|---|---|
+| A 存量装置/数据 | **24** | 13 | EnergySystemFlow 6F、GrowthPublicEndpointMapping 5E、DimensionRegistryMap 3F、UserServiceWechatLogin 2F(×2 类)、TaskReviewScP11 **1F(B-178-1 装置浮动 2→1)**、OrchestrationEngine/Integration 各 1F、MembershipPaySwitch 1F、PaymentServiceORD 1F、GuideModuleIntegration 1E、TeamProfitCron 1F、MembershipPlanPurchase 1F → **与 R196 逐类一致(零漂移第 29 次,除装置浮动 −1 例)** |
+| B TDD 前瞻契约(研发已声明 RED) | **240** | 36 | CoachProactive 24、SupplierManageAdmin 16、ChildMindCapture 15、DimensionConfigAdmin 13、SupplierNutritionSupply 13、AdminSupplierManage 10、MindModelManage 10、ChildFeedbackSubmit 9、ChildEnergyGain/AdminDataMigration 各 8、AdminUserGovern/ChildAiChat 各 7、EnergySystemFlow 非红、AdminArticleManage/ChildAuthLogin/ChildNotificationReceive/SupplierInventoryManage 各 6、GrowthPublic 非红、AdminOrderManual/AdminActivityConfig/AdminBadgeManage/AdminSystemMonitor/AICoachConsult/ChildShopPointsExchange/SupplierActivityAttend/SupplierExportCompliance/TaskCheckinChild 各 5、ChildGameReportScore/PlanContentSafetyReview/SupplierAfterSalesHandle/TeacherPlanCreate 各 4、ChildGrowthArchive/ChildDietViewMenu/ChildEnergyView 各 3、ChildGrowthArchiveExport/TeacherFamilyBind 各 2、PlanActivationScT05/TeacherDataIsolationScT13 各 1 → **与 R196 完全一致(240 例 / 36 类)** |
+| C 环境/其余 | 0 | 0 | 本轮无 ApplicationContext / JDBC 类环境红(`env_red_cases=0`) |
+
+**慢类 Top(B-191-2 观察,第 4 轮)**:UserServiceFamilyNameLink、GuidePackageService、GrowthPublicEndpointMapping、ActivityController、AIChatController、ProductController、DimensionAdminController、GuideRolePermission;54:22 总耗时中 `cfc-scheduler` 日志占比高(`@SpringBootTest` × 34 次上下文 + 每次 `DatabaseInitializer` 全量迁移)。
+
+### 4.2 浏览器 E2E(每节点单任务,串行)
+
+| 节点 | 项目 | 结果 | 证据 |
+|---|---|---|---|
+| **189**(`192.168.16.189:4090`) | admin-desktop | 首轮 **2F/3P** → **复验 5/5 通过(1.2m)** | 首轮失败:TC-A-U04/U05 `account-roles 接口非 200`(前置条件断言,B-197-2);复验全绿 → 节点/网络偶发非产品回归 |
+| **本机** | frontend-mobile | **6/6** | TC-F-U01~U06(游客浏览/导航/鉴权引导/资源) |
+| **本机** | shop-api | **4/4(13.7s)** | 价格排序 asc/desc/默认/白名单拦截 |
+| **本机** | health | **13/13(17.5s)** | 含 huawei-health/xiaomi-health 全端点 401 |
+| **本机** | dx-bridge | **2 跳过(404/404)** | 规格「仅登记不实现」→ 待派发(B-DX-1 第 36 轮) |
+| 合计 | — | **28 过 + 2 跳** | G6 ✅ |
+
+### 4.3 Jest 三套
+
+- `cfc-web`:**17 套件 / 116 例全绿**(225.6s)
+- `cfc-frontend`:**42 套件 / 624 例 = 609 过 / 12 跳 / 3 红**(3 红 = `AC-R1`、`AC-R2`、`AC-2 RED-A7`,S-cfc-132/133 预期 RED)→ 零漂移
+- 根级:`npx jest -c tests/jest.config.js` → **23 例 = 7 过 / 16 红**(20.3s,全 `ECONNREFUSED 127.0.0.1:9082`,本机后端未起,B-36 第 80 轮)
+
+### 4.4 线上 API
+
+- **点名 4 文件(api-smoke / nonfunc-security / nonfunc-perf-compat / traceability-p94-p95-c26)**:`Running 32 tests` → **25 过 / 0 红 / 7 跳 / 16.0s**
+- **全量(`npx playwright test -c playwright.config.api.js --project=desktop`,含 `e2e/api/generated/tc-scripted.spec.js`)**:`Running 990 tests` → **172 过 / 23 红 / 795 跳 / 0 未跑 / 18.5m**(**本轮首次完跑,56 未跑→0**)
+  - **23 红归因**(`_r197/api_full/.last-run.json` 23 项 + error-context 逐例核对):
+    - **服务端校验缺失(期望拒绝实得 200,`expect(r.code).not.toBe(200)` 系)15 例**:badge 4(含「无效勋章缺名称被拒」「非管理员创建被拒」「删除不存在勋章被拒」)、task-checkin 3、wish-flow 部分、task-create 2、task-c14 2 等 → **契约缺陷,属 B-196-6 语义类延续,需研发确认契约**
+    - **语义/状态不符 5 例**:`并发兑换请求应有 1 个成功`、`至少选择一个提醒渠道`、`请设置所需积分`、`id 不能为空`、`申请兑换失败,请检查心愿状态` ×2(R196 同款,未修)
+    - **服务端异常 2 例**:`服务器内部错误`(500)、`energy/list: undefined`
+    - **数据/环境 1 例**:`update: 请求参数格式错误`(JSON 结构)
+  - 涉及规格:wish-flow 6、task-checkin 3、badge 4、task-create 2、task-c14 2、coach-food 2、energy-sc 1、incentive-loop 1、task-frequency 1、wechat-login 1
+  - **与 R196 对照**:域集合基本一致(wish-flow 6 / task-checkin 3 全同);**净 +1** = badge 域 1~2 → 4、但ler-fallback 2 消失;无全新域 → **无新增确定性回归**
+
+### 4.5 langgraph@251(分派 251 节点)
+
+- 派发:`dispatch_251_pytest.cjs kick`,`.venv/bin/python -m pytest -q --ignore=tests/qna --ignore=tests/test_chat.py`,节点 HEAD `f4c31184d`(与远端同步)
+- 结果:**10 failed / 41 passed / 148.89s**;红例 = `test_analyze::test_analyze_missing_report` 1 + `test_auto_tag` 5 + `test_intent` 4 —— **与 R196 逐例一致**
+- 归因:B-196-2 延续(429 AgnesAI 配额 + 401 key `****ab12` invalid),`cfc-langgraph` 源码零变更 → **环境红非回归**
+- **B-177-1 第 19 轮复现**:summary(`10 failed, 41 passed`)已打印但 `EXIT=` 未落盘 → `_r195_cleanup_251.cjs` kill 后复核进程计数 0
+
+### 4.6 线上黑盒(HTTP 直采)
+
+| 检查 | 结果 |
+|---|---|
+| `/admin` `/frontend` `/` | **302 / 302 / 404** |
+| 匿名 6 端点(mind/energy/health-plan/xiaomi-health/huawei-health/admin-families,按 R196 更正后的真实路径) | **6/6 = 401 `{"code":401,"message":"请先登录"}`**(G8 ✅,B-142-1 销号维持第 25 轮) |
+| dx 两端点 | 404/404(B-DX-1,2 跳) |
+| 节点探活 | `189:4090`=200 · `251:4096`=200 · `204:4091`=200 · **`251:9000`=closed**(B-196-5 延续) |
+
+---
+
+## 5. 20 类测试覆盖矩阵(三态,逐类给证据)
+
+| # | 测试类型 | 状态 | 证据 |
+|---|---|---|---|
+| 1 | 单元测试 | **已发现** | 424 类 / 3745 例(surefire 聚合),`unit/` 为主 |
+| 2 | 组件测试 | **已发现** | cfc-frontend 42 套件(含 AC-R1/R2 组件契约)、cfc-web 17 套件 |
+| 3 | 集成测试 | **已发现** | `EnergySystemFlowTest`、`OrchestrationEngine/IntegrationTest`、`GuideModuleIntegrationTest`、`DimensionRegistryMapContractTest` |
+| 4 | 接口(API)测试 | **已发现** | `tests/e2e/api/*.spec.js` 26 份;点名 32 例 0 红;**全量 990 例 = 172 过 / 23 红 / 795 跳 / 0 未跑(完跑)** |
+| 5 | 端到端(E2E) | **已发现** | `tests/e2e-live/`:admin-desktop 5、frontend-mobile 6、shop-api 4、dx 2、health 13 |
+| 6 | 冒烟测试 | **已发现** | `api-smoke.spec.js`(4 例,随 32 例套件全绿) |
+| 7 | 回归测试 | **已发现** | 本轮全站 5579 例回归;红例集合与 R196 逐类一致(后端零漂移、lg 逐例一致) |
+| 8 | 探索性测试 | **未发现** | 仓库无 charter/会话记录 → 覆盖缺口 G-196-1 延续 |
+| 9 | 验收 UAT / BDD | **未发现** | 无 `*.feature`、无 UAT 脚本 → G-196-2 延续 |
+| 10 | 性能测试 | **待核实** | `nonfunc-perf-compat.spec.js` 部分过/跳;压测需联网授权 → **未授权未执行** |
+| 11 | 可靠性测试 | **待核实** | 实证缺陷:B-177-1(第 19 轮)、B-197-2(189 account-roles 偶发);无故障注入资产 |
+| 12 | 安全测试 | **已发现** | `nonfunc-security.spec.js`;匿名 6 端点 401;**`cancelAppointment` 越权未修(F1)**;SAST/DAST 未授权 |
+| 13 | 兼容性测试 | **待核实** | 仅 chromium 单浏览器 → G-196-3 延续 |
+| 14 | 可用性测试 | **未发现** | 无真实用户可用性证据 |
+| 15 | 无障碍测试 | **未发现** | 无 axe/WCAG 断言 → G-196-4 延续 |
+| 16 | 覆盖率度量 | **待核实** | JaCoCo 未配置;仅 cfc-web 有历史 coverage ~9.95% |
+| 17 | 变异测试 | **未发现** | 无 PIT/pitest 依赖 → G-196-5 延续 |
+| 18 | 缺陷度量 | **已发现** | `docs/tdd/test/blockers.md`(追加 R197 段);本报告 §7 |
+| 19 | 测试流程(QA) | **已发现** | 本报告 + `automation-run-2026-11-14-R197.md` + 门禁表 + 双 fetch/复验纪律 |
+| 20 | 全项目代码审查 | **已发现(抽样)** | 本轮窗口零源码变更(仅文档),审查范围 = R196 全景的延续确认(红类名单/API 失败 error-context/匿名探针);**非全量逐行** |
+
+---
+
+## 6. SRS / 场景变更同步(本轮强制动作)
+
+**变更**:无。`docs/superpowers/specs/`、`tests/test-cases/`、`tests/user-scenarios/`、API_REFERENCE 窗口**零提交**(git 窗口 = 仅研发 156 轮汇报文档)。
+
+**同步动作**:不需要更新测试用例(G12 ✅)。
+**口径升级**:R196 定向补测的 `TeacherAppointmentNoShowBehaviorContractTest`(8 例,S-cfc-227 行为契约)本轮**纳入后端全量基线**(424 类 / 3745 例),消除「补测游离于全量」的账目差。
+
+---
+
+## 7. 问题清单(五要素,逐条)
+
+### P0-1|API 全量 23 红:服务端校验缺失是主因(B-197-1,B-196-6 延续)
+
+1. **问题描述**:990 例 → **172 过 / 23 红 / 795 跳 / 0 未跑**(完跑)。23 红中 **15 例为「期望拒绝(`not.toBe(200)`)实得 200」——服务端缺少必填/权限/状态校验**(badge 缺 name 仍创建成功、非管理员创建勋章被接受、删除不存在勋章成功、无效打卡参数被接受、重复任务创建非幂等等);5 例为语义/状态不符(并发兑换仅 1 成功、至少选一提醒渠道、请设置所需积分、id 不能为空、申请兑换失败);2 例服务端异常(500 / energy undefined);1 例参数格式。
+2. **测试 bug 点**:`tests/e2e/api/{badge-sc-c09-c10-a05,wish-flow-sc-p13-p14-c04,task-checkin-sc-c05,task-create-scp10,task-c14-reject-recycle,coach-food-sc-b07,energy-sc-p87-p88-c24,incentive-loop-sc-x05,task-frequency-sc-p12,wechat-login}.spec.js`;截图/上下文留存 `_r197/api_full/`(23 份 error-context)。
+3. **最优修改方案**:① badge 4 / task-checkin 3 / task-create 2 等「无效输入应被拒」用例,交研发补齐服务端校验(name 必填、admin 角色守卫、幂等收敛)后转绿;② 语义 5 例逐条交研发确认是「契约缺失」还是「用例预期错」;③ 生产环境 `direct-register` 造数不可用项改 SKIP+原因(本轮已随完跑不再产生 56 未跑,但造数型红仍应按 R196 P0-1 方案迁移测试环境)。
+4. **修改目的**:让 API 全量套件成为可信回归网(当前 23 红噪声会掩盖真实回归,与 G11 同类)。
+5. **闭环**:研发按上述分流答复后重跑全量,期望「红 = 0 或全部带 issue 号」;本轮完跑(0 未跑)已先达成「全量可信」的一半。
+
+### P0-2|langgraph 上游 LLM 配额/key 失效,10 例环境红(B-196-2 延续)
+
+1. **问题描述**:51 例中 10 红(analyze 1 / auto_tag 5 / intent 4),与 R196 逐例一致;日志实证 429(AgnesAI 配额)+ 401(key `****ab12` invalid);源码零变更。
+2. **测试 bug 点**:`cfc-langgraph/tests/test_auto_tag.py`(5)、`tests/test_intent.py`(4)、`tests/test_analyze.py::test_analyze_missing_report`(1)。
+3. **最优修改方案**:运维轮换/升级 LLM key 与配额;测试侧改双档(`QUOTA_OK=1` 断言真实输出,否则 VCR/mock 断言解析降级契约)。
+4. **修改目的**:解耦「上游可用性」与「本服务逻辑」,让 G7 只度量本服务质量。
+5. **闭环**:连续 2 轮 ≥50/51 且无 429/401 → 销号 B-195-1;mock 档全绿即闭环逻辑面。
+
+### P1-1|CI 后端排除清单严重滞后,流水线必红(B-196-1 第 2 轮)
+
+1. **问题描述**:`.gitlab-ci.yml:61` 清单 33 类 vs 本轮实测红类 **49** → 漏拦 42 / 陈旧 26(本轮红类名单与 R196 完全一致,未修)。
+2. **测试 bug 点**:`.gitlab-ci.yml:61`。
+3. **最优修改方案**:清单替换为本轮 49 类实测快照 + 加「红类↔清单自动差集」前置作业。
+4. **修改目的**:恢复 CI 回归拦截能力(当前 CI 红是噪声)。
+5. **闭环**:`backend-blocking-junit` 一次 BUILD SUCCESS;G11 差集双向为 0。
+
+### P1-2|`cancelAppointment` 越权未修(F1,长期 P0)
+
+同 R196 P1-3:controller 无调用者身份校验(`@PathVariable Long id` 直通),任意登录用户可取消他人预约。**本轮窗口零源码变更 → 未修确认**。台账 TC-DV-01 长期红;补 userId 归属校验后复测拒绝即闭环。
+
+### P1-3|189 admin 首轮偶发「account-roles 非 200」(B-197-2 新增·疑似 B-120 uly)
+
+1. **问题描述**:189 admin-desktop 首轮 **2F/3P**:TC-A-U04/U05 在登录流中 `account-roles 接口非 200` 前置断言失败;**同轮即刻复验 5/5 全绿(1.2m)**;189 节点 git `pull --ff-only` 失败但 HEAD `ec8ced27a` 与 R196 相同(本地分叉 dev 提交,非代码变化)→ 判定**节点/网络偶发非产品回归**(B-120 同型)。
+2. **测试 bug 点**:`tests/e2e-live/admin-live.spec.js:160/188`(前置 `expect(rolesStatus).toBe(200)`)——属前置环境探针,无产品缺陷证据。
+3. **最优修改方案**:给 189 登录前置增加「非 200 重试 1 次」或上游接口加 1s 重试窗口;排查 189 至 cfc.iwintrue.com 的网关瞬时抖动。
+4. **修改目的**:消除节点偶发对 G6 的误报(本轮已按 B-120 惯例复验闭环)。
+5. **闭环**:连续 2 轮 189 首轮即 5/5 → 销号观察;否则升级为节点网络 issue。
+
+### P2-1|根级黑盒 16 红(B-36 第 80 轮) / P2-2|dx 端点 404 2 跳(B-DX-1 第 36 轮) / P2-3|251 无 langgraph HTTP 服务(B-196-5)
+
+同 R196(P2-1/P2-2/P2-3):9082 本机未起(16 红环境性)、dx 规格「仅登记不实现」(2 跳正确)、251 仅 80/4096 监听(live 链路面未实测)。
+
+---
+
+## 8. 覆盖缺口清单
+
+| 编号 | 缺口类型 | 现状 | 风险 | 建议测试设计 | 优先级 | 闭环方式 |
+|---|---|---|---|---|---|---|
+| G-196-1~5 | 探索性/UAT-BDD/多浏览器/无障碍/变异 | 无资产(延续) | 未知缺陷发现能力弱 | 见 R196 建议设计 | P2 | 连续 2 轮有记录即闭环 |
+| G-196-6 | 覆盖率 | JaCoCo 未配置 | 覆盖率不可度量 | cfc-backend pom 加 jacoco-maven-plugin | P1 | 首份 `jacoco.xml` 产出即闭环 |
+| G-196-7 | 性能压测 | 未授权联网 | 容量未知 | 授权后 3 核心接口 50/100/200 并发阶梯 | P1 | 出基线报告即闭环 |
+| G-196-8 | 前瞻契约 240 红 | 研发已声明 RED | 拉低 G1 至 92.84% | 按类分批使绿(每批 ≤30 红) | P1 | 红例逐批降至 0 |
+| G-196-9 | 根级黑盒 16 红 | 9082 未起 | 黑盒链路无守护 | 本地常驻 cfc-backend 或 CI service | P2 | 16 红转绿即闭环 |
+| G-196-10 | dx 端点 404 | 规格「仅登记不实现」 | 2 例长期 skip | 端点实现后自动转断言 | P3 | 端点上线即闭环 |
+| G-197-1 | API 全量 23 红分流 | 校验缺失 15/语义 5/异常 2/格式 1 | 全量套件不可信 | 见 §7 P0-1(研发确认契约 + 造数改 SKIP) | **P0** | 红=0 或全带 issue 号 |
+| G-197-2 | 189 admin account-roles 偶发 | 首轮 2F / 复验 5/5 绿 | 误报 G6 | B-197-2 观察 + 前置重试 | P2 | 连续 2 轮首轮即绿销号 |
+
+---
+
+## 9. 门禁结论
+
+| 门禁 | 阈值 | 实测 | 判定 |
+|---|---|---|---|
+| G1 全量通过率 | ≥95% | **93.37%**(剔 skip 4766;含 skip 79.76%;剔预期 RED >99%) | ❌ |
+| G2 红例数 | 0 | **316**(后端 264 / API 23 / 根级 16 / fe 3 / lg 10) | ❌ |
+| G3 浏览器 E2E | 全绿 | **28 过 + 2 跳** | ✅ |
+| G4 编译 | 0 错 | main 2125 + test 430 源 0 错 | ✅ |
+| G5 surefire XML 完整 | 100% | **424/424**,无沉默类、dump 0 | ✅ |
+| G6 浏览器流水线 | 全通过 | 5 套件复验后全绿、189 EXIT=0 | ✅ |
+| G7 langgraph | ≥50/51 | **41/51**(环境红逐例一致) | ❌ |
+| G8 匿名端点鉴权 | 6/6=401 | **6/6=401**(真实路径复核第 25 轮) | ✅ |
+| G9 用例锚点率 | ≥60% | **180/865 = 20.8%**(本轮零用例变更) | ❌ |
+| G10 多节点可比 | ≥2 节点 | 189 + 本机 + 251 + 204 | ✅ |
+| G11 CI 清单一致 | 差集=0 | 漏拦 42 / 陈旧 26(B-196-1 未修) | ❌ |
+| G12 SRS 变更同步 | 变更即更新用例 | 窗口零变更;补测 8 例纳入全量口径 | ✅ |
+| G13 存量零漂移 | 逐类逐例一致 | 13 类除装置浮动 −1 外逐例一致(**第 29 次**) | ✅ |
+| G14 场景映射 | ≥90% | **156/215 = 72.6%** | ❌ |
+
+### ⛔ 门禁结论:**不通过(承袭·有条件)**
+
+- **无新增确定性回归**:后端 49 红类 / 264 红例与 R196 逐类一致(仅 TaskReviewScP11 装置浮动 −1);langgraph 10 红逐例一致(环境);API 全量 23 红全部归入 R196 已识别类别(校验缺失/语义/造数/网关,badge 等域为既有问题重测曝光,无全新域);浏览器 28+2 跳(189 偶发复验闭环)。
+- **正向变化**:API 全量**首次完跑(0 未跑)**、全站过 +55、剔跳过率 93.29%→93.37%、后端全量口径补齐(补测 8 例纳入)、红例总数 316 持平(后端 −1 / API +1)。
+- **放行建议**:可持续集成可继续推进;不建议据此宣布质量达标。复评门槛见 §10。
+
+---
+
+## 10. 复评门槛(优先级降序)
+
+| # | 事项 | 责任 | 优先级 |
+|---|---|---|---|
+| 1 | langgraph key/配额恢复(429/401 → 连续 2 轮 ≥50/51) | 运维/研发 | **P0** |
+| 2 | API 全量 23 红分流(校验缺失 15 交研发 / 语义 5 答复 / 造数改 SKIP) | 研发/测试 | **P0** |
+| 3 | `cancelAppointment` 补归属校验(F1 越权) | 研发 | **P0** |
+| 4 | CI 排除清单改实测快照 + 差集守卫 | 研发/CI | **P1** |
+| 5 | 240 前瞻契约红分批使绿(每批 ≤30) | 研发 | **P1** |
+| 6 | JaCoCo 接入(G9 代理指标落地) | 研发 | **P1** |
+| 7 | 存量 13 类红归因(EnergySystemFlow 6 / DimensionRegistryMap 3 / GrowthPublic 5E) | 研发/测试 | **P1** |
+| 8 | 根级黑盒 16 红(9082 常驻) | 测试/运维 | P2 |
+| 9 | 锚点率 20.8% → 60%(台账与锚点双向对齐) | 测试 | P2 |
+| 10 | 探索性/UAT/兼容/无障碍四类缺口补齐 | 测试 | P2 |
+| 11 | dx 端点派发实现 | 研发 | P3 |
+
+---
+
+## 附录 A:本轮命令与口径
+
+```bash
+# 后端全量(工程根必须是 cfc-backend)
+cd cfc-backend && JAVA_HOME=/d/jdk1.8.0_25 /d/maven/apache-maven-3.6.1/bin/mvn.cmd -o -B clean test   # 54:22
+python docs/tdd/tools/test_report_metrics.py --reports cfc-backend/target/surefire-reports --out-json _r197_agg.json
+# → classes=424 tests=3745 pass=3477 F=258 E=6 S=4 rate=92.84% red_classes=49 red_cases=264
+
+# 浏览器(每节点单任务)
+node _r197_189_admin.cjs kick && node _r197_189_admin.cjs read     # 189 admin 首轮 2F→复验 5/5 EXIT=0
+cd tests && npx playwright test -c playwright.config.live.js --project=frontend-mobile --workers=1 --output=../_r197/fe   # 6/6
+cd tests && npx playwright test -c playwright.config.live.js --project=shop-api --workers=1 --output=../_r197/shop      # 4/4
+cd tests && npx playwright test -c playwright.config.live.js --project=dx-bridge --workers=1 --output=../_r197/dx       # 2 skipped
+cd tests && npx playwright test -c playwright.config.health.js --workers=1 --output=../_r197/health                    # 13/13
+
+# Jest
+cd cfc-web && npx jest          # 116/116(225.6s)
+cd cfc-frontend && npx jest     # 624 = 609/3/12
+npx jest -c tests/jest.config.js  # 23 = 7/16(9082 未起,20.3s)
+
+# 线上 API(点名 4 文件)
+cd tests && npx playwright test e2e/api/api-smoke.spec.js e2e/api/nonfunc-security.spec.js \
+  e2e/api/nonfunc-perf-compat.spec.js e2e/api/traceability-p94-p95-c26.spec.js \
+  -c playwright.config.api.js --project=desktop --workers=1 --output=../_r197/api32   # 32 = 25/0/7
+
+# 线上 API 全量(990 例,完跑)
+cd tests && npx playwright test -c playwright.config.api.js --project=desktop --reporter=list --workers=1 --output=../_r197/api_full
+# → 172 passed / 23 failed / 795 skipped / 0 did not run(18.5m)—— 红例明细见 _r197/api_full/.last-run.json
+
+# langgraph@251
+MSYS2_ENV_CONV_EXCL=LOG LOG=/tmp/r197_pytest.log node _r196_251_lg.cjs kick
+MSYS2_ENV_CONV_EXCL=LOG LOG=/tmp/r197_pytest.log node _r196_251_lg.cjs read   # 10F/41P/148.89s
+```
+
+**口径声明**:后端例数以 surefire XML 聚合为唯一权威;浏览器例数以 `Running N tests` + summary 双校验;API 全量 990 例含 `generated/tc-scripted.spec.js`;R196 定向补测 8 例已并入本轮全量。
+
+## 附录 B:线上 API 全量(990 例,本轮完跑)
+
+```
+172 passed / 23 failed / 795 skipped / 0 did not run(18.5m)
+```
+
+- 命中 23 红逐例 error-context 提取根因:`not.toBe(200)` 系 15(服务端校验缺失)、语义/状态 5、服务端异常 2、参数格式 1。
+- 795 跳主要来自 `generated/tc-scripted.spec.js` 占位用例(端点或前提未满足即 skip),计入总数不计入通过率。
+- 归因与 R196 对照见 §4.4 / §7 P0-1。
+
+## 附录 C:未实测项(如实声明)
+
+- 压力测试 / 容量测试:**未授权联网,未执行**
+- SAST / DAST / 依赖漏洞扫描:**未授权,未执行**
+- JaCoCo 行覆盖率 / PIT 变异:**本机未配置,未实测**
+- 多浏览器(firefox/webkit)/ 真机兼容:**未执行**
+- 无障碍(axe/WCAG 自动扫描):**未执行**
+- UAT / BDD:**无资产,未执行**
+- 探索性测试:**无 charter,未执行**
+- langgraph 链路面(live HTTP):**251 无 9000 服务,未实测**(B-196-5)
+- 全项目逐行代码审查:**本轮窗口零源码变更,抽样复核红类名单与 API 失败上下文**

+ 16 - 0
docs/tdd/test/blockers.md

@@ -1440,3 +1440,19 @@
 | **B-36(第 79 轮零漂移)** | 根级黑盒 23 例 16 红 | 测试(P2 环境) | `npx jest -c tests/jest.config.js` → **7 过 / 16 红**(21.0s),全 `ECONNREFUSED 127.0.0.1:9082`(本机后端未起) | 测试 | 2026-11-14 01:30 | 待处理 |
 | **B-DX-1(第 35 轮)** | dx-bridge 端点 404 | 部署/研发(P1) | 两端点 404/404 → 2 skip(规格「仅登记不实现」) | 部署/研发 | 2026-11-14 01:30 | 待处理 |
 | **R196 门禁** | 全量 **5579 / 4395** | 测试 | **不通过(有条件)**。✅G3 浏览器 28+2 跳 / G4 编译 0 错 / G5 XML 423/423 / G6 EXIT=0 / G8 6/6=401 / G10 三节点 / G12 **SRS 变更已同步**(台账 +4 TC + 8 例)/ G13 零漂移**第 28 次**;❌G1 **93.29%**(剔 skip/未跑)/G2 **316 红**(后端 265 + API 22 + 根级 16 + fe 3 + lg 10)/G7 41-51/G9 20.8%/G11 漏拦 42 陈旧 26/G14 72.6%。**变化** = API 全量首纳(+990 例 / +22 红)、后端 −7 红、lg 41/51、S-cfc-227 使绿 23 例、访客态三页增量复验零回归 | 测试(R196 闭环) | 2026-11-14 01:30 | 已记录 |
+
+## R197 段(2026-11-14 02:35,HEAD `0a3e376d3`,新增)
+
+| 编号 | 关联键/对象 | 类型 | 描述与处置 | 经办 | 登记时间 | 状态 |
+|---|---|---|---|---|---|---|
+| **B-197-1(P0 延续 B-196-6)** | 线上 API 全量 23 红 | 研发/测试 | R196 22 红 → **R197 23 红(+1 净变)**:**首次完跑**(172 过 / 23 红 / 795 跳 / **0 未跑**)。归因逐例:`not.toBe(200)` 系 15(服务端校验缺失:badge 4、task-checkin 3、task-create 2、task-c14 2、coach-food 2、energy-sc 1、incentive-loop 1)、语义/状态 5(并发兑换、至少一提醒渠道、请设置所需积分、id 不能为空、申请兑换失败)、服务端异常 2(500 / energy undefined)、参数格式 1。域分布与 R196 基本同(badge 1~2→4,butler-fallback 2 消失)→ **无新域,属既有问题重测曝光**。**研发需答**:15 例校验缺失契约是否需补(name 必填、admin 守卫、幂等);5 例语义契约确认是「契约缺失」还是「用例预期错」。 | 测试(R197 实测) | 2026-11-14 02:35 | 待研发确认分流(P0) |
+| **B-197-2(P2 新增·疑似 B-120 uly)** | 189 admin 首轮 account-roles 非 200 | 测试/网络(P2 环境) | 首轮 **2F/3P**:TC-A-U04/U05 登录流中 `expect(rolesStatus).toBe(200)` 前置失败;**同轮复验 5/5 全绿(1.2m)**;189 节点 git `pull --ff-only` 失败(diverging,dev 本地提交)但 HEAD `ec8ced27a` 与 R196 相同 → 判节点/网络偶发非产品回归。B-120 同型(189 首轮偶发)。建议:登录前置加 1s 重试窗口;连续 2 轮首轮即绿销号。 | 测试(R197 实测) | 2026-11-14 02:35 | 观察期(第 1 轮) |
+| **B-178-1(第 11 轮装置浮动)** | TaskReviewScP11 反射装置浮动 | 测试(P2) | **本轮 1F**(R196 2F)→ B-178-1 浮动,无规则。建议 `@MockBean` 替代 `ReflectionUtils`。 | 测试 | 2026-11-14 02:35 | 延续 |
+| **B-177-1(第 19 轮复现)** | 251 pytest 收尾不退出 | 研发/测试(P1) | summary(`10 failed, 41 passed`)已打印但 `EXIT=` 未落盘 → `_r195_cleanup_251.cjs` kill 后复核进程 0。解除:`app/main.py:84` 补 `await client.aclose()` + 派发器加 `timeout -k 10 900` | 研发/测试 | 2026-11-14 02:35 | 已清理,待复验 |
+| **B-196-2(P0 延续)** | langgraph 上游 LLM 配额/key | 运维/研发 | 51 例 **41 过 / 10 红**(148.89s)—— 与 R196 逐例一致;日志实证 429(AgnesAI 配额)+ 401(key `****ab12` invalid);源码零变更 → 环境红非回归 | 运维/研发 | 2026-11-14 02:35 | 待轮换 key/升配额(P0) |
+| **B-196-1(第 2 轮)** | `.gitlab-ci.yml:61` CI 排除清单 | 研发/CI(P1) | 清单 33 类 vs 实测 **49 红类** → 漏拦 42 / 陈旧 26(红类名单与 R196 完全一致,未修) | 研发/CI | 2026-11-14 02:35 | 待处理(P1) |
+| **F1(台账长期项)** | `cancelAppointment` 越权 | 研发(P0) | 本轮窗口零源码变更 → 未修确认;controller 依旧 `cancelAppointment(@PathVariable Long id)`,无调用者身份 | 研发 | 2026-11-14 02:35 | 待修(P0) |
+| **B-142-1(销号维持第 25 轮)** | 匿名端点鉴权 | 研发(已闭环) | 6 端点(mind/energy/health-plan/xiaomi-health/huawei-health/admin-families)全 **401 `请先登录`** | 测试(R197 实测) | 2026-11-14 02:35 | 已闭(观察维持) |
+| **B-36(第 80 轮零漂移)** | 根级黑盒 23 例 16 红 | 测试(P2 环境) | `npx jest -c tests/jest.config.js` → **7 过 / 16 红**(20.3s),全 `ECONNREFUSED 127.0.0.1:9082` | 测试 | 2026-11-14 02:35 | 待处理 |
+| **B-DX-1(第 36 轮)** | dx-bridge 端点 404 | 部署/研发(P1) | 两端点 404/404 → 2 skip | 部署/研发 | 2026-11-14 02:35 | 待处理 |
+| **R197 门禁** | 全量 **5579 / 4450** | 测试 | **不通过(承袭·有条件)**。✅G3 浏览器 28+2 跳 / G4 编译 0 错(2125+430 源)/ G5 XML 424/424 / G6 EXIT=0 / G8 6/6=401 / G10 四节点 / G12 窗口零变更+补测 8 例并入全量口径 / G13 零漂移**第 29 次**(除装置浮动 −1);❌G1 **93.37%**(剔跳)/G2 **316 红**(后端 264 / API 23 / 根级 16 / fe 3 / lg 10)/G7 41/51/G9 20.8%/G11 漏拦 42 陈旧 26/G14 72.6%。**变化** = API 全量**首次完跑(0 未跑)**、过 +55、剔跳过率 93.29%→**93.37%**、后端红 265→**264**(装置浮动 −1)→ **无新增确定性回归** | 测试(R197 闭环) | 2026-11-14 02:35 | 已记录 |