# MCP 实时数据迁移计划（2026-07-26）

## 目标

销售工作台全部数据通过 MCP 实时更新，消除手动 Excel 导出→加工→JSON 的离线管道。

## 当前架构 vs 目标架构

```
当前: Excel导出 → Python脚本 → JSON文件 → 后端静态服务 → 前端fetch
      MCP拉取  → JSON文件 ────────────────────────────────┘

目标: MCP飞书项目 ← 后端定时/按需拉取 → 内存缓存 → API → 前端fetch（自动刷新）
```

## 分阶段推进

| Phase | 内容 | 优先级 |
|-------|------|--------|
| 1 | 后端 MCP 拉取框架 + 缓存（统一封装 MCP 查询） | ⭐⭐⭐ |
| 2 | 前端切 API（ENDPOINTS 从 JSON 文件改 API 端点） | ⭐⭐⭐ |
| 3 | KPI 实时计算（基于 MCP 订单聚合月度/年度 KPI） | ⭐⭐ |
| 4 | 定时自动同步（Cron + 前端轮询） | ⭐ |

## 数据源 MCP 可替代性

| 模块 | 当前来源 | MCP 可替代？ |
|------|---------|-------------|
| 📊 看板 KPI | Excel→JSON | 订单聚合计算 |
| 📋 客户清单 | MCP ✓ | 已就绪 |
| 📦 订单管理 | ERP Excel | MCP 订单表（注意金额字段可能为0，见 Pitfall 41） |
| 🔴 客诉 | MCP ✓ | 已就绪 |
| 📅 我的活动 | MCP ✓ | 已就绪 |
| 🎯 商机沙盘 | 手动 JSON | MCP 商机表 |
| 📈 三年对比 | 历史归档 | 2026用MCP |

## 关键 API 端点设计

```
GET  /api/mcp/customers      — 客户数据（缓存 30min）
GET  /api/mcp/orders         — 订单数据（缓存 5min）
GET  /api/mcp/complaints     — 客诉数据（缓存 15min）
GET  /api/mcp/activities     — 活动数据（缓存 5min）
GET  /api/mcp/opportunities  — 商机数据（缓存 30min）
GET  /api/mcp/dashboard      — 聚合仪表盘（含 KPI 实时计算）
POST /api/mcp/refresh        — 强制刷新指定类型缓存
```

## 风险

1. MCP 订单金额字段可能恒为 0（见 `references/mcp-sales-amount-limitation.md`）
2. Tunnel URL 变化时需同步更新前端 AUTH_URLS
3. MCP API 频率限制需合理 TTL