# 客户档案全维度数据管线

## 架构

```
ERP Excel → pricing JSON (货号#聚合)
     ↓
飞书MCP → 客户MQL (决策链URL) → relation API → 联系人/商机/项目/客诉
     ↓
统一 JSON (profiles/{客户}_full.json) → HTML 档案卡
```

## 数据源与采集方式

| 维度 | 来源 | 方法 | 备注 |
|------|------|------|------|
| 💰 价格 | ERP本地JSON | `pricing/{客户}.json` | 按货号#聚合，含最新价/历史价/累计额 |
| 🔗 决策链 | 飞书MCP MQL | `WHERE 客户名称 = "精确名"` | 同集团客户可共享URL |
| 👤 联系人 | 飞书MCP relation | `list_related_workitem(relation_id=1715033831836)` | 客户-联系人关联 |
| 💼 商机 | 飞书视图 | `get_view_detail(view_id='sm7MYQiNg')` → relation | 528条全量，再逐条关联客户 |
| 🏗️ 项目 | 飞书视图 | `get_view_detail(view_id='uAhLe5eIR', PK=csrw)` → relation_1712924598201 | 64条 |
| 🔴 客诉 | 飞书视图 | `get_view_detail(view_id='TDWUJhYHg', PK=br-shgl)` → 订单→客户(二级跳) | 64条 |

## 关键客户筛选

首页列表仅显示 **大客户销售部** 清单中的客户（89家），从 `诊断原料&生命科学客户清单20260630.xls` 的「大客户销售部」Sheet 提取。

```python
df = pd.read_excel(fp, sheet_name='大客户销售部', header=1, dtype=str)
ka_names = set(r['客户名称'] for _, r in df.iterrows() if r['客户名称'] not in ['合计', '说明'])
key_custs = [c for c in index if c['name'] in ka_names]
```

生成 `_key_customers.json` 供前端加载。

## 集团决策链面板

同集团客户共享决策链URL。从客户清单的「集团简称」列提取映射。

```python
# 圣湘集团示例：
# 圣湘生物 → 决策链WIKI_A
# 湖南康得 → 决策链WIKI_A (同集团共享)
# 圣湘上海 → 决策链WIKI_B (独立)
# 湖南圣维 → 决策链WIKI_A
# 长沙圣维 → 决策链WIKI_A
```

前端渲染：当前客户加粗 + 同集团成员列表，缺失标⚠。

## 档案JSON结构

```json
{
  "customer": "圣湘生物科技股份有限公司",
  "work_item_id": "4196204802",
  "decision_url": "https://i16l6v9noru.feishu.cn/wiki/...",
  "level": "大客户",
  "group_name": "圣湘集团",
  "group_chains": [{"name": "湖南康得...", "url": "..."}],
  "pricing": {"total_amount": 11738288, "total_orders": 2366, "top_products": [...]},
  "contacts": [{"name": "段正兴", "id": "4418595508"}],
  "opportunities": [{"name": "脓毒症项目", "id": "6578453461", "url": "..."}],
  "projects": [...],
  "complaints": [...]
}
```

## 详情页链接格式

| 维度 | URL模板 |
|------|--------|
| 联系人 | `https://project.feishu.cn/xsguanli/lxr/detail/{id}` |
| 商机 | `https://project.feishu.cn/xsguanli/story/detail/{id}` |
| 项目 | `https://project.feishu.cn/csrw/test/detail/{id}` |
| 客诉 | `https://project.feishu.cn/br-shgl/khts/detail/{id}` |
| 决策链 | Wiki直链（含于MQL查询结果） |

## 客诉二级跳转

客诉（售后管理）不直接关联客户，需：
1. 客诉 `list_related_workitem(relation_1727283754885)` → 销售订单
2. 销售订单 `list_workitem_relations` → 找含"客户"的relation → list_related_workitem → 客户
3. ⚠️ 每笔订单的客户关联relation_id不同，必须动态获取

## HTML 首页模式

首页必须展示筛选列表，不直接显示单个客户档案：
- 搜索框 + KPI概要
- 表格列：客户 | 累计采购 | 决策链 | 联系人 | 商机 | 项目 | 客诉 | 查看→
- 点击行进入详情，顶栏显示 `← 返回列表`
- 仅加载关键客户（_key_customers.json），非全量