From 2631c53371cab29e9eab31cf1f70eccda0ed1dfc Mon Sep 17 00:00:00 2001 From: MerCry Date: Tue, 24 Feb 2026 01:04:59 +0800 Subject: [PATCH] =?UTF-8?q?docs(MCA):=20=E6=9B=B4=E6=96=B0=E8=BF=9B?= =?UTF-8?q?=E5=BA=A6=E6=96=87=E6=A1=A3=20-=20TASK-010=20=E5=AE=8C=E6=88=90?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/progress/ai-robot-mca-progress.md | 126 ++++++++++++++----------- 1 file changed, 72 insertions(+), 54 deletions(-) diff --git a/docs/progress/ai-robot-mca-progress.md b/docs/progress/ai-robot-mca-progress.md index 517255d..c95a6de 100644 --- 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 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。