--- 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` - **验收标准**: - [ ] DTO 类包含 design.md 2.1/2.2 定义的所有字段 - [ ] 包含 Lombok 注解 (@Data, @Builder) - [ ] 单元测试覆盖字段映射 ### 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` - **验收标准**: - [ ] processInboundMessage 实现完整流程 - [ ] routeBySessionState 根据状态路由 - [ ] 幂等性检查 ### TASK-022: 重构 MessageProcessService - **状态**: ⏳ 待开始 - **优先级**: P0 - **关联 AC**: AC-MCA-08 - **描述**: 将现有 MessageProcessService 逻辑迁移到 MessageRouterServiceImpl - **产出物**: - `src/main/java/com/wecom/robot/service/MessageProcessService.java` 更新或删除 - **验收标准**: - [ ] 现有功能保持兼容 - [ ] 微信专属逻辑移至 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 | | 已完成 | 1 | | 进行中 | 0 | | 待开始 | 19 | | 完成率 | 5% |