194 lines
6.8 KiB
Markdown
194 lines
6.8 KiB
Markdown
# 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)
|
||
|
||
- [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]
|
||
- [ ] Phase 4: AI 服务客户端 (0%) ⏳ [tasks.md: TASK-030 ~ TASK-033]
|
||
- [ ] Phase 5: 集成测试 (0%) ⏳ [tasks.md: TASK-040 ~ TASK-042]
|
||
|
||
---
|
||
|
||
## 🔄 Current Phase
|
||
|
||
### Goal
|
||
完成 ChannelAdapter 接口定义、WeChatAdapter 实现、ChannelAdapterFactory 创建、WecomCallbackController 重构。
|
||
|
||
### 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]
|
||
|
||
### Next Action (Must be Specific)
|
||
|
||
**Immediate**: 创建 `WeChatAdapter.java` 实现 ChannelAdapter 接口。
|
||
|
||
**Details**:
|
||
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.1 节（渠道适配器接口）
|
||
- `src/main/java/com/wecom/robot/service/WecomApiService.java`（现有实现）
|
||
4. constraints:
|
||
- 实现 ChannelAdapter 核心接口
|
||
- 实现 ServiceStateCapable、TransferCapable、MessageSyncCapable
|
||
- 现有功能保持兼容
|
||
|
||
---
|
||
|
||
## 🏗️ 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 命名混乱
|
||
|
||
- 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);
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 🧾 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
|
||
|
||
### 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）。
|
||
4. 每完成一个子任务，更新本进度文档并提交 Git。
|