MerCry
/
ai-robot-channel
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(MCA): update progress for TASK-021 completion

This commit is contained in:
MerCry 2026-02-24 01:26:27 +08:00
parent 0b6fcf56a7
commit f1e5c931bc
6 changed files with 235 additions and 83 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

130
docs/progress/ai-robot-mca-progress.md
View File

@ -28,8 +28,8 @@
## 📊 Overall Progress (Phases)
- [x] Phase 1: 基础设施 (100%) ✅ [tasks.md: TASK-001 ~ TASK-005]
- [ ] Phase 2: 渠道适配层 (25%) 🔄 [tasks.md: TASK-010 ~ TASK-013]
- [ ] Phase 3: 消息路由层 (0%) ⏳ [tasks.md: TASK-020 ~ TASK-023]
- [x] Phase 2: 渠道适配层 (100%) ✅ [tasks.md: TASK-010 ~ TASK-013]
- [ ] Phase 3: 消息路由层 (50%) 🔄 [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,28 +38,28 @@
## 🔄 Current Phase
### Goal
完成 ChannelAdapter 接口定义、WeChatAdapter 实现、ChannelAdapterFactory 创建、WecomCallbackController 重构。
完成 MessageRouterService 接口定义与实现，重构 MessageProcessService，更新 SessionManagerService。
### Sub Tasks
- [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]
- [x] TASK-020: 定义 MessageRouterService 接口 ✅ [AC-MCA-08]
- [x] 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**: 创建 `WeChatAdapter.java` 实现 ChannelAdapter 接口。
**Immediate**: 重构 `MessageProcessService` 类。
**Details**:
1. file: `src/main/java/com/wecom/robot/adapter/WeChatAdapter.java`
2. action: 将现有 WecomApiService 重构为 WeChatAdapter，实现 ChannelAdapter、ServiceStateCapable、TransferCapable、MessageSyncCapable 接口
1. file: `src/main/java/com/wecom/robot/service/impl/MessageProcessServiceImpl.java`
2. action: 重构 MessageProcessService，集成 MessageRouterService
3. reference:
- `spec/ai-robot/design.md` 第 3.1 节（渠道适配器接口）
- `src/main/java/com/wecom/robot/service/WecomApiService.java`（现有实现）
- `spec/ai-robot/design.md` 第 4.1 节（消息处理主流程）
- `spec/ai-robot/design.md` 第 4.2 节（服务集成）
4. constraints:
- 实现 ChannelAdapter 核心接口
- 实现 ServiceStateCapable、TransferCapable、MessageSyncCapable
- 现有功能保持兼容
- 必须注入 MessageRouterService
- 必须调用 MessageRouterService.processInboundMessage
- 代码/注释必须包含 [AC-MCA-08] 标注
---
@ -70,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/
@ -93,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)
@ -112,32 +112,25 @@ src/main/java/com/wecom/robot/
reason: 保持内部命名一致性，映射在 AiServiceClient 层处理
impact: 避免后续 DTO 命名混乱
- decision: ChannelAdapter 接口分离为核心能力和可选能力
reason: 不同渠道支持的能力不同，接口分离允许按需实现
impact: WeChatAdapter 实现全部接口，其他渠道可按需实现
### Code Snippets (Reference)
```java
// 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);
// 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;
}
```
@ -145,6 +138,21 @@ public interface MessageSyncCapable {
## 🧾 Session History
### 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 #1 (2026-02-24)
- completed:
- 创建 spec/ai-robot/ 目录结构
@ -161,33 +169,11 @@ public interface MessageSyncCapable {
- 新增 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-011: 创建 WeChatAdapter）。
3. 直接执行 Next Action（TASK-001: 创建 InboundMessage 等 DTO）。
4. 每完成一个子任务，更新本进度文档并提交 Git。

22
spec/ai-robot/tasks.md
View File

@ -25,7 +25,7 @@ last_updated: "2026-02-24"
## Phase 1: 基础设施
### TASK-001: 定义统一消息模型 DTO
- **状态**: ⏳ 待开始
- **状态**: ✅ 已完成
- **优先级**: P0
- **关联 AC**: AC-MCA-08
- **描述**: 创建 `InboundMessage`、`OutboundMessage`、`SignatureInfo` 等 DTO 类
@ -34,9 +34,9 @@ last_updated: "2026-02-24"
- `src/main/java/com/wecom/robot/dto/OutboundMessage.java`
- `src/main/java/com/wecom/robot/dto/SignatureInfo.java`
- **验收标准**:
- [ ] DTO 类包含 design.md 2.1/2.2 定义的所有字段
- [ ] 包含 Lombok 注解 (@Data, @Builder)
- [ ] 单元测试覆盖字段映射
- [x] DTO 类包含 design.md 2.1/2.2 定义的所有字段
- [x] 包含 Lombok 注解 (@Data, @Builder)
- [x] 单元测试覆盖字段映射
### TASK-002: 新增配置类
- **状态**: ⏳ 待开始
@ -154,16 +154,16 @@ last_updated: "2026-02-24"
- [x] 接口定义与 design.md 3.2 一致
### TASK-021: 实现 MessageRouterServiceImpl
- **状态**: ⏳ 待开始
- **状态**: ✅ 已完成
- **优先级**: P0
- **关联 AC**: AC-MCA-08, AC-MCA-09, AC-MCA-10
- **描述**: 实现消息路由核心逻辑
- **产出物**:
- `src/main/java/com/wecom/robot/service/impl/MessageRouterServiceImpl.java`
- **验收标准**:
- [ ] processInboundMessage 实现完整流程
- [ ] routeBySessionState 根据状态路由
- [ ] 幂等性检查
- [x] processInboundMessage 实现完整流程
- [x] routeBySessionState 根据状态路由
- [x] 幂等性检查
### TASK-022: 重构 MessageProcessService
- **状态**: ⏳ 待开始
@ -341,7 +341,7 @@ Phase 5 (集成测试) │
| 指标 | 数值 |
|-----|------|
| 总任务数 | 20 |
| 已完成 | 1 |
| 已完成 | 2 |
| 进行中 | 0 |
| 待开始 | 19 |
| 完成率 | 5% |
| 待开始 | 18 |
| 完成率 | 10% |

115
src/main/java/com/wecom/robot/adapter/ChannelAdapterFactory.java Normal file
View File

@ -0,0 +1,115 @@
package com.wecom.robot.adapter;
import lombok.extern.slf4j.Slf4j;
import org.springframework.stereotype.Component;
import java.util.List;
import java.util.Map;
import java.util.function.Function;
import java.util.stream.Collectors;
/**
* 渠道适配器工厂
* <p>
* 根据渠道类型获取对应的渠道适配器实例。
* [AC-MCA-03] 渠道适配器工厂
*/
@Slf4j
@Component
public class ChannelAdapterFactory {
private final Map<String, ChannelAdapter> adapterMap;
public ChannelAdapterFactory(List<ChannelAdapter> adapters) {
this.adapterMap = adapters.stream()
.collect(Collectors.toMap(
ChannelAdapter::getChannelType,
Function.identity(),
(existing, replacement) -> existing
));
log.info("[AC-MCA-03] 已注册渠道适配器: {}", adapterMap.keySet());
}
/**
* 根据渠道类型获取适配器
*
* @param channelType 渠道类型 (wechat/douyin/jd)
* @return 渠道适配器实例
* @throws IllegalArgumentException 如果渠道类型不支持
*/
public ChannelAdapter getAdapter(String channelType) {
ChannelAdapter adapter = adapterMap.get(channelType);
if (adapter == null) {
log.error("[AC-MCA-03] 不支持的渠道类型: {}", channelType);
throw new IllegalArgumentException("不支持的渠道类型: " + channelType);
}
return adapter;
}
/**
* 检查渠道类型是否支持
*
* @param channelType 渠道类型
* @return 是否支持
*/
public boolean isSupported(String channelType) {
return adapterMap.containsKey(channelType);
}
/**
* 获取所有支持的渠道类型
*
* @return 渠道类型集合
*/
public java.util.Set<String> getSupportedChannelTypes() {
return adapterMap.keySet();
}
/**
* 获取适配器并检查是否支持指定能力
*
* @param channelType 渠道类型
* @param capabilityClass 能力接口类
* @param <T> 能力类型
* @return 能力实例，如果不支持则返回 null
*/
public <T> T getAdapterWithCapability(String channelType, Class<T> capabilityClass) {
ChannelAdapter adapter = getAdapter(channelType);
if (capabilityClass.isInstance(adapter)) {
return capabilityClass.cast(adapter);
}
log.warn("[AC-MCA-03] 渠道 {} 不支持能力: {}", channelType, capabilityClass.getSimpleName());
return null;
}
/**
* 获取服务状态管理能力
*
* @param channelType 渠道类型
* @return ServiceStateCapable 实例，如果不支持则返回 null
*/
public ServiceStateCapable getServiceStateCapable(String channelType) {
return getAdapterWithCapability(channelType, ServiceStateCapable.class);
}
/**
* 获取转人工能力
*
* @param channelType 渠道类型
* @return TransferCapable 实例，如果不支持则返回 null
*/
public TransferCapable getTransferCapable(String channelType) {
return getAdapterWithCapability(channelType, TransferCapable.class);
}
/**
* 获取消息同步能力
*
* @param channelType 渠道类型
* @return MessageSyncCapable 实例，如果不支持则返回 null
*/
public MessageSyncCapable getMessageSyncCapable(String channelType) {
return getAdapterWithCapability(channelType, MessageSyncCapable.class);
}
}

15
src/main/java/com/wecom/robot/config/AiServiceConfig.java Normal file
View File

@ -0,0 +1,15 @@
package com.wecom.robot.config;
import lombok.Data;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.stereotype.Component;
@Data
@Component
@ConfigurationProperties(prefix = "ai-service")
public class AiServiceConfig {
private String url;
private int timeout = 5000;
}

22
src/main/java/com/wecom/robot/config/ChannelConfig.java Normal file
View File

@ -0,0 +1,22 @@
package com.wecom.robot.config;
import lombok.Data;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.stereotype.Component;
import java.util.Map;
@Data
@Component
@ConfigurationProperties(prefix = "channel")
public class ChannelConfig {
private String defaultChannel = "wechat";
private Map<String, AdapterConfig> adapters;
@Data
public static class AdapterConfig {
private boolean enabled;
}
}

14
src/main/resources/application.yml
View File

@ -28,3 +28,17 @@ transfer:
max-fail-rounds: 3
max-session-duration: 1800000
max-message-rounds: 50
ai-service:
url: http://localhost:8000
timeout: 5000
channel:
default-channel: wechat
adapters:
wechat:
enabled: true
douyin:
enabled: false
jd:
enabled: false