重构物流客服模块并完善会话接待工作台
- 拆分应用工厂、业务服务与路由，保留原有 HTTP/SSE 和存储入口 - 分离页面资源，重排客服工作台并完善响应式导航、草稿和附件交互 - 整理维护脚本、请求示例和贡献指南，移除启动脚本中的密钥配置 - 上传文件改为仅本地保留，补充隔离的后端与前端回归验证 验证：46 项 Python 测试通过，含 14 个已有子测试；12 个 Node 前端场景通过。
This commit is contained in:
@@ -0,0 +1,113 @@
|
||||
# 模块导航与拆分规范
|
||||
|
||||
四阶段拆分已落地：`am.py` 保留命令及 WSGI 兼容入口，应用工厂和业务代码位于 `logistics_chat/`，页面样式与脚本位于 `static/`。本文描述当前结构及后续结构调整约定。
|
||||
|
||||
## 先定位，再阅读
|
||||
|
||||
从 [AGENTS.md](../AGENTS.md) 选择文件，以函数、常量、接口为锚点，搜索后只读取相关实现和调用方。模块移动时更新索引，不保存易失效的行号。默认遵守 Git 忽略规则，排除附件、数据库、日志、备份、虚拟环境和工作草稿。
|
||||
|
||||
```powershell
|
||||
rg --files
|
||||
rg -n -F 'calc_freight' logistics_chat/pricing.py
|
||||
rg -n -F '/api/human/' logistics_chat/routes static/js examples
|
||||
rg -n '^(def |class | def )' scripts tests -g '*.py'
|
||||
```
|
||||
|
||||
PowerShell 下把目录和 `-g '*.py'` 分开传给 `rg`。报价字典可能整行很长，搜索时加 `--max-columns 200 --max-columns-preview`，避免输出整份数据。
|
||||
|
||||
## 当前模块索引
|
||||
|
||||
| 业务范围 | 实际文件与搜索锚点 | 联动位置 |
|
||||
|---|---|---|
|
||||
| 应用入口与配置 | `am.py`：`main`、延迟访问的 `app`；`logistics_chat/__init__.py`：`create_app`；`config.py`：`default_config`、`get_setting`；`runtime.py`：`serve_app` | `start.bat`、`.env.example` |
|
||||
| 请求钩子 | `logistics_chat/hooks.py`：`rate_limit`、`no_cache_html` | 工厂注册钩子；限流状态在 `app.extensions['rate_hits']` |
|
||||
| SQLite 与维护 | `logistics_chat/db.py`：`connect`、`close_connections`、`init_db`、`backup_db`、`save_message`、`last_user_question`、`load_context` | 维护 CLI 在 `scripts/`；旧会话自动清理仍未启用 |
|
||||
| 历史接口 | `logistics_chat/history_service.py`：`new_chat`、`get_history`、`get_messages`、`del_history`、`clear_all`；对应 `routes/history.py` | `static/js/chat.js`：`ensureConv`、`loadHistory`、`openConversation` |
|
||||
| 知识检索 | `logistics_chat/knowledge.py`：`knowledge_list`、`search_knowledge` | [knowledge.md](knowledge.md) 与代码同步，程序不读取该文档 |
|
||||
| 运费与附加费 | `logistics_chat/pricing.py`：`RATES`、`parse_shipping_intent`、`dims_to_cm`、`pick_rate`、`calc_freight`、`freight_reply`、`calc_warehouse_card`、`detect_surcharge`、`check_island` | `logistics_chat/rates_extra.py` 为唯一扩展数据源，根目录同名文件仅兼容转发 |
|
||||
| 运单轨迹 | `logistics_chat/tracking.py`：`extract_tracking_no`、`build_track`、`CARD_PREFIX`、`card_to_text` | `static/js/chat.js`：`fillTrackCard`、`addTrackCard`；模拟节点时间取当前时刻，回归对照需固定时钟 |
|
||||
| AI 与 SSE | `logistics_chat/chat_service.py`：`create_chat_stream`、`sse`；`ai_client.py`：`post_completion`、`compress_answer`、`gen_followups` | `routes/chat.py`：`stream_chat`；客户端 `doSend`、`renderError`、`renderFollowups` |
|
||||
| 人工会话 | `logistics_chat/human_service.py`：`human_*`；对应 `routes/human.py` | 输入状态在 `app.extensions['human_typing']`；客户 `startHumanPoll`；客服 `loadQueue`、`poll`、`sendReply` |
|
||||
| 附件 | `logistics_chat/file_service.py`：`upload_file`、`cleanup_uploads`；`routes/files.py`：`uploaded_file` | 扩展名/大小/目录由配置提供；客户端 `addMsg`，客服端 `appendMsg` |
|
||||
| 登录、统计、订单、留言、导出 | `logistics_chat/business_service.py`：`admin_login`、`admin_stats`、`my_orders`、`add_ticket`、`list_tickets`、`export_chat` | `routes/admin.py`、`routes/business.py`；登录页 `static/js/admin_login.js` |
|
||||
| 页面 | `templates/index.html`、`templates/admin.html`、`templates/admin_login.html` | 先加载共享 `static/css/theme.css`，再加载对应 `chat`、`admin`、`admin_login` 的 CSS/JS；保留全局事件入口 |
|
||||
| 回归 | `tests/test_rules.py`、`test_storage.py`、`test_api.py`、`test_startup.py`、`test_maintenance_scripts.py`、`test_frontend.py`；`tests/frontend/admin.test.cjs` | 数据、HTTP 与 SSE 使用隔离配置和模拟模型；Node 内置测试验证草稿、异步发送和服务资料抽屉；浏览器使用临时测试库 |
|
||||
|
||||
除标明的根目录文件外，表内缩写的 Python 文件均相对 `logistics_chat/`。
|
||||
|
||||
## 当前文件布局
|
||||
|
||||
```text
|
||||
am.py # CLI；显式请求 am.app 时创建默认 WSGI 应用
|
||||
rates_extra.py # 旧导入路径的兼容转发
|
||||
logistics_chat/
|
||||
├── __init__.py # create_app 与显式运行时初始化
|
||||
├── config.py # 环境变量、稳定根路径、服务/资源配置
|
||||
├── db.py # 连接、schema、历史持久化、备份
|
||||
├── knowledge.py # 知识与关键词检索
|
||||
├── pricing.py # 运费规则、解析、换算、附加费说明
|
||||
├── rates_extra.py # 扩展报价数据
|
||||
├── tracking.py # 单号识别、模拟轨迹、卡片协议
|
||||
├── ai_client.py # 模型 HTTP、压缩与追问
|
||||
├── chat_service.py # 问答编排与 SSE 帧
|
||||
├── history_service.py # 历史会话 CRUD
|
||||
├── human_service.py # 人工状态与消息
|
||||
├── business_service.py # 反馈、统计、登录、订单、留言、CSV
|
||||
├── file_service.py # 附件校验、保存、清理
|
||||
├── hooks.py # 限流及 HTML/SSE 缓存头
|
||||
├── runtime.py # Waitress / Flask 启动
|
||||
└── routes/
|
||||
├── __init__.py # Blueprint 注册
|
||||
├── chat.py
|
||||
├── history.py
|
||||
├── human.py
|
||||
├── admin.py
|
||||
├── business.py
|
||||
├── files.py
|
||||
└── pages.py
|
||||
templates/ # HTML/Jinja 及原有事件属性
|
||||
static/css/ # theme.css 共享令牌；chat/admin/admin_login 页面样式
|
||||
static/js/ # chat.js、admin.js、admin_login.js，经典脚本
|
||||
scripts/ # 可独立运行的维护 CLI
|
||||
tests/ # 按业务模块组织的回归
|
||||
```
|
||||
|
||||
## 模块边界与依赖方向
|
||||
|
||||
- 路由只解析请求并包装响应；服务组织业务；规则模块提供确定性计算。依赖方向为 `routes → services → rules / db / ai_client`，下层不导入路由或根入口。
|
||||
- `db.py` 统一连接、schema 和历史持久化。人工与管理业务的 SQL 放在所属服务，HTTP 路由不执行 SQL。请求及流式请求结束时关闭连接，未提交事务回滚。
|
||||
- 所有模型 HTTP 经 `ai_client.post_completion`。保留流式问答 `(5, 90)`、压缩 `(5, 30)`、追问 `(5, 15)` 三组连接/读取超时；不能因共用客户端而合并期限。流结束或取消时释放 HTTP 响应。
|
||||
- 模块导入不建库、不备份、不清理附件、不访问模型。`create_app` 默认显式初始化运行目录、数据库、备份与旧附件清理；`INITIALIZE_RUNTIME=False` 可禁止这些动作，此时调用方负责提供已有 schema。访问兼容入口 `am.app` 视为显式创建应用。
|
||||
- `config.ROOT_DIR` 指向仓库根目录，模板/静态目录显式提供给 Flask。数据库、上传、备份、日志使用配置中的绝对路径，避免包文件移动改变数据位置。
|
||||
- 限流、输入状态由应用实例持有，不能每请求重置或跨测试应用共享。维护 CLI 和纯规则可用标准库加载，包入口延迟导入 Web 依赖。
|
||||
- 单文件围绕一个职责；超过约 300–400 行时检查职责，而非按行数机械拆分。报价数据保持单一来源；兼容转发不复制字典。页面脚本按页面保留既有执行顺序和全局函数，不擅自改为 ES Modules。
|
||||
- 配色、字体基线和通用控件放在 `theme.css`，页面布局放在对应 CSS。客户页通过 `body.dark` 覆盖主题令牌；新增可翻译文案加入 `chat.js` 的 `I18N`，静态文案用 `data-i18n`。调整样式后检查桌面、390px 窄屏、侧栏、聊天卡片和客服空/活动状态。
|
||||
- 客户附件预览由 `clearAttachment` 管理，轨迹展开由 `fillTrackCard` 管理。客服 `drafts` 按 `sid` 保存草稿，发送成功后只清理已确认发送的内容；常用回复仅填入草稿。`renderList` 只在展示数据变化时重绘。
|
||||
- 客服工作台默认只展示会话列表和全高聊天区；统计使用原生 `details` 收在「数据概览」。`setSessionTab` 切换接待/排队列表，`setChatView` 与 `showSessionList` 控制 720px 及以下的整屏导航，不结束当前会话。`setToolsOpen` 控制默认关闭的服务资料：1200px 以上为侧栏，较窄屏为抽屉；列表入口让未选会话的手机用户也能查看留言。
|
||||
|
||||
## 后续结构调整顺序
|
||||
|
||||
| 阶段 | 范围 | 验收要求 |
|
||||
|---|---|---|
|
||||
| 1. 纯规则 | 知识、报价、运费、运单识别 | 边界结果与迁移前一致；固定时钟比较模拟轨迹；导入无运行数据副作用 |
|
||||
| 2. 数据访问 | 配置、SQLite、备份、附件 | 临时目录验证 schema 兼容、事务、保留/清理时机和跨目录 CLI |
|
||||
| 3. 服务/路由 | 模型、聊天、人工、应用工厂、Blueprint | URL/方法/状态/JSON/SSE 不变；保留限流、HTML/SSE 缓存头及根入口 |
|
||||
| 4. 前端 | 模板与 CSS/JS | 仅迁移时对照原资源内容；主动改版时验证语法、资源 URL、加载顺序、响应式和客户/客服页交互 |
|
||||
|
||||
每阶段完成相关验证再推进依赖阶段。鉴权、缺表和计费的业务修复单独说明，避免在结构调整中顺带改行为。
|
||||
|
||||
## 必须保留的接口与数据约定
|
||||
|
||||
- SSE 字段为 `t`、`e`、`card`、`replace`、`suggest`、`d`，保留流式输出、停止、异常及中断保存。
|
||||
- `chat_service.create_chat_stream` 在识别运单号时忽略 `[图片]/uploads/...` 和 `[文件]/uploads/...` 路径，避免附件文件名中的时间戳误触发查询；存储与请求仍保留原始附件标记和 URL。
|
||||
- 历史卡片以 `__CARD__{json}` 保存；原 SQLite 表、字段、角色值和历史记录继续可读。
|
||||
- 人工申请使用 `conv_id`，返回 `session_id`，后续用 `sid`。状态为 `waiting/active/closed`，消息方向为 `customer/agent`。
|
||||
- 计费档位、单位换算和舍入保持原样。`calc_freight.total` 仅含基础运费；附加费尚未统一并入。知识文档与 `knowledge_list` 同步维护。
|
||||
- 上传 URL 保留 `/uploads/`，默认 10MB，扩展名配置保持不变。原附件保留本地、继续忽略，目录迁移不另建一份数据。
|
||||
- `agents`、`orders`、`tickets` 缺少初始化、后台鉴权不完整、轨迹为模拟数据，仍是已知限制。临时 UI/接口测试中补表只属于测试夹具，不代表修复生产初始化。
|
||||
|
||||
## 验证与维护
|
||||
|
||||
先按 README 安装项目依赖。Windows 使用 `.\.venv\Scripts\python.exe -m pytest -v` 或同解释器的 `-m unittest discover -s tests -v`；Linux/macOS 使用 `.venv/bin/python`。业务测试依赖 Flask，不能用未安装依赖的全局 Python 运行整套测试。模型请求全部模拟，不代表真实 DeepSeek 联调。
|
||||
|
||||
路径、函数或资产移动后同步更新根 `AGENTS.md`、本文、知识资料和 README 目录树。仅改导航时检查路径、符号、命令；改业务时补充相关成功和失败分支，前端改动检查实际页面。
|
||||
@@ -0,0 +1,146 @@
|
||||
# 柏悦智能物流客服系统 · 知识资料
|
||||
|
||||
> 本文件整理了 [logistics_chat/knowledge.py](../logistics_chat/knowledge.py) 中的 `knowledge_list`，供评审与知识维护使用。
|
||||
> 数据来源：炜易达 VIP 10月15日9点执行报价表。
|
||||
> 修改知识内容请编辑 `logistics_chat/knowledge.py` 中的 `knowledge_list`，并同步更新本文件；程序不会直接读取此文档。
|
||||
|
||||
---
|
||||
|
||||
## 目录
|
||||
|
||||
1. 公司介绍（1 条）
|
||||
2. 联系方式与营业时间（2 条）
|
||||
3. 渠道与价格（7 条）
|
||||
4. 计费规则（4 条）
|
||||
5. 收货与交仓（2 条）
|
||||
6. 产品与禁限运（1 条）
|
||||
7. 清关与报关（2 条）
|
||||
8. 理赔与退件（2 条）
|
||||
9. FBA 与海外仓（1 条）
|
||||
|
||||
合计 **22** 条知识条目。
|
||||
|
||||
---
|
||||
|
||||
## 1. 公司介绍
|
||||
|
||||
### 公司、柏悦、柏悦物流、介绍、哪家、哪家货代、你们是哪家
|
||||
|
||||
浙江柏悦物流位于义乌，主营中欧跨境物流专线，依托义乌、宁波口岸优势，服务中小跨境卖家。主要渠道：欧洲海运快线、义乌-中欧铁路、中欧卡航、欧洲空运（空派）、英国空运，均支持欧洲、英国双清包税与VAT递延。义乌、泉州、广州、深圳均可交仓。
|
||||
|
||||
---
|
||||
|
||||
## 2. 联系方式与营业时间
|
||||
|
||||
### 人工客服、人工、客服、转人工、在线吗、上班、工作时间、营业时间、几点、周六、周日、星期六、星期日、星期天、礼拜、周末、双休、节假日、放假、休息
|
||||
|
||||
人工客服在线时间：**周一至周五 9:00—18:00**。周六、周日及法定节假日人工客服不上班。非工作时间可以先留言或提交需求，业务员会在下一个工作日回复您。
|
||||
|
||||
### 电话、联系方式、怎么联系、联系你们、微信
|
||||
|
||||
可以联系您的专属业务员，或在人工客服在线时间（周一至周五 9:00—18:00）通过在线客服咨询。建议提前准备好运单号、货物信息（品名、重量、尺寸、目的国），方便快速处理。
|
||||
|
||||
---
|
||||
|
||||
## 3. 渠道与价格
|
||||
|
||||
### 海运、船运、海派、海运快线、樱花快线
|
||||
|
||||
欧洲海运快线（双清/递延）单价：21KG+ 12.3元/kg，101KG+ 10.3元/kg，500KG+ 10.2元/kg，2000KG+ 10.0元/kg。时效：开船后38-45天提取。可走樱花快线（+0.3元/kg），递延价减1.7元/kg。主派送为UPS/DHL/DPD/CWE统配。
|
||||
|
||||
### 铁路、中欧班列、班列、义乌铁路、火车
|
||||
|
||||
义乌-中欧铁路专线单价：21KG+ 15.5元/kg，100KG+ 和 1000KG+ 均为13.5元/kg。时效：发车后36-40天提取。VAT递延减1元/kg。只限送义乌仓，义乌装柜经阿拉山口/霍尔果斯出境。
|
||||
|
||||
### 卡航、卡车、卡派
|
||||
|
||||
中欧卡航单价：21KG+ 19.4元/kg，101KG+ 和 500KG+ 17.4元/kg，2000KG+ 及 4000KG+ 17.3元/kg。时效：发车后欧盟16-20天提取。递延减1.5元/kg，普卡时效18-22天。纯纺织品另加5元/kg。
|
||||
|
||||
### 空运、空派、航空、欧洲空运
|
||||
|
||||
欧洲空运专线（空派）单价：21KG+ 39元/kg，45KG+ 38元/kg，71KG+ 37元/kg，101KG+ 36元/kg。时效：10-13天左右提取；快线8-13天，直飞快线12-15天。一票多件单件不足12KG按12KG计费。
|
||||
|
||||
### 英国海运、英国铁路、中英卡航、英国专线
|
||||
|
||||
英国专线(DPD)双清价格：英国海运21KG+ 12.8元/kg、101KG+/301KG+ 10.9元/kg，时效约40天提取；英国铁路21KG+ 18.0元/kg、101KG+ 16.2元/kg，发车后25-30天提取；中英卡航21KG+ 21.4元/kg、101KG+ 19.4元/kg，发车后20-22天提取。VAT自税/递延价更低（海运10.0/8.1、铁路15/13.2、卡航18.4/16.4）。北极航线英国海运25-28天，价格单询。卡航单件不超30kg、尺寸≤98×68×59cm。
|
||||
|
||||
### 英国空运、英国、UK、伦敦
|
||||
|
||||
英国空运专线（双清）单价：22KG+ 48元/kg，51KG+ 44元/kg，101KG+ 42元/kg，时效8-10个自然日提取。VAT自税/递延为44/40/38元/kg，带电货47.5/42.5/41.5元/kg。拒收北爱尔兰、苏格兰高地等偏远地址。
|
||||
|
||||
### 时效、多久、要几天、多长时间
|
||||
|
||||
各渠道时效：欧洲海运快线开船后38-45天提取；中欧铁路发车后36-40天提取；中欧卡航发车后16-20天提取；欧洲空运10-13天提取；英国空运8-10个自然日提取。海关查验、罢工、节假日等不可抗力导致的时间不计入。
|
||||
|
||||
---
|
||||
|
||||
## 4. 计费规则
|
||||
|
||||
### 报价、价格、费用、计费、怎么收费、计费重量、多少钱、运费、单价
|
||||
|
||||
运费计算方式：阶梯单价 × 计费重量。计费重量 = 实重与材积重取大值，材积 = 长×宽×高(cm)÷6000，即1CBM=167KG。各渠道最低起收21KG（英国空运22KG）。单件计费重不足13KG的渠道（铁路、卡航）按5元/kg加收超轻费；空运单件不足12KG按12KG计费。偏远地址加7元/kg，单票最低250元。价格不含税，税点以开出的发票为准。
|
||||
|
||||
|
||||
### 超轻费、计费重量不足、最低计费
|
||||
|
||||
单件计费重量不得低于13KG（空运12KG），可整票按平均13KG算，不足部分按5元/kg加收超轻费。例：单箱只有12KG，加收5×1=5元超轻费。欧洲热门仓卡派直送要求单件平均计费重12KG，不足按2元/kg加收派送费。
|
||||
|
||||
|
||||
### 偏远、偏远费、偏远地址
|
||||
|
||||
偏远地址加收7元/kg（不含燃油），单票偏远费最低消费250元/票。需要自行到UPS/DPD官网查询目的地址是否偏远，我司出货时不另行通知，以账单为准，偏远费6个月内有效。
|
||||
|
||||
|
||||
### 超重、超长、超大、尺寸限制
|
||||
|
||||
欧洲空运最长边≤99cm、次长边≤75cm、实重<24KG。英国DPD单件≤30KG，尺寸100×70×60cm以内，超重或超长各加收330元/件。UPS单边最长≤99cm、次边≤75cm、单件<24KG，超出加收240元+100元。热门仓卡派直送：单件超40KG加收30元/件。
|
||||
|
||||
|
||||
## 5. 收货与交仓
|
||||
|
||||
### 揽收、上门取件、上门收货、交仓、交货
|
||||
|
||||
义乌、深圳（龙华观澜、宝安福园）、广州（石井）、泉州均可交仓，义乌仓10:00-21:00收货。欧洲空运交仓义乌+1元/kg，泉州、广州+0.5元/kg；海运、铁路、卡航泉州交货+0.5元/kg。
|
||||
|
||||
|
||||
### 入仓、进仓、仓库收货、仓库地址、仓库在哪、义乌仓、交仓地址、送仓
|
||||
|
||||
义乌仓：义乌市稠江街道梦娜袜业德贸路东三门进，李东文 19558263692（10:00-21:00）。深圳龙华：龙华区观澜街道君子布社区张一村路黄背坑路1号B栋，张长印 18688937838。深圳宝安：福园二路九号海亨通物流B区C09-C14。广州：恒河沙仓储石井仓211，潘志红 13789206500。送货需打印交接清单随货交仓。
|
||||
|
||||
|
||||
## 6. 产品与禁限运
|
||||
|
||||
### 敏感、带电、电池、液体、粉末、禁品、不能寄、违禁品、拒收、拒接
|
||||
|
||||
可接带标准箱100瓦以下非危电池/内电产品（C卡航、海运快线均可），资料齐全加1元/kg，资料不齐加2元/kg；手机、平板电脑加5元/kg。拒接：纯液体、纯粉末、药品、食品、易燃易爆、仿牌侵权、木制品（空运）、陶瓷手表等反倾销品、电子烟、管制刀具、枪支。电池第一个托收400元/件，第二个起100元/件，600元封顶。
|
||||
|
||||
|
||||
## 7. 清关与报关
|
||||
|
||||
### 清关、递延、VAT、双清、包税、DDP
|
||||
|
||||
欧洲、英国渠道均支持双清包税与VAT递延（只付关税，增值税销售后缴纳）。递延需提供法人护照/身份证、欧盟VAT和EORI号及回执、营业执照、4份模板文件原件扫描件PDF。罗马尼亚等欧盟国家有二次清关风险，二次关税由客户自行缴纳。
|
||||
|
||||
|
||||
### 报关、单独报关、报关费
|
||||
|
||||
单独报关费用：空运350元/票，海运200元/票，铁路250元/票，卡航200元/票，续页费50元/页。一达通报关500元/票。单票品名最多5个，第6个起加收30元/个。报价不含税，税点以开出的发票为准。
|
||||
|
||||
|
||||
## 8. 理赔与退件
|
||||
|
||||
### 理赔、货损、丢件、赔付、破损、压坏、索赔
|
||||
|
||||
遗失赔付：未提取上网遗失按申报价值赔偿，最高不超过40元/kg，不退运费；已提取遗失按服务商标准，最高100USD/票。开查时间：交仓后7天未提取可申请开查，开查30天无果走索赔。签收后亚马逊未上架需2周内提出调查，包裹异常需1个月内提出。外包装无损的内件丢失不支持理赔，易碎品损坏不支持理赔。可自购保险，保费为货值千分之三（电池千分之五）。
|
||||
|
||||
|
||||
### 退件、退回、退货、退运、改地址
|
||||
|
||||
海运/铁路为散货拼柜，已装柜不接受退件和扣件。空运国外扣件费200欧/票，收件人改派地址最低200元/票。退回海外仓：德国境内15欧/件，欧盟境内25欧/件，操作费100元/票，5个工作日免仓储，超期1欧/kg/天。重派德国10欧/件、欧盟20欧/件。
|
||||
|
||||
|
||||
## 9. FBA 与海外仓
|
||||
|
||||
### 亚马逊、FBA、海外仓、仓库配送、卡派
|
||||
|
||||
支持FBA头程送亚马逊仓，热门仓卡派直送（德国WRO5/HAJ1/DTM1/DTM2、法国CDG7/LIL8、意大利TRN3、西班牙BCN8、罗马尼亚EMAG等）。卡派直送优势：超重附加费少、不限尺寸重量、上架快、基本无丢件。法国、意大利、西班牙其他亚马逊仓不能超UPS标准。
|
||||
Reference in New Issue
Block a user