diff --git a/docs/progress/ai-robot-mca-progress.md b/docs/progress/ai-robot-mca-progress.md new file mode 100644 index 0000000..817e784 --- /dev/null +++ b/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 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。