xinxin6623 7a01ed4db9 feat: add invoice batch wrap-up (name extraction + roster annotation) and web ui automation improvements

- add scripts/annotate_roster_invoices.py: match passenger names to invoice PDFs, write status + relative encoded hyperlinks into roster xlsx
- add scripts/add_invoice_passenger_name.py, scripts/calibrate.py
- add .opencode/skills/invoice-wrapup skill
- improve invoice_tool.py / web_ui.py / vision_fallback.py automation
- add device/screen/windows adaptation docs
- ignore out/ (delivered invoice PDFs contain sensitive data)

2026-07-10 00:11:45 +08:00

6.4 KiB

Raw Blame History

Windows 迁移清单

2026-07-09 整理。本项目从 macOS 搬到 Windows 前必读。

核心结论：代码不能直接跑，有 4 处硬编码 macOS 路径 + 3 个 bash 脚本依赖 launchd/lsof + Python 依赖需手动装。

一、必须一起带的文件（项目外依赖）

依赖	说明	当前位置	Windows 处理
ADB（platform-tools）	3 处硬编码路径引用，必须安装	`/opt/homebrew/share/android-commandlinetools/platform-tools/adb`	装 Android Platform Tools，改代码路径或加 PATH
Python 3.12+	标准库 + 3 个三方包	`/opt/homebrew/opt/python@3.12/bin/python3.12`（脚本里写死）	装 Python 3.12+，脚本里的 `python3` 换成 `python`
openpyxl	读 xlsx 名单（`invoice_tool.py:27`，try/except 守护）	pip 安装	`pip install openpyxl`
pypdf	`add_invoice_passenger_name.py` 硬 import	pip 安装	`pip install pypdf`
qrcode	生成二维码（`invoice_tool.py:1698`，lazy import）	pip 安装	`pip install qrcode`
numpy	可选（`invoice_tool.py:167`，try/except）	pip 安装	`pip install numpy`（不装也能跑）

二、必须改的代码（硬编码 macOS 路径）

2.1 ADB 路径（3 处，最关键）

scripts/invoice_tool.py:43    ADB_PATH = "/opt/homebrew/share/android-commandlinetools/platform-tools/adb"
scripts/invoice_tool.py:1334  ["/opt/homebrew/share/android-commandlinetools/platform-tools/adb", "exec-out", "screencap", "-p"]
scripts/calibrate.py:23       ADB = "/opt/homebrew/share/android-commandlinetools/platform-tools/adb"

Windows 改法：装 platform-tools 后，要么改成 C:\\platform-tools\\adb.exe，要么改成 "adb" 靠 PATH 解析（推荐，跨平台）。

注意 invoice_tool.py:1334 是独立硬编码（不走 ADB_PATH 变量），要单独改。

2.2 其他脚本用 `"adb"` 字符串（靠 PATH）

vision_fallback.py:38、record_step.py:64-69 用的是 ["adb", ...]，靠 PATH 解析。Windows 上把 adb.exe 加 PATH 即可。

2.3 Python 解释器路径

restart_web_ui.sh 和 install_web_ui_launch_agent.sh 里用 python3，Windows 用 python。但这两个脚本是 bash 脚本，Windows 上不能直接跑（见第三节）。

三、不能直接跑的脚本（macOS 专属）

脚本	问题	Windows 替代
`scripts/restart_web_ui.sh`	bash 脚本 + 用 `lsof` + `pgrep` + `launchctl` + `os.fork()`	见下方「Windows 启动方案」
`scripts/web_ui_watchdog.sh`	bash 脚本 + `lsof` + `curl` 循环	写个 `.bat` 或直接 `python scripts/web_ui.py` 前台跑
`scripts/install_web_ui_launch_agent.sh`	生成 macOS LaunchAgent plist	Windows 不需要，用启动菜单/任务计划程序替代

Windows 启动方案

最简单：开个 cmd 直接前台跑

