# 客户Tab MCP迁移

2026-07-25 完成。工作台客户Tab从ERP `_key_customers.json` / `_personnel.json` 切换为MCP数据源。

## 数据模型

```
mcp_customers.json  ← MCP 客户表 (kh, 1678条) + 订单按客户汇总金额
├── name:        客户名称 (MCP `name`)
├── group:       所属集团客户 (MCP `field_c3224b`)
├── contacts:    联系人数量 (MCP `field_8c870a`, number)
├── dept:        所属人部门/区域 (MCP `field_5ed7ab`, key_label_value)
├── opps:        商机数 (MCP `field_79aa0b` 或 `field_f43549`, workitem_related_multi_select count)
├── amount:      2026累计价税合计 (H1 + H2 按客户汇总)
├── h1_amount:   H1价税合计
├── location:    所在地 (MCP `field_6415cf`)
├── ctype:       客户类型 (MCP `field_2d5b6a`)
└── level:       客户等级 (MCP `field_17186c`)
```

## MCP 拉取

```bash
# 客户基础字段（34页，~30秒）
MQL = SELECT `name`, `field_8c870a`, `field_c3224b`, `field_5ed7ab`,
           `field_79aa0b`, `field_f43549`, `field_2d5b6a`, `field_17186c`, `field_6415cf`
       FROM `销售管理`.`客户` LIMIT 50 OFFSET {offset}

# H1 2026客户金额汇总（177页，~3分钟）
MQL = SELECT `购货单位#`, `价税合计`
       FROM `销售管理`.`销售订单`
       WHERE `创建时间` >= '2026-01-01' AND `创建时间` <= '2026-06-30'
       LIMIT 50 OFFSET {offset}
# 按客户去重累加价税合计
# → 606个客户，总额2296.9万

# H2 客户金额从 h2_live.json 中按 customer 字段汇总
```

## 页面功能

- **顶部2卡片**：客户数 / 联系人（不显示订单金额/订单数/商机数）
- **部门筛选**：`customerDeptFilter` 状态变量，从客户数据中提取 `dept` 去重（12个部门）
- **搜索**：客户名 + 集团名双字段模糊搜索
- **表格列**：客户(含所在地) / 集团 / 联系人 / 商机 / 2026累计采购 / 飞书→
- 显示上限500条，超出提示"仅显示前500条"
- **商机列强制数字**：`typeof c.opps === 'number' ? c.opps : (parseInt(c.opps) || 0)`

## 飞书客户详情链接

每行末尾有"飞书 →"链接，格式：
```
https://project.feishu.cn/xsguanli/workObjectView/65ae1e403c87b152f3365ca6/{work_item_id}?scope=workspaces
```
- `work_item_id` 需单独从MCP拉取（34页，MQL: `SELECT name, work_item_id FROM 销售管理.客户`）
- work_item_id 的 value_type=long_value，取 `value.long_value`
- 无ID的客户用 `#` 占位

## 联系人数：必须从MCP客户表获取

❌ 用订单收货人(recipient)去重 → 仅261人，严重偏低  
✅ MCP 客户 `联系人数量`(field_8c870a) 字段汇总 → 7723人  

联系人数和客户数写入 `shipment_status.json`：
- `mcp_customer_count`: 1678
- `mcp_contact_count`: 7723
- 看板通过 `shipments.mcp_customer_count` / `shipments.mcp_contact_count` 读取