# MQL 字段映射表（飞书项目 MCP）

> 飞书项目 MCP 返回字段名是中文显示名，需标准化映射后才能用英文 key 访问。
> 已确认：MQL SELECT 不支持 `*`；OFFSET 分页可靠，session_id 循环；WHERE + 大OFFSET 超时。

## 销售管理 → story（商机/活动）

| MQL SELECT | 返回名 | 标准化 | 说明 |
|-----------|--------|--------|------|
| `name` | 名称 | `name` | ✅ |
| `work_item_id` | 工作项id | `work_item_id` | ✅ URL: `xsguanli/story/detail/{id}` |
| `创建时间` | 创建时间 | `date` | ✅ ISO |
| `创建者` | 创建者 | `creator` | ⚠️ user_key ID |
| `description` | 描述 | `desc` | ✅ |
| `活动关联客户` | — | — | ❌ 关系字段 |

## 销售管理 → 销售订单（xsdd） — `销售管理`.`销售订单`

| MQL SELECT | 返回名 | 标准化 | 示例 |
|-----------|--------|--------|------|
| `单据编号` | 单据编号 | `order_no` | ZHBR260709013 |
| `创建时间` | 创建时间 | `date` | 2026-07-09 |
| `创建者` | 创建者 | `creator` | ⚠️ 机器人，非销售员 |
| `金额` | 金额 | `amount` | 1504.42 |
| `货号#` | 货号# | `product_code` | FE04-2-036001-10 |
| `单价` | 单价 | `unit_price` | ⚠️ 部分0 |
| `销售数量` | 销售数量 | `qty` | 0.1 |
| `work_item_id` | 工作项id | `work_item_id` | ✅ |
| `关联客户` | — | — | ❌ list_related_workitem 补全(60s超时) |
| `销售员` | — | — | ❌ get_workitem_brief→role_members |

## 销售管理 → 客户（kh） — `销售管理`.`客户`

| MQL SELECT | 返回名 |
|-----------|--------|
| `客户名称` | 客户名称 |
| `work_item_id` | 工作项id |

## 售后管理 → 客户反馈单

list_todo 返回 work_item_name（含日期+客户+问题）；get_node_detail 获取阻塞节点。

## URL 模板

```
商机/活动:     https://project.feishu.cn/xsguanli/story/detail/{id}
销售订单:      https://project.feishu.cn/xsguanli/xsdd/detail/{id}
售后客诉:      https://project.feishu.cn/br-shgl/detail/{id}
客户项目:      https://project.feishu.cn/csrw/detail/{id}

⚠️ 注意：type路径用 story 非 sj（导出模板缩写，前端路由不认）
```

## 客户名补全（relation 遍历）

```python
REL_CUSTOMER = "6593cd71471290e3cc6be6e6:work_item_relation:relation_1713785263022"
related = mcp("list_related_workitem", {
    "project_key": SALES_PK, "work_item_id": wid, "relation_id": REL_CUSTOMER
}, timeout=60)  # 必须60s，30s会超时
customer_name = related['list'][0]['name'] if related and related.get('list') else '未关联'
```