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

8.3 KiB
Raw Blame History

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

多渠道适配主框架架构改造（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 服务独立部署，主框架通过内网调用