MerCry
/
ai-robot-channel
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
ai-robot-channel/spec/ai-robot/design.md

637 lines
33 KiB
Markdown
Raw Normal View History

docs: 添加多渠道适配主框架架构设计 (design.md) [AC-MCA-01]
2026-02-23 16:51:29 +00:00
---
feature_id: "MCA"
title: "多渠道适配主框架架构设计"
status: "draft"
version: "0.2.0"
owners:
- "architect"
- "backend"
last_updated: "2026-02-24"
---
# 多渠道适配主框架架构设计（design.md）
## 1. 系统架构
### 1.1 整体架构图
```
┌─────────────────────────────────────────────────────────────────────────────┐
│ 外部系统 │
├─────────────────┬─────────────────┬─────────────────┬───────────────────────┤
│ 企业微信 API │ 抖音 API │ 京东 API │ 前端工作台 │
└────────┬────────┴────────┬────────┴────────┬────────┴──────────┬────────────┘
│ │ │ │
▼ ▼ ▼ ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ Java 主框架 (Spring Boot) │
├─────────────────────────────────────────────────────────────────────────────┤
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ 入口层 (Controller Layer) │ │
│ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │
│ │ │WecomCallback │ │DouyinCallback│ │ JdCallback │ (预留) │ │
│ │ │ Controller │ │ Controller │ │ Controller │ │ │
│ │ └──────┬───────┘ └──────────────┘ └──────────────┘ │ │
│ │ │ │ │
│ │ │ 验签/解密/解析 → InboundMessage │ │
│ │ ▼ │ │
│ └─────────┼───────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ 消息路由层 (Message Router) │ │
│ │ ┌──────────────────────────────────────────────────────────────┐ │ │
│ │ │ MessageRouterService (渠道无关) │ │ │
│ │ │ - processInboundMessage(InboundMessage) │ │ │
│ │ │ - routeBySessionState(Session, InboundMessage) │ │ │
│ │ │ - dispatchToAiService(Session, InboundMessage) │ │ │
│ │ │ - dispatchToManualCs(Session, InboundMessage) │ │ │
│ │ └──────────────────────────────────────────────────────────────┘ │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ 渠道适配层 (Channel Adapter) │ │
│ │ ┌──────────────────────────────────────────────────────────────┐ │ │
│ │ │ ChannelAdapter 接口 (核心能力) │ │ │
│ │ │ - getChannelType() │ │ │
│ │ │ - sendMessage(OutboundMessage) │ │ │
│ │ └──────────────────────────────────────────────────────────────┘ │ │
│ │ ┌──────────────────────────────────────────────────────────────┐ │ │
│ │ │ 可选能力接口 (Optional Capabilities) │ │ │
│ │ │ - ServiceStateCapable - TransferCapable - MessageSyncCapable│ │ │
│ │ └──────────────────────────────────────────────────────────────┘ │ │
│ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │
│ │ │ WeChatAdapter│ │DouyinAdapter │ │ JdAdapter │ (预留) │ │
│ │ │ (已实现) │ │ (预留) │ │ (预留) │ │ │
│ │ └──────────────┘ └──────────────┘ └──────────────┘ │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ┌─────────────────────────┼─────────────────────────┐ │
│ ▼ ▼ ▼ │
│ ┌──────────────┐ ┌──────────────────────┐ ┌──────────────┐ │
│ │ AI 服务客户端 │ │ 会话管理层 │ │ WebSocket 服务│ │
│ │AiServiceClient│ │SessionManagerService │ │WebSocketService│ │
│ └──────┬───────┘ └──────────────────────┘ └──────────────┘ │
│ │ │
└─────────┼───────────────────────────────────────────────────────────────────┘
│ HTTP
▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ Python AI 服务 (独立部署) │
├─────────────────────────────────────────────────────────────────────────────┤
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ OpenAI Client│ │DeepSeek Client│ │ 其他模型 │ │
│ └──────┬───────┘ └──────┬───────┘ └──────────────┘ │
│ │ │ │
│ ▼ ▼ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ AI 服务核心逻辑 │ │
│ │ - /ai/chat 生成 AI 回复 │ │
│ │ - /ai/health 健康检查 │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────────┘
```
### 1.2 模块职责
| 模块 | 职责 | 关联 AC |
|-----|------|--------|
| **入口层** | 接收渠道回调，验签/解密/解析，转换为统一的 InboundMessage | AC-MCA-08 |
| **消息路由层** | 渠道无关的消息路由，根据会话状态分发到 AI 或人工 | AC-MCA-08 ~ AC-MCA-10 |
| **渠道适配层** | 封装各渠道 API 差异，提供统一的消息发送接口 | AC-MCA-01 ~ AC-MCA-03 |
| **AI 服务客户端** | 调用 Python AI 服务，处理超时/降级 | AC-MCA-04 ~ AC-MCA-07 |
| **会话管理层** | 管理会话生命周期、状态变更、消息持久化 | AC-MCA-11 ~ AC-MCA-12 |
| **WebSocket 服务** | 实时推送消息到人工客服工作台 | AC-MCA-10 |
| **Python AI 服务** | AI 模型推理、置信度评估、转人工建议 | AC-MCA-04 ~ AC-MCA-05 |
## 2. 统一消息模型
### 2.1 入站消息 (InboundMessage)
```java
@Data
public class InboundMessage {
private String channelType; // 渠道类型: wechat/douyin/jd
private String channelMessageId; // 渠道原始消息ID (用于幂等)
private String sessionKey; // 会话标识 (customerId + kfId 组合)
private String customerId; // 客户ID
private String kfId; // 客服账号ID
private String sender; // 发送者标识
private String content; // 消息内容 (统一字段名)
private String msgType; // 消息类型: text/image/voice 等
private String rawPayload; // 原始消息体 (JSON/XML)
private Long timestamp; // 消息时间戳
private SignatureInfo signatureInfo; // 签名信息
private Map<String, Object> metadata; // 扩展元数据
}
@Data
public class SignatureInfo {
private String signature; // 签名值
private String timestamp; // 签名时间戳
private String nonce; // 随机数
private String algorithm; // 签名算法 (可选)
}
```
### 2.2 出站消息 (OutboundMessage)
```java
@Data
public class OutboundMessage {
private String channelType; // 渠道类型
private String receiver; // 接收者ID (customerId)
private String kfId; // 客服账号ID
private String content; // 消息内容
private String msgType; // 消息类型
private Map<String, Object> metadata; // 扩展元数据
}
```
### 2.3 字段映射策略
> **重要**：内部统一使用 `content` 字段名，与 AI 服务契约 (`currentMessage`) 的映射在 AiServiceClient 层处理。
| 内部字段 | AI 服务契约字段 | 映射位置 |
|---------|----------------|---------|
| `InboundMessage.content` | `ChatRequest.currentMessage` | `AiServiceClient.generateReply()` |
| `InboundMessage.sessionKey` | `ChatRequest.sessionId` | `AiServiceClient.generateReply()` |
| `InboundMessage.channelType` | `ChatRequest.channelType` | `AiServiceClient.generateReply()` |
```java
public ChatRequest toChatRequest(InboundMessage msg, List<Message> history) {
ChatRequest request = new ChatRequest();
request.setSessionId(msg.getSessionKey());
request.setCurrentMessage(msg.getContent()); // content → currentMessage
request.setChannelType(msg.getChannelType());
request.setHistory(history);
return request;
}
```
## 3. 核心接口设计
### 3.1 渠道适配器接口
```java
// 核心能力接口（所有渠道必须实现）
public interface ChannelAdapter {
String getChannelType();
void sendMessage(OutboundMessage message);
}
// 可选能力接口：服务状态管理
public interface ServiceStateCapable {
ServiceState getServiceState(String kfId, String customerId);
boolean transServiceState(String kfId, String customerId, int newState, String servicerId);
}
// 可选能力接口：转人工
public interface TransferCapable {
boolean transferToPool(String kfId, String customerId);
boolean transferToManual(String kfId, String customerId, String servicerId);
}
// 可选能力接口：消息同步
public interface MessageSyncCapable {
SyncMsgResponse syncMessages(String kfId, String cursor);
}
```
### 3.2 消息路由服务接口
```java
public interface MessageRouterService {
void processInboundMessage(InboundMessage message);
void routeBySessionState(Session session, InboundMessage message);
void dispatchToAiService(Session session, InboundMessage message);
void dispatchToManualCs(Session session, InboundMessage message);
void dispatchToPendingPool(Session session, InboundMessage message);
}
```
### 3.3 AI 服务客户端接口
```java
public interface AiServiceClient {
ChatResponse generateReply(ChatRequest request);
boolean healthCheck();
}
```
## 4. 核心流程
### 4.1 消息处理主流程（渠道无关）
```
┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐
│ 渠道回调入口 │────▶│ 验签/解密/解析 │────▶│ 构建 InboundMessage│
│ (Controller) │ │ (渠道专属逻辑) │ │ (统一消息模型) │
└──────────────────┘ └────────┬─────────┘ └──────────────────┘
│
▼
┌──────────────────┐
│ MessageRouter │
│ processInbound │
│ Message() │
└────────┬─────────┘
│
▼
┌──────────────────┐
│ 幂等检查 (msgId) │
│ Redis SETNX │
└────────┬─────────┘
│
▼
┌──────────────────┐
│ 获取/创建会话 │
│ SessionManager │
└────────┬─────────┘
│
▼
┌──────────────────┐
│ 获取渠道服务状态 │
│ (可选能力检测) │
└────────┬─────────┘
│
┌───────────────┼───────────────┐
▼ ▼ ▼
┌──────────┐ ┌──────────┐ ┌──────────┐
│ AI 状态 │ │ POOL 状态 │ │MANUAL 状态│
│ │ │ │ │ │
└────┬─────┘ └────┬─────┘ └────┬─────┘
│ │ │
▼ ▼ ▼
┌──────────────┐ ┌──────────┐ ┌──────────────┐
│dispatchTo │ │dispatchTo│ │dispatchTo │
│ AiService │ │PendingPool│ │ ManualCs │
└──────┬───────┘ └──────────┘ └──────────────┘
│
▼
┌──────────────┐
│ 判断是否转人工│
│shouldTransfer│
└──────┬───────┘
│
┌───────┴───────┐
▼ ▼
┌───────┐ ┌──────────────┐
│发送回复│ │ 转入待接入池 │
│给用户 │ │ TransferCapable│
└───────┘ └──────────────┘
```
### 4.2 AI 服务调用流程
```
┌──────────────────┐
│ 构造 ChatRequest │
│ sessionId │
│ currentMessage │←── content 映射
│ channelType │
│ history (可选) │
└────────┬─────────┘
│
▼
┌──────────────────┐ ┌──────────────────┐
│ HTTP POST │────▶│ Python AI 服务 │
│ /ai/chat │ │ 超时: 5s │
└────────┬─────────┘ └────────┬─────────┘
│ │
│ ┌──────────────┼──────────────┐
│ ▼ ▼ ▼
│ ┌──────────┐ ┌──────────┐ ┌──────────┐
│ │ 成功响应 │ │ 超时/失败 │ │ 服务不可用│
│ │ 200 OK │ │ Timeout │ │ 503 │
│ └────┬─────┘ └────┬─────┘ └────┬─────┘
│ │ │ │
│ ▼ ▼ ▼
│ ┌──────────┐ ┌──────────────────────┐
│ │ 返回回复 │ │ 降级处理 │
│ │ reply │ │ 返回固定回复 │
│ │confidence│ │ "正在转接人工客服..." │
│ │shouldTransfer│ └──────────┬───────────┘
│ └──────────┘ │
│ ▼
│ ┌──────────────┐
│ │ 触发转人工 │
│ │ TransferCapable│
│ └──────────────┘
│
▼
┌──────────────────┐
│ 处理响应 │
│ - 保存消息 │
│ - 发送给用户 │
│ - 判断转人工 │
└──────────────────┘
```
## 5. 数据模型
### 5.1 实体关系图
```
┌──────────────────┐ ┌──────────────────┐
│ Session │ │ Message │
├──────────────────┤ ├──────────────────┤
│ sessionId (PK) │──────▶│ msgId (PK) │
│ customerId │ 1:N │ sessionId (FK) │
│ kfId │ │ senderType │
│ channelType (新) │ │ senderId │
│ status │ │ content │
│ wxServiceState │ │ msgType │
│ manualCsId │ │ rawData │
│ createdAt │ │ createdAt │
│ updatedAt │ └──────────────────┘
└──────────────────┘
│
│ 1:N
▼
┌──────────────────┐
│ TransferLog │
├──────────────────┤
│ id (PK) │
│ sessionId (FK) │
│ triggerReason │
│ triggerTime │
│ acceptedCsId │
│ acceptedTime │
└──────────────────┘
```
### 5.2 数据库变更
> **口径说明**：本次仅做最小 schema 变更，新增 `channel_type` 字段，默认值为 `wechat`；可通过在线 DDL 方式执行；不涉及数据迁移。符合 requirements.md 中"仅增加渠道类型字段，不进行大规模迁移"的范围约定。
| 表名 | 变更类型 | 变更内容 |
|-----|---------|---------|
| `session` | 新增字段 | `channel_type VARCHAR(20) DEFAULT 'wechat'` |
**DDL 示例**：
```sql
ALTER TABLE session ADD COLUMN channel_type VARCHAR(20) DEFAULT 'wechat'
COMMENT '渠道类型: wechat/douyin/jd';
```
### 5.3 Redis 缓存结构
| Key 模式 | 类型 | 说明 | TTL |
|---------|------|------|-----|
| `wecom:access_token` | String | 微信 access_token | 7200s - 300s |
| `wecom:cursor:{openKfId}` | String | 消息同步游标 | 永久 |
| `session:status:{sessionId}` | String | 会话状态缓存 | 24h |
| `session:msg_count:{sessionId}` | String | 消息计数 | 24h |
| `idempotent:{msgId}` | String | 消息幂等键 | 1h |
## 6. 跨模块调用策略
### 6.1 AI 服务调用
| 配置项 | 值 | 说明 |
|-------|---|------|
| **超时时间** | 5 秒 | 连接 + 读取总超时 |
| **重试次数** | 0 | 不重试，直接降级 |
| **熔断阈值** | 5 次/分钟 | 连续失败 5 次触发熔断 |
| **熔断时间** | 30 秒 | 熔断后等待时间 |
| **降级策略** | 返回固定回复 + 转人工 | 见下方降级逻辑 |
### 6.2 熔断器选型
> **选型决策**：使用 **Resilience4j** 作为熔断器实现，与 Spring Boot 2.7 兼容。
| 方案 | 说明 |
|-----|------|
| **Resilience4j** | 推荐。轻量级，支持断路器、限流、重试，与 Spring Boot 2.7 兼容良好 |
| 最小实现 | 仅做 timeout + fallback，不做熔断（不推荐，与 requirements 不一致） |
**熔断状态存储**：
- 单实例：内存存储（CircuitBreakerRegistry）
- 多实例：可扩展为 Redis 存储（通过 Resilience4j + Redis 实现）
**依赖配置**：
```xml
<dependency>
<groupId>io.github.resilience4j</groupId>
<artifactId>resilience4j-spring-boot2</artifactId>
<version>2.1.0</version>
</dependency>
```
### 6.3 降级逻辑
```java
@Service
public class AiServiceClientImpl implements AiServiceClient {
@CircuitBreaker(name = "aiService", fallbackMethod = "fallback")
@TimeLimiter(name = "aiService")
public ChatResponse generateReply(ChatRequest request) {
// HTTP 调用 Python AI 服务
}
public ChatResponse fallback(ChatRequest request, Throwable cause) {
log.warn("AI 服务降级: sessionId={}, cause={}",
request.getSessionId(), cause.getMessage());
ChatResponse response = new ChatResponse();
response.setReply("抱歉，我暂时无法回答您的问题，正在为您转接人工客服...");
response.setConfidence(0.0);
response.setShouldTransfer(true);
return response;
}
}
```
### 6.4 错误映射
| AI 服务错误 | 主框架处理 | 用户感知 |
|------------|-----------|---------|
| 200 OK | 正常处理 | 返回 AI 回复 |
| 400 Bad Request | 记录日志，降级 | 转人工 |
| 500 Internal Error | 记录日志，降级 | 转人工 |
| 503 Service Unavailable | 记录日志，降级 | 转人工 |
| Timeout | 记录日志，降级 | 转人工 |
| Connection Refused | 触发熔断，降级 | 转人工 |
## 7. 消息幂等性设计
### 7.1 幂等键
- 使用 `InboundMessage.channelMessageId` 作为幂等键
- 微信渠道：使用微信返回的 `msgId`
- 其他渠道：使用渠道返回的消息 ID 或生成唯一 ID
### 7.2 幂等处理流程
```
┌──────────────────┐
│ 收到消息 │
│ channelMessageId │
└────────┬─────────┘
│
▼
┌──────────────────┐ ┌──────────────────┐
│ Redis 检查 │────▶│ Key 不存在 │
│ idempotent:{msgId}│ │ 继续处理 │
└────────┬─────────┘ └────────┬─────────┘
│ │
▼ ▼
┌──────────────────┐ ┌──────────────────┐
│ Key 已存在 │ │ 设置 Key (TTL 1h)│
│ 跳过处理 │ │ 处理消息 │
└──────────────────┘ └──────────────────┘
```
### 7.3 实现代码
```java
public boolean processMessageIdempotent(String channelMessageId, Runnable processor) {
String key = "idempotent:" + channelMessageId;
Boolean absent = redisTemplate.opsForValue()
.setIfAbsent(key, "1", 1, TimeUnit.HOURS);
if (Boolean.TRUE.equals(absent)) {
processor.run();
return true;
}
log.info("重复消息，跳过处理: channelMessageId={}", channelMessageId);
return false;
}
```
## 8. 配置管理
### 8.1 新增配置项
```yaml
# application.yml 新增配置
ai-service:
url: http://ai-service:8080
timeout: 5000
resilience4j:
circuitbreaker:
instances:
aiService:
failure-rate-threshold: 50
sliding-window-size: 10
sliding-window-type: COUNT_BASED
wait-duration-in-open-state: 30s
permitted-number-of-calls-in-half-open-state: 3
timelimiter:
instances:
aiService:
timeout-duration: 5s
channel:
default: wechat
adapters:
wechat:
enabled: true
douyin:
enabled: false
jd:
enabled: false
```
### 8.2 配置类
```java
@Data
@Component
@ConfigurationProperties(prefix = "ai-service")
public class AiServiceConfig {
private String url;
private int timeout = 5000;
}
@Data
@Component
@ConfigurationProperties(prefix = "channel")
public class ChannelConfig {
private String default;
private Map<String, AdapterConfig> adapters;
@Data
public static class AdapterConfig {
private boolean enabled;
}
}
```
## 9. 部署架构
### 9.1 部署拓扑
```
┌─────────────────────────────────────────────────────────────┐
│ 负载均衡器 │
└─────────────────────────────┬───────────────────────────────┘
│
┌───────────────┼───────────────┐
▼ ▼ ▼
┌──────────┐ ┌──────────┐ ┌──────────┐
│ Java 主 │ │ Java 主 │ │ Java 主 │
│ 框架实例1│ │ 框架实例2│ │ 框架实例3│
└────┬─────┘ └────┬─────┘ └────┬─────┘
│ │ │
└──────────────┼──────────────┘
│
┌──────────────────┼──────────────────┐
▼ ▼ ▼
┌──────────┐ ┌──────────┐ ┌──────────┐
│ Redis │ │ MySQL │ │Python AI │
│ (Cluster)│ │ (Master) │ │ 服务 │
└──────────┘ └──────────┘ └──────────┘
```
### 9.2 服务依赖
| 服务 | 依赖关系 | 健康检查 |
|-----|---------|---------|
| Java 主框架 | 依赖 Redis, MySQL, Python AI | `/actuator/health` |
| Python AI 服务 | 无外部依赖 | `/ai/health` |
## 10. 安全设计
### 10.1 渠道回调鉴权
| 渠道 | 鉴权方式 | 验证逻辑 |
|-----|---------|---------|
| 微信 | msg_signature + timestamp + nonce | **沿用现有 WeCom 官方验签/解密方案**（复用现有 `WXBizMsgCrypt` 实现） |
| 抖音 | X-Signature + X-Timestamp | 待实现 |
| 京东 | signature + timestamp | 待实现 |
> **说明**：微信回调验签/加解密使用企业微信官方方案，具体算法细节封装在现有 `WXBizMsgCrypt` 类中，不在本设计文档展开。
### 10.2 内部服务鉴权
- Java 主框架 → Python AI 服务：内网调用，无需鉴权（可扩展为 mTLS）
- WebSocket 连接：路径参数 `{csId}` 标识身份（可扩展为 Token 验证）
## 11. 监控与告警
> **说明**：本节为后续演进预留，MVP 阶段可暂不实现。
### 11.1 关键指标
| 指标 | 类型 | 说明 |
|-----|------|------|
| `ai.service.latency` | Histogram | AI 服务调用延迟 |
| `ai.service.error.rate` | Counter | AI 服务错误率 |
| `ai.service.circuit.breaker.open` | Gauge | 熔断器状态 |
| `message.process.count` | Counter | 消息处理数量 |
| `message.idempotent.skip` | Counter | 幂等跳过数量 |
| `session.active.count` | Gauge | 活跃会话数 |
### 11.2 告警规则
| 规则 | 条件 | 级别 |
|-----|------|------|
| AI 服务不可用 | 连续失败 5 次 | Critical |
| AI 服务延迟过高 | P99 > 3s | Warning |
| 熔断器触发 | circuit.breaker.open = 1 | Critical |