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 服务独立部署，主框架通过内网调用