348 lines
12 KiB
Markdown
348 lines
12 KiB
Markdown
---
|
||
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` 更新
|
||
- **验收标准**:
|
||
- [ ] 创建会话时记录 channelType
|
||
- [ ] 支持按 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 |
|
||
| 已完成 | 2 |
|
||
| 进行中 | 0 |
|
||
| 待开始 | 18 |
|
||
| 完成率 | 10% |
|