cd C:\path\to\autotrain
python scripts\web_ui.py

或者写个 start_web_ui.bat：

@echo off
cd /d %~dp0\..
python scripts\web_ui.py
pause

四、配置文件

config.local.json（已含识别 key，必须带）

{
  "company_title": "...",
  "tax_id": "...",
  "receiver_email": "...",
  "vision": {
    "provider": "siliconflow",
    "base_url": "https://api.siliconflow.cn/v1",
    "api_key": "sk-xxx",
    "model": "Qwen/Qwen3-VL-8B-Instruct"
  },
  "invoice_success_action": "download",
  "invoice_output_dir": "output/01"
}

这个文件在 .gitignore 里，必须手动打包带过去。 识别 key 已在里面。

work/ 目录（部分需要带）

work/ 整个在 .gitignore 里。需要带的：

文件	必须带	说明
`passenger_roster.csv`	✅	当前名单（44 人），不带要重新 import-roster
`android_invoice_progress.csv`	✅	开票进度（143 completed），不带会重复开票
`qr_page_order.csv`	✅	本二维码核查表
`agent_id_last8.txt`	✅	代理人证件后 8 位
`last_qr_image.png` / `last_qr_url.txt`	✅	上次扫码的二维码，H5 precheck 用
`device_profile.json`	❌（不存在）	Windows 上跑 `/calibrate` 重新生成
`android_page_queue.csv`	❌	当前页队列，临时态，可不带
`.log` / `.png`（调试截图）	❌	无价值

data/ 目录

.gitignore 忽略了 data/input/、data/mail/、data/attachments/。如果还要跑 import-codes / collect-mail，需要带对应输入文件。如果只跑 H5 开票，不需要。

五、手机/ADB 环境（Windows 侧准备）

装 Android Platform Tools：https://developer.android.com/tools/releases/platform-tools
手机开 USB 调试：设置 -> 开发者选项 -> USB 调试
验证 ADB 连通：adb devices 能看到设备
12306 App 装好，登录，能到扫码开票页

六、换手机/换屏幕必跑

到了 Windows + 新手机后，第一件事：

打开 http://127.0.0.1:8765/calibrate（改完代码启动后）
点「💾 保存设备配置」生成 work/device_profile.json
逐状态截图校准（重点：「确认」「继续开票」「开具」）
python scripts/invoice_tool.py android-h5-page-run --dry-run --max-actions 1 验证

详见 docs/device-adaptation.md。

七、打包压缩建议

要打包的：
  scripts/          （全量，含 9 个脚本）
  docs/             （全量，含 device-adaptation / screen-adaptation / web-ui-adaptation-log）
  templates/        （全量）
  config.local.json （关键！含识别 key）
  config.example.json
  AGENTS.md / INDEX.md / CHANGELOG.md / CODEMAP.md
  work/passenger_roster.csv
  work/android_invoice_progress.csv
  work/qr_page_order.csv
  work/agent_id_last8.txt
  work/last_qr_image.png
  work/last_qr_url.txt

不要打包的：
  archive/          （旧备份，体积大）
  output/           （已交付发票，体积大）
  data/input/       （原始开票码，如不跑 import-codes 不需要）
  data/mail/ data/attachments/
  work/*.log work/*.png（调试产物）
  work/__pycache__/
  .git/

八、Windows 上首次运行步骤

REM 1. 装 Python 3.12+ 和 ADB
REM 2. pip install openpyxl pypdf qrcode
REM 3. 改代码里的 ADB 路径（3 处，见第二节）
REM 4. 启动
cd C:\path\to\autotrain
python scripts\web_ui.py
REM 5. 浏览器打开 http://127.0.0.1:8765
REM 6. 进 /calibrate 生成 device_profile.json
REM 7. dry-run 验证
python scripts\invoice_tool.py android-h5-page-run --dry-run --max-actions 1

6.4 KiB Raw Blame History Unescape Escape