autotrain/docs/usage.md

铁路系统发票批量处理使用说明

原则

• 只使用铁路 12306 官方页面/App 完成开票。
• 本工具不保存 12306 账号密码，不绕过验证码或身份核验。
• 公司抬头、税号、接收邮箱从本地配置读取；不要写入 .env。
• config.local.json 已被 .gitignore 忽略，不要把真实公司信息写进 config.example.json。

初始化

python3 scripts/invoice_tool.py init

先复制一份本地配置：

cp config.example.json config.local.json

然后把 config.local.json 里的三项改成真实值：

{
  "company_title": "公司全称",
  "tax_id": "统一社会信用代码",
  "receiver_email": "统一收票邮箱"
}

导入开票码

把旅行社给的二维码图片或 PDF 放到：

data/input/开票码批次/

执行：

python3 scripts/invoice_tool.py import-codes

输出台账：

work/invoice_tasks.csv

如果本机没有二维码解码器，任务会进入 待补码。人工扫码后，把链接或码写入：

data/input/开票码批次/manual_codes.csv

再执行一次 import-codes。

如果这是铁路“扫码开票单”截图，二维码通常只能用 12306 App 扫。可以在 manual_codes.csv 里用 APP_SCAN 补录开票单号和代办人：

source_file,passenger,ticket_ref,code
data/input/开票码批次/ScreenShot_xxx.png,张*木,EKP37846902581249178,APP_SCAN

真实手工 POC

第一次必须用 1-3 张真实开票码在 Mac 上跑通：

1. 把真实二维码图片/PDF 放进 data/input/开票码批次/。
2. 执行 python3 scripts/invoice_tool.py import-codes。
3. 打开 work/invoice_tasks.csv 看状态：
   • 待网页开票：说明二维码可在 Mac 网页端继续，后续可做更强的网页自动化。
   • 待人工扫码 / 待补码：说明大概率要 12306 App 扫码，Mac 端只能做台账、收票和归档自动化。
4. 手动登录 12306，完成身份核验。
5. 执行 python3 scripts/invoice_tool.py rpa-plan，打开 output/rpa_helper.html。
6. 用辅助页逐条打开官方页面，填写统一公司抬头、税号、邮箱并提交。
7. 收到邮件后，把 .eml 放入 data/mail/，或把附件放入 data/attachments/。
8. 执行归集和汇总命令，检查 output/发票汇总.xlsx。

Android 自动填写身份证后 8 位

适用场景：12306 App 扫码后，页面显示脱敏姓名（如 张*岩），要求输入身份证后 8 位验证码。

本地 Web UI

启动本地页面：

./scripts/restart_web_ui.sh

这个脚本会先释放 8765 端口，再启动 web_ui_watchdog.sh 保活服务并验证页面可访问；日志写入 work/web_ui.log。

打开：

http://127.0.0.1:8765

页面支持上传 .xlsx/.xlsm/.csv 名单、查看成功/失败/处理中/未操作统计、显示手机连接/当前 App 状态、启动手机 12306、抓取当前页队列、启动/停止批处理，并持续读取：

work/android_invoice_progress.csv

这个 CSV 是逐人处理结果表，页面里的“下载进度表”会直接下载它。

1. 导入 Excel 名单

名单里至少要有“姓名”和“身份证/证件号码”两类列名。支持 .xlsx/.xlsm/.csv：

python3 scripts/invoice_tool.py import-roster --input /path/to/名单.xlsx

输出：

work/passenger_roster.csv

先离线验证一个脱敏姓名：

python3 scripts/invoice_tool.py match-roster --masked-name '张*岩'

如果出现 ambiguous，说明同名脱敏后匹配到多人，必须人工确认。

2. 连接 Android 手机

手机开启 USB 调试后连接 Mac：

/opt/homebrew/share/android-commandlinetools/platform-tools/adb devices

先手工在 12306 App 扫码，进入要求填写身份证后 8 位的页面。

读取当前页面文字：

python3 scripts/invoice_tool.py android-dump --output work/android_page.txt

如果能看到 张*岩 这类文字，就可以自动匹配并输入身份证后 8 位：

python3 scripts/invoice_tool.py android-type-id --tap 500,1200

--tap 是输入框坐标，需要按手机页面实际位置改。也可以用按钮/输入框可访问文字：

python3 scripts/invoice_tool.py android-type-id --click-text '证件号码后8位' --contains

3. 后续点击流程

复制并修改模板：

cp templates/android_flow.example.json templates/android_flow.local.json
python3 scripts/invoice_tool.py android-run-flow --flow templates/android_flow.local.json

模板支持这些动作：

action	用途
click_text	按完整文字点击
click_contains	按包含文字点击
tap	按坐标点击
input_id8_for_visible_masked_name	从当前页面识别 张*岩 并输入身份证后 8 位
input_config	输入 config.local.json 中的公司抬头、税号、邮箱
input_text	输入固定文本
sleep	等待
keyevent	发送 Android keyevent

真实 12306 App 页面可能不暴露全部控件文字。遇到找不到控件时，用 android-dump 看文字；如果没有文字，就改用 tap 坐标。

4. 单步状态机

当前页面已校准后，优先用单步命令。它每次只做一步动作，默认等待 10 秒，未出现目标状态再等 20 秒，仍不成功就暂停：

python3 scripts/invoice_tool.py android-invoice-step

如果当前在“发票开具成功”页，默认会点 继续开票 回列表。需要先发邮件时才加：

python3 scripts/invoice_tool.py android-invoice-step --send-email

5. 扫码列表页批处理队列

扫码开票单列表页不要用固定坐标。先抓当前可见的一页，按脱敏姓名和名单生成队列：

python3 scripts/invoice_tool.py android-build-page-queue

队列文件：

work/android_page_queue.csv

然后反复跑：

python3 scripts/invoice_tool.py android-page-step

行为：

• 当前在扫码列表页：按本页队列点击下一个可匹配人员的 开具。
• 当前在核验/发票管理/发票信息/成功页：执行普通单步状态机。
• 本页没有可处理人员：输出 page_done，不自动乱滑。

本页处理完后上滑到下一页并重建队列：

python3 scripts/invoice_tool.py android-page-next --rebuild

也可以让 android-page-step 在本页完成后自动上滑：

python3 scripts/invoice_tool.py android-page-step --auto-next

网页辅助开票

python3 scripts/invoice_tool.py rpa-plan

打开：

output/rpa_helper.html

先手动登录 12306 并完成核验，再逐条打开官方页面，复制公司抬头、税号和邮箱提交。

邮件和附件归集

如果有 .eml 邮件文件：

python3 scripts/invoice_tool.py collect-mail

如果已经把 PDF/OFD/XML 附件下载到 data/attachments/：

python3 scripts/invoice_tool.py collect-attachments

归集后的发票在：

output/invoices/

汇总和查漏

python3 scripts/invoice_tool.py export-summary

输出：

output/发票汇总.xlsx

工作簿包含：

• 发票汇总
• 缺票清单
• 合规检查

状态含义

状态	含义
待补码	未能自动识别二维码，需要人工扫码补录
待人工扫码	码不是网页链接，通常需要 12306 App 扫码
待网页开票	可以从辅助页打开官方页面处理
已收票	已匹配到发票附件