# MCP 实时数据架构 v2.0（2026-07-26）

## 架构图

```
飞书项目 MCP Server
    ↓ MQL 查询（search_by_mql）
销售工作台服务.py :8765
    ├── GET /api/mcp/customers     (1700条, 30分钟缓存)
    ├── GET /api/mcp/orders        (2500条, 5分钟缓存)
    ├── GET /api/mcp/activities    (2500条, 5分钟缓存)
    ├── GET /api/mcp/complaints    (动态, 15分钟缓存)
    ├── GET /api/mcp/opportunities (动态, 5分钟缓存)
    └── POST /api/mcp/refresh      (强制刷新)
    ↓ HTTP API（CORS已启用）
前端 fetchWithFallback:
    1. Tunnel URL API → 2. localhost API → 3. 本地 JSON 降级
    + adaptMcpFields() 字段映射
    + 5分钟自动刷新（仅 visible tab）
```

## MQL 查询规则

1. **不支持 `SELECT *`** — 必须显式列出所有字段
2. **表名用完整 type_key** — 不能用别名（`kh`→`65ae1e403c87b152f3365ca6`）
3. **字段权限逐个验证** — `field_ec1e8b`(行业)等字段无权限，报 `attribute key or value error (Code: 3010)` 时移除
4. **返回格式** — `moql_field_list` 嵌套 `[{key, name, value}]`，需展开为扁平 JSON
5. **枚举展开** — `value` 中的 `{key_label_value: {key, label}}` 提取 `label`

## 类型映射表

| 中文名 | type_key | MQL 表名 |
|--------|---------|---------|
| 客户 | `65ae1e403c87b152f3365ca6` | `` `6593cd71471290e3cc6be6e6`.`65ae1e403c87b152f3365ca6` `` |
| 销售订单 | `662612aea6bb7089fea044ef` | `` `6593cd71471290e3cc6be6e6`.`662612aea6bb7089fea044ef` `` |
| 活动 | `65ae1e5d44338dbe7c39a29a` | `` `6593cd71471290e3cc6be6e6`.`65ae1e5d44338dbe7c39a29a` `` |
| 缺陷(客诉) | `issue` | `` `6593cd71471290e3cc6be6e6`.`issue` `` |
| 商机 | `story` | `` `6593cd71471290e3cc6be6e6`.`story` `` |

## MCP 字段 → 前端字段映射

### 客户 (customers)
| MCP field_key | 前端字段 | 含义 |
|--------------|---------|------|
| name | name | 客户名称 |
| field_5ed7ab | dept | 所属部门 |
| field_17186c | level | 客户等级 |
| field_6415cf | location | 所在地 |
| field_2d5b6a | ctype | 客户类型 |
| field_c3224b | group | 所属集团 |
| field_c8e80d | cust_level | KA/重点客户 |
| field_a1ff52 | product_line | 意向产品线 |
| owner | creator | 创建者 |

### 订单 (orders)
| MCP field_key | 前端字段 | 含义 |
|--------------|---------|------|
| name | orderId | 单据编号 |
| field_2d6367 | customer | 购货单位 |
| field_a6e501 | orderType | 单据类型 |
| field_5ed7ab | dept | 销售部门 |
| field_4a1b47 | contractNo | 合同编号 |
| field_2e095b | createDate | 合同日期 |
| field_3a3ccb | product | 物料名称 |
| field_8c4b7b | sku | 货号 |
| field_5b2b3b | spec | 规格型号 |
| field_dbd4ab | unit | 销售单位 |

### 活动 (activities)
| MCP field_key | 前端字段 | 含义 |
|--------------|---------|------|
| name | name | 活动名称 |
| field_5f20fc | customer | 关联客户 |
| field_76654e | activity_type | 活动类型 |
| field_a2b3f6 | date | 开始时间 |
| field_5ed7ab | dept | 跟进部门 |
| field_b99055 | description | 活动描述 |
| work_item_status | status | 状态 |

## 金额字段限制

飞书 MCP 的 `销售订单` 工作项不返回财务金额。`金额`/`价税合计`/`含税单价` 均为 0。
KPI 金额数据以 ERP 导出为唯一可靠来源。

## 后端缓存架构

```python
MCP_CACHE = {}  # 内存缓存
MCP_CACHE_TTL = {
    'customers': 1800,   # 30分钟
    'orders': 300,       # 5分钟
    'complaints': 900,   # 15分钟
    'activities': 300,   # 5分钟
}
# 每次写入同时保存 JSON 备份文件：数据/mcp_{type}.json
```

## 前端降级链

```
Tunnel URL (board-celebrate-xxx.trycloudflare.com) → localhost:8765 → 本地 JSON 文件
```

## 已知问题

- `field_ec1e8b` (行业)、`field_e769ee` (国家)、`field_8c870a` (联系人数量) 无 MCP token 权限
- `field_f235aa` (销售组织) 可能在订单查询中也不可用，需逐个验证
- Tunnel URL 每次重启变化，需同步更新 HTML 中的 `API_BASE_URLS` 和 `AUTH_URLS`