# hermes-pitfalls-learned — data pipeline

## Pitfall 14: MQL字段名是中文显示名（2026-07-09）

**症状**：`SELECT work_item_id`→返回字段名"工作项id"，代码`fields.get('work_item_id')`永远为空。

**根因**：MCP返回字段名是中文显示名，非API key。

**修复**：parse_items中标准化映射：`工作项id→work_item_id, 名称→name, 单据编号→order_no, 货号#→product_code`。

**完整字段映射表**：见 `references/mql-field-mappings.md`。


## Pitfall 15: MQL创建者字段≠销售员（2026-07-09）

**症状**：所有销售订单创建者指向同一人（自动化机器人），KPI按人汇总无效。

**根因**：`创建者`返回飞书系统记录创建人，真实销售员在`get_workitem_brief→role_members→销售员`。

**⚠️ 关键原则**：**绝对不准估算**。KPI的所有数字必须是真实数据，禁止用目标占比分摊或任何近似计算。H2月度实际额只有在客户→部门映射完成后才能填入，在此之前字段应为0。


## Pitfall 26: MCP活动类型错误——查了story不是活动（2026-07-10）

**症状**：MCP返回7月24条story，Excel导出332行活动，差12倍。

**根因**：`销售管理.story` = 商机，不是活动。飞书项目的"活动"是独立type `销售管理.活动`，type_key=`65ae1e5d44338dbe7c39a29a`。

**发现方法**：`list_workitem_types` 列出13种类型，含"活动"。

**修复**：`SELECT ... FROM \`销售管理\`.\`活动\``，URL格式 `xsguanli/65ae1e5d44338dbe7c39a29a/detail/{id}`


## Pitfall 14: MQL字段名是中文显示名（2026-07-09）

**症状**：`SELECT work_item_id`→返回字段名"工作项id"，代码`fields.get('work_item_id')`永远为空。

**根因**：MCP返回字段名是中文显示名，非API key。

**修复**：parse_items中标准化映射：`工作项id→work_item_id, 名称→name, 单据编号→order_no, 货号#→product_code`。

**完整字段映射表**：见 `references/mql-field-mappings.md`。



## Pitfall 15: MQL创建者字段≠销售员（2026-07-09）

**症状**：所有销售订单创建者指向同一人（自动化机器人），KPI按人汇总无效。

**根因**：`创建者`返回飞书系统记录创建人，真实销售员在`get_workitem_brief→role_members→销售员`。

**⚠️ 关键原则**：**绝对不准估算**。KPI的所有数字必须是真实数据，禁止用目标占比分摊或任何近似计算。H2月度实际额只有在客户→部门映射完成后才能填入，在此之前字段应为0。



## Pitfall 26: MCP活动类型错误——查了story不是活动（2026-07-10）

**症状**：MCP返回7月24条story，Excel导出332行活动，差12倍。

**根因**：`销售管理.story` = 商机，不是活动。飞书项目的"活动"是独立type `销售管理.活动`，type_key=`65ae1e5d44338dbe7c39a29a`。

**发现方法**：`list_workitem_types` 列出13种类型，含"活动"。

**修复**：`SELECT ... FROM \`销售管理\`.\`活动\``，URL格式 `xsguanli/65ae1e5d44338dbe7c39a29a/detail/{id}`