docs(MCA): 更新进度文档 - TASK-010 完成

2026-02-24 01:04:59 +08:00 · 2026-02-24 01:04:59 +08:00 · 2631c53371
parent eb94eca920
commit 2631c53371
1 changed files with 72 additions and 54 deletions
--- a/docs/progress/ai-robot-mca-progress.md
+++ b/docs/progress/ai-robot-mca-progress.md
@ -28,8 +28,8 @@
 ## 📊 Overall Progress (Phases)

 - [x] Phase 1: 基础设施 (100%) ✅ [tasks.md: TASK-001 ~ TASK-005]
- [x] Phase 2: 渠道适配层 (100%) ✅ [tasks.md: TASK-010 ~ TASK-013]
- [ ] Phase 3: 消息路由层 (25%) 🔄 [tasks.md: TASK-020 ~ TASK-023]
+- [ ] Phase 2: 渠道适配层 (25%) 🔄 [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]

@ -38,29 +38,28 @@
 ## 🔄 Current Phase

 ### Goal
-完成 MessageRouterService 接口定义与实现，重构 MessageProcessService，更新 SessionManagerService。
+完成 ChannelAdapter 接口定义、WeChatAdapter 实现、ChannelAdapterFactory 创建、WecomCallbackController 重构。

 ### Sub Tasks
- [x] 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]
+- [x] TASK-010: 定义 ChannelAdapter 接口 ✅ [AC-MCA-01]
+- [ ] TASK-011: 实现 WeChatAdapter ⏳ [AC-MCA-02]
+- [ ] TASK-012: 创建 ChannelAdapterFactory ⏳ [AC-MCA-03]
+- [ ] TASK-013: 重构 WecomCallbackController ⏳ [AC-MCA-08]

 ### Next Action (Must be Specific)

-**Immediate**: 实现 `MessageRouterServiceImpl` 类。
+**Immediate**: 创建 `WeChatAdapter.java` 实现 ChannelAdapter 接口。

 **Details**:
-1. file: `src/main/java/com/wecom/robot/service/impl/MessageRouterServiceImpl.java`
-2. action: 实现 MessageRouterService 接口的所有方法
+1. file: `src/main/java/com/wecom/robot/adapter/WeChatAdapter.java`
+2. action: 将现有 WecomApiService 重构为 WeChatAdapter，实现 ChannelAdapter、ServiceStateCapable、TransferCapable、MessageSyncCapable 接口
 3. reference:
-   - `spec/ai-robot/design.md` 第 3.2 节（消息路由服务接口）
-   - `spec/ai-robot/design.md` 第 4.1 节（消息处理主流程）
+   - `spec/ai-robot/design.md` 第 3.1 节（渠道适配器接口）
+   - `src/main/java/com/wecom/robot/service/WecomApiService.java`（现有实现）
 4. constraints:
-   - 必须实现 processInboundMessage 完整流程
-   - 必须实现 routeBySessionState 根据状态路由
-   - 必须包含幂等性检查
-   - 代码/注释必须包含 [AC-MCA-08], [AC-MCA-09], [AC-MCA-10] 标注
+   - 实现 ChannelAdapter 核心接口
+   - 实现 ServiceStateCapable、TransferCapable、MessageSyncCapable
+   - 现有功能保持兼容

 ---

@ -71,20 +70,20 @@
 ```
 src/main/java/com/wecom/robot/
 ├── dto/
-│   ├── InboundMessage.java      # TASK-001
-│   ├── OutboundMessage.java     # TASK-001
-│   ├── SignatureInfo.java       # TASK-001
+│   ├── 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
+│   ├── 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
+│   ├── 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/
@ -94,9 +93,9 @@ src/main/java/com/wecom/robot/
 │       ├── MessageRouterServiceImpl.java # TASK-021
 │       └── AiServiceClientImpl.java      # TASK-031
 ├── util/
-│   └── IdempotentHelper.java    # TASK-005
+│   └── IdempotentHelper.java    # TASK-005 ✅
 └── entity/
-    └── Session.java             # TASK-003 更新
+    └── Session.java             # TASK-003 ✅
 ```

 ### Key Decisions (Why / Impact)
@ -113,25 +112,32 @@ src/main/java/com/wecom/robot/
  reason: 保持内部命名一致性，映射在 AiServiceClient 层处理
  impact: 避免后续 DTO 命名混乱

+- decision: ChannelAdapter 接口分离为核心能力和可选能力
+  reason: 不同渠道支持的能力不同，接口分离允许按需实现
+  impact: WeChatAdapter 实现全部接口，其他渠道可按需实现
+
 ### 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;
+// ChannelAdapter 接口定义 (design.md 3.1)
+public interface ChannelAdapter {
+    String getChannelType();
+    boolean sendMessage(OutboundMessage message);
+}
+
+// 可选能力接口
+public interface ServiceStateCapable {
+    ServiceStateResponse getServiceState(String kfId, String customerId);
+    boolean transServiceState(String kfId, String customerId, int newState, String servicerId);
+}
+
+public interface TransferCapable {
+    boolean transferToPool(String kfId, String customerId);
+    boolean transferToManual(String kfId, String customerId, String servicerId);
+}
+
+public interface MessageSyncCapable {
+    SyncMsgResponse syncMessages(String kfId, String cursor);
 }
 ```

@ -139,16 +145,6 @@ public class InboundMessage {

 ## 🧾 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/ 目录结构
@ -165,11 +161,33 @@ public class InboundMessage {
  - 新增 spec/ai-robot/design.md
  - 新增 spec/ai-robot/tasks.md

+### Session #2 (2026-02-24)
+- completed:
+  - TASK-001: 定义统一消息模型 DTO ✅
+  - TASK-002: 新增配置类 ✅
+  - TASK-003: 数据库 Schema 变更 ✅
+  - TASK-004: 添加 Resilience4j 依赖 ✅
+  - TASK-005: 消息幂等性工具类 ✅
+  - TASK-010: 定义 ChannelAdapter 接口 ✅
+- 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/util/IdempotentHelper.java
+  - 新增 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/entity/Session.java (新增 channelType 字段)
+  - 更新 pom.xml (新增 Resilience4j 依赖)
+
 ---

 ## 🚀 Startup Guide

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