diff --git a/spec/ai-robot/tasks.md b/spec/ai-robot/tasks.md new file mode 100644 index 0000000..87abb81 --- /dev/null +++ b/spec/ai-robot/tasks.md @@ -0,0 +1,347 @@ +--- +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` +- **验收标准**: + - [ ] 接口定义与 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 | +| 已完成 | 0 | +| 进行中 | 0 | +| 待开始 | 20 | +| 完成率 | 0% |