MerCry
/
ai-robot-channel
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
ai-robot-channel/docs/progress/ai-robot-mca-progress.md

10 KiB
Raw Blame History

ai-robot-MCA - Progress

多渠道适配主框架架构改造进度文档 遵循 docs/session-handoff-protocol.md 协议

📋 Context

  • module: ai-robot
  • feature: MCA (Multi-Channel Adapter)
  • status: 🔄 进行中

🔗 Spec References (SSOT)

  • agents: AGENTS.md
  • contracting: spec/contracting.md
  • requirements: spec/ai-robot/requirements.md
  • openapi_provider: spec/ai-robot/openapi.provider.yaml
  • openapi_deps: spec/ai-robot/openapi.deps.yaml
  • design: spec/ai-robot/design.md
  • tasks: spec/ai-robot/tasks.md

📊 Overall Progress (Phases)

  • Phase 1: 基础设施 (100%) ✅ [tasks.md: TASK-001 ~ TASK-005]
  • Phase 2: 渠道适配层 (100%) ✅ [tasks.md: TASK-010 ~ TASK-013]
  • Phase 3: 消息路由层 (100%) ✅ [tasks.md: TASK-020 ~ TASK-023]
  • Phase 4: AI 服务客户端 (100%) ✅ [tasks.md: TASK-030 ~ TASK-033]
  • Phase 5: 集成测试 (0%) ⏳ [tasks.md: TASK-040 ~ TASK-042]

🔄 Current Phase

Goal

完成集成测试，验证多渠道适配框架的完整功能。

Sub Tasks

  • TASK-030: 定义 AI 服务 DTO ✅ [AC-MCA-04-REQ, AC-MCA-05]
  • TASK-031: 实现 AiServiceClient ✅ [AC-MCA-04, AC-MCA-05]
  • TASK-032: 实现熔断与降级 ✅ [AC-MCA-06, AC-MCA-07]
  • TASK-033: 删除旧 AiService ✅
  • TASK-040: 集成测试 ⏳
  • TASK-041: 端到端测试 ⏳
  • TASK-042: 性能测试 ⏳

Next Action (Must be Specific)

Immediate: 执行 Phase 5 集成测试任务。

Details:

  1. task: TASK-040 集成测试
  2. action: 编写集成测试验证消息路由流程
  3. reference:
    • spec/ai-robot/tasks.md TASK-040 定义
  4. constraints:
    • 测试覆盖 InboundMessage → AI Service → OutboundMessage 完整流程
    • 验证幂等性、熔断降级逻辑

🏗️ Technical Context

Module Structure (Only What Matters)

src/main/java/com/wecom/robot/
├── dto/
│   ├── InboundMessage.java      # TASK-001 ✅
│   ├── OutboundMessage.java     # TASK-001 ✅
│   ├── SignatureInfo.java       # TASK-001 ✅
│   └── ai/
│       ├── ChatRequest.java     # TASK-030
│       └── ChatResponse.java    # TASK-030
├── config/
│   ├── AiServiceConfig.java     # TASK-002 ✅
│   └── ChannelConfig.java       # TASK-002 ✅
├── adapter/
│   ├── ChannelAdapter.java      # TASK-010 ✅
│   ├── ServiceStateCapable.java # TASK-010 ✅
│   ├── TransferCapable.java     # TASK-010 ✅
│   ├── MessageSyncCapable.java  # TASK-010 ✅
│   ├── WeChatAdapter.java       # TASK-011 ✅
│   └── ChannelAdapterFactory.java # TASK-012 ✅
├── service/
│   ├── MessageRouterService.java      # TASK-020 ✅
│   ├── AiServiceClient.java           # TASK-031
│   └── impl/
│       ├── MessageRouterServiceImpl.java # TASK-021 ✅
│       └── AiServiceClientImpl.java      # TASK-031
├── util/
│   └── IdempotentHelper.java    # TASK-005 ✅
└── entity/
    └── Session.java             # TASK-003 ✅

