# 柏悦智能物流客服系统

基于 Flask + DeepSeek 的中欧/英国跨境物流智能客服，支持多轮对话、运费试算、运单查询、历史会话管理。

## 功能

- **多轮上下文**：能理解"那空运呢""这个多少钱"这类追问
- **知识库优先**：优先使用本地知识库回答，减少模型编造
- **追问兜底**：当前问题没命中关键词时，用上一句提问去检索
- **运费试算**：识别重量/尺寸/渠道，按报价表阶梯单价计算并展示完整明细
- **运单号查询**：发送 8~20 位运单号，返回时间轴轨迹卡片
- **历史会话**：会话保存到 SQLite，支持打开、搜索、删除
- **交互**：停止生成、复制（纯文本）、重答、多行输入、回到底部
- **中英文切换**：右上角「中/EN」按钮或快捷键 `Ctrl + L`
- **异常处理**：接口超时、Key 失效、中断时给出明确提示与重试
- **深色模式**：右上角切换，偏好本地保存
- **响应式**：窄屏下侧栏自动变为抽屉

## 报价数据

运费试算使用 **炜易达 VIP 报价表（2026-10-15 9:00 执行版）** 中的真实数据，覆盖 8 条渠道：

| 渠道 | 21KG+ | 101KG+ | 500KG+ | 2000KG+ | 参考时效 |
|---|---|---|---|---|---|
| 欧洲海运快线 | 12.3 | 10.3 | 10.2 | 10.0 | 开船后 38-45 天 |
| 义乌中欧铁路 | 15.5 | 13.5 | — | 13.5（1000+） | 发车后 36-40 天 |
| 中欧卡航 | 19.4 | 17.4 | 17.4 | 17.3 | 发车后 16-20 天 |
| 欧洲空运 | 39 | 36 | — | 37（71+） | 10-13 天 |
| 英国海运 | 12.8 | 10.9 | — | — | 约 40 天 |
| 英国铁路 | 18.0 | 16.2 | — | — | 25-30 天 |
| 中英卡航 | 21.4 | 19.4 | — | — | 20-22 天 |
| 英国空运 | 48（22+） | 42 | — | 44（51+） | 8-10 天 |

**计费规则**（均来自报价表）：

- 运费 = 阶梯单价 × 计费重量，按重量落入的档位取价
- 计费重量 = 实重与材积重取大，材积 = 长×宽×高(cm) ÷ 6000（1CBM = 167KG）
- 最低起收档 21KG（英国空运 22KG）
- 铁路、卡航单件计费重不足 13KG 加收超轻费 5 元/kg；空运单件不足 12KG 按 12KG 计费
- 偏远地址 +7 元/kg，单票最低 250 元

数据定义在 `am.py` 的 `RATES` 字典中，修改价格只需改这里，不需要动计算逻辑。

### 扩展数据（rates_extra.py）

从同一份报价表提取、目前已支持：

- **海外仓卡派按方计费**：0.5CBM+ / 1CBM+ 两档，按提问里的国家自动匹配仓点分组
- **产品附加费**：47 类产品（手机 5 元/kg、电池 1-2 元/kg、玩具 2 元/kg 等）
- **DPD 岛屿偏远判断**：12 个国家的岛屿/偏远邮编，命中即提示 35 欧/件

用法示例：

| 提问 | 效果 |
|---|---|
| 2方 海运 到德国海外仓多少钱 | 按 1CBM+ 档计算并列出德国仓点分组 |
| 寄手机到德国要加什么费用 | 给出 5 元/kg 附加费 |
| 邮编07000 算偏远吗 | 命中意大利撒丁岛，提示 35 欧/件 |

> ⚠️ 报价表含商业价格与联系人信息，公开发布前请脱敏或替换为示例数据。

## 运行环境

- Python 3.9 及以上
- Windows / macOS / Linux

## 快速启动（Windows）

双击 `start.bat` 即可，脚本会自动检查端口占用、API Key 和依赖。

## 安装与启动

### 1. 安装依赖

```bash
pip install -r requirements.txt
```

### 2. 配置 API Key

Key 不写进代码，通过系统环境变量提供。

Windows PowerShell：

```powershell
setx DEEPSEEK_API_KEY "sk-你的key"
```

设置后需要**重新打开终端**才生效，可用下面的命令确认：

```powershell
echo $env:DEEPSEEK_API_KEY
```

Linux / macOS：

```bash
export DEEPSEEK_API_KEY="sk-你的key"
```

Key 申请地址：https://platform.deepseek.com/api_keys

