# 销售工作台 MCP 实时数据推进计划

> **For Hermes:** 分 4 个 Phase 逐步推进，每 Phase 独立可交付。

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

**当前架构：**
```
Excel 导出 → Python 脚本处理 → JSON 文件 → 后端静态服务 → 前端 fetch
MCP 拉取   → JSON 文件 ─────────────────────────────────────────┘
```
**目标架构：**
```
MCP 飞书项目 ←── 后端定时/按需拉取 → 内存缓存 → API → 前端 fetch（带自动刷新）
```

---

## Phase 1: MCP 数据层标准化（后端）

> **目标：** 建立一个统一的 MCP 数据拉取 + 缓存框架，替代现有的手动脚本。

### 任务 1.1：创建 MCP 数据拉取模块

**文件：** 新建 `脚本/mcp_sync.py`

封装所有 MCP 查询为独立函数，返回标准化结构：

```python
# mcp_sync.py 核心函数
def pull_customers() -> dict   # 客户表
def pull_orders() -> dict      # 订单表（替代 ERP 导出）
def pull_complaints() -> dict  # 客诉表
def pull_activities() -> dict  # 活动表
def pull_opportunities() -> dict # 商机表
```

每函数返回 `{"updated_at": "ISO时间", "data": [...]}` 统一格式。

### 任务 1.2：添加智能缓存层

- 内存缓存 + JSON 文件双写（JSON 作为降级备份）
- TTL 策略：订单/活动 5 分钟，客户/商机 30 分钟，客诉 15 分钟
- 手动刷新端点：`POST /api/mcp/refresh?type=orders`

### 任务 1.3：后端新增 MCP 数据 API

在 `销售工作台服务.py` 中添加：

| 端点 | 说明 |
|------|------|
| `GET /api/mcp/customers` | 客户数据（带缓存） |
| `GET /api/mcp/orders` | 订单数据（带缓存） |
| `GET /api/mcp/complaints` | 客诉数据（带缓存） |
| `GET /api/mcp/activities` | 活动数据（带缓存） |
| `GET /api/mcp/opportunities` | 商机数据（带缓存） |
| `GET /api/mcp/dashboard` | 聚合仪表盘数据（含 KPI 计算） |
| `POST /api/mcp/refresh` | 强制刷新指定类型缓存 |

---

## Phase 2: 前端切 API（销售工作台 HTML）

> **目标：** 前端从读本地 JSON 文件改为读后端 API，数据真正实时。

### 任务 2.1：前端数据加载层改造

修改 `ENDPOINTS` 配置，指向 API 端点：

```javascript
var ENDPOINTS = [
  ['customers',    '/api/mcp/customers'],
  ['complaints',   '/api/mcp/complaints'],
  ['orders',       '/api/mcp/orders'],
  ['activities',   '/api/mcp/activities'],
  ['oppSandbox',   '/api/mcp/opportunities'],
  ['kpiDashboard', '/api/mcp/dashboard'],
  // ...
];
```

### 任务 2.2：添加自动刷新机制

- 页面加载后每 5 分钟自动 `refreshData()`
- 刷新按钮加 loading 动画
- 显示"最后更新于 XX:XX:XX"

### 任务 2.3：数据降级策略

- API 不可用时自动 fallback 到 Tunnel URL → 本地 JSON
- `tryApiFirst(urls, fallbackPath)` 函数

---

## Phase 3: KPI 实时计算

> **目标：** 看板核心指标（年度达成率、月度趋势、三年对比）基于 MCP 订单数据实时计算。

### 任务 3.1：基于订单计算月度销售额

从 MCP 订单数据聚合：按月份 `GROUP BY` → 各月销售额

```python
def compute_monthly_sales(orders):
    """从订单列表计算每月销售额"""
    monthly = defaultdict(float)
    for o in orders:
        month = o['create_date'][:7]  # "2026-07"
        monthly[month] += o['amount']
    return dict(monthly)
```

### 任务 3.2：计算年度 KPI 达成

- 年度目标：从 `h2_monthly_targets.json` 或 MCP 目标字段读取
- 累计达成：MCP 订单汇总
- 达成率：累计 / 目标 × 100

### 任务 3.3：三年对比基于历史归档 + MCP

- 2024/2025：使用已归档的 `h1_archive.json` / `three_year_monthly.json`
- 2026：MCP 实时订单数据
- 合并渲染

---

## Phase 4: 定时自动同步（Cron + WebSocket）

> **目标：** 数据无需手动刷新，自动保持最新。

### 任务 4.1：Cron 定时拉取

```bash
# 每 5 分钟拉取订单/活动，写入 JSON 文件
*/5 * * * * curl -X POST http://127.0.0.1:8765/api/mcp/refresh?type=all
```

或通过 Hermes cronjob 实现。

### 任务 4.2：前端轮询优化

- `setInterval(refreshData, 5 * 60 * 1000)` 
- 仅在 tab 可见时刷新（`document.visibilityState`）
- 数据无变化时不重渲染（hash 比对）

### 任务 4.3（可选）：WebSocket 推送

- 后端数据变化时主动推送到前端
- 适合数据变化频率高的场景

---

## 数据优先级矩阵

| 模块 | 当前来源 | MCP 可替代？ | 优先级 |
|------|---------|-------------|--------|
| 📊 看板 KPI | Excel→JSON | 订单聚合计算 | ⭐⭐⭐ |
| 📋 客户清单 | MCP ✓ | 已就绪 | ⭐ |
| 📦 订单管理 | ERP Excel | MCP 订单表 | ⭐⭐⭐ |
| 🔴 客诉 | MCP ✓ | 已就绪 | ⭐ |
| 📅 我的活动 | MCP ✓ | 已就绪 | ⭐ |
| 🎯 商机沙盘 | 手动 JSON | MCP 商机表 | ⭐⭐ |
| 📈 三年对比 | 历史归档 | 2026用MCP | ⭐⭐ |
| 📝 访前准备 | 本地 JSON | 暂不变 | ⭐ |

---

## 风险 & 注意事项

1. **MCP API 频率限制** — 需要合理的缓存 TTL 避免触发限流
2. **Tunnel 稳定性** — Tunnel URL 变化时需要同步更新，后续考虑固定域名
3. **订单表字段匹配** — MCP 订单字段可能与 ERP 订单字段名不同，需要映射
4. **历史数据** — 2024/2025 数据 MCP 可能没有，需要保持归档 JSON
5. **离线兜底** — 后端/Tunnel 不可用时，前端应降级到本地 JSON 文件

---

## 建议推进顺序

**本周：Phase 1.1 + 1.2**（MCP 拉取框架 + 缓存）
**下周：Phase 2.1 + 2.2**（前端切 API，先切客户/活动/客诉）
**第三周：Phase 3**（KPI 实时计算）
**第四周：Phase 4**（自动同步 + 优化）

每个 Phase 完成后立即验证，渐进交付，不影响现有功能。