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

test(S-cfc-250): RED 契约单测 ai.coach.handoffPlanner(SC-B-09 教练转接成长规划师)

Sisyphus Agent 3 дней назад
Родитель
Сommit
405ef34461

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