174 lines
6.4 KiB
Markdown
174 lines
6.4 KiB
Markdown
# 中国邮政揽收系统 - 自动填单工具 v2.0
|
||
|
||
通过 HTTP API + Node.js token bridge 实现，**不依赖浏览器自动化**。读取 Excel 运单数据，逐条自动填写产品、客户、运单信息并提交。
|
||
|
||
## 运行环境
|
||
|
||
- Windows 10/11 64 位
|
||
- **Node.js 18+**（用于 token bridge，计算 $_ts 安全框架的 c93l5Fya 动态 token）
|
||
|
||
## 快速开始
|
||
|
||
```bash
|
||
# 安装 Python 依赖
|
||
uv sync
|
||
|
||
# 安装 token bridge 依赖
|
||
cd token_bridge && npm install && cd ..
|
||
|
||
# 运行
|
||
uv run python main.py
|
||
```
|
||
|
||
## 打包
|
||
|
||
```bash
|
||
build.bat # Windows
|
||
bash build.sh # Linux
|
||
```
|
||
|
||
输出 `dist/PickupAuto.exe`，用户端需安装 Node.js 18+。
|
||
|
||
## 架构
|
||
|
||
```
|
||
┌─────────────────────────────────────────┐
|
||
│ Python (requests.Session) │
|
||
│ ├─ engine.py 引擎/表单组装/提交 │
|
||
│ ├─ pickup_api.py HTTP API 封装(18个) │
|
||
│ ├─ login_helper.py cookies 导入 │
|
||
│ ├─ field_mapping.py 中文字段映射 │
|
||
│ ├─ excel_reader.py Excel 读写 │
|
||
│ ├─ main.py Tkinter GUI │
|
||
│ └─ log.py 统一日志 │
|
||
├─────────────────────────────────────────┤
|
||
│ Node.js (HTTP server, 同进程启动) │
|
||
│ └─ token_bridge/server.js │
|
||
│ jsdom 加载 $_ts 安全 JS │
|
||
│ 计算 c93l5Fya token │
|
||
└─────────────────────────────────────────┘
|
||
```
|
||
|
||
### 数据流
|
||
|
||
```
|
||
Excel 行数据
|
||
→ 产品选择 (启动前搜索 + 缓存) → 用户确认
|
||
→ 客户选择 (启动前搜索 + 缓存) → 用户确认
|
||
→ 运单查询 → 获取收寄件人/地址/电话
|
||
→ 地址匹配 → 获取区划代码
|
||
→ 组装表单 (5层优先级) → 确认弹窗（首行） → 提交
|
||
```
|
||
|
||
### 表单字段优先级
|
||
|
||
```
|
||
强制固定值 (force=true)
|
||
> API 获取值 (运单/产品/客户/地址匹配)
|
||
> 固定值 (force=false)
|
||
> Excel 表格值
|
||
> 默认值 (config.json defaults)
|
||
```
|
||
|
||
### token bridge 原理
|
||
|
||
揽收系统使用 `$_ts` 安全框架（954KB 混淆 JS），所有 AJAX 请求需附带 `c93l5Fya=TOKEN` 参数。token bridge 在 jsdom 中运行该 JS，通过 HTTP API 对外提供 token 计算服务，Python 拿到 token 后用自己的 `requests.Session` 发请求。
|
||
|
||
## 使用流程
|
||
|
||
### 1. 登录（获取 cookies）
|
||
|
||
点击 `🔑 登录` → 弹出对话框 → 用浏览器 cookies 导出工具导出 `10.4.188.1` 的所有 cookies 为 JSON 数组 → 粘贴到对话框 → 保存。
|
||
|
||
cookies 保存到 `session.json`（与 exe 同目录）。登录成功后自动初始化 token bridge 和搜索 API，供后续产品/客户搜索使用。
|
||
|
||
`HFZrs6pXKulzS` 为可选 cookie：导出数据中存在时导入，不存在时不影响必需 cookie 检查。运行期间若服务器通过 `Set-Cookie` 返回该 cookie，会自动接收，并在保存会话时保留。
|
||
|
||
### 2. 选择产品/客户
|
||
|
||
登录后，在"固定值设置"区域的产品和客户输入框中输入关键词，自动触发搜索并弹出下拉选择框。选中后自动获取产品详情和客户详情并缓存，缓存有效期为一个 batch（处理完一批 Excel 数据后自动清空）。
|
||
|
||
### 3. 选择 Excel
|
||
|
||
点击 `选择文件`，选择要处理的 Excel 文件。
|
||
|
||
### 4. 配置固定值（可选）
|
||
|
||
在固定值区域填写：
|
||
|
||
| 字段 | 说明 |
|
||
|------|------|
|
||
| 产品 | 用于 autocomplete 搜索，从下拉框选择 |
|
||
| 客户 | 用于 autocomplete 搜索，从下拉框选择 |
|
||
| 寄达地 | 强制覆盖运单返回的寄达地（勾选强制覆盖后生效） |
|
||
| 寄达地区划代码 | 直接决定寄达地，勾选强制覆盖后优先级最高 |
|
||
| 寄件人姓名 | 强制覆盖客户资料中的寄件人 |
|
||
| 寄件地址 | 强制覆盖客户资料中的寄件地址 |
|
||
| 长 / 宽 / 高 | 有值即强制覆盖提交表单中的包裹尺寸 |
|
||
|
||
### 5. 开始处理
|
||
|
||
点击 `▶ 开始处理` → 首行弹出确认弹窗 → 确认后自动批量处理后续行。提交结果实时显示在下方表格中。
|
||
|
||
## Excel 格式
|
||
|
||
| 字段 | 说明 | 来源 |
|
||
|------|------|------|
|
||
| 单号 | 运单号 | Excel 必填 |
|
||
| 重量 | 单位克 | Excel |
|
||
| 产品名称 | 用于 autocomplete 搜索 | Excel/固定值 |
|
||
| 客户名称 | 用于 autocomplete 搜索 | Excel/固定值 |
|
||
| 收件人/手机/地址 | 运单 API 自动填充，Excel 可覆盖 | API/Excel |
|
||
| 寄件人/手机/地址 | 客户资料 API 自动填充 | API/固定值 |
|
||
| 寄达地/寄达地区划 | 地址匹配 API 自动获取，固定值可强制覆盖 | API/固定值 |
|
||
| 电商平台 | 默认 "无"(WU) | 默认值 |
|
||
| 付款方式 | 默认 "寄付"(1) | 默认值 |
|
||
| 内件属性 | 产品 API 返回 `innerpartsType` | API |
|
||
| 运输类型 | 默认 "基本"(1)，陆运=3 | 默认值 |
|
||
|
||
## 配置说明 (config.json)
|
||
|
||
### system
|
||
- `url`: 揽收系统地址
|
||
|
||
### timing
|
||
- `delay_between_rows_ms`: 行间延时（毫秒），GUI 中间隔输入框单位也是毫秒
|
||
|
||
### fixed_values
|
||
```
|
||
"字段名": {"value": "值", "force": false}
|
||
```
|
||
`force: true` 时覆盖 API 获取值。GUI 中通过复选框控制，点击"开始处理"时自动保存到配置文件。
|
||
长、宽、高在 GUI 中填写后会自动保存为强制固定值；留空时不覆盖 Excel 或系统已有值。
|
||
|
||
### defaults
|
||
字段的默认值（中文名，自动翻译为系统编码）。
|
||
|
||
### field_mapping
|
||
Excel 列名 → 表单参数名的自定义映射。内置映射覆盖常见字段，仅需在此配置自定义列名。
|
||
|
||
## 开发
|
||
|
||
### 日志等级
|
||
|
||
`log.py` 中修改 `LEVEL`:
|
||
- `-1` = 关闭所有日志（默认）
|
||
- `0` = 仅用户级消息
|
||
- `1` = 调试级
|
||
- `2` = 追踪级（API 请求/响应）
|
||
|
||
修改后重新打包生效。
|
||
|
||
## 文档
|
||
|
||
项目级文档见 `../docs/`：
|
||
|
||
| 文件 | 说明 |
|
||
|------|------|
|
||
| `分析报告.md` | 系统 API 分析 |
|
||
| `字段覆盖检查报告.md` | 字段来源和覆盖关系 |
|
||
| `har-successful-submit-fields.json` | 成功提交的完整表单字段模板 |
|
||
| `portal-to-pickup-full-flow.har` | 门户→揽收页面完整网络流 |
|
||
| `product-customer-selection-flow.har` | 产品/客户选择 API 流 |
|
||
| `successful-submit-with-address-change.har` | 改寄达地后成功提交 |
|