# 宝锐生物 · 销售工作台 产品说明书

> 版本：v2.0（MCP 实时数据版）  
> 更新日期：2026-07-26  
> 产品负责人：刘新元

---

## 一、产品概述

宝锐销售工作台是一套**零依赖、自包含**的 HTML 单页应用，为宝锐生物营销中心提供统一的销售数据驾驶舱。覆盖诊断原料与生命科学两条业务线，服务约 30 名销售人员及管理层。

**核心价值：** 一个页面看全盘，数据实时来自飞书项目 MCP，无需手动导出 Excel。

---

## 二、用户与权限

### 2.1 三级权限体系

| 角色 | 标识 | 数据范围 | 人数 |
|------|------|---------|------|
| **管理员 (admin)** | 👑 | 全公司全量数据 | 1（刘新元） |
| **部门经理 (manager)** | 📊 | 本部门数据 | 4（刘欣/韩远怀/吴云/王诗香） |
| **销售员 (sales)** | 💼 | 本人数据 | ~18 |

### 2.2 部门架构

```
诊断原料销售部（刘新元 · 总监）
├── 销售拓展部（刘欣 · 经理）—— 12人
├── 大客户部（张立娅/赵云浩）—— 2人
├── 生命科学-浙江（吴云 · 经理）—— 3人
└── 生命科学-广东（韩远怀 · 经理）—— 2人
```

### 2.3 登录方式

| 方式 | 适用场景 | 说明 |
|------|---------|------|
| **密码登录** | PC 浏览器 | 选择姓名 + 输入邮箱前缀 |
| **飞书免登** | 飞书桌面端 | OAuth 自动授权，无需密码 |
| **飞书移动端** | 手机飞书 | 正常密码登录 |

---

## 三、功能模块

### 3.1 📊 看板（Dashboard）

首页仪表盘，面向管理层的核心数据总览：

| 指标 | 数据来源 | 刷新频率 |
|------|---------|---------|
| 客户总数 | MCP 客户表 | 30 分钟 |
| 2026 价税合计 | MCP 订单表 | 5 分钟 |
| 本月价税 | MCP 订单表（实时计算） | 5 分钟 |
| 联系人数量 | MCP 客户联系人字段 | 30 分钟 |
| 年度 KPI 达成率 | MCP 订单 + 目标配置 | 5 分钟 |
| 月度目标/达成趋势图 | 目标配置 + 实际 | — |
| H2 月度目标 vs 实际 | 目标配置 + 实时 | — |
| 客户 Top 10 | MCP 订单汇总 | 5 分钟 |
| 三年逐月销售对比 | 历史归档 + 实时 MCP | — |

### 3.2 📋 客户（Customers）

- **数据来源**：MCP 客户表（1,700+ 条），含客户名称、等级、行业、所在地、部门归属
- **筛选**：按部门 / 关键词搜索
- **权限过滤**：admin 看全部，manager 看本部门，sales 看自己

### 3.3 📝 访前准备（Visit Prep）

- 基于客户档案生成访前作战卡
- 聚合客户背景、联系人、商机、客诉历史
- 关联飞书活动记录

### 3.4 🎯 商机沙盘（Opp Sandbox）

- 商机列表与状态追踪
- 数据来源：MCP 商机表

### 3.5 🔴 客诉（Complaints）

- 客诉工单列表
- 按紧急程度、KA 标识筛选
- 数据来源：MCP 缺陷表（实时）

### 3.6 📦 订单管理（Orders）

- ⭐ **本次重大升级**：数据从 ERP Excel 导出 → **MCP 销售订单表实时拉取**
- 2,500+ 条订单，按客户、日期、状态筛选
- 含购货单位、物料编码、货号、价税等完整字段

### 3.7 📅 我的活动（My Activities）

- ⭐ **本次升级**：数据从本地 JSON → **MCP 活动表实时拉取**
- 2,500+ 条活动记录
- 活动类型：线下拜访 / 线上跟进 / 陌拜 / 协同拜访
- 按月份、部门、创建者聚合

### 3.8 ✅ 待办（Todos）

- 个人待办管理
- 支持新增、完成、关闭
- 数据持久化到后端 JSON，跨设备同步

---

## 四、技术架构

