ai-robot-channel/docs/progress/ai-robot-mca-progress.md

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: 消息路由层 (25%) 🔄 [tasks.md: TASK-020 ~ TASK-023]
• Phase 4: AI 服务客户端 (0%) ⏳ [tasks.md: TASK-030 ~ TASK-033]
• Phase 5: 集成测试 (0%) ⏳ [tasks.md: TASK-040 ~ TASK-042]

---

🔄 Current Phase

Goal

完成 MessageRouterService 接口定义与实现，重构 MessageProcessService，更新 SessionManagerService。

Sub Tasks

• TASK-020: 定义 MessageRouterService 接口 ✅ [AC-MCA-08]
• TASK-021: 实现 MessageRouterServiceImpl ⏳ [AC-MCA-08, AC-MCA-09, AC-MCA-10]
• TASK-022: 重构 MessageProcessService ⏳ [AC-MCA-08]
• TASK-023: 更新 SessionManagerService ⏳ [AC-MCA-11, AC-MCA-12]

Next Action (Must be Specific)

Immediate: 实现 MessageRouterServiceImpl 类。

Details:

1. file: src/main/java/com/wecom/robot/service/impl/MessageRouterServiceImpl.java
2. action: 实现 MessageRouterService 接口的所有方法
3. reference:
   • spec/ai-robot/design.md 第 3.2 节（消息路由服务接口）
   • spec/ai-robot/design.md 第 4.1 节（消息处理主流程）
4. constraints:
   • 必须实现 processInboundMessage 完整流程
   • 必须实现 routeBySessionState 根据状态路由
   • 必须包含幂等性检查
   • 代码/注释必须包含 [AC-MCA-08], [AC-MCA-09], [AC-MCA-10] 标注

---

🏗️ 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 命名混乱

Code Snippets (Reference)

// InboundMessage 结构参考 (design.md 2.1)
@Data
@Builder
public class InboundMessage {
    private String channelType;           // wechat/douyin/jd
    private String channelMessageId;      // 渠道原始消息ID (幂等键)
    private String sessionKey;            // 会话标识
    private String customerId;
    private String kfId;
    private String sender;
    private String content;               // 统一字段名
    private String msgType;
    private String rawPayload;
    private Long timestamp;
    private SignatureInfo signatureInfo;
    private Map<String, Object> metadata;
}

---

🧾 Session History

Session #2 (2026-02-24)

• completed:
  • TASK-020: 定义 MessageRouterService 接口
  • 创建 src/main/java/com/wecom/robot/service/MessageRouterService.java
  • 定义 5 个核心方法：processInboundMessage, routeBySessionState, dispatchToAiService, dispatchToManualCs, dispatchToPendingPool
• changes:
  • 新增 src/main/java/com/wecom/robot/service/MessageRouterService.java
  • 更新 docs/progress/ai-robot-mca-progress.md
• commit: b9792c8

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-001: 创建 InboundMessage 等 DTO）。
4. 每完成一个子任务，更新本进度文档并提交 Git。