# MCP数据同步到工作台模式（2026-07-10 实战）

## 架构

```
飞书MCP API → Python管道脚本 → JSON数据文件 → HTML面板(fetch渲染)
     ↑                                              ↓
  cron每8h刷新                              工作台顶栏链接按钮
```

## 实现步骤

### 1. 数据管道脚本

创建独立的Python脚本（如 `mcp_refresh.py`），包含：
- MCP直连（curl + token）
- 全量分页拉取（ASC排序，连续2页空才停止）
- 字段解析（部门编码→名称、创建者ID→姓名）
- 数据标准化（去重、聚合、JSON输出）

### 2. JSON文件规范

输出到 `~/Desktop/Hermes输出-工作类/数据/` 目录，HTTP服务器可访问。

```json
{
  "updated": "2026-07-10 14:30",
  "total": 2817,
  "by_month": {"2026-04": {"诊断原料销售部": 669, ...}},
  "by_dept": {"诊断原料销售部": 2190, ...},
  "items": [...]
}
```

关键原则：
- 顶层包含 `updated` 时间戳
- 聚合统计前置（by_month, by_dept）
- 明细数据后置（items, highlights）
- 确保 `ensure_ascii=False`（中文不转义）

### 3. HTML面板设计

- 零依赖：纯 HTML + CSS + JS，不依赖 Chart.js/HermesTable
- 多Tab：顶部 `tab-btn` 切换视图
- Fetch加载：`Promise.all([fetch(...)])` 并行加载所有JSON
- 白底蓝调：匹配作战室风格（`--pri:#1a73e8`）

### 4. 工作台入口

在现有工作台HTML的顶栏添加链接按钮：
```html
<a href="/工具/飞书实时数据面板.html" target="_blank"
   style="padding:5px 12px;border:1px solid var(--pri);border-radius:6px;
          color:var(--pri);text-decoration:none;font-weight:600">
  📡 飞书数据
</a>
```

已集成入口：
- `诊断原料作战室.html` — 顶栏 `📡 飞书数据`
- `宝锐统一工作平台.html` — 顶栏 `📡 飞书数据`
- `宝锐销售工作台_生产版-ima.html` — 顶栏 `📡 飞书`

### 5. 定时刷新

```python
# cronjob: 每8小时运行 mcp_refresh.py
schedule: "0 */8 * * *"
prompt: "执行 ~/Desktop/Hermes输出-工作类/数据/mcp_refresh.py 刷新飞书数据"
```

## 数据文件清单（本次创建）

| 文件 | 内容 | 来源 |
|------|------|------|
| `mcp_activities.json` | 2,817条活动（含部门+创建者） | MQL `销售管理.活动` |
| `mcp_complaints.json` | 24条客诉（含阻塞节点+负责人） | `mcp_pipeline.py` → `feishu_complaints.json` |
| `mcp_blockers.json` | 42条审批阻塞（按空间分类） | `mcp_pipeline.py` → `feishu_blockers.json` |
| `mcp_refresh.py` | 定时刷新脚本 | 综合上述三个数据源 |

## 常见陷阱

1. **Panel加载失败** → 检查HTTP服务器运行：`lsof -ti:8765`
2. **JSON中文乱码** → 确保 `ensure_ascii=False`
3. **数据过期不动** → 检查 cron 是否 paused
4. **分页假死** → 用ASC排序，不用DESC（见 `references/activity-mql-pitfalls.md`）
5. ⚠️ **API服务器僵尸导致工作台瘫痪**（2026-07-10 实战教训）：`api_server.py` 的实时MCP端点（如`/api/activities`）可能在MCP超时时挂起不返回，导致工作台 `Promise.all` 永远等待。**解决方案**：工作台用本地JSON文件替代实时API + 所有fetch加超时兜底。

```javascript
// 替换：fetch('/api/activities')  — 可能永远挂起
// 改为：fetchWithTimeout('/数据/mcp_activities.json', 5000, fallback)

function fetchWithTimeout(url, timeout, fallback){
  return new Promise(function(resolve){
    var timer=setTimeout(function(){resolve(fallback)}, timeout);
    fetch(url).then(r=>r.json()).then(d=>{clearTimeout(timer);resolve(d)})
              .catch(function(){clearTimeout(timer);resolve(fallback)});
  });
}
```

6. **浏览器缓存旧版JS** → 修改HTML后页面不更新。URL加`?v=N`强制刷新，或Ctrl+Shift+R。
7. **API服务器进程僵尸** → `lsof -ti:8765` 显示进程存在但不响应请求。`lsof -ti:8765 | xargs kill -9` 后重启。