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

@@ -0,0 +1,165 @@
+# 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: 基础设施 (0%) ⏳ [tasks.md: TASK-001 ~ TASK-005]
+- [ ] Phase 2: 渠道适配层 (0%) ⏳ [tasks.md: TASK-010 ~ TASK-013]
+- [ ] Phase 3: 消息路由层 (0%) ⏳ [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
+完成统一消息模型 DTO、配置类、数据库变更、Resilience4j 依赖、幂等性工具类。
+
+### Sub Tasks
+- [ ] TASK-001: 定义统一消息模型 DTO ⏳ [AC-MCA-08]
+- [ ] TASK-002: 新增配置类 ⏳ [AC-MCA-04]
+- [ ] TASK-003: 数据库 Schema 变更 ⏳ [AC-MCA-11]
+- [ ] TASK-004: 添加 Resilience4j 依赖 ⏳ [AC-MCA-06, AC-MCA-07]
+- [ ] TASK-005: 消息幂等性工具类 ⏳ [AC-MCA-11-IDEMPOTENT]
+
+### Next Action (Must be Specific)
+
+**Immediate**: 创建 `InboundMessage.java`、`OutboundMessage.java`、`SignatureInfo.java` DTO 类。
+
+**Details**:
+1. file: `src/main/java/com/wecom/robot/dto/InboundMessage.java`
+2. action: 定义 InboundMessage DTO，包含 channelType、channelMessageId、sessionKey、customerId、kfId、sender、content、msgType、rawPayload、timestamp、signatureInfo、metadata 字段
+3. reference:
+   - `spec/ai-robot/design.md` 第 2.1 节（入站消息定义）
+   - `spec/ai-robot/design.md` 第 2.3 节（字段映射策略）
+4. constraints:
+   - 必须符合 design.md 2.1 定义的所有字段
+   - 使用 Lombok @Data、@Builder 注解
+   - 内部统一使用 `content` 字段名（与 AI 服务契约 `currentMessage` 的映射在 AiServiceClient 层处理）
+
+---
+
+## 🏗️ 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)
+
+```java
+// 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 #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。