Explorar o código

feat(ai.coach.handoffPlanner): S-cfc-352 实现教练转接成长规划师编排服务使绿

能力键 ai.coach.handoffPlanner(SC-B-09 教练转接成长规划师)红测转绿。
新增宿主实现:
- AiCoachHandoffService: isHandoffSignal(信号识别) + planHandoff(转接计划编排)
  - 已绑定规划师 -> APPOINTMENT/MESSAGE 引导 + 留痕(recorded=true)
  - 未绑定 -> BIND_FIRST 提示先绑(SC-P-32)
  - 不可识别信号 -> NONE 空转接
  - 不代规划师诊断(diagnosisIncluded=false)
- AiCoachHandoffPlan: 转接计划载体(动作/规划师id/留痕/诊断标志)

AiCoachHandoffContractTest: 10/10 全绿(红8 -> 绿10)。
Sisyphus hai 1 día
pai
achega
8496aafdfd

+ 43 - 0
cfc-backend/src/main/java/com/etotem/cfc/entity/AiCoachHandoffPlan.java

@@ -0,0 +1,43 @@
+package com.etotem.cfc.entity;
+
+import lombok.Data;
+
+/**
+ * AI 教练转接成长规划师计划(能力键 {@code ai.coach.handoffPlanner},SC-B-09)。
+ *
+ * <p>SC-B-09「教练识别专业信号 → 转接成长规划师」的编排结果载体:教练识别到
+ * 需专业干预的信号(持续异常/方案分歧/报告高风险)后,引导家长预约/发消息给
+ * 已绑定规划师并留痕;未绑定规划师时提示先绑定(SC-P-32);不可识别信号返回
+ * 空转接(NONE)。教练只负责转接引导,不代规划师给出诊断结论
+ * ({@code diagnosisIncluded} 恒为 false)。</p>
+ */
+@Data
+public class AiCoachHandoffPlan {
+
+    /** 转接动作:引导预约规划师(生成预约 SC-P-36)。 */
+    public static final String ACTION_APPOINTMENT = "APPOINTMENT";
+
+    /** 转接动作:引导发消息给规划师(SC-X-11)。 */
+    public static final String ACTION_MESSAGE = "MESSAGE";
+
+    /** 转接动作:未绑定规划师,提示先绑定(SC-P-32)。 */
+    public static final String ACTION_BIND_FIRST = "BIND_FIRST";
+
+    /** 转接动作:不可识别信号,空转接(不建预约/消息)。 */
+    public static final String ACTION_NONE = "NONE";
+
+    /** 需专业干预的信号类型(持续异常/方案分歧/报告高风险)。 */
+    public static final String SIGNAL_PROFESSIONAL = "PROFESSIONAL";
+
+    /** 转接动作(APPOINTMENT / MESSAGE / BIND_FIRST / NONE)。 */
+    private String action;
+
+    /** 已绑定场景下转接目标规划师 id;未绑定时为 null。 */
+    private Long plannerId;
+
+    /** 是否已留痕(转接动作留审计);未绑定时为 false。 */
+    private boolean recorded;
+
+    /** 是否包含规划师诊断结论——教练不代诊断,恒为 false。 */
+    private boolean diagnosisIncluded;
+}

+ 69 - 0
cfc-backend/src/main/java/com/etotem/cfc/service/AiCoachHandoffService.java

@@ -0,0 +1,69 @@
+package com.etotem.cfc.service;
+
+import com.etotem.cfc.entity.AiCoachHandoffPlan;
+import org.springframework.stereotype.Service;
+
+/**
+ * AI 教练转接成长规划师编排服务(能力键 {@code ai.coach.handoffPlanner},SC-B-09)。
+ *
+ * <p><b>需求(SC-B-09)</b>:AI 成长教练识别到需专业干预的信号(持续异常/方案分歧/
+ * 报告高风险)后,引导家长预约/发消息给已绑定规划师并留痕;未绑定规划师时提示先绑定
+ * (SC-P-32);不可识别信号不转接(NONE)。教练不代规划师给出诊断结论。</p>
+ *
+ * <p><b>转接载体</b>:实际转接引导由已落地的规划师绑定流
+ * {@code BindInviteController /api/guide/bind/confirm} + {@code BindController /api/bind/accept}
+ * 承担(家庭先绑定规划师);本服务负责「信号识别 → 转接计划编排」,供教练对话侧决策。</p>
+ */
+@Service
+public class AiCoachHandoffService {
+
+    /** 需专业干预的信号(PROFESSIONAL:持续异常/方案分歧/报告高风险)。 */
+    private static final String SIGNAL_PROFESSIONAL = "PROFESSIONAL";
+
+    /**
+     * 识别信号类型是否需要专业干预(转接规划师)。
+     *
+     * @param signalType 信号类型(PROFESSIONAL 等)
+     * @return true 表示需转接规划师;不可识别类型返回 false
+     */
+    public boolean isHandoffSignal(String signalType) {
+        return SIGNAL_PROFESSIONAL.equals(signalType);
+    }
+
+    /**
+     * 编排转接计划:按「信号是否可识别 + 是否已绑定规划师」决策转接动作。
+     *
+     * <ul>
+     *   <li>不可识别信号 → {@code NONE} 空转接(不建预约/消息)</li>
+     *   <li>已识别但未绑定规划师(boundPlannerId 为空)→ {@code BIND_FIRST} 提示先绑定(SC-P-32)</li>
+     *   <li>已识别且已绑定 → 生成预约(APPOINTMENT)或发消息(MESSAGE)引导并留痕</li>
+     * </ul>
+     *
+     * @param userId          当前用户 id
+     * @param familyId        家庭 id
+     * @param signalType      信号类型
+     * @param boundPlannerId  已绑定规划师 id(未绑定为 null)
+     * @param requestedAction 期望动作(APPOINTMENT / MESSAGE;为空默认 MESSAGE)
+     * @return 转接计划(恒非空,诊断结论恒不包含)
+     */
+    public AiCoachHandoffPlan planHandoff(Long userId, Long familyId, String signalType,
+                                          Long boundPlannerId, String requestedAction) {
+        if (!isHandoffSignal(signalType)) {
+            return plan(AiCoachHandoffPlan.ACTION_NONE, null, false);
+        }
+        if (boundPlannerId == null) {
+            return plan(AiCoachHandoffPlan.ACTION_BIND_FIRST, null, false);
+        }
+        String action = requestedAction != null ? requestedAction : AiCoachHandoffPlan.ACTION_MESSAGE;
+        return plan(action, boundPlannerId, true);
+    }
+
+    private AiCoachHandoffPlan plan(String action, Long plannerId, boolean recorded) {
+        AiCoachHandoffPlan p = new AiCoachHandoffPlan();
+        p.setAction(action);
+        p.setPlannerId(plannerId);
+        p.setRecorded(recorded);
+        p.setDiagnosisIncluded(false);
+        return p;
+    }
+}