# MCP 功能迁移文档索引

## 文档概述

本目录包含了 operator-app 和 operator-integration 服务合并的完整迁移文档，详细描述了 MCP（Model Context Protocol）相关功能从双服务架构向单服务架构迁移的全过程。

## 📚 文档列表

### 1️⃣ [迁移前架构与交互流程](./01-迁移前架构与交互流程.md)

**内容摘要：**
- 迁移前的双服务架构设计
- operator-integration 和 operator-app 的职责划分
- 核心模块和目录结构
- 服务间交互的详细流程图
- 数据存储设计和 API 接口定义
- 迁移前架构的优势与问题分析

**关键流程图：**
- 整体架构图
- MCP Server 创建流程
- MCP 工具调用流程
- MCP Server 更新流程
- 系统启动时实例初始化流程

**适合阅读人群：**
- 需要了解迁移背景的开发人员
- 第一次接触该项目的新成员
- 需要对比迁移前后差异的架构师

---

### 2️⃣ [整体迁移方案](./02-整体迁移方案.md)

**内容摘要：**
- 迁移目标和范围定义
- 详细的迁移策略（重构式迁移）
- 分阶段执行计划（Phase 1-5）
- 核心技术改进：实例池设计
- 接口定义、核心逻辑、API 层、数据层迁移方案
- 风险评估与应对措施
- 测试方案和上线计划

**关键设计：**
- 实例池（Instance Pool）替代全局单例
  - LRU 淘汰机制
  - TTL 过期策略
  - 活跃连接保护
  - 懒加载机制
- 自动版本解析
- 路由整合策略

**流程图：**
- 整体迁移流程图
- MCP Server 创建流程（迁移后）
- 实例池工作流程

**适合阅读人群：**
- 执行迁移的开发人员
- 技术负责人和架构师
- 需要了解技术细节的 Code Reviewer

---

### 3️⃣ [迁移后架构与交互流程](./03-迁移后架构与交互流程.md)

**内容摘要：**
- 迁移后的单服务架构设计
- 与迁移前架构的详细对比
- 核心组件详解：实例池、部署器、版本管理
- 数据模型和数据库表结构
- 完整的交互流程（带时序图）
- API 接口变化对比
- 监控指标和性能优化
- 容错与高可用设计

**关键组件：**
- **实例池（Instance Pool）**
  - 设计原理和数据结构
  - 核心方法和工作流程
  - 实例保护机制
- **部署器（Deployer）**
  - HTTP/SSE 部署器
  - 部署流程
- **版本管理**
  - 自动版本解析
  - 版本状态机

**详细流程图：**
- 系统架构图
- 模块层次结构图
- MCP Server 创建流程
- MCP 工具调用流程（Stream 模式）
- MCP Server 更新流程
- 实例池清理流程
- 系统启动流程

**性能数据：**
- 优化点对比表
- 预期性能提升数据

**适合阅读人群：**
- 迁移后的运维人员
- 需要理解新架构的开发人员
- 进行性能调优的工程师
- 编写监控和告警的 SRE

---

### 4️⃣ [测试验证方案](./04-测试验证方案.md)

**内容摘要：**
- **聚焦迁移验证**：针对本次迁移的核心功能验证
- 实例池功能测试（懒加载、LRU淘汰、活跃保护）
- 端到端业务流程测试
- API 兼容性验证
- 迁移前后性能对比
- 精简的测试执行计划（5天完成）

**核心测试场景：**
1. **实例池测试**（3个核心场景）
   - 懒加载和缓存
   - LRU 淘汰机制
   - 活跃连接保护
2. **业务流程测试**
   - 完整的创建→访问→更新→访问流程
3. **兼容性测试**
   - API 响应格式对比
4. **性能对比测试**
   - P50/P99 延迟对比
   - 吞吐量对比

**测试规模：**
- 25 个核心测试用例
- 5 天测试周期
- 重点验证迁移相关功能

**流程图：**
- 端到端业务流程图
- 测试排期 Gantt 图

**适合阅读人群：**
- 测试工程师（执行迁移验证）
- 开发人员（编写单元测试）
- 项目经理（了解测试进度）

---

## 🎯 快速导航

### 按角色查看

**架构师/技术负责人：**
1. 先阅读 [01-迁移前架构](./01-迁移前架构与交互流程.md) 了解背景
2. 重点阅读 [02-整体迁移方案](./02-整体迁移方案.md) 的迁移策略和风险评估
3. 查看 [03-迁移后架构](./03-迁移后架构与交互流程.md) 的对比分析

**开发人员：**
1. 快速浏览 [01-迁移前架构](./01-迁移前架构与交互流程.md) 的模块结构
2. 详细阅读 [02-整体迁移方案](./02-整体迁移方案.md) 的实现细节
3. 参考 [03-迁移后架构](./03-迁移后架构与交互流程.md) 进行代码编写

**测试人员：**
1. 了解 [01-迁移前架构](./01-迁移前架构与交互流程.md) 的交互流程
2. **详细阅读 [04-测试验证方案](./04-测试验证方案.md) 全部内容**
3. 查看 [02-整体迁移方案](./02-整体迁移方案.md) 的测试方案章节
4. 对照 [03-迁移后架构](./03-迁移后架构与交互流程.md) 编写测试用例

