---
feature_id: "MCA"
title: "多渠道适配主框架架构改造"
status: "draft"
version: "0.2.0"
owners:
  - "backend"
  - "architect"
last_updated: "2026-02-24"
source:
  type: "conversation"
  ref: "架构改造需求"
---

# 多渠道适配主框架架构改造（MCA）

## 1. 背景与目标

### 1.1 背景

当前系统为"企业微信智能客服系统"，核心逻辑围绕企业微信客服 API 构建：
- 微信消息接收、加解密、同步
- AI 回复生成（紧耦合在 Java 主应用中）
- 会话状态管理、转人工逻辑
- 人工客服工作台（WebSocket）

随着业务扩展，需要接入更多渠道（抖音、京东等），同时 AI 服务需要独立演进（支持多模型、Prompt 工程、RAG 等）。当前架构存在以下问题：

1. **渠道耦合**：AI 服务、消息处理与微信 API 紧密耦合，难以扩展新渠道
2. **AI 服务受限**：Java 生态对 AI/LLM 支持不如 Python 丰富，迭代效率低
3. **职责不清**：消息路由、AI 调用、状态管理混杂在同一服务中

### 1.2 目标

1. **多渠道适配**：抽象渠道适配层，支持 WeChat/Douyin/JD 等渠道的快速接入
2. **AI 服务剥离**：将 AI 服务剥离为独立 Python 服务，主框架通过 HTTP 调用
3. **职责清晰**：主框架负责消息路由、会话管理、渠道适配；AI 服务负责模型推理

### 1.3 非目标（Out of Scope）

- 本次改造不涉及前端界面重构
- 不涉及数据库迁移或数据模型重大变更
- 不涉及 AI 模型训练或微调

## 2. 模块边界（Scope）

### 2.1 覆盖

| 模块 | 说明 |
|-----|------|
| **渠道适配层** | 抽象 ChannelAdapter 接口，实现 WeChatAdapter，预留 DouyinAdapter/JdAdapter 扩展点 |
| **消息路由层** | MessageProcessService 重构，支持多渠道消息分发 |
| **会话管理层** | SessionManagerService 保持不变，增加渠道类型字段 |
| **AI 服务客户端** | 新增 AiServiceClient，通过 HTTP 调用 Python AI 服务 |
| **Python AI 服务** | 独立服务，提供 `/ai/chat` 等接口 |
| **配置管理** | 支持多渠道配置、AI 服务配置 |

### 2.2 不覆盖

| 模块 | 说明 |
|-----|------|
| **抖音/京东适配器实现** | 仅预留接口，后续迭代实现 |
| **人工客服工作台** | WebSocket 相关逻辑保持不变 |
| **数据库表结构** | 仅增加渠道类型字段，不进行大规模迁移 |
| **前端界面** | 不涉及 |

## 3. 依赖盘点（Dependencies）

### 3.1 本模块依赖的外部服务

| 依赖 | 用途 | 契约文件 |
|-----|------|---------|
| **Python AI 服务** | AI 回复生成、置信度评估 | `openapi.deps.yaml` |
| **企业微信 API** | 微信消息收发、会话状态管理 | 第三方 API |
| **Redis** | 会话状态缓存、Token 缓存 | 基础设施 |
| **MySQL** | 会话、消息持久化 | 基础设施 |

### 3.2 本模块对外提供的能力

| 能力 | 消费方 | 契约文件 |
|-----|-------|---------|
| **人工客服工作台 API** | 前端 | `openapi.provider.yaml` |
| **WebSocket 消息推送** | 前端 | `openapi.provider.yaml` |

## 4. 用户故事（User Stories）

### 4.1 渠道适配

- [US-MCA-01] 作为系统架构师，我希望主框架支持多渠道适配器接口，以便快速接入新渠道（抖音、京东等）。

### 4.2 AI 服务剥离

- [US-MCA-02] 作为 AI 工程师，我希望 AI 服务独立部署为 Python 服务，以便使用 Python 生态的 AI 框架和工具。
- [US-MCA-03] 作为后端开发者，我希望主框架通过 HTTP 调用 AI 服务，以便主框架与 AI 服务独立演进。

### 4.3 消息路由

- [US-MCA-04] 作为系统运维，我希望消息路由逻辑与渠道适配解耦，以便新增渠道时不影响核心路由逻辑。

### 4.4 会话管理

- [US-MCA-05] 作为系统运维，我希望会话管理支持多渠道标识，以便区分不同渠道的会话。

## 5. 验收标准（Acceptance Criteria, EARS）

### 5.1 渠道适配层

#### 5.1.1 核心能力接口（所有渠道必须实现）

- [AC-MCA-01] WHEN 定义 ChannelAdapter 核心接口 THEN 系统 SHALL 包含 `receiveMessage`（接收消息）、`sendMessage`（发送消息）、`getChannelType`（获取渠道类型）方法签名。

#### 5.1.2 可选能力接口（按渠道特性实现）

