156 lines
4.9 KiB
Markdown
156 lines
4.9 KiB
Markdown
# 中国邮政揽收系统 - 自动填单工具
|
||
|
||
通过 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 行数据
|
||
→ 产品搜索 (autocomplete API) → 用户选择
|
||
→ 客户搜索 (autocomplete API) → 用户选择
|
||
→ 运单查询 → 获取收寄件人/地址/电话
|
||
→ 地址匹配 → 获取区划代码
|
||
→ 组装表单 (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 同目录）。
|
||
|
||
### 2. 选择 Excel
|
||
|
||
点击 `选择文件`，选择要处理的 Excel 文件。
|
||
|
||
### 3. 配置固定值（可选）
|
||
|
||
在 GUI 固定值表格中设置常用字段，勾选 "强制覆盖" 可覆盖 API 获取的值。
|
||
|
||
### 4. 开始处理
|
||
|
||
点击 `▶ 开始处理` → 弹出产品/客户选择框 → 确认提交信息 → 自动批量处理后续行。
|
||
|
||
## Excel 格式
|
||
|
||
| 字段 | 说明 | 来源 |
|
||
|------|------|------|
|
||
| 单号 | 运单号 | Excel 必填 |
|
||
| 重量 | 单位克 | Excel |
|
||
| 产品名称 | 用于 autocomplete 搜索 | Excel/固定值 |
|
||
| 客户名称 | 用于 autocomplete 搜索 | Excel/固定值 |
|
||
| 收件人/手机/地址 | 运单 API 自动填充，Excel 可覆盖 | API/Excel |
|
||
| 寄件人/手机/地址 | 客户资料 API 自动填充 | API/固定值 |
|
||
| 寄达地/寄达地区划 | 地址匹配 API 自动获取，固定值可强制覆盖 | API/固定值 |
|
||
| 电商平台 | 默认 "无"(WU) | 默认值 |
|
||
| 付款方式 | 默认 "寄付"(1) | 默认值 |
|
||
| 内件属性 | 产品 API 返回 `innerpartsType` | API |
|
||
| 运输类型 | 默认 "陆运"(1) | 默认值 |
|
||
|
||
## 配置说明 (config.json)
|
||
|
||
### system
|
||
- `url`: 揽收系统地址
|
||
|
||
### timing
|
||
- `delay_between_rows_ms`: 行间延时（毫秒）
|
||
|
||
### fixed_values
|
||
```
|
||
"字段名": {"value": "值", "force": false}
|
||
```
|
||
`force: true` 时覆盖 API 获取值。
|
||
|
||
### defaults
|
||
字段的默认值（中文名，自动翻译为系统编码）。
|
||
|
||
### field_mapping
|
||
Excel 列名 → 表单参数名的自定义映射。内置映射覆盖常见字段，仅需在此配置自定义列名。
|
||
|
||
## 文档
|
||
|
||
项目级文档见 `../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` | 改寄达地后成功提交 |
|
||
|
||
## 开发
|
||
|
||
### 日志等级
|
||
|
||
`log.py` 中修改 `LEVEL`:
|
||
- `0` = 仅用户级消息
|
||
- `1` = 调试级
|
||
- `2` = 追踪级（API 请求/响应）
|
||
|
||
修改后重新打包生效。
|