ai-robot-channel/spec/ai-robot/tasks.md

---
feature_id: "MCA"
title: "多渠道适配主框架任务清单"
status: "draft"
version: "0.1.0"
owners:
  - "backend"
last_updated: "2026-02-24"
---

# 多渠道适配主框架任务清单（tasks.md）

## 任务概览

| 阶段 | 任务数 | 说明 |
|-----|-------|------|
| Phase 1: 基础设施 | 5 | 统一消息模型、配置、数据库 |
| Phase 2: 渠道适配层 | 4 | ChannelAdapter 接口与 WeChatAdapter 重构 |
| Phase 3: 消息路由层 | 4 | MessageRouterService 重构 |
| Phase 4: AI 服务客户端 | 4 | AiServiceClient 实现 |
| Phase 5: 集成测试 | 3 | 端到端测试 |

---

## Phase 1: 基础设施

### TASK-001: 定义统一消息模型 DTO
- **状态**: ✅ 已完成
- **优先级**: P0
- **关联 AC**: AC-MCA-08
- **描述**: 创建 `InboundMessage`、`OutboundMessage`、`SignatureInfo` 等 DTO 类
- **产出物**:
  - `src/main/java/com/wecom/robot/dto/InboundMessage.java`
  - `src/main/java/com/wecom/robot/dto/OutboundMessage.java`
  - `src/main/java/com/wecom/robot/dto/SignatureInfo.java`
- **验收标准**:
  - [x] DTO 类包含 design.md 2.1/2.2 定义的所有字段
  - [x] 包含 Lombok 注解 (@Data, @Builder)
  - [x] 单元测试覆盖字段映射

### TASK-002: 新增配置类
- **状态**: ⏳ 待开始
- **优先级**: P0
- **关联 AC**: AC-MCA-04
- **描述**: 创建 AI 服务配置类和渠道配置类
- **产出物**:
  - `src/main/java/com/wecom/robot/config/AiServiceConfig.java`
  - `src/main/java/com/wecom/robot/config/ChannelConfig.java`
  - `src/main/resources/application.yml` 更新
- **验收标准**:
  - [ ] 配置类可正确读取 application.yml
  - [ ] 包含默认值

### TASK-003: 数据库 Schema 变更
- **状态**: ⏳ 待开始
- **优先级**: P0
- **关联 AC**: AC-MCA-11
- **描述**: Session 表新增 channel_type 字段
- **产出物**:
  - `src/main/resources/db/migration/V1__add_channel_type.sql` (如使用 Flyway)
  - 或手动 DDL 脚本
- **验收标准**:
  - [ ] DDL 可在线执行
  - [ ] 默认值为 'wechat'
  - [ ] Session 实体类同步更新

### TASK-004: 添加 Resilience4j 依赖
- **状态**: ⏳ 待开始
- **优先级**: P1
- **关联 AC**: AC-MCA-06, AC-MCA-07
- **描述**: 在 pom.xml 添加 Resilience4j 依赖
- **产出物**:
  - `pom.xml` 更新
- **验收标准**:
  - [ ] 依赖正确添加
  - [ ] 项目可正常构建

### TASK-005: 消息幂等性工具类
- **状态**: ⏳ 待开始
- **优先级**: P0
- **关联 AC**: AC-MCA-11-IDEMPOTENT
- **描述**: 实现基于 Redis 的消息幂等性处理
- **产出物**:
  - `src/main/java/com/wecom/robot/util/IdempotentHelper.java`
- **验收标准**:
  - [ ] 使用 Redis SETNX 实现
  - [ ] TTL 1 小时
  - [ ] 单元测试覆盖

---

## Phase 2: 渠道适配层

### TASK-010: 定义 ChannelAdapter 接口
- **状态**: ⏳ 待开始
- **优先级**: P0
- **关联 AC**: AC-MCA-01
- **描述**: 创建核心能力接口和可选能力接口
- **产出物**:
  - `src/main/java/com/wecom/robot/adapter/ChannelAdapter.java`
  - `src/main/java/com/wecom/robot/adapter/ServiceStateCapable.java`
  - `src/main/java/com/wecom/robot/adapter/TransferCapable.java`
  - `src/main/java/com/wecom/robot/adapter/MessageSyncCapable.java`
- **验收标准**:
  - [ ] 接口定义与 design.md 3.1 一致
  - [ ] sendMessage 使用 OutboundMessage 参数

### TASK-011: 实现 WeChatAdapter
- **状态**: ⏳ 待开始
- **优先级**: P0
- **关联 AC**: AC-MCA-02
- **描述**: 将现有 WecomApiService 重构为 WeChatAdapter
- **产出物**:
  - `src/main/java/com/wecom/robot/adapter/WeChatAdapter.java`