```
┌─────────────────────────────────────────────┐
│              用户浏览器（PC / 飞书 / 手机）      │
└─────────────────┬───────────────────────────┘
                  │ HTTPS
┌─────────────────▼───────────────────────────┐
│       CloudBase 静态托管（CDN）               │
│  index.html + logo.png + 静态 JSON（降级备份） │
└─────────────────┬───────────────────────────┘
                  │ API 调用（优先）
┌─────────────────▼───────────────────────────┐
│         Cloudflare Tunnel（公网入口）          │
│  board-celebrate-nylon-address.trycloudflare │
└─────────────────┬───────────────────────────┘
                  │
┌─────────────────▼───────────────────────────┐
│      本地后端（macOS · Python 标准库）         │
│  销售工作台服务.py :8765                       │
│  ├── 静态文件服务                              │
│  ├── MCP 实时数据 API（带缓存）                 │
│  ├── 飞书 OAuth 免登                           │
│  ├── IMA 知识库搜索                            │
│  └── 待办事项 CRUD                             │
└─────────────────┬───────────────────────────┘
                  │ MCP Token
┌─────────────────▼───────────────────────────┐
│          飞书项目 MCP Server                   │
│  ├── 客户表（kh）    → /api/mcp/customers      │
│  ├── 销售订单（xsdd） → /api/mcp/orders        │
│  ├── 活动（sj）      → /api/mcp/activities     │
│  ├── 缺陷（issue）   → /api/mcp/complaints     │
│  └── 商机（story）   → /api/mcp/opportunities  │
└─────────────────────────────────────────────┘
```

### 降级策略

```
1. Tunnel API（实时） → 2. localhost API（本地直连） → 3. 本地 JSON（离线备份）
```

---

## 五、数据字典

### 5.1 MCP 实时数据

| 数据 | 类型 Key | 数据量 | 刷新间隔 |
|------|---------|--------|---------|
| 客户 | `65ae1e403c87b152f3365ca6` | ~1,700 | 30 分钟 |
| 销售订单 | `662612aea6bb7089fea044ef` | ~2,500 | 5 分钟 |
| 活动 | `65ae1e5d44338dbe7c39a29a` | ~2,500 | 5 分钟 |
| 客诉 | `issue` | 动态 | 15 分钟 |
| 商机 | `story` | 动态 | 5 分钟 |

### 5.2 本地计算数据（暂未 MCP 化）

| 数据 | 文件 | 说明 |
|------|------|------|
| KPI 仪表盘 | `kpi_dashboard.json` | 年度目标 + 部门分解 |
| KPI 进度 | `kpi_progress.json` | 7 月实时达成 |
| H1 月度 | `h1_monthly.json` | 1-6 月分月数据 |
| H2 目标 | `h2_monthly_targets.json` | 7-12 月目标 |
| 三年月度 | `three_year_monthly.json` | 2024-2026 年月度对比 |
| 人员 | `_personnel.json` | 在职人员清单 |
| 客户定价 | `pricing/*.json` | 客户历史价格 |

---

## 六、运维手册

### 6.1 启动后端

```bash
cd ~/Desktop/Hermes输出-工作类
python3 脚本/销售工作台服务.py 8765
```

### 6.2 启动 Tunnel

```bash
cloudflared tunnel --url http://localhost:8765
```

### 6.3 部署前端

```bash
cp 工具/销售工作台.html /tmp/tcb_deploy/index.html
tcb hosting deploy /tmp/tcb_deploy -e bier-sales-d0gatbvlx288724e9
```

### 6.4 Tunnel URL 变更时

Tunnel 重启后 URL 会变，需同步更新两处：

1. `工具/销售工作台.html` 中的 `API_BASE_URLS` 和 `feishuAutoLogin` 的 `AUTH_URLS`
2. 重新执行 6.3 部署

### 6.5 强制刷新数据缓存

```bash
# 全量刷新
curl -X POST http://127.0.0.1:8765/api/mcp/refresh -d '{"type":"all"}'

# 单项刷新
curl "http://127.0.0.1:8765/api/mcp/customers?refresh=1"
```

---

## 七、v2.0 更新日志

| 日期 | 更新内容 |
|------|---------|
| 2026-07-26 | **MCP 实时数据架构上线**：客户/订单/活动从 Excel → MCP 实时拉取 |
| 2026-07-26 | 飞书桌面端 OAuth 免登 |
| 2026-07-26 | 三级降级策略（Tunnel → localhost → JSON） |
| 2026-07-26 | 5 分钟自动刷新（仅可见 tab） |

---

## 八、已知限制 & 后续规划

| 项目 | 状态 | 计划 |
|------|------|------|
| KPI 实时计算 | 仍用本地 JSON | 从 MCP 订单实时聚合 |
| 三年对比 2026 年 | 部分本地 | 完全切 MCP |
| Tunnel URL 不稳定 | 重启会变 | 使用固定域名 |
| 飞书应用正式发布 | 开发版 | 提交审核 |
| 待办同步飞书 | 本地 | 双向同步到飞书项目 |

---

## 九、联系方式

- **产品负责人**：刘新元
- **工作台地址**：https://bier-sales-d0gatbvlx288724e9-1458438710.tcloudbaseapp.com
- **后端服务**：macOS 本机 `localhost:8765`