From b9792c8673fce8d5e0a8e1ddc9bb2f999500ad0f Mon Sep 17 00:00:00 2001
From: MerCry <jiong1114>
Date: Tue, 24 Feb 2026 01:02:35 +0800
Subject: [PATCH] feat(MCA): define MessageRouterService interface [TASK-020]
 [AC-MCA-08]

---
 .../robot/service/MessageRouterService.java   | 81 +++++++++++++++++++
 1 file changed, 81 insertions(+)
 create mode 100644 src/main/java/com/wecom/robot/service/MessageRouterService.java

diff --git a/src/main/java/com/wecom/robot/service/MessageRouterService.java b/src/main/java/com/wecom/robot/service/MessageRouterService.java
new file mode 100644
index 0000000..902dea9
--- /dev/null
+++ b/src/main/java/com/wecom/robot/service/MessageRouterService.java
@@ -0,0 +1,81 @@
+package com.wecom.robot.service;
+
+import com.wecom.robot.dto.InboundMessage;
+import com.wecom.robot.entity.Session;
+
+/**
+ * 消息路由服务接口 - 渠道无关的消息路由核心服务
+ * 
+ * <p>职责：
+ * <ul>
+ *   <li>处理入站消息的统一路由</li>
+ *   <li>根据会话状态分发到 AI 服务或人工客服</li>
+ *   <li>协调消息处理流程中的各组件</li>
+ * </ul>
+ * 
+ * <p>关联 AC: [AC-MCA-08] 统一消息路由
+ * 
+ * @see InboundMessage
+ * @see Session
+ */
+public interface MessageRouterService {
+
+    /**
+     * 处理入站消息 - 主入口方法
+     * 
+     * <p>执行流程：
+     * <ol>
+     *   <li>幂等性检查（基于 channelMessageId）</li>
+     *   <li>获取或创建会话</li>
+     *   <li>根据会话状态路由消息</li>
+     * </ol>
+     * 
+     * @param message 入站消息，包含渠道类型、消息内容等信息
+     */
+    void processInboundMessage(InboundMessage message);
+
+    /**
+     * 根据会话状态路由消息
+     * 
+     * <p>路由规则：
+     * <ul>
+     *   <li>AI 状态 → dispatchToAiService</li>
+     *   <li>PENDING 状态 → dispatchToPendingPool</li>
+     *   <li>MANUAL 状态 → dispatchToManualCs</li>
+     * </ul>
+     * 
+     * @param session 当前会话
+     * @param message 入站消息
+     */
+    void routeBySessionState(Session session, InboundMessage message);
+
+    /**
+     * 分发到 AI 服务处理
+     * 
+     * <p>调用 AI 服务生成回复，并根据返回结果判断是否需要转人工
+     * 
+     * @param session 当前会话
+     * @param message 入站消息
+     */
+    void dispatchToAiService(Session session, InboundMessage message);
+
+    /**
+     * 分发到人工客服处理
+     * 
+     * <p>将消息推送给在线的人工客服（通过 WebSocket）
+     * 
+     * @param session 当前会话
+     * @param message 入站消息
+     */
+    void dispatchToManualCs(Session session, InboundMessage message);
+
+    /**
+     * 分发到待接入池
+     * 
+     * <p>将消息暂存，等待人工客服接入
+     * 
+     * @param session 当前会话
+     * @param message 入站消息
+     */
+    void dispatchToPendingPool(Session session, InboundMessage message);
+}