- **验收标准**:
  - [ ] 实现 ChannelAdapter 核心接口
  - [ ] 实现 ServiceStateCapable、TransferCapable、MessageSyncCapable
  - [ ] 现有功能保持兼容

### TASK-012: 创建 ChannelAdapterFactory
- **状态**: ⏳ 待开始
- **优先级**: P1
- **关联 AC**: AC-MCA-03
- **描述**: 创建渠道适配器工厂，根据 channelType 获取对应适配器
- **产出物**:
  - `src/main/java/com/wecom/robot/adapter/ChannelAdapterFactory.java`
- **验收标准**:
  - [ ] 支持 wechat 渠道
  - [ ] 预留 douyin、jd 扩展点

### TASK-013: 重构 WecomCallbackController
- **状态**: ⏳ 待开始
- **优先级**: P0
- **关联 AC**: AC-MCA-08
- **描述**: Controller 负责验签/解密/解析，构建 InboundMessage
- **产出物**:
  - `src/main/java/com/wecom/robot/controller/WecomCallbackController.java` 更新
- **验收标准**:
  - [ ] 验签/解密逻辑保持不变
  - [ ] 输出 InboundMessage 传递给 MessageRouterService

---

## Phase 3: 消息路由层

### TASK-020: 定义 MessageRouterService 接口
- **状态**: ✅ 已完成
- **优先级**: P0
- **关联 AC**: AC-MCA-08
- **描述**: 创建渠道无关的消息路由服务接口
- **产出物**:
  - `src/main/java/com/wecom/robot/service/MessageRouterService.java`
- **验收标准**:
  - [x] 接口定义与 design.md 3.2 一致

### TASK-021: 实现 MessageRouterServiceImpl
- **状态**: ✅ 已完成
- **优先级**: P0
- **关联 AC**: AC-MCA-08, AC-MCA-09, AC-MCA-10
- **描述**: 实现消息路由核心逻辑
- **产出物**:
  - `src/main/java/com/wecom/robot/service/impl/MessageRouterServiceImpl.java`
- **验收标准**:
  - [x] processInboundMessage 实现完整流程
  - [x] routeBySessionState 根据状态路由
  - [x] 幂等性检查

### TASK-022: 重构 MessageProcessService
- **状态**: ✅ 已完成
- **优先级**: P0
- **关联 AC**: AC-MCA-08
- **描述**: 将现有 MessageProcessService 逻辑迁移到 MessageRouterServiceImpl
- **产出物**:
  - `src/main/java/com/wecom/robot/service/MessageProcessService.java` 更新或删除
- **验收标准**:
  - [x] 现有功能保持兼容
  - [x] 微信专属逻辑移至 WeChatAdapter

### TASK-023: 更新 SessionManagerService
- **状态**: ✅ 已完成
- **优先级**: P0
- **关联 AC**: AC-MCA-11, AC-MCA-12
- **描述**: 支持渠道类型字段
- **产出物**:
  - `src/main/java/com/wecom/robot/service/SessionManagerService.java` 更新
  - `src/main/java/com/wecom/robot/entity/Session.java` 更新
- **验收标准**:
  - [x] 创建会话时记录 channelType
  - [x] 支持按 channelType 筛选

---

## Phase 4: AI 服务客户端

### TASK-030: 定义 AI 服务 DTO
- **状态**: ⏳ 待开始
- **优先级**: P0
- **关联 AC**: AC-MCA-04-REQ, AC-MCA-05
- **描述**: 创建 ChatRequest、ChatResponse DTO
- **产出物**:
  - `src/main/java/com/wecom/robot/dto/ai/ChatRequest.java`
  - `src/main/java/com/wecom/robot/dto/ai/ChatResponse.java`
- **验收标准**:
  - [ ] 字段与 openapi.deps.yaml 一致
  - [ ] 包含映射方法 (InboundMessage → ChatRequest)

### TASK-031: 实现 AiServiceClient
- **状态**: ⏳ 待开始
- **优先级**: P0
- **关联 AC**: AC-MCA-04, AC-MCA-05
- **描述**: 实现 HTTP 调用 Python AI 服务
- **产出物**:
  - `src/main/java/com/wecom/robot/service/AiServiceClient.java`
  - `src/main/java/com/wecom/robot/service/impl/AiServiceClientImpl.java`
- **验收标准**:
  - [ ] 使用 RestTemplate 调用 /ai/chat
  - [ ] 超时 5 秒
  - [ ] 正确映射字段

### TASK-032: 实现熔断与降级
- **状态**: ⏳ 待开始
- **优先级**: P1
- **关联 AC**: AC-MCA-06, AC-MCA-07
- **描述**: 使用 Resilience4j 实现熔断和降级
- **产出物**:
  - `src/main/java/com/wecom/robot/service/impl/AiServiceClientImpl.java` 更新
  - `src/main/resources/application.yml` 更新