也可以参考项目根目录的 **.env.example**（不含真实 Key 的配置示例文件），其中列出了需要设置的环境变量及说明。

### 3. 启动服务

```bash
cd E:\wuliu_chat
python am.py
```

### 4. 打开页面

浏览器访问 http://127.0.0.1:5000

## 测试

### 单元测试

```bash
pytest -v
```

共 **52 个用例**，覆盖运费意图解析、运单号识别、阶梯价计算、卡派按方、附加费识别、岛屿邮编、卡片转换等。
测试在临时目录中运行，不会改动 `history.db`。

### 回答长度控制

- 中文回答：120~350 字；英文回答：120~700 字
- 超过上限时由代码自动压缩一次（保留全部数字），仍超标再压一次
- 提示词之外的第二道保险，确保字数可控

### 场景测试

`测试记录.md` 记录了 **29 个业务场景**的输入、预期结果、首次结果、修复动作与复测结果，
其中 26 项通过或已修复，3 项列为未解决／待验证（超长输入、并发提问、无答案兜底）。

## 目录结构

```
wuliu_chat/
├── am.py                主程序（路由、知识库、对话逻辑、运单查询、运费试算）
├── rates_extra.py       报价表扩展数据（卡派按方、附加费、岛屿邮编）
├── test_am.py           单元测试（52 个用例）
├── start.bat            Windows 一键启动脚本
├── requirements.txt     依赖清单
├── README.md            说明文档
├── knowledge.md         知识资料（由 knowledge_list 导出）
├── 测试记录.md          场景测试记录（29 个场景）
├── .gitignore           Git 忽略规则
├── .env.example         配置示例（不含 Key）
├── history.db           SQLite 数据库（会话与消息）
├── static/              静态资源
│   └── fa.jpg           网站图标
├── templates/
│   └── index.html       前端页面
└── .vscode/
    └── launch.json      VS Code 调试配置
```

> `kefu.py`、`SQLite.py` 为早期遗留文件，不影响运行，可安全删除。

## 主要接口

| 方法 | 路径 | 说明 |
|---|---|---|
| GET | `/` | 聊天页面 |
| GET | `/stream_chat?msg=&conv_id=` | 流式对话（SSE） |
| POST | `/api/new_chat` | 新建会话，返回 `{"id": 会话id}` |
| GET | `/api/get_history` | 会话列表 |
| GET | `/api/get_messages?conv_id=` | 单个会话的全部消息 |
| DELETE | `/api/del_history?id=` | 删除会话（级联删消息） |
| DELETE | `/api/clear_all` | 清空全部历史 |

### 流式事件格式

`/stream_chat` 返回 Server-Sent Events，每帧是一条 JSON：

```
data: {"t": "正文片段"}     正常回答片段
data: {"e": "错误提示"}     出错时
data: {"card": {...}}      运单轨迹卡片
data: {"d": 1}             正常结束
```

## 数据库

SQLite，文件为 `history.db`，首次启动自动创建。

- `chat_history`：会话（id、title、ctime、utime）
- `messages`：消息（id、conv_id、role、content、ctime）

运单卡片以 `__CARD__{json}` 形式保存在 `messages.content`，前端识别后重新渲染。

## 常见问题

**页面报"服务未配置 API Key"**
环境变量没读到。确认变量名是 `DEEPSEEK_API_KEY`，并**重新打开终端**后再启动。

**页面报"API Key 无效或已过期"**
Key 已作废，去平台重新生成一把，再用 `setx` 覆盖。

**端口 5000 被占用**
```powershell
netstat -ano | findstr ":5000 "
taskkill /PID <进程号> /F
```
确认只有一行 `LISTENING`，避免两个进程同时抢端口。

**改了 am.py 没生效**
Flask 启动时加载代码，改后端必须重启服务；只改 `index.html` 则刷新页面即可。

## 说明

- 运单轨迹当前为**模拟数据**（按单号固定生成），接真实接口只需修改 `am.py` 中的 `build_track()`。
- 服务使用 Waitress 多线程启动（8 个线程），适合内网小范围使用；面向公网仍需反向代理与 HTTPS。
- 默认只监听 `127.0.0.1`，如需局域网访问，把 `am.py` 中的 `HOST` 改为 `"0.0.0.0"`。
- 运费计费方式为**阶梯单价 × 计费重量**，价格与时效来自炜易达报价表。报价更新时只需修改 `RATES`；知识库文案在 `knowledge_list` 中，两者建议同步更新。
- 材积按 ÷6000 计算（1CBM = 167KG），与部分渠道 ÷5000 的口径不同，修改时注意核对报价表。