# MCP 销售订单字段映射陷阱

## `owner` ≠ 下单人（⚠️ 已反复踩坑）

**MCP 销售订单的 `owner`（创建者）是飞书系统记录创建人**，通常为物流/财务人员（如殷士海 yinshihai@lundong.com），**不代表销售员**。

## KPI 数据路线（两条，2026-07-30更新）

| 路线 | 方法 | 适用 |
|------|------|------|
| **MCP 直接** | MQL拉单→按单据去重→`get_workitem_brief(fields=['role_7dd6e0'])`查销售员→汇总 | 日常增量（1436条≈90s，缓存命中95%） |
| **ERP Excel** | `merge_workbench_data.py` → `kpi_progress.json` | 有Excel导出时 |

完整脚本见 `mcp-pipeline-patterns` → `references/kpi-refresh-terminal-script.md`。

## MQL 可用字段（销售订单）

| 字段 | MQL key | 类型 |
|------|---------|------|
| 单据编号 | `name` | string_value |
| 工作项ID | `work_item_id` | long_value |
| 创建时间 | `start_time` | datetime |
| 价税合计 | `field_51d592` | double_value |
| 价税合计(本位币) | `field_a49c23` | double_value |
| 销售订单关联客户 | `field_e1001d` | key_label_value（取 label） |
| 货号# | `field_8c4b7b` | string_value（完整货号含后缀） |
| 货号（无后缀） | `field_ed92b8` | string_value（母体号） |
| 销售数量 | `field_7c344f` | double_value |
| 订单类型# | `field_0bed7c` | string_value（采购(配COA)/测试(无需COA)） |

❌ `工作项ID`、`名称`、`id` 均不可用（中文 label 报 attr not found）。
字段 key 未知时用 `list_workitem_field_config(project_key=..., work_item_type='销售订单', field_query='货号')` 现查（field_name ↔ field_key）。

## 按「货号 × 客户」反查订单（实测可行，本地文件做不到）

```sql
SELECT `name`, `货号#`, `货号（无后缀）`, `start_time`, `订单类型#`, `销售数量`, `价税合计(本位币)`
FROM `销售管理`.`销售订单`
WHERE `销售订单关联客户` = '客户全称' AND `货号#` like '%FHW%' AND start_time >= '2026-01-01'
ORDER BY start_time DESC LIMIT 50
```

- 本地没有可用的替代源：`数据/` 的订单/客户 JSON 是订单级、不含货号（且多为**单行 JSON**，grep 只回整行）；ERP 导出 xlsx 含货号列但是二进制，`search_files` 匹配不到、行数又超单次读取上限。**别为此 grep 本地文件，直接 MCP。**
- `list[0].count` 是**分录行数**，同一 `单据编号` 会有多行（不同货号、或同货号不同数量）；按 `单据编号` 去重才是订单数，报数时写明口径。
- `订单类型#` 为 `测试(无需COA)`、或单号以 `FO` 开头的预测单，金额恒为 0（≠免费发货），汇总时要与采购单分开。
- `tool_call` 一次只能提交一个 MCP 调用；`tool_describe` 可以一次批量拿多个 schema。

## `name` 字段值

实测所有销售订单的 `name` 值含 `ZHBR` / `FO` 前缀，即为单据编号。

## 当日活动数据（可行）

MCP `销售管理.活动` 可通过 `owner`（创建者=销售员本人）正确获取：
```
SELECT `活动描述`, `活动关联客户`, `创建者`, `创建时间` 
FROM `销售管理`.`活动` 
WHERE `创建时间` >= 'YYYY-MM-DD'
```