- [AC-MCA-01-OPT-01] WHEN 渠道支持服务状态管理 THEN 系统 SHALL 实现 `ServiceStateCapable` 接口，包含 `getServiceState`、`transServiceState` 方法。
- [AC-MCA-01-OPT-02] WHEN 渠道支持转人工 THEN 系统 SHALL 实现 `TransferCapable` 接口，包含 `transferToManual`、`transferToPool` 方法。
- [AC-MCA-01-OPT-03] WHEN 渠道支持消息同步 THEN 系统 SHALL 实现 `MessageSyncCapable` 接口，包含 `syncMessages` 方法。

> **设计说明**：可选能力接口的具体定义将在 `design.md` 中详细说明。主框架在运行时通过能力检测（如 `instanceof` 或 `Optional.ofNullable`）判断渠道是否支持某能力。

#### 5.1.3 适配器实现

- [AC-MCA-02] WHEN 实现 WeChatAdapter THEN 系统 SHALL 实现核心接口及所有可选能力接口，封装现有 WecomApiService 的所有功能。
- [AC-MCA-03] WHEN 新增渠道适配器 THEN 系统 SHALL 至少实现核心接口，可选能力按需实现，无需修改核心路由逻辑。

### 5.2 AI 服务剥离

#### 5.2.1 请求契约

- [AC-MCA-04] WHEN 主框架调用 AI 服务 THEN 系统 SHALL 通过 HTTP POST `/ai/chat` 接口获取 AI 回复。
- [AC-MCA-04-REQ] WHEN 构造 AI 服务请求 THEN 系统 SHALL 包含以下最小字段：`sessionId`（会话ID）、`currentMessage`（当前消息）、`channelType`（渠道类型）。
- [AC-MCA-04-OPT] WHEN 构造 AI 服务请求 THEN 系统 MAY 包含以下可选字段：`history`（历史消息）、`metadata`（扩展元数据）。

#### 5.2.2 响应契约

- [AC-MCA-05] WHEN AI 服务返回回复 THEN 系统 SHALL 包含 `reply`（回复内容）、`confidence`（置信度）、`shouldTransfer`（是否建议转人工）字段。

#### 5.2.3 容错处理

- [AC-MCA-06] WHEN AI 服务不可用 THEN 系统 SHALL 返回降级回复并记录错误日志，不影响消息接收流程。
- [AC-MCA-07] WHEN AI 服务响应超时 THEN 系统 SHALL 在配置的超时时间后返回降级回复。

### 5.3 消息路由

- [AC-MCA-08] WHEN 收到消息 THEN 系统 SHALL 根据渠道类型路由到对应的渠道适配器。
- [AC-MCA-09] WHEN 会话状态为 AI THEN 系统 SHALL 调用 AI 服务生成回复。
- [AC-MCA-10] WHEN 会话状态为 MANUAL THEN 系统 SHALL 推送消息到人工客服工作台。

### 5.4 消息幂等性

- [AC-MCA-11-IDEMPOTENT] WHEN 收到重复的 messageId THEN 系统 SHALL 幂等处理，不重复调用 AI 服务、不重复发送回复消息。

### 5.5 会话管理

- [AC-MCA-11] WHEN 创建会话 THEN 系统 SHALL 记录渠道类型（channelType）。
- [AC-MCA-12] WHEN 查询会话 THEN 系统 SHALL 支持按渠道类型筛选。

### 5.6 兼容性

- [AC-MCA-13] WHEN 改造完成后 THEN 系统 SHALL 保持现有微信渠道功能完全兼容，无业务中断。

## 6. 追踪映射（Traceability）

| AC ID | Endpoint | 方法 | operationId | 备注 |
|-------|----------|------|-------------|------|
| AC-MCA-04 | /ai/chat | POST | generateReply | AI 服务接口（deps） |
| AC-MCA-04-REQ | /ai/chat | POST | generateReply | AI 请求最小字段 |
| AC-MCA-05 | /ai/chat | POST | generateReply | AI 服务响应格式 |
| AC-MCA-06 | /ai/chat | POST | generateReply | 降级处理 |
| AC-MCA-07 | /ai/chat | POST | generateReply | 超时处理 |
| AC-MCA-08 | /wecom/callback | POST | handleWecomCallback | **微信渠道** Provider Endpoint，其它渠道后续补齐 |
| AC-MCA-09 | /ai/chat | POST | generateReply | AI 状态路由 |
| AC-MCA-10 | WebSocket | - | pushToManualCs | 人工状态路由 |
| AC-MCA-11-IDEMPOTENT | - | - | - | 幂等处理（内部逻辑，无对外接口） |

## 7. 风险与约束

### 7.1 技术风险

| 风险 | 影响 | 缓解措施 |
|-----|------|---------|
| AI 服务调用延迟 | 用户体验下降 | 设置合理超时、异步处理、降级策略 |
| 渠道 API 差异 | 适配器实现复杂 | 抽象公共接口、渠道特有能力单独处理 |

### 7.2 约束

- Java 版本：1.8（不升级）
- Spring Boot 版本：2.7.18（不升级）
- AI 服务通信协议：HTTP REST（非 gRPC）
- 部署方式：AI 服务独立部署，主框架通过内网调用