**运维人员：**
1. 跳过技术细节，直接阅读 [02-整体迁移方案](./02-整体迁移方案.md) 的上线方案
2. 重点查看 [03-迁移后架构](./03-迁移后架构与交互流程.md) 的监控与可观测性章节
3. 了解 [03-迁移后架构](./03-迁移后架构与交互流程.md) 的容错与高可用设计
4. 参考 [04-测试验证方案](./04-测试验证方案.md) 的性能测试结果

---

### 按主题查看

**了解架构变化：**
- [01-迁移前架构](./01-迁移前架构与交互流程.md) - 第 2、3 章
- [03-迁移后架构](./03-迁移后架构与交互流程.md) - 第 2 章（包含对比表）

**理解实例池设计：**
- [02-整体迁移方案](./02-整体迁移方案.md) - 第 3.2.2 节
- [03-迁移后架构](./03-迁移后架构与交互流程.md) - 第 4.1 节

**查看交互流程：**
- [01-迁移前架构](./01-迁移前架构与交互流程.md) - 第 4 章（迁移前）
- [03-迁移后架构](./03-迁移后架构与交互流程.md) - 第 6 章（迁移后）

**API 接口变化：**
- [01-迁移前架构](./01-迁移前架构与交互流程.md) - 第 6 章
- [03-迁移后架构](./03-迁移后架构与交互流程.md) - 第 7 章

**性能优化：**
- [02-整体迁移方案](./02-整体迁移方案.md) - 第 8 节
- [03-迁移后架构](./03-迁移后架构与交互流程.md) - 第 10 章

**监控和运维：**
- [03-迁移后架构](./03-迁移后架构与交互流程.md) - 第 9、11 章

**测试验证：**
- [04-测试验证方案](./04-测试验证方案.md) - 完整测试方案
- [04-测试验证方案](./04-测试验证方案.md) - 第 2-7 章（各类测试方案）
- [04-测试验证方案](./04-测试验证方案.md) - 第 10 章（测试执行计划）

---

## 📊 文档统计

| 文档 | 章节数 | 流程图/时序图 | 代码示例 | 表格 |
|------|--------|--------------|----------|------|
| 01-迁移前架构 | 8 | 7 | 5+ | 4 |
| 02-整体迁移方案 | 9 | 4 | 10+ | 6 |
| 03-迁移后架构 | 12 | 15 | 8+ | 8 |
| 04-测试验证方案 | 8 | 2 | 6 | 6 |
| **总计** | **37** | **28** | **29+** | **24** |

---

## 🔄 迁移状态

| 阶段 | 状态 | 负责人 | 完成时间 |
|------|------|--------|----------|
| Phase 1: 接口定义迁移 | ✅ 已完成 | - | 2026-01-20 |
| Phase 2: 核心逻辑迁移 | ✅ 已完成 | - | 2026-01-21 |
| Phase 3: API 层整合 | ✅ 已完成 | - | 2026-01-21 |
| Phase 4: 数据层整合 | ✅ 已完成 | - | 2026-01-21 |
| **Phase 5: 测试与优化** | **📝 测试方案已完成** | **测试团队** | **2026-02-13（计划）** |
| 上线部署 | ⏳ 待开始 | - | - |

**测试详细进度：**（参见 [04-测试验证方案](./04-测试验证方案.md)）
- 单元测试：⏳ 待开始（2026-01-29 ~ 02-02）
- 集成测试：⏳ 待开始（2026-02-03 ~ 02-05）
- 性能测试：⏳ 待开始（2026-02-06 ~ 02-09）
- 兼容性测试：⏳ 待开始（2026-02-04 ~ 02-06）
- 回归测试：⏳ 待开始（2026-02-10 ~ 02-12）

---

## 🔗 相关资源

### 代码仓库
- 旧代码（迁移前）：https://github.com/kweaver-ai/adp/tree/main/execution-factory
- 新代码（迁移后）：`/home/chenshu/code/adp/execution-factory/operator-integration`

### 相关文档
- MCP 协议规范：https://modelcontextprotocol.io/
- Execution Factory README：[../README.md](../../README.md)
- API 文档：[../apis/](../apis/)

### 技术栈
- Go 1.24+
- Gin Web Framework
- MCP Go SDK: github.com/mark3labs/mcp-go
- 数据库：MySQL / MariaDB / DM8

---

## 📝 文档维护

### 更新记录

| 日期 | 版本 | 更新内容 | 作者 |
|------|------|----------|------|
| 2026-01-28 | v1.0 | 初始版本，创建三个迁移文档 | AI Assistant |

### 反馈与建议

如有文档问题或建议，请：
1. 在项目中提交 Issue
2. 直接联系项目维护者

---

## 📖 阅读建议

1. **首次阅读：** 建议按顺序阅读三个文档，完整理解迁移的来龙去脉
2. **查找特定信息：** 使用本索引的"按主题查看"部分快速定位
3. **代码实现：** 结合文档中的流程图和代码示例理解实现逻辑
4. **问题排查：** 参考交互流程图进行调用链追踪

---

**最后更新时间：** 2026-01-28