- **验收标准**:
  - [ ] @CircuitBreaker 注解配置
  - [ ] @TimeLimiter 注解配置
  - [ ] fallback 方法返回降级回复

### TASK-033: 删除旧 AiService
- **状态**: ⏳ 待开始
- **优先级**: P2
- **关联 AC**: -
- **描述**: 删除旧的 AiService 类，清理相关配置
- **产出物**:
  - 删除 `src/main/java/com/wecom/robot/service/AiService.java`
  - 删除 `src/main/java/com/wecom/robot/config/AiConfig.java`
- **验收标准**:
  - [ ] 无编译错误
  - [ ] 无运行时错误

---

## Phase 5: 集成测试

### TASK-040: 微信回调端到端测试
- **状态**: ⏳ 待开始
- **优先级**: P0
- **关联 AC**: AC-MCA-08, AC-MCA-09, AC-MCA-10
- **描述**: 测试微信回调完整流程
- **产出物**:
  - `src/test/java/com/wecom/robot/integration/WecomCallbackIntegrationTest.java`
- **验收标准**:
  - [ ] 消息正确路由到 AI 服务
  - [ ] 消息正确路由到人工客服
  - [ ] 幂等性验证

### TASK-041: AI 服务调用测试
- **状态**: ⏳ 待开始
- **优先级**: P0
- **关联 AC**: AC-MCA-04, AC-MCA-05, AC-MCA-06, AC-MCA-07
- **描述**: 测试 AI 服务调用、超时、降级
- **产出物**:
  - `src/test/java/com/wecom/robot/service/AiServiceClientTest.java`
- **验收标准**:
  - [ ] 正常调用返回正确响应
  - [ ] 超时触发降级
  - [ ] 熔断触发降级

### TASK-042: 会话管理测试
- **状态**: ⏳ 待开始
- **优先级**: P1
- **关联 AC**: AC-MCA-11, AC-MCA-12
- **描述**: 测试会话创建、状态变更、渠道类型
- **产出物**:
  - `src/test/java/com/wecom/robot/service/SessionManagerServiceTest.java`
- **验收标准**:
  - [ ] 会话创建包含 channelType
  - [ ] 支持按 channelType 筛选

---

## 待澄清事项

| ID | 问题 | 状态 | 备注 |
|----|------|------|------|
| CLARIFY-001 | AI 服务超时时间确认 | ✅ 已确认 | 5 秒 |
| CLARIFY-002 | 降级回复策略确认 | ✅ 已确认 | 返回固定回复 + 转人工 |
| CLARIFY-003 | 历史消息数量限制 | ✅ 已确认 | 50 条（openapi.deps.yaml） |
| CLARIFY-004 | 渠道扩展优先级 | ✅ 已确认 | WeChat → Douyin → JD |
| CLARIFY-005 | Python AI 服务部署方式 | ⏳ 待确认 | 独立进程 / Docker / K8s |

---

## 任务依赖关系

```
Phase 1 (基础设施)
    │
    ├── TASK-001 (DTO) ─────────────────────────────────────────┐
    ├── TASK-002 (配置) ────────────────────────────────────────┤
    ├── TASK-003 (数据库) ──────────────────────────────────────┤
    ├── TASK-004 (Resilience4j) ──┐                             │
    └── TASK-005 (幂等性) ────────┤                             │
                                 │                             │
Phase 2 (渠道适配层)             │                             │
    │                            │                             │
    ├── TASK-010 (接口) ◄────────┼─────────────────────────────┤
    ├── TASK-011 (WeChatAdapter) ◄┘                             │
    ├── TASK-012 (Factory)                                      │
    └── TASK-013 (Controller) ◄─────────────────────────────────┘
                                 │
Phase 3 (消息路由层)             │
    │                            │
    ├── TASK-020 (接口) ◄────────┘
    ├── TASK-021 (实现)
    ├── TASK-022 (重构)
    └── TASK-023 (Session)
                                 │
Phase 4 (AI 服务客户端)          │
    │                            │
    ├── TASK-030 (DTO) ◄─────────┘
    ├── TASK-031 (实现)
    ├── TASK-032 (熔断)
    └── TASK-033 (清理)
                                 │
Phase 5 (集成测试)               │
    │                            │
    ├── TASK-040 ◄───────────────┘
    ├── TASK-041
    └── TASK-042
```

---

## 进度统计

| 指标 | 数值 |
|-----|------|
| 总任务数 | 20 |
| 已完成 | 4 |
| 进行中 | 0 |
| 待开始 | 16 |
| 完成率 | 20% |