Key Decisions (Why / Impact)

  • decision: 统一消息模型 (InboundMessage/OutboundMessage) reason: 实现渠道无关的消息处理，Controller 层负责验签/解析，Router 层处理统一消息 impact: 后续新增渠道只需实现 ChannelAdapter，无需修改核心路由逻辑

  • decision: 使用 Resilience4j 实现熔断 reason: 与 Spring Boot 2.7 兼容良好，支持断路器、限流、超时 impact: AI 服务调用具备熔断/降级能力，提升系统稳定性

  • decision: 内部字段统一用 content，AI 服务契约用 currentMessage reason: 保持内部命名一致性，映射在 AiServiceClient 层处理 impact: 避免后续 DTO 命名混乱

  • decision: ChannelAdapter 接口分离为核心能力和可选能力 reason: 不同渠道支持的能力不同，接口分离允许按需实现 impact: WeChatAdapter 实现全部接口，其他渠道可按需实现

Code Snippets (Reference)

// ChannelAdapter 接口定义 (design.md 3.1)
public interface ChannelAdapter {
    String getChannelType();
    boolean sendMessage(OutboundMessage message);
}

// MessageRouterService 接口定义 (design.md 3.2)
public interface MessageRouterService {
    void processInboundMessage(InboundMessage message);
    void routeBySessionState(Session session, InboundMessage message);
    void dispatchToAiService(Session session, InboundMessage message);
    void dispatchToManualCs(Session session, InboundMessage message);
    void dispatchToPendingPool(Session session, InboundMessage message);
}

🧾 Session History

Session #4 (2026-02-24)

  • completed:
    • TASK-001: 定义统一消息模型 DTO ✅
    • TASK-002: 新增配置类 ✅
    • TASK-003: 数据库 Schema 变更 ✅
    • TASK-004: 添加 Resilience4j 依赖 ✅
    • TASK-005: 消息幂等性工具类 ✅
    • TASK-030: 定义 AI 服务 DTO ✅
    • TASK-031: 实现 AiServiceClient ✅
    • TASK-032: 实现熔断与降级 ✅
    • TASK-033: 删除旧 AiService ✅
  • changes:
    • 新增 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
    • 新增 src/main/java/com/wecom/robot/config/AiServiceConfig.java
    • 新增 src/main/java/com/wecom/robot/config/ChannelConfig.java
    • 新增 src/main/java/com/wecom/robot/config/RestTemplateConfig.java
    • 新增 src/main/java/com/wecom/robot/util/IdempotentHelper.java
    • 新增 src/main/java/com/wecom/robot/dto/ai/ChatRequest.java
    • 新增 src/main/java/com/wecom/robot/dto/ai/ChatResponse.java
    • 新增 src/main/java/com/wecom/robot/dto/ai/ChatMessage.java
    • 新增 src/main/java/com/wecom/robot/service/AiServiceClient.java
    • 新增 src/main/java/com/wecom/robot/service/impl/AiServiceClientImpl.java
    • 新增 src/main/resources/db/migration/V1__add_channel_type.sql
    • 删除 src/main/java/com/wecom/robot/service/AiService.java
    • 删除 src/main/java/com/wecom/robot/config/AiConfig.java
    • 更新 src/main/resources/application.yml (添加 ai-service, channel, resilience4j 配置)
    • 更新 src/main/java/com/wecom/robot/service/impl/MessageRouterServiceImpl.java
    • 更新 src/main/java/com/wecom/robot/controller/DebugController.java
    • 更新 pom.xml (添加 Resilience4j 依赖)
  • commits: 多个独立 commit

