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