# 中国邮政揽收系统 - 自动填单工具

通过 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 请求/响应）

修改后重新打包生效。