Session #3 (2026-02-24)

  • completed:
    • TASK-010: 定义 ChannelAdapter 接口 ✅
    • TASK-011: 实现 WeChatAdapter ✅
    • TASK-012: 创建 ChannelAdapterFactory ✅
    • TASK-013: 重构 WecomCallbackController ✅
    • TASK-022: 重构 MessageProcessService ✅
  • changes:
    • 新增 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
    • 新增 src/main/java/com/wecom/robot/adapter/WeChatAdapter.java
    • 新增 src/main/java/com/wecom/robot/adapter/ChannelAdapterFactory.java
    • 更新 src/main/java/com/wecom/robot/controller/WecomCallbackController.java
    • 更新 src/main/java/com/wecom/robot/service/MessageProcessService.java
  • commits: 4e9c5ba, 2631c53, 07561fe

Session #2 (2026-02-24)

  • completed:
    • TASK-020: 定义 MessageRouterService 接口
    • TASK-021: 实现 MessageRouterServiceImpl
    • 创建 src/main/java/com/wecom/robot/service/MessageRouterService.java
    • 创建 src/main/java/com/wecom/robot/service/impl/MessageRouterServiceImpl.java
    • 实现 5 个核心方法：processInboundMessage, routeBySessionState, dispatchToAiService, dispatchToManualCs, dispatchToPendingPool
    • 实现幂等性检查（基于 Redis SETNX）
  • changes:
    • 新增 src/main/java/com/wecom/robot/service/MessageRouterService.java
    • 新增 src/main/java/com/wecom/robot/service/impl/MessageRouterServiceImpl.java
    • 更新 docs/progress/ai-robot-mca-progress.md
    • 更新 spec/ai-robot/tasks.md
  • commits: b9792c8, 0b6fcf5

Session #2 (2026-02-24)

  • completed:
    • TASK-020: 定义 MessageRouterService 接口
    • TASK-021: 实现 MessageRouterServiceImpl
    • TASK-022: 重构 MessageProcessService
    • TASK-023: 更新 SessionManagerService 支持 channelType
    • 创建 src/main/java/com/wecom/robot/service/MessageRouterService.java
    • 创建 src/main/java/com/wecom/robot/service/impl/MessageRouterServiceImpl.java
    • 更新 Session 实体添加 channelType 字段
    • 更新 SessionManagerService 支持按渠道类型创建和筛选会话
    • 实现 5 个核心方法：processInboundMessage, routeBySessionState, dispatchToAiService, dispatchToManualCs, dispatchToPendingPool
    • 实现幂等性检查（基于 Redis SETNX）
  • changes:
    • 新增 src/main/java/com/wecom/robot/service/MessageRouterService.java
    • 新增 src/main/java/com/wecom/robot/service/impl/MessageRouterServiceImpl.java
    • 更新 src/main/java/com/wecom/robot/service/MessageProcessService.java
    • 更新 src/main/java/com/wecom/robot/entity/Session.java
    • 更新 src/main/java/com/wecom/robot/service/SessionManagerService.java
    • 更新 docs/progress/ai-robot-mca-progress.md
    • 更新 spec/ai-robot/tasks.md
  • commits: b9792c8, 0b6fcf5, db378af, a8d7474

Session #1 (2026-02-24)

  • completed:
    • 创建 spec/ai-robot/ 目录结构
    • 编写 requirements.md (v0.2.0)
    • 编写 openapi.deps.yaml (L0)
    • 编写 openapi.provider.yaml (L0)
    • 编写 design.md (v0.2.0)
    • 编写 tasks.md (20 个任务)
    • 所有规范文件已提交到 Git
  • changes:
    • 新增 spec/ai-robot/requirements.md
    • 新增 spec/ai-robot/openapi.deps.yaml
    • 新增 spec/ai-robot/openapi.provider.yaml
    • 新增 spec/ai-robot/design.md
    • 新增 spec/ai-robot/tasks.md

🚀 Startup Guide

  1. 读取本进度文档，定位当前 Phase 与 Next Action。
  2. 打开并阅读 Spec References 指向的模块规范（requirements/openapi/design/tasks）。
  3. 直接执行 Next Action（TASK-030: 创建 ChatRequest/ChatResponse DTO）。
  4. 每完成一个子任务，更新本进度文档并提交 Git。