# MCP 订单数据管道改进（2026-07-28）

## 1. 按单号去重（解决页面重复）

### 问题
MCP 返回的销售订单中，同一订单号（`单据编号`）对应多个工作项（不同产品行），`pull_orders.py` 仅按 `work_item_id` 去重不够，导致 `shipment_status.json` 中同订单重复出现。

### 修复
`pull_orders.py` 输出时加按 `单据编号` 去重：

```python
output = []
seen_oid = set()
for o in all_items:
    oid = o.get('name', '')
    if oid in seen_oid:
        continue
    seen_oid.add(oid)
    # ... 构建输出 ...
```

效果：384条 → 186条，103个重复单号归零。

## 2. 下单人角色查询（替代客户 owner 映射）

### 问题
旧逻辑通过 `mcp_customers.json` 的 `owner` 字段映射销售员。离职人员（黄文清/李丽佳）名下58个客户未更新，导致订单"创建者"显示离职人员。

### 正确做法
用 `get_workitem_brief` 查询每个订单的 `role_members`，提取「下单人」角色成员：

```python
result = mcp("get_workitem_brief", {
    "project_key": PK,
    "work_item_id": wid
})
role_members = result.get('work_item_attribute', {}).get('role_members', [])
for rm in role_members:
    if rm.get('name') == '下单人':
        members = rm.get('members', [])
        if members:
            xdr = {'name_cn': members[0].get('name', ''), 'email': members[0].get('email', '')}
```

### 缓存机制
角色数据通过 `order_role_cache.json` 缓存，新订单才查询 API：

```python
ROLE_CACHE_FILE = os.path.join(BASE, 'order_role_cache.json')
role_cache = json.load(open(ROLE_CACHE_FILE)) if os.path.exists(ROLE_CACHE_FILE) else {}
uncached = [o for o in unique_orders if o.get('name') not in role_cache]
# 仅查询未缓存的订单，结果写回缓存
```

### 订单角色结构
`get_workitem_brief` 返回的 `work_item_attribute.role_members`：
```json
[
  {"key": "role_00a9b7", "name": "下单人", "members": [
    {"key": "7628113803590241210", "name": "徐卓凡", "email": "xuzhuofan@biori.com"}
  ]},
  {"key": "role_7dd6e0", "name": "销售员", "members": [...]},
  {"key": "role_9d3509", "name": "客户-所属人", "members": [...]}
]
```

## 3. 合同编号字段缺失

### 问题
`contractNo` 列为空。`pull_orders.py` 的 MQL SELECT 未包含 `field_4a1b47`（合同编号#），`shipment_pipeline.py` 也未传递。

### 修复
- `pull_orders.py`: MQL SELECT 加 `field_4a1b47`，输出加 `'合同编号#'`
- `shipment_pipeline.py`: 输出加 `"contractNo": o.get("合同编号#", "")`

## 4. CloudBase HTML 部署陷阱

### 问题
`cb_sync.sh` 仅同步数据 JSON 文件到 CloudBase，不包含 `index.html`。修改页面后 CloudBase 仍是旧版。

### 修复
在 `cb_sync.sh` 末尾加 HTML 部署步骤：

```bash
# 6. 部署工作台 HTML 到 CloudBase
echo ">>> 部署工作台 HTML..." >> "$LOG"
tcb hosting deploy "$WORKDIR/工具/index.html" /workbench/index.html -e "$CB_ENV" >> "$LOG" 2>&1
```