From cf9cd75f13f440d33fcd1a06627aa0beefcff9b5 Mon Sep 17 00:00:00 2001 From: MerCry Date: Tue, 24 Feb 2026 00:27:13 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=B7=BB=E5=8A=A0=E5=A4=9A=E6=B8=A0?= =?UTF-8?q?=E9=81=93=E9=80=82=E9=85=8D=E4=B8=BB=E6=A1=86=E6=9E=B6=E9=9C=80?= =?UTF-8?q?=E6=B1=82=E8=A7=84=E8=8C=83=20[AC-INIT]?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- spec/ai-robot/requirements.md | 189 ++++++++++++++++++++++++++++++++++ 1 file changed, 189 insertions(+) create mode 100644 spec/ai-robot/requirements.md diff --git a/spec/ai-robot/requirements.md b/spec/ai-robot/requirements.md new file mode 100644 index 0000000..df0b654 --- /dev/null +++ b/spec/ai-robot/requirements.md @@ -0,0 +1,189 @@ +--- +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 服务独立部署，主框架通过内网调用