commit 2648440f22a5528d238736ca26a3ae65825dc322
Author: xinxin6623 <qoragufimo390@gmail.com>
Date:   Thu Jun 11 12:18:53 2026 +0800

    init autotrain project

diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..51d7701
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,10 @@
+__pycache__/
+*.pyc
+.DS_Store
+config.local.json
+archive/
+data/input/
+data/mail/
+data/attachments/
+output/
+work/
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..f3b33d2
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,112 @@
+---
+trio: standard-v2
+trio-initialized: 2026-06-08
+---
+
+# 铁路系统发票 · Agent 操作守则
+
+> **上来先读这份**，再看 [`INDEX.md`](./INDEX.md) 找模块和导航。
+>
+> **通用三件套协议**见 [`../docs/trio-protocol.md`](../docs/trio-protocol.md)（文档维护节奏 / Handoff 写入 / 子项目嵌套 / 记忆三条线边界 / 语言规则 / 跨项目反例）。**本文件只列本项目专属守则**。
+>
+> **`trio: standard-v2`** = 本项目按当前标准维护三件套。
+
+## 这是什么项目
+
+铁路系统发票专项工作区，用于沉淀铁路系统相关发票资料、处理脚本、核对记录和衍生产出。
+
+### 核心愿景（Core Vision）
+
+**最终目标**：用户在 Web UI 上操作，脚本全自动完成开票、状态记录、结果文档输出。
+
+**技术路线**：
+- **截屏驱动**：ADB 截屏 → 视觉 LLM（Qwen3-VL via SiliconFlow）识别页面元素、脱敏姓名、按钮位置
+- **脚本编排**：视觉 LLM 返回归一化 bbox（0-1000 坐标系）→ 脚本判断当前页面状态 → 决定下一步动作（tap / scroll / back）
+- **UI 配合**：Web UI 负责触发、监控进度、展示结果；脚本在子进程中运行，通过 CSV 文件与 UI 交换状态
+- **对话调试**：James 和 Claude Code 通过实际运行观察手机行为，持续修正脚本的判断逻辑和边界条件
+
+**当前阶段**：H5 扫码开票单页面自动化。页面结构：单个开票单下挂 N 个乘客（脱敏姓名 + 身份证类型 + 脱敏身份证号 + 「开具」按钮），需要逐人点击「开具」走完子流程，记录每个乘客的开票结果。
+
+**已完成的路径**（保留不动）：
+1. 原生列表页视觉驱动批量（`android-vision-page-run`）：截图 → list-rows 识行 → anchor 去重 → 点击 → 核验/发票管理子流程
+2. 原生列表页 XML 驱动（`android-page-run`）：uiautomator dump → 解析 XML → 匹配 text/bounds
+
+## 上手三步
+
+1. 读 [`INDEX.md`](./INDEX.md)，看项目结构和子模块导航。
+2. 找到目标模块目录，**先读它的本地文档**（如 `<module>/README.md` 或 `<module>/AGENTS.md` 若存在）。
+3. 看根目录或模块里有没有脚本入口、配置文件、环境变量样例。
+
+## 项目专属硬规则
+
+- **不要随手改 `.env` / 凭证 / `settings.json`**：敏感配置由项目所有者维护。
+- **不要主动删除文件**：废弃 / 旧版本 / 半成品请移动到 `archive/` 或 `不加载/` 这类约定目录，不要 `rm`。
+- **不要重命名公共接口、路由、对外 API 字段**：除非明确授权，这些是契约。
+- **涉及发票、金额、税号、单位名称等字段时先保留原始值**：规范化和清洗产物另存，不覆盖来源资料。
+- **改动前确认是否有依赖你正在改的代码的其他模块**：先 `grep` 引用再下手。
+
+## 目录命名约定
+
+| 子目录 | 用途 |
+|---|---|
+| `data/` | 本项目自有数据与导入材料 |
+| `scripts/` | 可执行脚本 |
+| `src/` 或 `lib/` | 主代码 |
+| `tests/` | 测试 |
+| `docs/` | 详细文档 |
+| `assets/` | 静态素材 |
+| `templates/` | 模板文件 |
+| `archive/` 或 `不加载/` | 归档区，不参与构建 |
+
+## 项目专属"不要做的事"
+
+- ❌ 删除文件（应该 `mv` 到归档目录）
+- ❌ 自动提交 secrets / 凭证
+- ❌ 覆盖原始发票资料或人工核对记录
+- ❌ 未经确认修改发票字段含义、金额口径、税率口径
+
+## 架构与关键依赖
+
+> 本节是给 Claude Code 看的"big picture"。具体命令清单在 `INDEX.md` 的"常用操作"段；详细用法在 `docs/usage.md`。这里只写**读多个文件才能拼出来的事**。
+
+### 四个脚本的分工
+
+`scripts/` 下没有 `src/lib`，所有逻辑都在四个独立 Python 文件里，彼此通过文件（CSV / 配置 / 截图）耦合，而不是 import：
+
+| 脚本 | 角色 | 入口形式 |
+|---|---|---|
+| `invoice_tool.py` | 主 CLI，~1700 行，argparse 多子命令。覆盖：台账 / 名单 / 邮件归集 / 网页辅助页 / Android ADB 自动化 / 视觉驱动批量。所有路径常量、`run_adb`、`Config` 都在这里 | `python3 scripts/invoice_tool.py <subcmd>` |
+| `web_ui.py` | 本地 HTTP 服务（端口 8765），`import invoice_tool` 复用其常量和 `run_adb`，把批处理包成子进程跑 | `python3 scripts/web_ui.py` |
+| `vision_fallback.py` | 视觉调用层：adb 截屏 → base64 → 调 SiliconFlow Qwen3-VL grounding API → 解析归一化 bbox | `python3 scripts/vision_fallback.py {ping,detect-page,ask,list-rows}` |
+| `record_step.py` | 录制工具：`adb uiautomator dump` + `screencap` 落盘到 `work/replay/<session>/<NN_label>/`，用于"人工演示 → 反推脚本" | `python3 scripts/record_step.py "label" [--new] [--list]` |
+
+`web_ui.py` 当前调用的是旧路径 `android-page-run`（XML/文字匹配），**没有接** `android-vision-page-run`。如果改 Web UI 的"开始运行"按钮，注意切换的是 `invoice_tool.py` 的子命令名。
+
+### 两条 Android 自动化路径并存
+
+12306 App 是脱敏姓名（`张*岩`）+ 输入身份证后 8 位的开票流程。代码里有两套实现，**都保留**：
+
+1. **旧：`android-page-run` / `android-page-step`** — 走 `uiautomator dump` 读 XML，按 text / bounds 匹配。问题是 12306 列表页很多控件没有 text，全靠坐标。
+2. **新：`android-vision-page-run`** — 截屏交给 Qwen3-VL，模型返回归一化 bbox（**0-1000 坐标系**，不是像素），脚本再 denormalize 到屏幕像素后 tap。流程：截图 → `vision_fallback.list-rows` 识所有可见行 → anchor 去重防滑动后重复 tap → 子流程（核验 / 发票管理 / 成功页）走旧的状态机。
+
+### 配置与外部依赖
+
+- **ADB 路径硬编码**：`invoice_tool.py:39` 写死 `/opt/homebrew/share/android-commandlinetools/platform-tools/adb`（Apple Silicon Homebrew）。换机器或换 Intel Mac 要改这里。
+- **`config.local.json`**：除 `company_title / tax_id / receiver_email`（`config.example.json` 已示范）外，**视觉路径还需要一个 `vision` 段**：`base_url` / `api_key` / `model`（当前用 SiliconFlow + `Qwen/Qwen3-VL-8B-Instruct`，详见 memory `reference_siliconflow_qwen_vl.md`）。`vision_fallback.load_vision_config` 缺任一键直接抛错。
+- `config.local.json`、`work/`、`data/input|mail|attachments/`、`output/` 全在 `.gitignore` 里。
+
+### 关键工作文件（都在 `work/`，CSV，UTF-8-BOM）
+
+| 文件 | 内容 | 写入者 |
+|---|---|---|
+| `passenger_roster.csv` | 名单：姓名 / 身份证号 / 后 8 位 / 来源 | `import-roster` |
+| `invoice_tasks.csv` | 开票码主台账 | `import-codes` |
+| `android_invoice_progress.csv` | 逐人处理结果（masked_name / real_name / id_last8 / status） | Android 子命令 + Web UI 读 |
+| `android_page_queue.csv` | 当前可见页的待点击队列 | `android-build-page-queue` |
+| `replay/<session>/` | record_step.py 的演示快照（ui.xml + screen.png + texts.txt + meta.json） | `record_step.py` |
+
+CSV header 常量都集中在 `invoice_tool.py` 顶部（`TASK_HEADERS` / `ROSTER_HEADERS` / `PROGRESS_HEADERS` / `PAGE_QUEUE_HEADERS`）。改字段要同步改这里 + 所有读它的子命令。
+
+### 测试
+
+`tests/` 当前是空目录。没有单测 / 集成测试框架；验证靠 `--dry-run` 子命令 + 真机跑 + `work/replay/` 录制比对。新增功能不强求加测试，但如果改了 CSV schema 或 ADB 命令组合，至少跑一次 `--dry-run --max-actions 1`。
diff --git a/CHANGELOG.md b/CHANGELOG.md
new file mode 100644
index 0000000..40cf009
--- /dev/null
+++ b/CHANGELOG.md
@@ -0,0 +1,173 @@
+## 2026-06-11 #fix scope:android-h5-automation - 下载后自动退出发票预览页
+
+- Why: 下载确认后会停在预览页,需要稳定回到成功页/列表继续下一人
+- 详见: scripts/invoice_tool.py:1004, scripts/invoice_tool.py:1892
+
+## 2026-06-11 #fix scope:android-h5-automation - 下载发票文件名带真实姓名
+
+- Why: 仅用脱敏名无法区分和归档,本地 PDF 需要直接体现发票归属人
+- 详见: scripts/invoice_tool.py:1919
+
+## 2026-06-11 #fix scope:android-h5-automation - 处理发票下载完成确认弹窗
+
+- Why: PDF 已保存后卡在下载进度 100% 弹窗,导致无法自动回到列表
+- 详见: scripts/invoice_tool.py:1004, scripts/invoice_tool.py:1886
+
+## 2026-06-11 #fix scope:web-ui - 保存目录输入不再被自动刷新覆盖
+
+- Why: UI 状态轮询会重置正在编辑的目录,导致用户无法自定义保存位置
+- 详见: scripts/web_ui.py:481, scripts/web_ui.py:696
+
+## 2026-06-11 #feat scope:android-h5-automation scope:web-ui - 成功页支持下载发票到本地
+
+- Why: 后续需要保留邮箱流程,同时默认把发票文件直接沉淀到电脑目录
+- 详见: scripts/invoice_tool.py:959, scripts/web_ui.py:212
+
+## 2026-06-11 #fix #perf scope:android-h5-automation scope:web-ui - 修复核验同名歧义、优化续跑锚点、优化图库选码
+
+- Why: UI 跑流程经常报错，需先验证 CLI、再固化续跑断点、再优化重试顺序
+- 详见: scripts/invoice_tool.py:402, scripts/invoice_tool.py:1485, scripts/web_ui.py:899
+
+# 铁路系统发票 · CHANGELOG
+
+> 每次动了什么记一条。详细记录写在各自模块目录下，根目录 CHANGELOG 是**强标签化的检索索引**。
+>
+> **如本项目下有子项目**（子目录里也有 AGENTS/INDEX/CHANGELOG 三件套）：本 CHANGELOG **只记录跨多个子项目的同时操作**；单一子项目操作记在该子项目自己的 CHANGELOG 里。详见 `../docs/trio-protocol.md`。
+
+## 格式规范（严格）
+
+```text
+## YYYY-MM-DD #<type> scope:<name> [#<extra-tag>...] - <一句话主题>
+
+- Why: <一句话动机，不复述 what>
+- 详见: <path 或 commit hash>
+```
+
+**硬约束**：
+- 日期必须 ISO 格式 `YYYY-MM-DD`
+- 类型标签必须以 `#` 开头，从下面字典选一个为主标签
+- 作用域必须 `scope:<name>` 形式，name 用 kebab-case；多模块改动用多个 `scope:`
+- Why 一行不超过 80 字符
+- **不贴 diff、不复述 what**，那些进 commit 或模块自己的文档
+
+## 类型标签字典
+
+| 标签 | 含义 |
+|---|---|
+| `#feat` | 新功能 |
+| `#fix` | bug 修复 |
+| `#refactor` | 重构（无行为变化） |
+| `#perf` | 性能优化 |
+| `#docs` | 文档变更 |
+| `#test` | 测试相关 |
+| `#chore` | 构建/依赖/工具链/初始化 |
+| `#archive` | 归档/弃用 |
+| `#breaking` | 破坏性变更（叠加） |
+| `#deprecated` | 标记弃用（叠加） |
+| `#wip` | 进行中（叠加） |
+
+## 检索示例
+
+```bash
+grep -E "^## .* #feat .* scope:invoice" CHANGELOG.md
+grep "#breaking" CHANGELOG.md
+grep "^## 2026-06" CHANGELOG.md
+```
+
+---
+
+## 2026-06-09 #feat scope:android-automation #scope:vision-fallback - 视觉驱动批量开票路径打通
+
+- Why: 用户改路线,手动扫码进列表 → 视觉抓行 → anchor 去重 → 按页批次开票
+- 详见: scripts/invoice_tool.py 新增 `android-vision-page-run` 命令(并行存在,不动老路径);scripts/vision_fallback.py 新增 `list-rows` 子命令 + 0-1000 归一化反推
+- docs/debug-trace-2026-06-09.md 全程实测时间线
+
+## 2026-06-09 #chore scope:vision-fallback - 换用硅基流动 Qwen3-VL-8B-Instruct
+
+- Why: 豆包 Doubao-Seed-2.0-mini OCR 准但 grounding 失败(返坐标完全猜的);Qwen3-VL 系列做过 grounding 训练,实测 bbox 误差 <25px
+- 详见: config.local.json provider 改 siliconflow,model Qwen/Qwen3-VL-8B-Instruct;费用估算 21-25 次/全程 ≈ ¥0.05-0.1
+
+## 2026-06-09 #fix scope:android-automation - 兜底 back 退过头 + 2 字脱敏名正则失配
+
+- Why: no_match 名 tap 后核验弹窗解析失败,旧 back+back 兜底把列表页一起退到 12306 首页
+- 详见: invoice_tool.py 核验弹窗正则 `{1,3}`→`{0,3}` 兼容澳*/吴* 类两字名;safe_back_until_list 加首页检测 + 单次 back 后 1.5s 等待,外层 abort 闸门避免误操作
+
+## 2026-06-09 #feat scope:replay - 录制工具 record_step.py
+
+- Why: 视觉模型坐标精度够但子流程边界(2 字名 / 已开过 / 已退 H5)边界 case 多,人工示范+录制比盲调更快
+- 详见: scripts/record_step.py — `python3 scripts/record_step.py "label"` 当前 session 累加;`--new` 开新 session
+
+## 2026-06-09 #feat scope:vision-fallback - 接入火山豆包视觉模型作为 adb dump 兜底
+
+- Why: adb 节点解析对 H5 内嵌 UI / 弹窗状态不稳,加视觉 LLM 二次确认
+- 详见: scripts/vision_fallback.py (detect-page / ask / ping),config.local.json vision 段;模型 doubao-seed-1-6-flash-250615
+
+## 2026-06-09 #feat scope:web-ui - 开始运行流程改成"先回顶 + 截屏建队列 + 才操作"
+
+- Why: 原流程开始即翻页,用户没看到本页识别结果就直接 swipe,体验跟"卡死"无异
+- 详见: scripts/web_ui.py start_runner 前置同步两步骤;新 UI 复选框"开始前回顶"默认勾选
+
+## 2026-06-09 #feat scope:android-automation - 翻页到底 fingerprint 检测 + 回顶命令
+
+- Why: swipe 后页面没变化以前会无限滑;新加 android-page-top 让人能从底部回到列表顶端开干
+- 详见: scripts/invoice_tool.py android_page_top / android_page_step _last_done_fp 状态比对
+
+## 2026-06-09 #fix scope:android-automation - 运行时异常软失败,不整体崩 runner
+
+- Why: 单个人开票流程出错以前会让整批停掉,无人值守语义不成立
+- 详见: scripts/invoice_tool.py mark_clicked_as_runtime_error / android_page_run try-except
+
+## 2026-06-09 #feat scope:android-automation - 本页 retry 一次 + 身份证首末位增强匹配
+
+- Why: 用户要求整页跑完后失败者再走一遍才翻页;同名歧义用脱敏身份证首末位解掉
+- 详见: scripts/invoice_tool.py build_visible_page_queue / match_roster / RETRYABLE_FAILURES
+
+## 2026-06-09 #fix scope:web-ui - 启动命令默认带 --auto-next 避免整页 skip 时空转
+
+- Why: 当前页全 skip_progress / no_match 时不上滑下一页,20 步连续 page_done 无进展
+- 详见: scripts/web_ui.py start_runner
+
+## 2026-06-08 #feat scope:web-ui - 增加本地批处理进度页面
+
+- Why: 50 人名单批处理需要可视化上传入口、实时状态和逐人结果表
+- 详见: scripts/web_ui.py / scripts/invoice_tool.py / docs/usage.md
+
+## 2026-06-08 #feat scope:android-automation - 增加扫码列表页队列和翻页处理
+
+- Why: 列表页开具按钮不是固定坐标，需要按当前页姓名和 bounds 生成队列逐个处理
+- 详见: scripts/invoice_tool.py / docs/usage.md
+
+## 2026-06-08 #feat scope:android-automation - 增加 12306 单步开票状态机
+
+- Why: 截图逐页校准成本高，需要用 XML 状态识别减少人工判断和 token 消耗
+- 详见: scripts/invoice_tool.py / docs/usage.md
+
+## 2026-06-08 #feat scope:android-automation - 增加 Android 端身份证后 8 位自动填入
+
+- Why: 12306 App 扫码后需按脱敏姓名匹配名单并填写身份证后 8 位，人工逐个填写太慢
+- 详见: scripts/invoice_tool.py / templates/android_flow.example.json / docs/usage.md
+
+## 2026-06-08 #fix scope:batch-invoice - 识别 PNG 扫码开票单为 App 扫码流程
+
+- Why: 真实铁路扫码开票单截图要求 12306App 扫码，不能误判为网页自动开票
+- 详见: scripts/invoice_tool.py / work/invoice_tasks.csv / docs/usage.md
+
+## 2026-06-08 #feat scope:batch-invoice - 落地铁路发票批量处理本地工具
+
+- Why: 普通代购票缺统一批量开票入口，需要用官方页面配合本地台账和收票归集降本
+- 详见: scripts/invoice_tool.py / docs/usage.md / INDEX.md
+
+## 2026-06-10 #feat scope:h5-automation scope:web-ui - H5扫码开票单视觉驱动批量 + 优雅退出 + UI模式切换
+
+- Why: H5单页挂N个乘客,back重置scroll;手机被占用(微信来电)时常发生,需优雅退出而非崩溃
+- 详见: scripts/invoice_tool.py android-h5-page-run + _h5_scroll_down;scripts/web_ui.py mode=h5/h5+模式选择器;三处优雅退出(PREECHECK_FAILED/PAGE_AWAY/sub-flow无法回列表)
+
+## 2026-06-10 #feat scope:web-ui scope:qr-decode - 粘贴二维码截图自动解码 + ADB 在手机打开
+
+- Why: 用户拿到开票二维码截图后不用再手动扫,贴到 UI 自动解码→在手机打开对应页面
+- 详见: scripts/invoice_tool.py decode_qr_image(OpenCV QRCodeDetector);scripts/web_ui.py /api/decode-qr /api/open-on-phone
+
+## 2026-06-08 #chore scope:init - 项目初始化
+
+- Why: 新专项需要独立工作区和三件套入口，便于后续发票资料处理与核对
+- 详见: AGENTS.md / INDEX.md / 本文件
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 120000
index 0000000..47dc3e3
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1 @@
+AGENTS.md
\ No newline at end of file
diff --git a/INDEX.md b/INDEX.md
new file mode 100644
index 0000000..edc015a
--- /dev/null
+++ b/INDEX.md
@@ -0,0 +1,123 @@
+# 铁路系统发票
+
+铁路系统发票专项工作区，用于沉淀铁路系统相关发票资料、处理脚本、核对记录和衍生产出。
+
+> 🤖 Agent 上手先读 [`AGENTS.md`](./AGENTS.md) 的操作守则（通用协议在 [`../docs/trio-protocol.md`](../docs/trio-protocol.md)）；改动后记得追加 [`CHANGELOG.md`](./CHANGELOG.md)（强标签格式见文件顶部）。
+
+<!--
+## 当前接力点 (Handoff)
+
+**未完成续跑逻辑调整**：当前锚点已识别正确（王*凝），但需要调整为「先处理当前页可见、跳过已完成、优先失败项」而不是「只处理锚点之后」。
+
+### 当前状态盘点
+- ✅ CLI 健全：validate 通过，dry-run 续跑锚点生效
+- ✅ 核验弹窗同名歧义已修复：优先用进度表 in_progress 精确身份
+- ✅ QR 重推已修复：UI 粘贴后自动推新图到手机图库
+- ✅ 续跑锚点已固化：从最后更新人后开始，不会从顶部旧失败项抢跑
+- 🚧 调整中：当前页处理顺序（失败优先、跳过已完成）
+
+### 下次上手
+1. 确认手机当前在 12306 H5 开票列表，不要停在业务须知页
+2. 如果不在列表页，用 UI 粘贴正确的二维码重新进入
+3. 调整续跑逻辑：当前页优先失败项重试、跳过已完成、再处理未处理
+4. 小范围验证后再批量跑
+
+### 关键指针
+- work/android_invoice_progress.csv:39 锚点为姚*文（最新 completed）
+- scripts/invoice_tool.py:1551 续跑锚点过滤逻辑
+- scripts/invoice_tool.py:1543 失败重试逻辑
+
+## 当前接力点 (Handoff)
+
+**H5 全自动开票已跑通 18 人,剩余待处理约 9 人。等待时间已优化,下次直接继续跑即可**(2026-06-10)。
+
+### 状态盘点
+
+- ✅ H5 全流程跑通:截屏识行 → 逐人开具 → 7状态机子流程 → back回列表 → 滚动
+- ✅ 四级恢复链:sub-flow error → safe_back → 说明页检测 → auto_scan(扫码→相册→选QR)→回列表
+- ✅ XML+视觉渐进 fallback:`_xml_or_vision_click()` 三级查找覆盖所有 H5 按钮
+- ✅ 邮件死循环已修:`completed` 标记移到发邮件之前
+- ✅ 视觉坐标反归一化已修:`px = norm * width / 1000`
+- ✅ 法条说明页误判已修:`is_on_instructions_page()` 排除
+- ✅ 等待时间优化:short_wait=1s, wait_primary=5s, wait_secondary=10s
+- ✅ Web UI 功能:粘贴QR解码、模式切换(H5/列表)、视觉刷新当前页、手动标记完成
+
+### 下次上手
+
+1. `python3 scripts/web_ui.py &` 启动UI
+2. 浏览器 `http://127.0.0.1:8765`，选「H5开票单」模式
+3. 如果手机不在列表页 → 点「重新进入开票页」或直接点「开始运行」(自动恢复)
+4. 点「开始运行」继续处理剩余人
+
+### 关键文件
+
+- `scripts/invoice_tool.py`: `android-h5-page-run`、`auto_scan_qr_to_list`、`_xml_or_vision_click`、`_vision_find_button` 等
+- `scripts/web_ui.py`: 模式切换 + 视觉刷新 + 手动标记
+- `scripts/vision_fallback.py`: list-rows / ask / ping(带 --image)
+- `work/android_invoice_progress.csv`: 36人进度
+- `work/last_qr_url.txt`: 已保存的 QR URL
+- `work/qr_code.png`: 已生成的 QR 图片(用于 auto_scan)
+
+## 项目结构
+
+```text
+铁路系统发票/
+├── AGENTS.md
+├── CHANGELOG.md
+├── CLAUDE.md -> AGENTS.md
+├── INDEX.md
+├── config.example.json
+├── config.local.json（本地自建，忽略提交）
+├── data/
+│   ├── attachments/
+│   ├── input/开票码批次/
+│   └── mail/
+├── docs/
+│   └── usage.md
+├── output/
+├── scripts/
+│   └── invoice_tool.py
+├── templates/
+│   └── android_flow.example.json
+└── work/
+```
+
+## 子模块导航
+
+（本项目暂无子目录）
+
+## 常用操作
+
+```bash
+# 初始化目录和配置模板
+python3 scripts/invoice_tool.py init
+cp config.example.json config.local.json
+
+# 导入二维码/手工码生成开票任务
+python3 scripts/invoice_tool.py import-codes
+
+# 导入名单并匹配身份证后 8 位
+python3 scripts/invoice_tool.py import-roster --input /path/to/名单.xlsx
+python3 scripts/invoice_tool.py match-roster --masked-name '张*岩'
+
+# Android 页面读取和身份证后 8 位输入
+python3 scripts/invoice_tool.py android-dump --output work/android_page.txt
+python3 scripts/invoice_tool.py android-type-id --tap 500,1200
+
+# 本地 Web UI：上传名单、看进度、启动/停止批处理
+python3 scripts/web_ui.py
+
+# 生成网页辅助开票页
+python3 scripts/invoice_tool.py rpa-plan
+
+# 归集邮件/附件并导出汇总
+python3 scripts/invoice_tool.py collect-mail
+python3 scripts/invoice_tool.py collect-attachments
+python3 scripts/invoice_tool.py export-summary
+```
+
+## 相关链接
+
+- 📓 演绎记录：[CHANGELOG.md](./CHANGELOG.md)
+- 🤖 Agent 守则：[AGENTS.md](./AGENTS.md)
+- 使用说明：[docs/usage.md](./docs/usage.md)
diff --git a/config.example.json b/config.example.json
new file mode 100644
index 0000000..1772bf6
--- /dev/null
+++ b/config.example.json
@@ -0,0 +1,7 @@
+{
+  "company_title": "请填写公司全称",
+  "tax_id": "请填写统一社会信用代码",
+  "receiver_email": "invoice@example.com",
+  "invoice_success_action": "download",
+  "invoice_output_dir": "output/invoices"
+}
diff --git a/docs/debug-trace-2026-06-09.md b/docs/debug-trace-2026-06-09.md
new file mode 100644
index 0000000..07f23be
--- /dev/null
+++ b/docs/debug-trace-2026-06-09.md
@@ -0,0 +1,208 @@
+# 调试跟踪 · 2026-06-09 实测
+
+> 真机调试现场记录。按时间顺序追加,**不要回头改老条目**——错就再写一条新的把前条作废。
+> 命名规则:`docs/debug-trace-YYYY-MM-DD.md`,一天一份。
+
+## 环境快照
+
+| 项 | 值 |
+|---|---|
+| 日期 | 2026-06-09 |
+| Web UI | `http://127.0.0.1:8765` (PID 71108,启动 01:02) |
+| Android 设备 | `10ADCX2GUK002A8` (已 `adb devices` 确认) |
+| 名单总数 | 149 |
+| 当前进度 | 5 完成 / 3 失败 / 141 待办 |
+| 日志路径 | `work/web_runner.log` · `work/web_ui.log` |
+
+## 验证目标(来自 Handoff)
+
+1. 新版"开始运行"流程:回顶 → 建队列 → page-run --auto-next
+2. 翻页是否会在真到底时停在 `stop_reason=bottom_reached`,不再无限滑
+3. 决定 `scripts/vision_fallback.py` 接入到哪些叉路:
+   - (a) `page_bottom_reached` 之前先视觉确认
+   - (b) 未知页面状态异常时视觉判断
+   - (c) 关键按钮 adb dump 找不到时视觉给坐标
+
+## 时间线
+
+### [14:33] 现场盘点
+
+- Web UI 健康,HTTP 200。`work/web_runner.log` 只有 prelude 两段:
+  - `android-page-top rc=0 / at_top iterations=2`
+  - `android-build-page-queue rc=0 / rows=7 pending=0`
+  - 顶页 7 行全部 skipped:3 个 `skip_progress`(程*桐 / 朱*玉 / 王*平,已开过)+ 4 个 `no_match`(张*丽 / 李*国 / 王*楠 / 陈*胜,名单匹配不上)
+- runner 子进程已不在(`ps -ef | grep invoice_tool` 空)。Web UI 重启后内存里的 `RUNNER` 是 None,前次留下的日志是孤儿。
+- 结论:**需要重新触发一次"开始运行",从顶部跑起,观察后续翻页**。
+
+### 待办清单
+
+- [ ] 调 `/api/start` 触发完整流程
+- [ ] tail -f `work/web_runner.log` 观察 `page_done` / `page_open` / `page_bottom_reached` 是否按预期出现
+- [ ] 真到底时是否停在 `stop_reason=bottom_reached`
+- [ ] 出现需要 fallback 的卡点时,跑 `python3 scripts/vision_fallback.py detect-page` 抓 JSON
+
+### [14:37] 从零开始 · 清空工作态
+
+用户决定从零起测,流程**从 UI 上传名单**开始。
+
+把 `work/` 下 7 个状态文件 `mv` 到 `archive/reset_20260609_<ts>/`(**遵循"不 rm,只归档"项目规则**):
+
+| 文件 | 用途 |
+|---|---|
+| `passenger_roster.csv` | 名单 |
+| `android_invoice_progress.csv` | 进度 |
+| `android_page_queue.csv` | 当前页队列 |
+| `web_runner.log` | runner 日志 |
+| `web_ui.log` | UI 日志 |
+| `invoice_tasks.csv` | 任务清单 |
+| `last_screenshot.png` | 最近截屏 |
+
+保留 `work/android_*.txt`(纯调试 dump 快照,不影响行为)。
+
+清空后 `/api/status` 响应:
+- `counts: {total:0, completed:0, failed:0, in_progress:0, pending:0}` ✓
+- `roster: []` ✓
+- `runner.status: failed`(残留 RUNNER 指针指向上次的死子进程,无害,下次 start 会覆盖)
+
+**下一步**:等用户在浏览器里 `http://127.0.0.1:8765` 点"上传名单"导入 xlsx,再观察 `/api/status` 是否吃进 149 行。
+
+### [14:55] 方向大调整 · 改走视觉驱动
+
+用户暂停传统路径,提新方案:
+- 手机端**用户手动**扫码进入开票界面(不需要程序回顶)
+- 点"开始"→ **直接截图 → 视觉识别**当前页所有可见乘客行 → 按页为批次开票
+- 一批完后**滑动**,**保证至少 1 行重叠**,视觉识别新页 → 去掉重叠 → 下一批
+- 一直滑到底
+
+锁定决策(三问三答):
+1. 子流程(核验/提交/邮件)→ **保留 adb XML 驱动**(视觉只用列表页 + 翻页)
+2. 翻页去重 → **anchor 驱动**(记上批最后一行 masked_name,新截图视觉找位置,以下为新行)
+3. 前置自检 → **做**(调一次 detect-page 要 `page=list`)
+
+我自定的小决策:
+- `button_bbox` 取中心 tap
+- 截图原始像素传给豆包,要求按真实坐标返
+- 批次内失败重试 1 次,翻页后不回头
+- 老的 `android-page-run` 路径保留并行
+
+### [15:00] 步骤① 视觉 list-rows 接口已加
+
+`scripts/vision_fallback.py` 新增 `list-rows` 子命令:
+- 截图 → 读 PNG header 提取真实像素 width/height → 塞给 prompt
+- prompt 要求豆包返回 `{rows:[{masked_name, id_first, id_last, button_bbox:[x1,y1,x2,y2]}], scroll_position, page_ok}`
+- 增加 `parse_json_lenient`,容错 markdown 代码块包裹
+
+下一步:跑 `python3 scripts/vision_fallback.py list-rows` 抽样验证 bbox 准确性,再做步骤②。
+
+### [15:03] 步骤③ dry-run 失败 · 豆包 key 401
+
+`list-rows` 调用返回 401 AuthenticationError(`The API key doesn't exist`)。
+昨晚 handoff 明确说"测完明天记得把它置空或撤销"—— 用户应该已撤销。
+
+**阻塞**:需要用户在 `config.local.json` 重填 `vision.api_key` 才能继续视觉路径验证。
+
+### [15:18] 模型切换 · Doubao-Seed-2.0-mini
+
+用户提供新 key,授权范围 `Doubao-Seed-2.0-mini`。查方舟 `/models`:
+- 实际 model id:`doubao-seed-2-0-mini-260428`(2026-04 版,带 audio 模态最新版)
+- 状态 Active,modalities 含 image
+- 之前认为应该用 `doubao-seed-1-6-vision-250815`,但用户 key 限定 mini → 改用 mini
+
+更新 `config.local.json`:
+- `vision.api_key` → 新 key
+- `vision.model` → `doubao-seed-2-0-mini-260428`
+
+### [15:21] 通路验证 OK,但手机黑屏
+
+`python3 scripts/vision_fallback.py detect-page` 返回 200,2.97s 响应,JSON 合规。
+模型回答:`page=other, summary=当前页面为全黑,无法识别具体内容`。
+说明:**API 通,但截屏拿到的是锁屏黑画面**。需要用户先解锁 + 打开 12306 列表页。
+
+成本对账(本次调用):
+- prompt_tokens=1618(图片占大头)
+- completion_tokens=212(含 182 reasoning)
+- 单次成本估算几厘钱
+
+**阻塞**:等用户解锁手机 + 切到扫码开票单列表页,然后重跑 `list-rows`。
+
+### [15:30] 步骤③ dry-run 结果:豆包 mini 不能给坐标
+
+跑 `list-rows`,7 个名字 OCR 完美(全对),但 **bbox 是模型按"7 行均分屏"猜的等差数列**:
+- 模型 reasoning 漏嘴:"按钮的x1是720,y1是290,...大概的坐标"
+- y 值 295/385/475/565/655/745/835 等差 90;真实 y 值 845/1139/1433/1727/2021/2315/2609 等差 294
+- 误差 500-1700 px,完全不可用
+
+**结论**:Doubao-Seed-2.0-mini 没有 visual grounding 能力,只能 OCR 不能定位。
+
+### [15:36] 换硅基流动 Qwen3-VL-8B,grounding 通过
+
+用户给了硅基流动 key + `Qwen/Qwen3-VL-8B-Instruct`。更新 `config.local.json`。
+
+重跑 `list-rows`,bbox 精度大幅提升,但发现 Qwen 用 **0-1000 归一化坐标**(Qwen 系标准约定,不论 prompt 怎么写都按这个返)。
+反推到绝对像素:`x = qwen_x * image_width / 1000`,误差稳定在 5-21 px,**全部落在按钮内**(按钮 250×94)。
+
+代码改动:
+1. `vision_fallback.py` 加 `denormalize_bboxes()`:任一坐标 > 1000 视为已是绝对像素,否则按 0-1000 反推。同时在每行注入 `tap_point=[cx,cy]`。
+2. prompt 改为明确要求 Qwen 返 0-1000 归一化,免得不同图片混乱。
+
+成本量级:Qwen3-VL-8B / 硅基流动,单次 ~4200 token ≈ 几厘钱;全程 21-25 次 ≈ ¥0.05-0.1。可以接受。
+
+### [15:42] 进入步骤② · android-vision-page-run
+
+设计循环(已对齐):
+- 自检 detect-page == list
+- 视觉 list-rows → anchor 去重 → 匹配 roster → tap pending 行
+- tap 后复用现有 `android_invoice_step` 跑子流程(核验/提交/邮件)直到回列表
+- 本批末行 masked_name 作下批 anchor
+- swipe `y=2300 → y=200`(2800 屏保 1-2 行重叠)
+- 终止:scroll_position=bottom 且去重后空集 / 或 anchor 连续两批没变(安全网)
+
+### [15:50] 步骤② 完成 + dry-run 全过
+
+- `invoice_tool.py` 新增 `android_vision_page_run` + 4 个 helper(`call_vision_subcommand` / `vision_detect_list_page` / `vision_list_rows` / `android_swipe_up` + `drive_invoice_subflow`),老命令 `android-page-run` 不动并行存在
+- 注册新 subparser `android-vision-page-run` 含 `--dry-run / --max-actions / --max-batches / --no-precheck` 等
+- dry-run 输出:precheck ✓ / 视觉 7 行 ✓ / roster 匹配 3 pending(程*桐/朱*玉/王*平)/ tap 坐标对齐 XML 真值
+
+### [15:51] 单人真测 · 程*桐 → no_ticket 分支闭环
+
+`--max-actions 1`:tap [1029, 841] → 视觉抓出"扫码开票单 / 您没有可开具电子发票的客票" → 标 `no_ticket` → back 回列表(1 次)→ `sub_back_to_list steps=1` → max_actions 命中即停。
+完整流程 ✓:**视觉抓行 + tap + 子流程分支 + 状态写回 + 自动退出**,全部按预期。
+
+### [15:55] 用户改要求 · "不管 roster,识别出来就 tap"
+
+用户决定:no_match 名也 tap,12306 返啥就记啥。改 `android_vision_page_run` 移除 `match_count != 1` 跳过,无名单匹配也进 sub-flow(预期:已开过 → no_ticket 干净退;未开 → 核验弹窗 → 报错 → 兜底 back)。
+
+### [16:04] 翻车一 · denormalize 阈值 bug
+
+`--max-actions 2`,视觉抓到屏幕已被人为滚动到的 9 行新名字。tap 坐标变成 [816, 156] / [816, 261] — y 极小,落在标题栏。
+原因:Qwen 这次最大坐标返回 1013(赵*丹 底部行),`denormalize_bboxes` 的判定 `> 1000 视为绝对像素` 太严,1013 被误判 → bbox 没反归一 → 中心点直接用归一化值当像素 tap。
+修:阈值改成 `max <= 1100 且 image_min_dim > 1100`,允许 Qwen rounding 飘到 1000-1030。
+
+### [16:08] 翻车二 · 2 字脱敏名正则失配 + back 退过头
+
+修阈值后真 tap 落点:李*霞 ✓ 进 no_ticket、澳* tap ✓ 进核验框,但核验弹窗内"请输入乘车人 澳* 证件号码后8位" 被正则 `[一-鿿]{1,3}` 强制 ≥1 字过滤,**澳* 是 2 字脱敏**,无法解析。
+报错 → 兜底连按 4 次 back → 把列表页一起退出 → 手机停在 12306 首页。
+
+### [16:13] 三处修复
+
+1. 核验正则:`[一-鿿]{0,3}` 兼容 澳* / 吴* / 周* 之类 2 字名
+2. `safe_back_until_list` 改:max_back 4→2,每次后 sleep 1→1.5s,加 `is_on_12306_home()` 检测,退过头立刻 stop
+3. 外层 abort 闸门:子流程返回非 `back_to_list` 时,如不在列表页就 `return`,不再 tap
+
+### [16:14] 用户提出录制示范方案
+
+用户决定换打法:**他手动操作一遍 → 我用 `record_step.py` 抓 XML+screenshot → 反推脚本逻辑**。
+新工具 `scripts/record_step.py` 就位(session 自增、`--new` / `--list` / 默认追加)。
+本次 session 未真正录制,留给下次。
+
+### [16:15] 收尾 · 用户重开 session
+
+写 CHANGELOG 4 条 + INDEX.md Handoff 全状态盘点 + 本日志收口。下次开会的 Claude 看 INDEX 接力点即可上手。
+
+---
+
+> 本日志到此封顶。后续工作重新写 `docs/debug-trace-YYYY-MM-DD.md`,不在本文件追加。
+
+---
+
+> 后续条目继续以 `### [HH:MM] 标题` 追加。每条只写**发生了什么 / 看到了什么 / 接下来做什么**。
diff --git a/docs/usage.md b/docs/usage.md
new file mode 100644
index 0000000..71bb26e
--- /dev/null
+++ b/docs/usage.md
@@ -0,0 +1,294 @@
+# 铁路系统发票批量处理使用说明
+
+## 原则
+
+- 只使用铁路 12306 官方页面/App 完成开票。
+- 本工具不保存 12306 账号密码，不绕过验证码或身份核验。
+- 公司抬头、税号、接收邮箱从本地配置读取；不要写入 `.env`。
+- `config.local.json` 已被 `.gitignore` 忽略，不要把真实公司信息写进 `config.example.json`。
+
+## 初始化
+
+```bash
+python3 scripts/invoice_tool.py init
+```
+
+先复制一份本地配置：
+
+```bash
+cp config.example.json config.local.json
+```
+
+然后把 `config.local.json` 里的三项改成真实值：
+
+```json
+{
+  "company_title": "公司全称",
+  "tax_id": "统一社会信用代码",
+  "receiver_email": "统一收票邮箱"
+}
+```
+
+## 导入开票码
+
+把旅行社给的二维码图片或 PDF 放到：
+
+```text
+data/input/开票码批次/
+```
+
+执行：
+
+```bash
+python3 scripts/invoice_tool.py import-codes
+```
+
+输出台账：
+
+```text
+work/invoice_tasks.csv
+```
+
+如果本机没有二维码解码器，任务会进入 `待补码`。人工扫码后，把链接或码写入：
+
+```text
+data/input/开票码批次/manual_codes.csv
+```
+
+再执行一次 `import-codes`。
+
+如果这是铁路“扫码开票单”截图，二维码通常只能用 12306 App 扫。可以在
+`manual_codes.csv` 里用 `APP_SCAN` 补录开票单号和代办人：
+
+```csv
+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
+
+启动本地页面：
+
+```bash
+python3 scripts/web_ui.py
+```
+
+打开：
+
+```text
+http://127.0.0.1:8765
+```
+
+页面支持上传 `.xlsx/.xlsm/.csv` 名单、查看成功/失败/处理中/未操作统计、显示手机连接/当前 App 状态、启动手机 12306、抓取当前页队列、启动/停止批处理，并持续读取：
+
+```text
+work/android_invoice_progress.csv
+```
+
+这个 CSV 是逐人处理结果表，页面里的“下载进度表”会直接下载它。
+
+### 1. 导入 Excel 名单
+
+名单里至少要有“姓名”和“身份证/证件号码”两类列名。支持 `.xlsx/.xlsm/.csv`：
+
+```bash
+python3 scripts/invoice_tool.py import-roster --input /path/to/名单.xlsx
+```
+
+输出：
+
+```text
+work/passenger_roster.csv
+```
+
+先离线验证一个脱敏姓名：
+
+```bash
+python3 scripts/invoice_tool.py match-roster --masked-name '张*岩'
+```
+
+如果出现 `ambiguous`，说明同名脱敏后匹配到多人，必须人工确认。
+
+### 2. 连接 Android 手机
+
+手机开启 USB 调试后连接 Mac：
+
+```bash
+/opt/homebrew/share/android-commandlinetools/platform-tools/adb devices
+```
+
+先手工在 12306 App 扫码，进入要求填写身份证后 8 位的页面。
+
+读取当前页面文字：
+
+```bash
+python3 scripts/invoice_tool.py android-dump --output work/android_page.txt
+```
+
+如果能看到 `张*岩` 这类文字，就可以自动匹配并输入身份证后 8 位：
+
+```bash
+python3 scripts/invoice_tool.py android-type-id --tap 500,1200
+```
+
+`--tap` 是输入框坐标，需要按手机页面实际位置改。也可以用按钮/输入框可访问文字：
+
+```bash
+python3 scripts/invoice_tool.py android-type-id --click-text '证件号码后8位' --contains
+```
+
+### 3. 后续点击流程
+
+复制并修改模板：
+
+```bash
+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 秒`，仍不成功就暂停：
+
+```bash
+python3 scripts/invoice_tool.py android-invoice-step
+```
+
+如果当前在“发票开具成功”页，默认会点 `继续开票` 回列表。需要先发邮件时才加：
+
+```bash
+python3 scripts/invoice_tool.py android-invoice-step --send-email
+```
+
+### 5. 扫码列表页批处理队列
+
+扫码开票单列表页不要用固定坐标。先抓当前可见的一页，按脱敏姓名和名单生成队列：
+
+```bash
+python3 scripts/invoice_tool.py android-build-page-queue
+```
+
+队列文件：
+
+```text
+work/android_page_queue.csv
+```
+
+然后反复跑：
+
+```bash
+python3 scripts/invoice_tool.py android-page-step
+```
+
+行为：
+
+- 当前在扫码列表页：按本页队列点击下一个可匹配人员的 `开具`。
+- 当前在核验/发票管理/发票信息/成功页：执行普通单步状态机。
+- 本页没有可处理人员：输出 `page_done`，不自动乱滑。
+
+本页处理完后上滑到下一页并重建队列：
+
+```bash
+python3 scripts/invoice_tool.py android-page-next --rebuild
+```
+
+也可以让 `android-page-step` 在本页完成后自动上滑：
+
+```bash
+python3 scripts/invoice_tool.py android-page-step --auto-next
+```
+
+## 网页辅助开票
+
+```bash
+python3 scripts/invoice_tool.py rpa-plan
+```
+
+打开：
+
+```text
+output/rpa_helper.html
+```
+
+先手动登录 12306 并完成核验，再逐条打开官方页面，复制公司抬头、税号和邮箱提交。
+
+## 邮件和附件归集
+
+如果有 `.eml` 邮件文件：
+
+```bash
+python3 scripts/invoice_tool.py collect-mail
+```
+
+如果已经把 PDF/OFD/XML 附件下载到 `data/attachments/`：
+
+```bash
+python3 scripts/invoice_tool.py collect-attachments
+```
+
+归集后的发票在：
+
+```text
+output/invoices/
+```
+
+## 汇总和查漏
+
+```bash
+python3 scripts/invoice_tool.py export-summary
+```
+
+输出：
+
+```text
+output/发票汇总.xlsx
+```
+
+工作簿包含：
+
+- `发票汇总`
+- `缺票清单`
+- `合规检查`
+
+## 状态含义
+
+| 状态 | 含义 |
+|---|---|
+| `待补码` | 未能自动识别二维码，需要人工扫码补录 |
+| `待人工扫码` | 码不是网页链接，通常需要 12306 App 扫码 |
+| `待网页开票` | 可以从辅助页打开官方页面处理 |
+| `已收票` | 已匹配到发票附件 |
diff --git a/scripts/invoice_tool.py b/scripts/invoice_tool.py
new file mode 100755
index 0000000..bbe69aa
--- /dev/null
+++ b/scripts/invoice_tool.py
@@ -0,0 +1,2576 @@
+#!/usr/bin/env python3
+"""Local helper for railway invoice batch tasks.
+
+The tool intentionally avoids non-official 12306 APIs. It only prepares local
+ledgers, files, and browser helper pages for a logged-in human operator.
+"""
+
+from __future__ import annotations
+
+import argparse
+import csv
+import email
+import hashlib
+import html
+import json
+import re
+import shutil
+import subprocess
+import time
+import xml.etree.ElementTree as ET
+from dataclasses import dataclass
+from datetime import datetime
+from email import policy
+from pathlib import Path
+
+try:
+    from openpyxl import Workbook, load_workbook
+except Exception:  # pragma: no cover
+    Workbook = None
+    load_workbook = None
+
+PROJECT_ROOT = Path(__file__).resolve().parents[1]
+TASKS_CSV = PROJECT_ROOT / "work" / "invoice_tasks.csv"
+CONFIG_EXAMPLE_PATH = PROJECT_ROOT / "config.example.json"
+CONFIG_LOCAL_PATH = PROJECT_ROOT / "config.local.json"
+ROSTER_CSV = PROJECT_ROOT / "work" / "passenger_roster.csv"
+PROGRESS_CSV = PROJECT_ROOT / "work" / "android_invoice_progress.csv"
+PAGE_QUEUE_CSV = PROJECT_ROOT / "work" / "android_page_queue.csv"
+LAST_QR_URL = PROJECT_ROOT / "work" / "last_qr_url.txt"
+ADB_PATH = "/opt/homebrew/share/android-commandlinetools/platform-tools/adb"
+
+TASK_HEADERS = [
+    "task_id",
+    "乘车人",
+    "票号/订单标识",
+    "二维码来源文件",
+    "开票码/链接",
+    "公司抬头",
+    "税号",
+    "接收邮箱",
+    "状态",
+    "失败原因",
+    "下一步动作",
+    "发票文件路径",
+    "开票时间",
+    "身份证后8位",
+    "名单匹配状态",
+]
+
+ROSTER_HEADERS = ["姓名", "身份证号", "身份证后8位", "来源文件", "来源工作表", "来源行号"]
+PROGRESS_HEADERS = ["masked_name", "real_name", "id_last8", "status", "updated_at"]
+PAGE_QUEUE_HEADERS = ["page_id", "masked_name", "id_first", "id_last", "real_name", "id_last8", "button_bounds", "match_status", "queue_status", "attempts", "updated_at"]
+RETRYABLE_FAILURES = {"no_match", "ambiguous", "no_button", "runtime_error"}
+
+INVOICE_EXTENSIONS = {".pdf", ".ofd", ".xml"}
+QR_INPUT_EXTENSIONS = {".png", ".jpg", ".jpeg", ".webp", ".bmp", ".gif", ".pdf", ".txt", ".csv"}
+
+
+@dataclass
+class Config:
+    company_title: str
+    tax_id: str
+    receiver_email: str
+    invoice_output_dir: str = "output/invoices"
+    invoice_success_action: str = "download"
+
+
+def project_path(value: str | Path) -> Path:
+    path = Path(value)
+    return path if path.is_absolute() else PROJECT_ROOT / path
+
+
+def ensure_dirs() -> None:
+    for relative in [
+        "data/input/开票码批次",
+        "data/mail",
+        "data/attachments",
+        "work",
+        "output/invoices",
+        "archive",
+        "docs",
+    ]:
+        project_path(relative).mkdir(parents=True, exist_ok=True)
+
+
+def load_config(config_path: Path) -> Config:
+    if not config_path.exists() and config_path.name == "config.local.json":
+        config_path = CONFIG_EXAMPLE_PATH
+    if not config_path.exists():
+        return Config(company_title="", tax_id="", receiver_email="")
+    data = json.loads(config_path.read_text(encoding="utf-8"))
+    return Config(
+        company_title=str(data.get("company_title", "")).strip(),
+        tax_id=str(data.get("tax_id", "")).strip(),
+        receiver_email=str(data.get("receiver_email", "")).strip(),
+        invoice_output_dir=str(data.get("invoice_output_dir", "output/invoices")).strip() or "output/invoices",
+        invoice_success_action=str(data.get("invoice_success_action", "download")).strip() or "download",
+    )
+
+
+def read_tasks(path: Path = TASKS_CSV) -> list[dict[str, str]]:
+    if not path.exists():
+        return []
+    with path.open("r", encoding="utf-8-sig", newline="") as fh:
+        return list(csv.DictReader(fh))
+
+
+def write_tasks(tasks: list[dict[str, str]], path: Path = TASKS_CSV) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with path.open("w", encoding="utf-8-sig", newline="") as fh:
+        writer = csv.DictWriter(fh, fieldnames=TASK_HEADERS)
+        writer.writeheader()
+        for task in tasks:
+            writer.writerow({key: task.get(key, "") for key in TASK_HEADERS})
+
+
+def make_task_id(*parts: str) -> str:
+    return hashlib.sha1("|".join(parts).encode("utf-8")).hexdigest()[:12]
+
+
+def derive_passenger_and_ref(path: Path) -> tuple[str, str]:
+    if path.stem.lower().startswith(("screenshot", "screen_shot", "截屏", "截图")):
+        return "", ""
+    parts = re.split(r"[_\-\s]+", path.stem)
+    passenger = parts[0] if parts else ""
+    ticket_ref = next((part for part in parts[1:] if re.search(r"\d", part)), "")
+    return passenger, ticket_ref
+
+
+def decode_qr_with_zbar(path: Path) -> str:
+    zbarimg = shutil.which("zbarimg")
+    if not zbarimg:
+        return ""
+    try:
+        result = subprocess.run(
+            [zbarimg, "--raw", str(path)],
+            check=False,
+            capture_output=True,
+            text=True,
+            timeout=20,
+        )
+    except Exception:
+        return ""
+    return result.stdout.strip().splitlines()[0] if result.stdout.strip() else ""
+
+
+def decode_qr_image(image_bytes: bytes) -> dict[str, object]:
+    """用 OpenCV 从图片 bytes 中解码 QR 码。
+
+    返回 {"results": [...], "error": ""}；results 是解码出的字符串列表。
+    """
+    try:
+        import cv2
+        import numpy as np
+    except ImportError:
+        return {"results": [], "error": "OpenCV (cv2) 未安装"}
+
+    nparr = np.frombuffer(image_bytes, np.uint8)
+    img = cv2.imdecode(nparr, cv2.IMREAD_COLOR)
+    if img is None:
+        return {"results": [], "error": "无法解析图片，请确认粘贴的是有效图片"}
+
+    detector = cv2.QRCodeDetector()
+
+    # 先试单 QR
+    data, _bbox, _straight = detector.detectAndDecode(img)
+    if data:
+        return {"results": [data], "error": ""}
+
+    # 再试多 QR（截图里可能有多个码）
+    ret, decoded_strings, _points, _straights = detector.detectAndDecodeMulti(img)
+    if ret and decoded_strings:
+        return {"results": [str(s) for s in decoded_strings if s], "error": ""}
+
+    return {"results": [], "error": "未识别到二维码，请确认截图包含清晰的二维码"}
+
+
+def decode_input_file(path: Path) -> str:
+    if path.suffix.lower() == ".txt":
+        return path.read_text(encoding="utf-8", errors="ignore").strip()
+    if path.suffix.lower() == ".csv":
+        return ""
+    return decode_qr_with_zbar(path)
+
+
+APP_SCAN_REQUIRED = "__APP_SCAN_REQUIRED__"
+
+
+def new_task(task_id: str, source_file: str, code: str, passenger: str, ticket_ref: str, config: Config) -> dict[str, str]:
+    if code == APP_SCAN_REQUIRED:
+        status = "待人工扫码"
+        failure = ""
+        next_step = "这类扫码开票单通常需使用 12306 App 扫码开票；Mac 端负责台账、收票、归档"
+        display_code = ""
+    elif not code:
+        status = "待补码"
+        failure = "未能自动识别二维码"
+        next_step = "人工扫描二维码后，把链接/码写入 manual_codes.csv 再重新导入"
+        display_code = ""
+    elif code.startswith(("http://", "https://")):
+        status = "待网页开票"
+        failure = ""
+        next_step = "用 RPA 辅助页打开链接并在官方页面提交"
+        display_code = code
+    else:
+        status = "待人工扫码"
+        failure = ""
+        next_step = "用 12306 App 扫码，或补录可网页打开的链接"
+        display_code = code
+
+    return {
+        "task_id": task_id,
+        "乘车人": passenger,
+        "票号/订单标识": ticket_ref,
+        "二维码来源文件": source_file,
+        "开票码/链接": display_code,
+        "公司抬头": config.company_title,
+        "税号": config.tax_id,
+        "接收邮箱": config.receiver_email,
+        "状态": status,
+        "失败原因": failure,
+        "下一步动作": next_step,
+        "发票文件路径": "",
+        "开票时间": "",
+    }
+
+
+def rows_from_manual_csv(path: Path, config: Config) -> list[dict[str, str]]:
+    rows: list[dict[str, str]] = []
+    with path.open("r", encoding="utf-8-sig", newline="") as fh:
+        reader = csv.DictReader(fh)
+        for source_row in reader:
+            code = (source_row.get("开票码/链接") or source_row.get("code") or "").strip()
+            status_hint = (source_row.get("状态") or source_row.get("status") or "").strip().lower()
+            if code.upper() in {"APP_SCAN", "APP_SCAN_REQUIRED"} or "扫码" in status_hint:
+                code = APP_SCAN_REQUIRED
+            source_file = (source_row.get("二维码来源文件") or source_row.get("source_file") or path.name).strip()
+            passenger = (source_row.get("乘车人") or source_row.get("passenger") or "").strip()
+            ticket_ref = (source_row.get("票号/订单标识") or source_row.get("ticket_ref") or "").strip()
+            task_id = make_task_id(source_file, passenger, ticket_ref, code)
+            rows = [row for row in rows if row.get("二维码来源文件") != source_file]
+            rows.append(new_task(task_id, source_file, code, passenger, ticket_ref, config))
+    return rows
+
+
+def import_codes(args: argparse.Namespace) -> None:
+    ensure_dirs()
+    config = load_config(project_path(args.config))
+    input_dir = project_path(args.input)
+    existing = {task["task_id"]: task for task in read_tasks()}
+    imported = 0
+
+    for path in sorted(input_dir.rglob("*")):
+        if not path.is_file() or path.suffix.lower() not in QR_INPUT_EXTENSIONS:
+            continue
+        if path.name == "manual_codes.csv":
+            for row in rows_from_manual_csv(path, config):
+                existing = {task_id: task for task_id, task in existing.items() if task.get("二维码来源文件") != row.get("二维码来源文件")}
+                existing[row["task_id"]] = row
+                imported += 1
+            continue
+        if path.suffix.lower() == ".csv":
+            continue
+        passenger, ticket_ref = derive_passenger_and_ref(path)
+        code = decode_input_file(path)
+        if not code and path.suffix.lower() in {".png", ".jpg", ".jpeg", ".webp", ".bmp", ".gif", ".pdf"}:
+            code = APP_SCAN_REQUIRED
+        rel_source = str(path.relative_to(PROJECT_ROOT))
+        existing = {task_id: task for task_id, task in existing.items() if task.get("二维码来源文件") != rel_source}
+        task_id = make_task_id(rel_source, passenger, ticket_ref, code)
+        existing[task_id] = new_task(task_id, rel_source, code, passenger, ticket_ref, config)
+        imported += 1
+
+    write_tasks(list(existing.values()))
+    print(f"imported={imported}")
+    print(f"tasks={TASKS_CSV}")
+
+
+def safe_filename(value: str) -> str:
+    value = re.sub(r"[\\/:*?\"<>|\s]+", "_", value.strip())
+    return value.strip("_") or "unknown"
+
+
+def extract_invoice_number(text: str) -> str:
+    for pattern in [r"发票号码[:：\s]*([0-9]{8,20})", r"([0-9]{20})"]:
+        match = re.search(pattern, text)
+        if match:
+            return match.group(1)
+    return ""
+
+
+def unique_dest(path: Path) -> Path:
+    if not path.exists():
+        return path
+    counter = 2
+    while True:
+        candidate = path.with_name(f"{path.stem}_{counter}{path.suffix}")
+        if not candidate.exists():
+            return candidate
+        counter += 1
+
+
+def normalize_name(value: str) -> str:
+    return re.sub(r"\s+", "", str(value or "").strip())
+
+
+def masked_name_matches(masked: str, real_name: str) -> bool:
+    masked = normalize_name(masked).replace("＊", "*")
+    real_name = normalize_name(real_name)
+    if not masked or not real_name or "*" not in masked:
+        return masked == real_name
+    if len(masked) != len(real_name):
+        return False
+    return all(mask_char == "*" or mask_char == real_char for mask_char, real_char in zip(masked, real_name))
+
+
+def id_last8(value: str) -> str:
+    text = str(value or "").strip().upper()
+    text = re.sub(r"[^0-9X]", "", text)
+    return text[-8:] if len(text) >= 8 else ""
+
+
+def guess_column(headers: list[str], candidates: list[str]) -> int | None:
+    normalized = [str(header or "").strip() for header in headers]
+    for candidate in candidates:
+        for index, header in enumerate(normalized):
+            if candidate in header:
+                return index
+    return None
+
+
+def write_roster(rows: list[dict[str, str]], path: Path = ROSTER_CSV) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with path.open("w", encoding="utf-8-sig", newline="") as fh:
+        writer = csv.DictWriter(fh, fieldnames=ROSTER_HEADERS)
+        writer.writeheader()
+        for row in rows:
+            writer.writerow({key: row.get(key, "") for key in ROSTER_HEADERS})
+
+
+def read_roster(path: Path = ROSTER_CSV) -> list[dict[str, str]]:
+    if not path.exists():
+        return []
+    with path.open("r", encoding="utf-8-sig", newline="") as fh:
+        return list(csv.DictReader(fh))
+
+
+def read_progress(path: Path = PROGRESS_CSV) -> list[dict[str, str]]:
+    if not path.exists():
+        return []
+    with path.open("r", encoding="utf-8-sig", newline="") as fh:
+        return list(csv.DictReader(fh))
+
+
+def write_progress(rows: list[dict[str, str]], path: Path = PROGRESS_CSV) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with path.open("w", encoding="utf-8-sig", newline="") as fh:
+        writer = csv.DictWriter(fh, fieldnames=PROGRESS_HEADERS)
+        writer.writeheader()
+        for row in rows:
+            writer.writerow({key: row.get(key, "") for key in PROGRESS_HEADERS})
+
+
+def update_progress(masked_name: str, real_name: str, id8: str, status: str) -> None:
+    rows = read_progress()
+    now = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+    updated = False
+    for row in rows:
+        if row.get("masked_name") == masked_name and row.get("real_name") == real_name:
+            row.update({"id_last8": id8, "status": status, "updated_at": now})
+            updated = True
+            break
+    if not updated:
+        rows.append({"masked_name": masked_name, "real_name": real_name, "id_last8": id8, "status": status, "updated_at": now})
+    write_progress(rows)
+
+
+def progress_names(statuses: set[str]) -> set[str]:
+    return {row.get("masked_name", "") for row in read_progress() if row.get("status") in statuses}
+
+
+def retryable_failed_names(current_names: set[str], max_attempts: int = 1) -> set[str]:
+    if max_attempts <= 0:
+        return set()
+    retried = getattr(retryable_failed_names, "_retried", set())
+    failed = progress_names({"failed", "error"}) & current_names
+    return {name for name in failed if name not in retried}
+
+
+def mark_failed_retry_attempt(masked_name: str) -> None:
+    retried = getattr(retryable_failed_names, "_retried", set())
+    retried.add(masked_name)
+    setattr(retryable_failed_names, "_retried", retried)
+
+
+def last_progress_anchor() -> str:
+    rows = [row for row in read_progress() if row.get("status") in {"completed", "no_ticket", "failed", "error"}]
+    if not rows:
+        return ""
+
+    def key(row: dict[str, str]) -> str:
+        return row.get("updated_at", "")
+
+    return max(rows, key=key).get("masked_name", "")
+
+
+def read_page_queue(path: Path = PAGE_QUEUE_CSV) -> list[dict[str, str]]:
+    if not path.exists():
+        return []
+    with path.open("r", encoding="utf-8-sig", newline="") as fh:
+        return list(csv.DictReader(fh))
+
+
+def write_page_queue(rows: list[dict[str, str]], path: Path = PAGE_QUEUE_CSV) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with path.open("w", encoding="utf-8-sig", newline="") as fh:
+        writer = csv.DictWriter(fh, fieldnames=PAGE_QUEUE_HEADERS)
+        writer.writeheader()
+        for row in rows:
+            writer.writerow({key: row.get(key, "") for key in PAGE_QUEUE_HEADERS})
+
+
+def import_roster(args: argparse.Namespace) -> None:
+    ensure_dirs()
+    source = project_path(args.input)
+    rows: list[dict[str, str]] = []
+    name_candidates = ["姓名", "乘车人", "人员姓名", "客户姓名", "学生姓名"]
+    id_candidates = ["身份证", "证件号码", "身份证号", "证件号", "证件信息"]
+
+    if source.suffix.lower() in {".xlsx", ".xlsm"}:
+        if load_workbook is None:
+            raise RuntimeError("openpyxl 不可用，无法读取 Excel 名单")
+        wb = load_workbook(source, read_only=True, data_only=True)
+        for sheet_name in wb.sheetnames:
+            ws = wb[sheet_name]
+            iterator = enumerate(ws.iter_rows(values_only=True), start=1)
+            header_row_no = 0
+            headers: list[str] = []
+            buffered_rows: list[tuple[int, tuple[object, ...]]] = []
+            for row_no, values in iterator:
+                headers = [str(value or "").strip() for value in values]
+                name_index = guess_column(headers, name_candidates)
+                id_index = guess_column(headers, id_candidates)
+                if name_index is not None and id_index is not None:
+                    header_row_no = row_no
+                    break
+                if row_no >= 30:
+                    break
+            if not header_row_no:
+                continue
+            name_index = guess_column(headers, name_candidates)
+            id_index = guess_column(headers, id_candidates)
+            if name_index is None or id_index is None:
+                continue
+            for row_no, values in iterator:
+                name = normalize_name(values[name_index] if name_index < len(values) else "")
+                cert_id = str(values[id_index] if id_index < len(values) and values[id_index] is not None else "").strip()
+                last8 = id_last8(cert_id)
+                if name and last8:
+                    rows.append({"姓名": name, "身份证号": cert_id, "身份证后8位": last8, "来源文件": str(source), "来源工作表": sheet_name, "来源行号": str(row_no)})
+    elif source.suffix.lower() == ".csv":
+        with source.open("r", encoding="utf-8-sig", newline="") as fh:
+            reader = csv.DictReader(fh)
+            headers = reader.fieldnames or []
+            name_key = next((key for key in headers if any(candidate in key for candidate in name_candidates)), None)
+            id_key = next((key for key in headers if any(candidate in key for candidate in id_candidates)), None)
+            if not name_key or not id_key:
+                raise RuntimeError("CSV 未找到姓名列或身份证列")
+            for row_no, row in enumerate(reader, start=2):
+                name = normalize_name(row.get(name_key, ""))
+                cert_id = str(row.get(id_key, "")).strip()
+                last8 = id_last8(cert_id)
+                if name and last8:
+                    rows.append({"姓名": name, "身份证号": cert_id, "身份证后8位": last8, "来源文件": str(source), "来源工作表": "", "来源行号": str(row_no)})
+    else:
+        raise RuntimeError("名单只支持 .xlsx/.xlsm/.csv")
+
+    write_roster(rows)
+    print(f"roster_rows={len(rows)}")
+    print(f"roster={ROSTER_CSV}")
+
+
+def match_roster(masked_name: str, roster: list[dict[str, str]], id_first: str = "", id_last: str = "") -> list[dict[str, str]]:
+    masked_name = normalize_name(masked_name)
+    id_first = (id_first or "").strip().upper()
+    id_last = (id_last or "").strip().upper()
+    result = []
+    for row in roster:
+        if not masked_name_matches(masked_name, row.get("姓名", "")):
+            continue
+        cert = (row.get("身份证号", "") or "").strip().upper()
+        if id_first and cert[:1] != id_first:
+            continue
+        if id_last and cert[-1:] != id_last:
+            continue
+        result.append(row)
+    return result
+
+
+def match_roster_command(args: argparse.Namespace) -> None:
+    roster = read_roster(project_path(args.roster))
+    matches = match_roster(args.masked_name, roster)
+    if not matches:
+        print(f"no_match={args.masked_name}")
+        raise SystemExit(1)
+    if len(matches) > 1:
+        print(f"ambiguous={args.masked_name}")
+        for row in matches:
+            print(f"{row.get('姓名')} {row.get('身份证后8位')} {row.get('来源行号')}")
+        raise SystemExit(2)
+    row = matches[0]
+    print(f"name={row.get('姓名')}")
+    print(f"id_last8={row.get('身份证后8位')}")
+
+
+def enrich_tasks_with_roster(args: argparse.Namespace) -> None:
+    tasks = read_tasks()
+    roster = read_roster(project_path(args.roster))
+    for task in tasks:
+        masked_name = task.get("乘车人", "")
+        if not masked_name or task.get("身份证后8位"):
+            continue
+        matches = match_roster(masked_name, roster)
+        if len(matches) == 1:
+            task["身份证后8位"] = matches[0].get("身份证后8位", "")
+            task["名单匹配状态"] = f"已匹配:{matches[0].get('姓名', '')}"
+        elif len(matches) > 1:
+            task["名单匹配状态"] = f"多人匹配:{len(matches)}"
+        else:
+            task["名单匹配状态"] = "未匹配"
+    write_tasks(tasks)
+    print(f"tasks={TASKS_CSV}")
+
+
+def adb_binary() -> str:
+    return ADB_PATH if Path(ADB_PATH).exists() else "adb"
+
+
+def run_adb(arguments: list[str], *, check: bool = True) -> subprocess.CompletedProcess[str]:
+    result = subprocess.run([adb_binary(), *arguments], capture_output=True, text=True, check=False)
+    if check and result.returncode != 0:
+        raise RuntimeError(result.stderr.strip() or result.stdout.strip() or "adb command failed")
+    return result
+
+
+def parse_bounds(bounds: str) -> tuple[int, int] | None:
+    match = re.match(r"\[(\d+),(\d+)\]\[(\d+),(\d+)\]", bounds or "")
+    if not match:
+        return None
+    left, top, right, bottom = map(int, match.groups())
+    return ((left + right) // 2, (top + bottom) // 2)
+
+
+def adb_dump_nodes() -> list[dict[str, str]]:
+    run_adb(["shell", "uiautomator", "dump", "/sdcard/window.xml"])
+    xml_text = run_adb(["exec-out", "cat", "/sdcard/window.xml"]).stdout
+    root = ET.fromstring(xml_text)
+    nodes: list[dict[str, str]] = []
+    for node in root.iter("node"):
+        nodes.append(dict(node.attrib))
+    return nodes
+
+
+def adb_visible_texts(nodes: list[dict[str, str]]) -> list[str]:
+    texts: list[str] = []
+    for node in nodes:
+        for key in ("text", "content-desc", "resource-id"):
+            value = (node.get(key) or "").strip()
+            if value:
+                texts.append(value)
+    return texts
+
+
+def find_android_node(nodes: list[dict[str, str]], text: str, *, contains: bool = False) -> dict[str, str] | None:
+    for node in nodes:
+        values = [node.get("text", ""), node.get("content-desc", ""), node.get("resource-id", "")]
+        if any((text in value if contains else text == value) for value in values):
+            return node
+    return None
+
+
+def find_android_nodes(nodes: list[dict[str, str]], text: str, *, contains: bool = False, clickable: bool | None = None) -> list[dict[str, str]]:
+    matches: list[dict[str, str]] = []
+    for node in nodes:
+        if clickable is not None and node.get("clickable") != str(clickable).lower():
+            continue
+        values = [node.get("text", ""), node.get("content-desc", ""), node.get("resource-id", "")]
+        if any((text in value if contains else text == value) for value in values):
+            matches.append(node)
+    return matches
+
+
+def adb_tap_bounds(bounds: str) -> None:
+    point = parse_bounds(bounds)
+    if not point:
+        raise RuntimeError(f"无法解析 bounds: {bounds}")
+    run_adb(["shell", "input", "tap", str(point[0]), str(point[1])])
+
+
+def adb_input_text(text: str) -> None:
+    safe = str(text).replace(" ", "%s")
+    run_adb(["shell", "input", "text", safe])
+
+
+def extract_masked_names(texts: Iterable[str]) -> list[str]:
+    found: list[str] = []
+    pattern = re.compile(r"[\u4e00-\u9fff][*＊][\u4e00-\u9fff]{1,3}")
+    for text in texts:
+        for match in pattern.findall(text):
+            if match not in found:
+                found.append(match.replace("＊", "*"))
+    return found
+
+
+def node_center_y(node: dict[str, str]) -> int:
+    point = parse_bounds(node.get("bounds", ""))
+    return point[1] if point else 0
+
+
+def click_node(node: dict[str, str], label: str) -> None:
+    print(f"click={label} bounds={node.get('bounds', '')}")
+    adb_tap_bounds(node.get("bounds", ""))
+
+
+def wait_and_probe(primary_seconds: int, secondary_seconds: int, success_terms: list[str]) -> list[dict[str, str]]:
+    """等待页面进入目标状态；命中关键字就提前返回，避免固定 sleep 拖慢流程。"""
+    started = time.perf_counter()
+    nodes: list[dict[str, str]] = []
+
+    def probe() -> tuple[list[dict[str, str]], str | None]:
+        current_nodes = adb_dump_nodes()
+        text = "\n".join(adb_visible_texts(current_nodes))
+        hit = next((term for term in success_terms if term in text), None)
+        return current_nodes, hit
+
+    def poll_for(seconds: float, phase: str) -> tuple[list[dict[str, str]], bool]:
+        nonlocal nodes
+        deadline = time.perf_counter() + max(seconds, 0)
+        interval = 0.35 if seconds <= 1.5 else 0.5
+        while True:
+            remaining = deadline - time.perf_counter()
+            if remaining > 0:
+                time.sleep(min(interval, remaining))
+            nodes, hit = probe()
+            elapsed = time.perf_counter() - started
+            if hit:
+                print(f"wait_hit phase={phase} term={hit} elapsed={elapsed:.1f}s")
+                return nodes, True
+            if time.perf_counter() >= deadline:
+                return nodes, False
+
+    nodes, found = poll_for(primary_seconds, "primary")
+    if found or secondary_seconds <= 0:
+        return nodes
+
+    print(f"wait_more={secondary_seconds}s")
+    nodes, _ = poll_for(secondary_seconds, "secondary")
+    return nodes
+
+
+def apply_speed_defaults(args: argparse.Namespace) -> None:
+    if getattr(args, "fast", False):
+        args.wait_primary = min(getattr(args, "wait_primary", 10), 1)
+        args.wait_secondary = min(getattr(args, "wait_secondary", 20), 3)
+        args.short_wait = min(getattr(args, "short_wait", 2), 0.7)
+        args.between_steps = min(getattr(args, "between_steps", 0.3), 0.15)
+    # 默认短等待 1s(大多数页面切换只需1s)
+    if getattr(args, "short_wait", 2) == 2:
+        args.short_wait = 1
+
+
+def wait_short(args: argparse.Namespace, success_terms: list[str]) -> list[dict[str, str]]:
+    return wait_and_probe(getattr(args, "short_wait", 2), 0, success_terms)
+
+
+def wait_long(args: argparse.Namespace, success_terms: list[str]) -> list[dict[str, str]]:
+    return wait_and_probe(getattr(args, "wait_primary", 10), getattr(args, "wait_secondary", 20), success_terms)
+
+
+def first_matched_visible_passenger(nodes: list[dict[str, str]], roster: list[dict[str, str]], skip_masked_names: set[str]) -> tuple[str, dict[str, str], dict[str, str]] | None:
+    masked_nodes = []
+    for node in nodes:
+        text = (node.get("text") or "").replace("＊", "*")
+        if re.fullmatch(r"[\u4e00-\u9fff][*][\u4e00-\u9fff]{1,3}", text):
+            masked_nodes.append((text, node))
+    open_buttons = find_android_nodes(nodes, "开具", clickable=True)
+    id_nodes = visible_id_mask_nodes(nodes)
+    for masked_name, masked_node in masked_nodes:
+        if masked_name in skip_masked_names:
+            print(f"skip_done={masked_name}")
+            continue
+        masked_y = node_center_y(masked_node)
+        id_first, id_last = id_mask_for(masked_y, id_nodes)
+        matches = match_roster(masked_name, roster, id_first, id_last)
+        if not matches and (id_first or id_last):
+            matches = match_roster(masked_name, roster)
+        if len(matches) != 1:
+            print(f"skip_masked={masked_name} matches={len(matches)} id={id_first}*{id_last}")
+            continue
+        candidates = [button for button in open_buttons if abs(node_center_y(button) - masked_y) < 120]
+        if candidates:
+            return masked_name, matches[0], candidates[0]
+    return None
+
+
+def visible_masked_name_nodes(nodes: list[dict[str, str]], max_y: int = 2650) -> list[tuple[str, dict[str, str]]]:
+    result: list[tuple[str, dict[str, str]]] = []
+    for node in nodes:
+        text = (node.get("text") or "").replace("＊", "*")
+        y = node_center_y(node)
+        if y and y <= max_y and re.fullmatch(r"[\u4e00-\u9fff][*][\u4e00-\u9fff]{1,3}", text):
+            result.append((text, node))
+    return result
+
+
+ID_MASK_PATTERN = re.compile(r"([0-9])\*{2,}([0-9X])")
+
+
+def visible_id_mask_nodes(nodes: list[dict[str, str]], max_y: int = 2650) -> list[tuple[str, str, int]]:
+    items: list[tuple[str, str, int]] = []
+    for node in nodes:
+        text = (node.get("text") or "").strip().upper()
+        y = node_center_y(node)
+        if not y or y > max_y:
+            continue
+        match = ID_MASK_PATTERN.fullmatch(text)
+        if match:
+            items.append((match.group(1), match.group(2), y))
+    return items
+
+
+def id_mask_for(masked_y: int, id_nodes: list[tuple[str, str, int]]) -> tuple[str, str]:
+    candidates = [(abs(y - masked_y), first, last) for first, last, y in id_nodes if abs(y - masked_y) < 120]
+    if not candidates:
+        return "", ""
+    candidates.sort(key=lambda item: item[0])
+    return candidates[0][1], candidates[0][2]
+
+
+def visible_open_buttons(nodes: list[dict[str, str]], max_y: int = 2650) -> list[dict[str, str]]:
+    return [node for node in find_android_nodes(nodes, "开具", clickable=True) if 0 < node_center_y(node) <= max_y]
+
+
+def page_id_for_names(masked_nodes: list[tuple[str, dict[str, str]]]) -> str:
+    signature = "|".join(f"{name}@{node.get('bounds', '')}" for name, node in masked_nodes)
+    return make_task_id(signature)
+
+
+def build_visible_page_queue(nodes: list[dict[str, str]], roster: list[dict[str, str]]) -> list[dict[str, str]]:
+    masked_nodes = visible_masked_name_nodes(nodes)
+    buttons = visible_open_buttons(nodes)
+    id_nodes = visible_id_mask_nodes(nodes)
+    page_id = page_id_for_names(masked_nodes)
+    skip_names = progress_names({"completed", "no_ticket"})
+    in_progress_names = progress_names({"in_progress"})
+    rows: list[dict[str, str]] = []
+    now = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+
+    for masked_name, masked_node in masked_nodes:
+        masked_y = node_center_y(masked_node)
+        id_first, id_last = id_mask_for(masked_y, id_nodes)
+        if masked_name in skip_names:
+            match_status = "skip_progress"
+            real_name = ""
+            id8 = ""
+            queue_status = "skipped"
+        else:
+            matches = match_roster(masked_name, roster, id_first, id_last)
+            if not matches and (id_first or id_last):
+                matches = match_roster(masked_name, roster)
+            if len(matches) == 1:
+                match_status = "matched"
+                real_name = matches[0].get("姓名", "")
+                id8 = matches[0].get("身份证后8位", "")
+                queue_status = "pending"
+            elif len(matches) > 1:
+                match_status = "ambiguous"
+                real_name = ""
+                id8 = ""
+                queue_status = "skipped"
+            else:
+                match_status = "no_match"
+                real_name = ""
+                id8 = ""
+                queue_status = "skipped"
+
+        candidate_buttons = [button for button in buttons if abs(node_center_y(button) - masked_y) < 120]
+        button_bounds = candidate_buttons[0].get("bounds", "") if candidate_buttons else ""
+        if queue_status == "pending" and not button_bounds:
+            queue_status = "skipped"
+            match_status = "no_button"
+        if masked_name in in_progress_names and queue_status == "pending":
+            match_status = "resume_in_progress"
+
+        rows.append(
+            {
+                "page_id": page_id,
+                "masked_name": masked_name,
+                "id_first": id_first,
+                "id_last": id_last,
+                "real_name": real_name,
+                "id_last8": id8,
+                "button_bounds": button_bounds,
+                "match_status": match_status,
+                "queue_status": queue_status,
+                "attempts": "0",
+                "updated_at": now,
+            }
+        )
+    return rows
+
+
+def android_build_page_queue(args: argparse.Namespace) -> None:
+    nodes = adb_dump_nodes()
+    page_text = "\n".join(adb_visible_texts(nodes))
+    if "扫码开票单" not in page_text:
+        raise RuntimeError("当前不在扫码开票单列表页，不能生成一页队列")
+    rows = build_visible_page_queue(nodes, read_roster(project_path(args.roster)))
+    write_page_queue(rows)
+    pending = [row for row in rows if row.get("queue_status") == "pending"]
+    print(f"page_queue={PAGE_QUEUE_CSV}")
+    print(f"rows={len(rows)} pending={len(pending)}")
+    for row in rows:
+        print(f"{row['queue_status']} {row['masked_name']} {row['real_name']} {row['id_last8']} {row['match_status']} {row['button_bounds']}")
+
+
+def android_page_next(args: argparse.Namespace) -> None:
+    run_adb(["shell", "input", "swipe", str(args.x), str(args.start_y), str(args.x), str(args.end_y), str(args.duration_ms)])
+    time.sleep(args.after)
+    if args.rebuild:
+        android_build_page_queue(argparse.Namespace(roster=args.roster))
+
+
+def call_vision_subcommand(sub_args: list[str]) -> dict:
+    """以子进程调用 vision_fallback.py,返回它打印的 JSON。"""
+    vision_script = PROJECT_ROOT / "scripts" / "vision_fallback.py"
+    cmd = ["python3", str(vision_script), *sub_args]
+    result = subprocess.run(cmd, cwd=PROJECT_ROOT, capture_output=True, text=True, check=False)
+    if result.returncode != 0:
+        raise RuntimeError(f"vision_fallback failed rc={result.returncode}: {result.stderr.strip()[:500]}")
+    try:
+        return json.loads(result.stdout)
+    except json.JSONDecodeError as exc:
+        raise RuntimeError(f"vision_fallback 输出非 JSON: {exc} body={result.stdout[:500]}")
+
+
+def vision_detect_list_page() -> tuple[bool, str]:
+    """调豆包/Qwen 判断当前页是不是扫码开票单列表页。返回 (is_list, summary)。"""
+    out = call_vision_subcommand(["detect-page"])
+    content = out.get("content", "")
+    try:
+        parsed = json.loads(content)
+    except Exception:
+        return False, content[:200]
+    return parsed.get("page") == "list", parsed.get("summary", "")
+
+
+def vision_list_rows() -> dict:
+    """截屏 + 视觉识别列表页所有可见乘客行,返回 parsed dict(已反归一到绝对像素)。
+
+    返回字典:
+      - rows: [{masked_name, id_first, id_last, button_bbox:[x1,y1,x2,y2], tap_point:[x,y]}, ...]
+      - scroll_position: 'top'|'middle'|'bottom'
+      - page_ok: bool
+    """
+    out = call_vision_subcommand(["list-rows"])
+    parsed = out.get("parsed")
+    if not parsed:
+        raise RuntimeError(f"vision_list_rows 解析失败: {out.get('parse_error') or out.get('content', '')[:300]}")
+    return parsed
+
+
+def _xml_or_vision_click(nodes: list[dict], text: str, label: str, *, clickable: bool | None = None, contains: bool = False) -> bool:
+    """先 XML 找按钮点击,找不到则视觉 fallback。返回 True=已点击, False=都找不到。"""
+    matches = find_android_nodes(nodes, text, clickable=clickable, contains=contains)
+    visible = [n for n in matches if n.get("bounds", "[0,0][0,0]") != "[0,0][0,0]"]
+    if visible:
+        click_node(visible[0], label)
+        return True
+    # 视觉 fallback
+    print(f"XML 未找到「{text}」按钮,视觉 fallback...")
+    pt = _vision_find_button(text)
+    if pt:
+        run_adb(["shell", "input", "tap", str(pt[0]), str(pt[1])])
+        print(f"vision_click {label} at {pt}")
+        return True
+    return False
+
+
+def _vision_find_button(text: str) -> tuple[int, int] | None:
+    """截屏 + 视觉 API 找按钮坐标,返回像素 (x, y) 或 None。XML 找不到时用。"""
+    screenshot_path = PROJECT_ROOT / "work" / "_vision_find_tmp.png"
+    _adb_screenshot(screenshot_path)
+    width, height = _screenshot_size(screenshot_path)
+
+    out = call_vision_subcommand([
+        "ping",
+        "--image", str(screenshot_path),
+        "--prompt",
+        f"找到屏幕上文字为「{text}」的可点击按钮。"
+        f"用 0-1000 归一化坐标(不是像素)返回按钮中心点。"
+        f"只返回一个 JSON 对象(不要 markdown 代码块):"
+        f'{{{{"found": true/false, "x": 0-1000归一化x(整数), "y": 0-1000归一化y(整数)}}}}'
+        f"如果找到多个,返回第一个(最靠上的)。找不到就 found:false。",
+    ])
+    content = out.get("content", "")
+    try:
+        parsed = json.loads(content)
+    except Exception:
+        import re as _re
+        m = _re.search(r'\{[^}]+\}', content)
+        if m:
+            try:
+                parsed = json.loads(m.group())
+            except Exception:
+                return None
+        else:
+            return None
+    if parsed.get("found") and parsed.get("x") is not None and parsed.get("y") is not None:
+        # denormalize: 0-1000 → pixel
+        px = int(int(parsed["x"]) * width / 1000)
+        py = int(int(parsed["y"]) * height / 1000)
+        return px, py
+    return None
+
+
+def _adb_screenshot(path: Path) -> None:
+    """adb 截屏到指定路径。"""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    result = subprocess.run(
+        ["/opt/homebrew/share/android-commandlinetools/platform-tools/adb", "exec-out", "screencap", "-p"],
+        capture_output=True, check=False,
+    )
+    if result.returncode != 0:
+        raise RuntimeError(f"adb screencap 失败: {result.stderr.decode('utf-8', 'ignore')}")
+    path.write_bytes(result.stdout)
+
+
+def _screenshot_size(image_path: Path) -> tuple[int, int]:
+    """读 PNG 头获取宽高,避免额外依赖。"""
+    data = image_path.read_bytes()
+    if len(data) >= 24 and data[:8] == b"\x89PNG\r\n\x1a\n":
+        width = int.from_bytes(data[16:20], "big")
+        height = int.from_bytes(data[20:24], "big")
+        return width, height
+    return 1260, 2800  # fallback
+
+
+def _adb_download_candidates() -> list[dict[str, str]]:
+    result = run_adb(["shell", "find", "/sdcard/Download", "-maxdepth", "2", "-type", "f", "\\(", "-iname", "*.pdf", "-o", "-iname", "*.ofd", "-o", "-iname", "*.xml", "\\)", "-printf", "%T@|%p\n"], check=False)
+    if result.returncode != 0:
+        result = run_adb(["shell", "find", "/sdcard/Download", "-type", "f"], check=False)
+    rows: list[dict[str, str]] = []
+    for line in result.stdout.splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        if "|" in line:
+            mtime, path = line.split("|", 1)
+        else:
+            mtime, path = "0", line
+        lower = path.lower()
+        if lower.endswith((".pdf", ".ofd", ".xml")):
+            rows.append({"mtime": mtime, "path": path})
+    return rows
+
+
+def pull_latest_invoice_file(output_dir: str | Path, before_paths: set[str], row_label: str) -> Path | None:
+    output_path = project_path(output_dir)
+    output_path.mkdir(parents=True, exist_ok=True)
+    deadline = time.time() + 20
+    latest: dict[str, str] | None = None
+    while time.time() < deadline:
+        candidates = [item for item in _adb_download_candidates() if item["path"] not in before_paths]
+        if candidates:
+            latest = max(candidates, key=lambda item: float(item.get("mtime") or 0))
+            break
+        time.sleep(1)
+    if not latest:
+        print("download_pull_skip reason=no_new_file")
+        return None
+
+    remote_path = latest["path"]
+    suffix = Path(remote_path).suffix or ".pdf"
+    safe_label = re.sub(r"[^\w\u4e00-\u9fff*-]+", "_", row_label).strip("_") or "invoice"
+    local_path = output_path / f"{datetime.now().strftime('%Y%m%d_%H%M%S')}_{safe_label}{suffix}"
+    result = run_adb(["pull", remote_path, str(local_path)], check=False)
+    if result.returncode != 0:
+        raise RuntimeError(f"下载文件拉取失败: {result.stderr.strip() or result.stdout.strip()}")
+    print(f"download_pulled remote={remote_path} local={local_path}")
+    return local_path
+
+
+def click_invoice_download(args: argparse.Namespace, nodes: list[dict], row_label: str) -> Path:
+    before_paths = {item["path"] for item in _adb_download_candidates()}
+    if not _xml_or_vision_click(nodes, "发票预览/下载", "invoice_preview_download"):
+        raise RuntimeError("成功页未找到发票预览/下载按钮")
+    time.sleep(getattr(args, "download_wait", 5))
+    after_nodes = adb_dump_nodes()
+    after_text = "\n".join(adb_visible_texts(after_nodes))
+    if "下载" in after_text:
+        _xml_or_vision_click(after_nodes, "下载", "invoice_download", contains=True)
+        time.sleep(getattr(args, "download_wait", 5))
+    local_path = pull_latest_invoice_file(getattr(args, "invoice_output_dir", "output/invoices"), before_paths, row_label)
+    if not local_path:
+        raise RuntimeError("点击发票预览/下载后未发现新的 PDF/OFD/XML 文件")
+    for _ in range(8):
+        nodes = adb_dump_nodes()
+        page_text = "\n".join(adb_visible_texts(nodes))
+        if "发票下载" in page_text and "下载进度" in page_text and "确定" in page_text:
+            if _xml_or_vision_click(nodes, "确定", "download_done_ok", clickable=True):
+                time.sleep(1.0)
+            break
+        if "发票预览" in page_text or "发票开具成功" in page_text:
+            break
+        time.sleep(0.5)
+    return local_path
+
+
+def save_qr_url(url: str) -> None:
+    """保存解码后的 QR URL,供自动重进使用。"""
+    LAST_QR_URL.parent.mkdir(parents=True, exist_ok=True)
+    LAST_QR_URL.write_text(url.strip(), encoding="utf-8")
+    print(f"qr_url_saved: {url[:80]}...")
+
+
+def reopen_qr_url() -> bool:
+    """用 ADB intent 在手机上重新打开上次解码的 QR URL。返回 True=成功。"""
+    if not LAST_QR_URL.exists():
+        print("reopen_qr: no saved URL")
+        return False
+    url = LAST_QR_URL.read_text(encoding="utf-8").strip()
+    if not url:
+        return False
+    print(f"reopen_qr: {url[:80]}...")
+    result = subprocess.run(
+        [ADB_PATH, "shell", "am", "start", "-a", "android.intent.action.VIEW", "-d", url],
+        capture_output=True, text=True, check=False,
+    )
+    ok = result.returncode == 0 and "Error" not in result.stdout
+    print(f"reopen_qr rc={result.returncode} ok={ok}")
+    return ok
+
+
+def auto_scan_qr_to_list() -> bool:
+    """自动回到扫码开票单列表页。三级路径:
+    1. 已经在列表 → 直接返回
+    2. 页面上有"扫码开票"按钮(说明页) → 点击进入扫码
+    3. 都没有 → 从主页导航: 订单 → 电子发票 → 扫码开票
+    然后: 相册 → 选QR缩略图 → 验证进入列表
+    返回 True=成功进入列表页。
+    """
+    if is_on_list_page():
+        print("auto_scan: already on list page")
+        return True
+
+    # 确保手机相册里是最新一次粘贴/保存的 QR；不能只判断本地文件是否存在。
+    if not generate_and_push_qr():
+        print("auto_scan: 无法生成QR图片")
+        return False
+
+    # Step 1: 到达扫码界面(三种路径)
+    pt_scan = _vision_find_button("扫码开票")
+    if pt_scan:
+        print(f"auto_scan: 找到扫码开票按钮 → 点击 {pt_scan}")
+        run_adb(["shell", "input", "tap", str(pt_scan[0]), str(pt_scan[1])])
+        time.sleep(2)
+    else:
+        # 从主页/其他页面导航: 订单 → 电子发票 → 扫码开票
+        print("auto_scan: 未找到扫码按钮,尝试 订单→电子发票→扫码...")
+        pt_order = _vision_find_button("订单")
+        if not pt_order:
+            print("auto_scan: 未找到「订单」按钮,放弃")
+            return False
+        print(f"auto_scan: 点击「订单」 {pt_order}")
+        run_adb(["shell", "input", "tap", str(pt_order[0]), str(pt_order[1])])
+        time.sleep(2)
+
+        pt_fapiao = _vision_find_button("电子发票")
+        if not pt_fapiao:
+            print("auto_scan: 未找到「电子发票」入口,放弃")
+            return False
+        print(f"auto_scan: 点击「电子发票」 {pt_fapiao}")
+        run_adb(["shell", "input", "tap", str(pt_fapiao[0]), str(pt_fapiao[1])])
+        time.sleep(2)
+
+        pt_scan2 = _vision_find_button("扫码开票")
+        if not pt_scan2:
+            print("auto_scan: 说明页未找到扫码开票按钮,放弃")
+            return False
+        print(f"auto_scan: 点击「扫码开票」 {pt_scan2}")
+        run_adb(["shell", "input", "tap", str(pt_scan2[0]), str(pt_scan2[1])])
+        time.sleep(2)
+
+    # Step 2: 在扫码界面点击"相册"
+    nodes = adb_dump_nodes()
+    page_text = "\n".join(adb_visible_texts(nodes))
+    if "相册" not in page_text:
+        print("auto_scan: 未进入扫码界面")
+        return False
+    album_btn = find_android_node(nodes, "相册")
+    if not album_btn:
+        print("auto_scan: 未找到相册按钮")
+        return False
+    click_node(album_btn, "open_album")
+    time.sleep(2)
+
+    # Step 3: 在相册中找 QR 码缩略图(纯视觉)
+    print("auto_scan: 在相册找QR码...")
+    pt_qr = _latest_gallery_image_point()
+    if pt_qr:
+        print(f"auto_scan: 选择相册最新图片 {pt_qr}")
+    else:
+        pt_qr = _vision_find_qr_thumbnail()
+    if not pt_qr:
+        print("auto_scan: 未找到QR缩略图,回退")
+        run_adb(["shell", "input", "keyevent", "4"])
+        return False
+    run_adb(["shell", "input", "tap", str(pt_qr[0]), str(pt_qr[1])])
+    time.sleep(3)
+
+    # Step 4: 验证进入列表页
+    for _ in range(3):
+        if is_on_list_page():
+            print("auto_scan: ✅ 成功进入列表页")
+            return True
+        nodes = adb_dump_nodes()
+        page_text = "\n".join(adb_visible_texts(nodes))
+        if "身份核验" in page_text and "证件号码的后8位" in page_text:
+            match = re.search(r"请输入购票\(代办\)人\s*([\u4e00-\u9fff][*＊][\u4e00-\u9fff]{0,3})\s*证件号码的后8位", page_text)
+            masked_name = match.group(1).replace("＊", "*") if match else "未识别"
+            print(f"auto_scan: 停在代办人身份核验页,需要 {masked_name} 的证件后8位")
+            return False
+        time.sleep(2)
+    print("auto_scan: 未能进入列表页")
+    return False
+
+
+def _vision_find_qr_thumbnail() -> tuple[int, int] | None:
+    """在相册选择器中找到黑白QR码缩略图(纯视觉,不依赖文字)。"""
+    screenshot_path = PROJECT_ROOT / "work" / "_vision_album_tmp.png"
+    _adb_screenshot(screenshot_path)
+    width, height = _screenshot_size(screenshot_path)
+    out = call_vision_subcommand([
+        "ping",
+        "--image", str(screenshot_path),
+        "--prompt",
+        "这是手机相册选择界面。屏幕上有若干图片缩略图,"
+        "其中有一张是黑白QR二维码图片(纯黑白方块,不是照片)。"
+        "找到这张QR码缩略图的中心,用0-1000归一化坐标返回。"
+        '只返回JSON: {"found":true,"x":500,"y":300} 找不到就found:false。',
+    ])
+    content = out.get("content", "")
+    try:
+        parsed = json.loads(content)
+    except Exception:
+        import re as _re
+        m = _re.search(r'\{[^{}]*"found"[^{}]*\}', content)
+        if m:
+            try:
+                parsed = json.loads(m.group())
+            except Exception:
+                return None
+        else:
+            return None
+    if parsed.get("found") and parsed.get("x") is not None:
+        px = int(int(parsed["x"]) * width / 1000)
+        py = int(int(parsed["y"]) * height / 1000)
+        return px, py
+    return None
+
+
+def _latest_gallery_image_point() -> tuple[int, int] | None:
+    """系统相册选择器中优先选最新图片(通常就是刚推送的 QR)。"""
+    nodes = adb_dump_nodes()
+    candidates: list[tuple[int, dict[str, str]]] = []
+    for node in nodes:
+        desc = node.get("content-desc", "") or ""
+        match = re.search(r"图片(\d+)", desc)
+        if not match:
+            continue
+        point = parse_bounds(node.get("bounds", ""))
+        if not point:
+            continue
+        candidates.append((int(match.group(1)), node))
+    if not candidates:
+        return None
+    candidates.sort(key=lambda item: item[0])
+    return parse_bounds(candidates[0][1].get("bounds", ""))
+
+
+def generate_and_push_qr() -> bool:
+    """从保存的 QR URL 生成二维码图片并推送到手机相册。返回 True=成功。"""
+    if not LAST_QR_URL.exists():
+        print("gen_qr: no saved URL")
+        return False
+    url = LAST_QR_URL.read_text(encoding="utf-8").strip()
+    if not url:
+        return False
+    try:
+        import qrcode
+    except ImportError:
+        print("gen_qr: qrcode 库未安装, pip3 install qrcode --break-system-packages")
+        return False
+
+    qr_path = PROJECT_ROOT / "work" / "qr_code.png"
+    img = qrcode.make(url)
+    img.save(str(qr_path))
+    print(f"gen_qr: saved {qr_path} ({qr_path.stat().st_size} bytes)")
+
+    # 推送到手机 DCIM/Camera
+    result = subprocess.run(
+        [ADB_PATH, "push", str(qr_path), "/sdcard/DCIM/Camera/qr_code.png"],
+        capture_output=True, text=True, check=False,
+    )
+    if result.returncode != 0:
+        print(f"gen_qr: push failed: {result.stderr}")
+        return False
+    # 触发媒体扫描
+    subprocess.run(
+        [ADB_PATH, "shell", "am", "broadcast", "-a", "android.intent.action.MEDIA_SCANNER_SCAN_FILE",
+         "-d", "file:///sdcard/DCIM/Camera/qr_code.png"],
+        capture_output=True, check=False,
+    )
+    time.sleep(1)
+    print("gen_qr: pushed to phone gallery ✓")
+    return True
+
+
+def android_swipe_up(args: argparse.Namespace) -> None:
+    """单纯上滑,不重建队列(给视觉路径用)。"""
+    run_adb([
+        "shell", "input", "swipe",
+        str(args.swipe_x), str(args.swipe_start_y),
+        str(args.swipe_x), str(args.swipe_end_y),
+        str(args.swipe_duration_ms),
+    ])
+    time.sleep(args.after_swipe)
+
+
+def is_on_list_page() -> bool:
+    """dump XML 判断当前是不是扫码开票单列表页(无任何子流程标记)。"""
+    nodes = adb_dump_nodes()
+    page_text = "\n".join(adb_visible_texts(nodes))
+    non_list_terms = [
+        "请输入乘车人", "证件号码后8位", "发票管理", "发票信息",
+        "发票信息确认", "发票开具成功", "邮箱地址确认", "邮件发送完成",
+    ]
+    # 排除法条说明页(包含"业务须知"但无实际乘客列表)
+    not_list_terms = [
+        "业务须知", "国家税务总局", "公告",
+        "铁路旅客运输领域推广", "铁路运输企业对通过铁路",
+    ]
+    return (
+        "扫码开票单" in page_text
+        and "开票流水号" in page_text
+        and "开具" in page_text
+        and not any(t in page_text for t in non_list_terms)
+        and not any(t in page_text for t in not_list_terms)
+    )
+
+
+def is_on_instructions_page() -> bool:
+    """探测当前是不是 12306 电子发票说明页(法条说明页)。"""
+    nodes = adb_dump_nodes()
+    page_text = "\n".join(adb_visible_texts(nodes))
+    return "业务须知" in page_text and "国家税务总局" in page_text
+
+
+def is_on_12306_home() -> bool:
+    """探测当前是不是 12306 首页(火车票/查询车票),用来阻止 back 退过头。"""
+    nodes = adb_dump_nodes()
+    page_text = "\n".join(adb_visible_texts(nodes))
+    return (
+        "扫码开票单" not in page_text
+        and ("查询车票" in page_text or ("火车票" in page_text and "飞机票" in page_text))
+    )
+
+
+def safe_back_until_list(max_back: int = 2) -> bool:
+    """逐次按 back,每次后等 UI 再检查;回列表了就停,退过头到首页/说明页就立刻停。
+
+    max_back 默认 2:核验弹窗 1 次 back 即关,no_ticket 页 1 次 back 即回,
+    给一次容错。多了反而会把列表页本身退掉。
+    """
+    for i in range(max_back + 1):
+        if is_on_list_page():
+            return True
+        if is_on_12306_home():
+            print(f"safe_back_aborted reason=on_12306_home back_count={i}")
+            return False
+        if is_on_instructions_page():
+            print(f"safe_back_stopped reason=on_instructions_page back_count={i}")
+            return False  # 停在说明页,由调用方触发 auto_scan
+        if i >= max_back:
+            break
+        run_adb(["shell", "input", "keyevent", "4"])
+        time.sleep(2.0)  # H5 页面加载慢,等久一点
+    return is_on_list_page()
+
+
+def drive_invoice_subflow(args: argparse.Namespace, row_label: str) -> str:
+    """tap"开具"后,反复调 android_invoice_step 直到回到列表页或达上限。
+
+    返回:
+      - "back_to_list":检测到 page_text 重新出现"扫码开票单"且不在子流程页
+      - "max_steps":达到 sub_max_steps 还没回列表
+      - "error":连续 step_error >= 2,已经按 back 兜底回到列表(或最大尝试次数耗尽)
+    """
+    consecutive_errors = 0
+    for step in range(1, args.sub_max_steps + 1):
+        if is_on_list_page():
+            print(f"sub_back_to_list row={row_label} steps={step - 1}")
+            return "back_to_list"
+        try:
+            android_invoice_step(args)
+            consecutive_errors = 0
+        except RuntimeError as exc:
+            print(f"sub_step_error row={row_label} step={step}: {exc}")
+            mark_clicked_as_runtime_error()
+            consecutive_errors += 1
+            if consecutive_errors >= 2:
+                recovered = safe_back_until_list(max_back=4)
+                if not recovered:
+                    # 可能在法条说明页,尝试自动扫码回到列表
+                    if is_on_instructions_page():
+                        print(f"sub_recover via auto_scan row={row_label}")
+                        if auto_scan_qr_to_list():
+                            recovered = True
+                print(f"sub_abort row={row_label} consecutive_errors=2 recovered_to_list={recovered}")
+                return "error"
+        time.sleep(args.between_steps)
+    print(f"sub_max_steps row={row_label} steps={args.sub_max_steps}")
+    return "max_steps"
+
+
+def android_vision_page_run(args: argparse.Namespace) -> None:
+    """视觉驱动的批量开票循环。
+
+    流程:
+      1. 视觉自检 page=list
+      2. 循环:
+         - 截图+视觉识别当前页所有可见乘客行
+         - 用 prev_anchor 去掉上一批已处理的重叠行
+         - 没新行 + scroll=bottom -> 退出;没新行非 bottom -> 滑一页继续
+         - 匹配 roster + 进度,过滤 completed / no_match
+         - 对每行 pending:tap button center -> drive sub-flow until back to list
+         - prev_anchor = 本批最后一行 masked_name
+         - 滑动一页
+    """
+    apply_speed_defaults(args)
+
+    if args.precheck:
+        is_list, summary = vision_detect_list_page()
+        if not is_list:
+            print(f"PREECHECK: 不在扫码开票单列表页 (summary={summary}),尝试自动扫码...")
+            if not (PROJECT_ROOT / "work" / "qr_code.png").exists():
+                generate_and_push_qr()
+            if auto_scan_qr_to_list():
+                print(f"precheck_ok 自动扫码进入列表页")
+            else:
+                print(f"PREECHECK_FAILED 自动扫码失败,请手动扫码进入列表")
+                return  # 优雅退出,不抛异常
+        else:
+            print(f"precheck_ok summary={summary}")
+
+    prev_anchor: str | None = None
+    anchor_history: list[str] = []
+    batch_no = 0
+    total_tapped = 0
+    total_skipped = 0
+
+    while batch_no < args.max_batches:
+        batch_no += 1
+        print(f"=== batch={batch_no} prev_anchor={prev_anchor} ===")
+
+        parsed = vision_list_rows()
+        if not parsed.get("page_ok"):
+            raise RuntimeError(f"视觉判定当前非列表页,batch={batch_no} 终止")
+        rows: list[dict] = parsed.get("rows") or []
+        scroll_pos = parsed.get("scroll_position", "middle")
+        print(f"vision_rows={len(rows)} scroll={scroll_pos} names={[r['masked_name'] for r in rows]}")
+
+        new_rows = rows
+        if prev_anchor:
+            anchor_idx = None
+            for idx, r in enumerate(rows):
+                if r.get("masked_name") == prev_anchor:
+                    anchor_idx = idx
+                    break
+            if anchor_idx is None:
+                print(f"warn: anchor '{prev_anchor}' 在新页未找到,可能滑过头;按整页新行处理")
+            else:
+                new_rows = rows[anchor_idx + 1:]
+                print(f"dedup_after_anchor anchor='{prev_anchor}' kept={len(new_rows)}")
+
+        if not new_rows:
+            if scroll_pos == "bottom":
+                print(f"done reason=bottom_and_empty_batch")
+                break
+            print(f"empty_batch swipe_again scroll={scroll_pos}")
+            android_swipe_up(args)
+            continue
+
+        roster = read_roster(project_path(args.roster))
+        skip_names = progress_names({"completed", "no_ticket", "failed"})
+        actions = []
+        queue_rows = []
+        batch_page_id = f"vision_b{batch_no}_{int(time.time())}"
+        now_str = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+        for row in new_rows:
+            masked = row.get("masked_name", "")
+            id_first = row.get("id_first", "") or ""
+            id_last = row.get("id_last", "") or ""
+            bbox = row.get("button_bbox") or []
+            button_bounds = f"[{bbox[0]},{bbox[1]}][{bbox[2]},{bbox[3]}]" if len(bbox) == 4 else ""
+
+            entry = {
+                "page_id": batch_page_id,
+                "masked_name": masked,
+                "id_first": id_first,
+                "id_last": id_last,
+                "real_name": "",
+                "id_last8": "",
+                "button_bounds": button_bounds,
+                "match_status": "",
+                "queue_status": "",
+                "attempts": "0",
+                "updated_at": now_str,
+            }
+            queue_rows.append(entry)
+
+            if masked in skip_names:
+                entry["match_status"] = "skip_progress"
+                entry["queue_status"] = "skipped"
+                print(f"skip {masked} reason=progress_done")
+                total_skipped += 1
+                continue
+
+            matches = match_roster(masked, roster, id_first, id_last)
+            if not matches and (id_first or id_last):
+                matches = match_roster(masked, roster)
+
+            if len(matches) == 1:
+                matched_person = matches[0]
+                entry["real_name"] = matched_person.get("姓名", "")
+                entry["id_last8"] = matched_person.get("身份证后8位", "")
+                entry["match_status"] = "matched"
+                entry["queue_status"] = "pending"
+            else:
+                entry["match_status"] = "ambiguous" if len(matches) > 1 else "no_match"
+                entry["queue_status"] = "skipped"
+                print(f"skip {masked} reason=no_unique_match match_count={len(matches)}")
+                total_skipped += 1
+                continue
+
+            tap_point = row.get("tap_point") or [
+                (bbox[0] + bbox[2]) // 2,
+                (bbox[1] + bbox[3]) // 2,
+            ]
+            actions.append((row, matched_person, tap_point, 1, entry))
+
+        write_page_queue(queue_rows)
+        print(f"batch_to_tap={len(actions)} batch_skipped_so_far={total_skipped} page_queue_rows={len(queue_rows)}")
+
+        if args.dry_run:
+            for row, person, tap, mc, _entry in actions:
+                tag = f"matched={person.get('姓名')} id_last8={person.get('身份证后8位')}" if person else f"match_count={mc}"
+                print(f"DRY_RUN would_tap masked={row['masked_name']} {tag} tap={tap}")
+        else:
+            for row, person, tap, mc, entry in actions:
+                if args.max_actions and total_tapped >= args.max_actions:
+                    print(f"stop reason=max_actions_reached total_tapped={total_tapped}")
+                    return
+                masked = row["masked_name"]
+                real_name = person.get("姓名", "") if person else ""
+                id8 = person.get("身份证后8位", "") if person else ""
+                tag = f"matched={real_name} id_last8={id8}"
+                print(f"page_open={masked} {tag} tap={tap}")
+                update_progress(masked, real_name, id8, "in_progress")
+                entry["queue_status"] = "clicked"
+                entry["updated_at"] = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+                write_page_queue(queue_rows)
+                run_adb(["shell", "input", "tap", str(tap[0]), str(tap[1])])
+                wait_short(args, ["请输入乘车人", "证件号码后8位", "发票管理", "您没有可开具"])
+                result = drive_invoice_subflow(args, masked)
+                total_tapped += 1
+                if result != "back_to_list":
+                    if not is_on_list_page():
+                        print(f"ABORT row={masked} sub_result={result} 当前不在列表页,停止后续 tap 避免误操作。手动恢复后再跑。")
+                        return
+                    print(f"warn row={masked} sub_result={result} (但已回列表,继续)")
+                time.sleep(args.between_steps)
+
+        prev_anchor = rows[-1].get("masked_name") if rows else prev_anchor
+        anchor_history.append(prev_anchor or "")
+        if len(anchor_history) >= 3 and anchor_history[-1] == anchor_history[-2] == anchor_history[-3]:
+            print(f"safety: anchor '{prev_anchor}' 连续 3 批未变,视为到底")
+            break
+
+        if scroll_pos == "bottom":
+            print(f"done reason=bottom_after_processing")
+            break
+
+        android_swipe_up(args)
+
+    print(f"finished batches={batch_no} tapped={total_tapped} skipped={total_skipped}")
+
+
+def android_h5_page_run(args: argparse.Namespace) -> None:
+    """H5 扫码开票单页面视觉驱动批量开票。
+
+    与 android-vision-page-run 的区别:
+    - H5 单页内滚动(不是翻页),scroll 参数用 --h5-scroll-*
+    - back 后 scroll 重置到顶部,所以每轮重新截屏
+    - 当前屏所有 pending 处理完才滚动下一屏
+    - 不用 anchor 去重(back 重置后无重叠行)
+    """
+    config = load_config(CONFIG_LOCAL_PATH)
+    if not getattr(args, "invoice_success_action", ""):
+        args.invoice_success_action = config.invoice_success_action
+    if not getattr(args, "invoice_output_dir", ""):
+        args.invoice_output_dir = config.invoice_output_dir
+    apply_speed_defaults(args)
+
+    if args.precheck:
+        parsed = vision_list_rows()
+        if not parsed.get("page_ok"):
+            if is_on_list_page():
+                print(f"precheck_ok vision flag page_ok=False but XML says list;继续")
+            else:
+                print(f"PREECHECK: 不在 H5 开票单页,尝试自动扫码...")
+                # 确保 QR 图片在手机上
+                if not (PROJECT_ROOT / "work" / "qr_code.png").exists():
+                    generate_and_push_qr()
+                if auto_scan_qr_to_list():
+                    parsed = vision_list_rows()
+                    if parsed.get("page_ok"):
+                        print(f"precheck_ok 自动扫码成功进入列表页")
+                    else:
+                        print(f"PREECHECK_FAILED 扫码后仍未识别列表页,请手动确认")
+                        return
+                else:
+                    print(f"PREECHECK_FAILED 自动扫码失败,请手动扫码进入列表")
+                    return
+        rows = parsed.get("rows") or []
+        print(f"precheck_ok rows={len(rows)} scroll={parsed.get('scroll_position')}")
+
+    roster = read_roster(project_path(args.roster))
+    batch_no = 0
+    total_tapped = 0
+    total_skipped = 0
+    total_no_ticket = 0
+    total_completed = 0
+    resume_anchor = last_progress_anchor() if getattr(args, "resume_after_last_progress", True) else ""
+    resume_anchor_seen = not resume_anchor
+    if resume_anchor:
+        print(f"resume_anchor={resume_anchor}")
+
+    while batch_no < args.max_batches:
+        batch_no += 1
+
+        # 防熄屏:轻点屏幕唤醒
+        if not args.dry_run:
+            run_adb(["shell", "input", "tap", "630", "1400"], check=False)
+            time.sleep(0.3)
+
+        # 截屏 + 视觉识别
+        parsed = vision_list_rows()
+        if not parsed.get("page_ok"):
+            if is_on_list_page():
+                print(f"batch={batch_no} vision page_ok=False but XML says list;继续")
+            else:
+                # 可能屏幕熄了或页面跳转;再试一次
+                print(f"batch={batch_no} page_ok=False, retry after wake tap")
+                run_adb(["shell", "input", "keyevent", "224"], check=False)  # wake
+                time.sleep(1)
+                parsed = vision_list_rows()
+                if not parsed.get("page_ok") and not is_on_list_page():
+                    print(f"PAGE_AWAY batch={batch_no} 手机已离开 H5 开票单页面")
+                    # 尝试自动扫码恢复
+                    if auto_scan_qr_to_list():
+                        print(f"page_away_recovered via auto_scan")
+                        continue  # 回到 while 循环重新截屏
+                    print(f"当前进度: tapped={total_tapped} skipped={total_skipped} completed={total_completed} no_ticket={total_no_ticket}")
+                    print(f"进度已保存到 {PROGRESS_CSV},手机恢复后从 UI 重新启动即可续接")
+                    return  # 优雅退出
+
+        rows: list[dict] = parsed.get("rows") or []
+        scroll_pos = parsed.get("scroll_position", "middle")
+        print(f"\n=== batch={batch_no} rows={len(rows)} scroll={scroll_pos} tapped={total_tapped} ===")
+        for r in rows:
+            print(f"  {r['masked_name']} id={r.get('id_first','')}*{r.get('id_last','')}")
+
+        if not resume_anchor_seen:
+            visible_names = [row.get("masked_name", "") for row in rows]
+            if resume_anchor in visible_names:
+                resume_anchor_seen = True
+                print(f"  resume_anchor_seen={resume_anchor}; only process rows after it")
+            else:
+                if scroll_pos == "bottom":
+                    print(f"  resume_anchor_not_found={resume_anchor} at bottom; fallback process current view")
+                    resume_anchor_seen = True
+                else:
+                    print(f"  resume_seek anchor={resume_anchor} not in current view → 滚动下一屏")
+                    _h5_scroll_down(args)
+                    continue
+
+        # 找当前屏所有"在名单且未处理"的人；failed/error 默认在当前运行内重试一次。
+        current_names = {row.get("masked_name", "") for row in rows if row.get("masked_name")}
+        retry_names = retryable_failed_names(
+            current_names,
+            getattr(args, "retry_failed_once", 1),
+        )
+        if retry_names:
+            print(f"  retry_failed_once={sorted(retry_names)}")
+        skip_names = progress_names({"completed", "no_ticket", "failed", "error", "in_progress"}) - retry_names
+        actions: list[tuple[dict, dict, list[int]]] = []  # (row, matched_person, tap_point)
+
+        process_rows = rows
+        if resume_anchor and resume_anchor_seen:
+            for index, row in enumerate(rows):
+                if row.get("masked_name") == resume_anchor:
+                    process_rows = rows[index + 1:]
+                    break
+
+        for row in process_rows:
+            masked = row.get("masked_name", "")
+            id_first = row.get("id_first", "") or ""
+            id_last = row.get("id_last", "") or ""
+            bbox = row.get("button_bbox") or []
+
+            if masked in skip_names:
+                continue
+
+            matches = match_roster(masked, roster, id_first, id_last)
+            if not matches and (id_first or id_last):
+                matches = match_roster(masked, roster)
+
+            if len(matches) == 1:
+                tap_point = row.get("tap_point") or [
+                    (bbox[0] + bbox[2]) // 2,
+                    (bbox[1] + bbox[3]) // 2,
+                ]
+                actions.append((row, matches[0], tap_point))
+            else:
+                reason = "no_match" if not matches else f"ambiguous({len(matches)})"
+                print(f"  skip {masked} reason={reason}")
+                total_skipped += 1
+
+        print(f"  pending_in_view={len(actions)} skipped_so_far={total_skipped}")
+
+        if not actions:
+            if scroll_pos == "bottom":
+                print(f"done reason=bottom_no_pending")
+                break
+            print(f"  → 滚动下一屏")
+            _h5_scroll_down(args)
+            continue
+
+        # 逐人处理当前屏的 pending
+        for idx, (row, person, tap_point) in enumerate(actions):
+            if args.max_actions and total_tapped >= args.max_actions:
+                print(f"stop reason=max_actions total_tapped={total_tapped}")
+                return
+
+            masked = row["masked_name"]
+            real_name = person.get("姓名", "")
+            id8 = person.get("身份证后8位", "")
+
+            if args.dry_run:
+                print(f"DRY_RUN would_tap {masked} → {real_name}({id8}) tap={tap_point}")
+                total_tapped += 1
+                if args.max_actions and total_tapped >= args.max_actions:
+                    print(f"stop reason=max_actions total_tapped={total_tapped}")
+                    return
+                continue
+
+            print(f"\n--- tap #{total_tapped+1} {masked} → {real_name}({id8}) ---")
+            if masked in retry_names:
+                mark_failed_retry_attempt(masked)
+                print(f"retry_failed_attempt {masked}")
+            update_progress(masked, real_name, id8, "in_progress")
+            run_adb(["shell", "input", "tap", str(tap_point[0]), str(tap_point[1])])
+            wait_short(args, ["请输入乘车人", "证件号码后8位", "发票管理", "您没有可开具"])
+
+            result = drive_invoice_subflow(args, masked)
+            total_tapped += 1
+
+            if result == "back_to_list":
+                # 检查子流程最终状态
+                progress = read_progress()
+                for p_row in progress:
+                    if p_row.get("masked_name") == masked and p_row.get("status") == "completed":
+                        total_completed += 1
+                    elif p_row.get("masked_name") == masked and p_row.get("status") == "no_ticket":
+                        total_no_ticket += 1
+            else:
+                recovered = safe_back_until_list(max_back=4)
+                if not recovered:
+                    # 可能在法条说明页,尝试自动扫码
+                    if is_on_instructions_page():
+                        print(f"recover via auto_scan row={masked}")
+                        if auto_scan_qr_to_list():
+                            recovered = True
+                if not recovered:
+                    print(f"STOP row={masked} sub_result={result} 无法回到列表页")
+                    print(f"进度已保存,手机恢复后从 UI 重新启动即可续接")
+                    return  # 优雅退出
+                print(f"recovered row={masked} sub_result={result} → back_to_list")
+
+            # back 后 scroll 重置到顶部,跳出 actions 循环重新截屏
+            if idx < len(actions) - 1:
+                print(f"  (back 重置 scroll,重新截屏找下一个)")
+            break
+
+        # dry-run 模式下当前屏全部看完后自动滚动
+        if args.dry_run and actions and scroll_pos != "bottom":
+            print(f"  → dry-run 滚动下一屏")
+            _h5_scroll_down(args)
+
+    print(f"\nfinished batches={batch_no} tapped={total_tapped} skipped={total_skipped} "
+          f"completed={total_completed} no_ticket={total_no_ticket}")
+
+
+def _h5_scroll_down(args: argparse.Namespace) -> None:
+    """H5 页面内向下滚动一屏。"""
+    run_adb([
+        "shell", "input", "swipe",
+        str(args.h5_scroll_x), str(args.h5_scroll_start_y),
+        str(args.h5_scroll_x), str(args.h5_scroll_end_y),
+        str(args.h5_scroll_duration_ms),
+    ])
+    time.sleep(args.h5_scroll_after)
+
+
+def android_page_top(args: argparse.Namespace) -> None:
+    last_fp: str | None = None
+    for i in range(1, args.max_iterations + 1):
+        nodes = adb_dump_nodes()
+        fp = "|".join(sorted(name for name, _ in visible_masked_name_nodes(nodes)))
+        if fp == last_fp:
+            print(f"at_top iterations={i}")
+            return
+        last_fp = fp
+        run_adb(["shell", "input", "swipe", str(args.x), str(args.start_y), str(args.x), str(args.end_y), str(args.duration_ms)])
+        time.sleep(args.after)
+    print(f"max_iterations_reached={args.max_iterations}")
+
+
+def android_page_step(args: argparse.Namespace) -> None:
+    apply_speed_defaults(args)
+    nodes = adb_dump_nodes()
+    page_text = "\n".join(adb_visible_texts(nodes))
+    non_list_terms = [
+        "请输入乘车人",
+        "证件号码后8位",
+        "发票管理",
+        "发票信息",
+        "发票信息确认",
+        "发票开具成功",
+        "邮箱地址确认",
+        "邮件发送完成",
+    ]
+    if "扫码开票单" not in page_text or any(term in page_text for term in non_list_terms):
+        android_invoice_step(args)
+        return
+
+    queue = read_page_queue()
+    visible = visible_masked_name_nodes(nodes)
+    current_fp = "|".join(sorted(name for name, _ in visible))
+    current_page_id = page_id_for_names(visible)
+    if not queue or queue[0].get("page_id") != current_page_id or args.rebuild:
+        queue = build_visible_page_queue(nodes, read_roster(project_path(args.roster)))
+        write_page_queue(queue)
+
+    pending = [row for row in queue if row.get("queue_status") == "pending"]
+    if not pending:
+        retry_rows = [
+            row for row in queue
+            if row.get("match_status") in RETRYABLE_FAILURES
+            and int(row.get("attempts") or 0) < 1
+        ]
+        if retry_rows:
+            roster = read_roster(project_path(args.roster))
+            now = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+            promoted = 0
+            for row in retry_rows:
+                matches = match_roster(row.get("masked_name", ""), roster, row.get("id_first", ""), row.get("id_last", ""))
+                if not matches and (row.get("id_first") or row.get("id_last")):
+                    matches = match_roster(row.get("masked_name", ""), roster)
+                if len(matches) == 1 and row.get("button_bounds"):
+                    row["real_name"] = matches[0].get("姓名", "")
+                    row["id_last8"] = matches[0].get("身份证后8位", "")
+                    row["match_status"] = "matched"
+                    row["queue_status"] = "pending"
+                    promoted += 1
+                row["attempts"] = str(int(row.get("attempts") or 0) + 1)
+                row["updated_at"] = now
+            write_page_queue(queue)
+            print(f"retry_round attempts=1 promoted={promoted} total_failed={len(retry_rows)}")
+            if promoted:
+                return
+        last_fp = getattr(args, "_last_done_fp", None)
+        swiped = getattr(args, "_swiped_after_last_done", False)
+        if last_fp == current_fp and swiped:
+            print("page_bottom_reached")
+            args._bottom_reached = True
+            return
+        print("page_done")
+        args._last_done_fp = current_fp
+        args._swiped_after_last_done = False
+        if args.auto_next:
+            android_page_next(argparse.Namespace(x=args.swipe_x, start_y=args.swipe_start_y, end_y=args.swipe_end_y, duration_ms=args.swipe_duration_ms, after=args.after_swipe, rebuild=True, roster=args.roster))
+            args._swiped_after_last_done = True
+        return
+
+    row = pending[0]
+    point = parse_bounds(row.get("button_bounds", ""))
+    if not point:
+        raise RuntimeError(f"队列行缺 button_bounds: {row}")
+    print(f"page_open={row['masked_name']} matched={row['real_name']} id_last8={row['id_last8']} bounds={row['button_bounds']}")
+    run_adb(["shell", "input", "tap", str(point[0]), str(point[1])])
+    for item in queue:
+        if item.get("masked_name") == row.get("masked_name") and item.get("button_bounds") == row.get("button_bounds"):
+            item["queue_status"] = "clicked"
+            item["updated_at"] = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+            break
+    write_page_queue(queue)
+    wait_short(args, ["请输入乘车人", "证件号码后8位"])
+
+
+def mark_clicked_as_runtime_error() -> None:
+    queue = read_page_queue()
+    if queue:
+        now = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+        changed = False
+        for row in queue:
+            if row.get("queue_status") == "clicked":
+                row["queue_status"] = "skipped"
+                row["match_status"] = "runtime_error"
+                row["updated_at"] = now
+                changed = True
+        if changed:
+            write_page_queue(queue)
+    progress = read_progress()
+    if progress:
+        now = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+        changed = False
+        for row in progress:
+            if row.get("status") == "in_progress":
+                row["status"] = "failed"
+                row["updated_at"] = now
+                changed = True
+        if changed:
+            write_progress(progress)
+
+
+def android_page_run(args: argparse.Namespace) -> None:
+    apply_speed_defaults(args)
+    consecutive_errors = 0
+    for index in range(1, args.steps + 1):
+        print(f"run_step={index}")
+        try:
+            android_page_step(args)
+            consecutive_errors = 0
+        except RuntimeError as exc:
+            print(f"step_error={exc}")
+            mark_clicked_as_runtime_error()
+            consecutive_errors += 1
+            if consecutive_errors >= 3:
+                print("abort_consecutive_errors=3")
+                raise
+            run_adb(["shell", "input", "keyevent", "4"])
+            time.sleep(1)
+            run_adb(["shell", "input", "keyevent", "4"])
+            time.sleep(1)
+        if getattr(args, "_bottom_reached", False):
+            print("stop_reason=bottom_reached")
+            break
+        time.sleep(args.between_steps)
+
+
+def android_invoice_step(args: argparse.Namespace) -> None:
+    config = load_config(CONFIG_LOCAL_PATH)
+    if not getattr(args, "invoice_success_action", ""):
+        args.invoice_success_action = config.invoice_success_action
+    if not getattr(args, "invoice_output_dir", ""):
+        args.invoice_output_dir = config.invoice_output_dir
+    apply_speed_defaults(args)
+    nodes = adb_dump_nodes()
+    texts = adb_visible_texts(nodes)
+    page_text = "\n".join(texts)
+    roster = read_roster(project_path(args.roster))
+
+    if "发票下载" in page_text and "下载进度" in page_text and "确定" in page_text:
+        if not _xml_or_vision_click(nodes, "确定", "download_done_ok", clickable=True):
+            raise RuntimeError("下载完成提示存在，但未找到确定按钮")
+        return
+
+    if "发票预览" in page_text and "下载发票" in page_text:
+        run_adb(["shell", "input", "keyevent", "4"])
+        time.sleep(1.5)
+        return
+
+    if "邮件发送完成，请注意查收。" in page_text:
+        in_progress = [row for row in read_progress() if row.get("status") == "in_progress"]
+        if in_progress:
+            row = in_progress[-1]
+            update_progress(row.get("masked_name", ""), row.get("real_name", ""), row.get("id_last8", ""), "completed")
+        if not _xml_or_vision_click(nodes, "确定", "mail_done_ok"):
+            raise RuntimeError("邮件完成提示存在，但未找到确定按钮(XML+视觉均失败)")
+        return
+
+    if "邮箱地址确认" in page_text:
+        if not _xml_or_vision_click(nodes, "确认", "email_confirm", clickable=True):
+            raise RuntimeError("邮箱确认页未找到确认按钮")
+        wait_short(args, ["邮件发送完成", "发票开具成功"])
+        return
+
+    if "发票信息确认" in page_text:
+        if not _xml_or_vision_click(nodes, "确认", "invoice_info_confirm", clickable=True):
+            raise RuntimeError("发票信息确认页未找到确认按钮")
+        wait_long(args, ["发票开具成功"])
+        return
+
+    if "发票开具中" in page_text or "发票正在开具中" in page_text:
+        print("invoice_opening_wait")
+        wait_and_probe(1, getattr(args, "wait_secondary", 10), ["发票开具成功", "邮件发送完成", "发票管理"])
+        return
+
+    if "发票开具成功" in page_text:
+        in_progress = [row for row in read_progress() if row.get("status") == "in_progress"]
+        current_row = in_progress[-1] if in_progress else {}
+        masked_label = current_row.get("masked_name", "invoice") or "invoice"
+        real_label = current_row.get("real_name", "") or ""
+        row_label = f"{real_label}_{masked_label}" if real_label else masked_label
+        success_action = getattr(args, "invoice_success_action", "") or ("email" if getattr(args, "send_email", False) else "download")
+        if getattr(args, "send_email", False):
+            success_action = "email"
+
+        if success_action == "email" and in_progress and "邮件发送完成，请注意查收。" not in page_text:
+            row = current_row
+            update_progress(row.get("masked_name", ""), row.get("real_name", ""), row.get("id_last8", ""), "completed")
+            if _xml_or_vision_click(nodes, "发送至邮箱", "send_email"):
+                wait_short(args, ["邮箱地址确认", "邮件发送完成"])
+                return
+        if success_action == "download" and in_progress:
+            local_path = click_invoice_download(args, nodes, row_label)
+            row = current_row
+            update_progress(row.get("masked_name", ""), row.get("real_name", ""), row.get("id_last8", ""), "completed")
+            print(f"invoice_saved row={row_label} path={local_path}")
+            for _ in range(2):
+                nodes = adb_dump_nodes()
+                page_text = "\n".join(adb_visible_texts(nodes))
+                if "发票开具成功" in page_text:
+                    break
+                run_adb(["shell", "input", "keyevent", "4"])
+                time.sleep(1.5)
+            nodes = adb_dump_nodes()
+        if success_action == "continue" and in_progress:
+            row = current_row
+            update_progress(row.get("masked_name", ""), row.get("real_name", ""), row.get("id_last8", ""), "completed")
+        if not _xml_or_vision_click(nodes, "继续开票", "continue_invoice"):
+            raise RuntimeError("成功页未找到继续开票按钮(XML+视觉均失败)")
+        return
+
+    if "请输入乘车人" in page_text and "证件号码后8位" in page_text:
+        match = re.search(r"请输入乘车人\s*([\u4e00-\u9fff][*＊][\u4e00-\u9fff]{0,3})\s*证件号码后8位", page_text)
+        if not match:
+            raise RuntimeError("核验弹窗存在，但未解析出脱敏姓名")
+        masked_name = match.group(1).replace("＊", "*")
+        in_progress = [row for row in read_progress() if row.get("status") == "in_progress" and row.get("masked_name") == masked_name]
+        if in_progress:
+            selected = in_progress[-1]
+            id8 = selected.get("id_last8", "")
+            real_name = selected.get("real_name", "")
+        else:
+            matches = match_roster(masked_name, roster)
+            if len(matches) != 1:
+                raise RuntimeError(f"{masked_name} 名单匹配数量={len(matches)}")
+            selected = matches[0]
+            id8 = selected["身份证后8位"]
+            real_name = selected.get("姓名", "")
+        edit_nodes = [node for node in nodes if node.get("class") == "android.widget.EditText"]
+        if not edit_nodes:
+            raise RuntimeError("未找到身份证后8位输入框")
+        click_node(edit_nodes[0], f"id8_input:{masked_name}")
+        time.sleep(0.3)
+        adb_input_text(id8)
+        update_progress(masked_name, real_name, id8, "in_progress")
+        if not _xml_or_vision_click(adb_dump_nodes(), "核验", "verify"):
+            raise RuntimeError("未找到核验按钮(XML+视觉均失败)")
+        wait_short(args, ["发票管理", "待开票", "发票信息"])
+        return
+
+    if "身份核验" in page_text and "证件号码的后8位" in page_text:
+        match = re.search(r"请输入购票\(代办\)人\s*([\u4e00-\u9fff][*＊][\u4e00-\u9fff]{0,3})\s*证件号码的后8位", page_text)
+        masked_name = match.group(1).replace("＊", "*") if match else ""
+        matches = match_roster(masked_name, roster) if masked_name else []
+        if len(matches) != 1:
+            raise RuntimeError(f"代办人身份核验缺少后8位: {masked_name or '未识别'} 名单匹配数量={len(matches)}")
+        edit_nodes = [node for node in nodes if node.get("class") == "android.widget.EditText"]
+        if not edit_nodes:
+            raise RuntimeError("代办人身份核验页未找到输入框")
+        click_node(edit_nodes[0], f"agent_id8_input:{masked_name}")
+        time.sleep(0.3)
+        adb_input_text(matches[0]["身份证后8位"])
+        if not _xml_or_vision_click(adb_dump_nodes(), "开始核验", "agent_verify"):
+            raise RuntimeError("代办人身份核验页未找到开始核验按钮")
+        wait_short(args, ["扫码开票单", "开票流水号"])
+        return
+
+    if "发票信息" in page_text and "提交" in page_text:
+        title_ok = "学知苑国际旅行社（北京）有限公司" in page_text
+        tax_ok = "91110102MA019MUJ3Q" in page_text
+        if not (title_ok and tax_ok):
+            raise RuntimeError("发票信息页未检测到默认抬头/税号，暂停，需手工确认")
+        if not _xml_or_vision_click(nodes, "提交", "submit_invoice_info"):
+            raise RuntimeError("未找到提交按钮(XML+视觉均失败)")
+        wait_short(args, ["发票信息确认"])
+        return
+
+    if "发票管理" in page_text and "您没有可开具电子发票的客票" in page_text:
+        in_progress = [row for row in read_progress() if row.get("status") == "in_progress"]
+        if in_progress:
+            row = in_progress[-1]
+            update_progress(row.get("masked_name", ""), row.get("real_name", ""), row.get("id_last8", ""), "no_ticket")
+        print("no_ticket_current_passenger")
+        run_adb(["shell", "input", "keyevent", "4"])
+        time.sleep(2)
+        return
+
+    if "发票管理" in page_text and "开具" in page_text:
+        open_nodes = find_android_nodes(nodes, "开具", clickable=True)
+        if not open_nodes:
+            # H5 页面按钮可能不标记 clickable,放宽条件重试
+            open_nodes = [n for n in find_android_nodes(nodes, "开具") if n.get("bounds", "[0,0][0,0]") != "[0,0][0,0]"]
+        if not open_nodes:
+            # 纯视觉 fallback:截屏让 Qwen 找"开具"按钮
+            print("发票管理页 XML 未找到开具按钮,尝试视觉 fallback")
+            pt = _vision_find_button("开具")
+            if pt:
+                run_adb(["shell", "input", "tap", str(pt[0]), str(pt[1])])
+                wait_short(args, ["发票信息"])
+                return
+            raise RuntimeError("发票管理页未找到单张开具按钮(XML+视觉均失败)")
+        # Avoid bottom batch button; choose first visible normal button.
+        node = sorted(open_nodes, key=node_center_y)[0]
+        click_node(node, "ticket_open")
+        wait_short(args, ["发票信息"])
+        return
+
+    if "扫码开票单" in page_text:
+        passenger = first_matched_visible_passenger(nodes, roster, progress_names({"completed", "in_progress", "no_ticket"}))
+        if not passenger:
+            raise RuntimeError("当前可见列表没有可唯一匹配名单的乘车人")
+        masked_name, row, button = passenger
+        print(f"passenger={masked_name} matched={row.get('姓名')} id_last8={row.get('身份证后8位')}")
+        click_node(button, f"list_open:{masked_name}")
+        wait_short(args, ["请输入乘车人", "证件号码后8位"])
+        return
+
+    if "com.bbk.launcher2" in page_text or "launcher" in page_text:
+        print(page_text)
+        raise RuntimeError("手机当前在桌面，请先打开 12306 App 并进入扫码开票单/发票页面")
+
+    print(page_text)
+    raise RuntimeError("未知页面状态，暂停操作")
+
+
+def android_dump(args: argparse.Namespace) -> None:
+    nodes = adb_dump_nodes()
+    for text in adb_visible_texts(nodes):
+        print(text)
+    if args.output:
+        output = project_path(args.output)
+        output.parent.mkdir(parents=True, exist_ok=True)
+        output.write_text("\n".join(adb_visible_texts(nodes)), encoding="utf-8")
+        print(f"output={output}")
+
+
+def android_type_id(args: argparse.Namespace) -> None:
+    nodes = adb_dump_nodes()
+    masked_names = extract_masked_names(adb_visible_texts(nodes))
+    if not masked_names:
+        raise RuntimeError("当前手机页面未识别到类似 张*岩 的脱敏姓名")
+    masked_name = args.masked_name or masked_names[0]
+    matches = match_roster(masked_name, read_roster(project_path(args.roster)))
+    if len(matches) != 1:
+        print(f"masked_name={masked_name}")
+        print(f"matches={len(matches)}")
+        for row in matches:
+            print(f"{row.get('姓名')} {row.get('身份证后8位')}")
+        raise SystemExit(2 if matches else 1)
+
+    id8 = matches[0]["身份证后8位"]
+    if args.click_text:
+        node = find_android_node(nodes, args.click_text, contains=args.contains)
+        if not node:
+            raise RuntimeError(f"未找到可点击控件: {args.click_text}")
+        adb_tap_bounds(node.get("bounds", ""))
+        time.sleep(0.4)
+    elif args.tap:
+        x, y = args.tap.split(",", 1)
+        run_adb(["shell", "input", "tap", x.strip(), y.strip()])
+        time.sleep(0.4)
+
+    adb_input_text(id8)
+    print(f"masked_name={masked_name}")
+    print(f"matched_name={matches[0].get('姓名')}")
+    print(f"id_last8={id8}")
+
+
+def android_run_flow(args: argparse.Namespace) -> None:
+    flow = json.loads(project_path(args.flow).read_text(encoding="utf-8"))
+    roster = read_roster(project_path(args.roster))
+    for index, step in enumerate(flow.get("steps", []), start=1):
+        action = step.get("action")
+        if action == "sleep":
+            time.sleep(float(step.get("seconds", 1)))
+        elif action == "tap":
+            run_adb(["shell", "input", "tap", str(step["x"]), str(step["y"])])
+        elif action in {"click_text", "click_contains"}:
+            nodes = adb_dump_nodes()
+            node = find_android_node(nodes, str(step["text"]), contains=action == "click_contains")
+            if not node:
+                raise RuntimeError(f"step {index}: 未找到控件 {step['text']}")
+            adb_tap_bounds(node.get("bounds", ""))
+        elif action == "input_text":
+            adb_input_text(str(step["text"]))
+        elif action == "input_config":
+            config = load_config(project_path(step.get("config", "config.local.json")))
+            value = getattr(config, step["field"])
+            adb_input_text(value)
+        elif action == "input_id8_for_visible_masked_name":
+            nodes = adb_dump_nodes()
+            masked_names = extract_masked_names(adb_visible_texts(nodes))
+            if not masked_names:
+                raise RuntimeError(f"step {index}: 未识别到脱敏姓名")
+            masked_name = step.get("masked_name") or masked_names[0]
+            matches = match_roster(masked_name, roster)
+            if len(matches) != 1:
+                raise RuntimeError(f"step {index}: {masked_name} 匹配结果数量={len(matches)}")
+            adb_input_text(matches[0]["身份证后8位"])
+            print(f"step={index} masked_name={masked_name} id_last8={matches[0]['身份证后8位']}")
+        elif action == "keyevent":
+            run_adb(["shell", "input", "keyevent", str(step["key"])])
+        else:
+            raise RuntimeError(f"step {index}: 未知 action {action}")
+        time.sleep(float(step.get("after", 0.5)))
+    print("flow_done")
+
+
+def collect_attachments(args: argparse.Namespace) -> None:
+    ensure_dirs()
+    source_dir = project_path(args.input)
+    dest_dir = project_path(args.output)
+    dest_dir.mkdir(parents=True, exist_ok=True)
+    copied = 0
+
+    for path in sorted(source_dir.rglob("*")):
+        if not path.is_file() or path.suffix.lower() not in INVOICE_EXTENSIONS:
+            continue
+        invoice_no = extract_invoice_number(path.stem)
+        prefix = invoice_no or path.stem
+        dest = unique_dest(dest_dir / safe_filename(f"{prefix}_{path.name}"))
+        shutil.copy2(path, dest)
+        copied += 1
+
+    print(f"copied={copied}")
+    print(f"output={dest_dir}")
+
+
+def collect_mail(args: argparse.Namespace) -> None:
+    ensure_dirs()
+    source_dir = project_path(args.input)
+    dest_dir = project_path(args.output)
+    dest_dir.mkdir(parents=True, exist_ok=True)
+    extracted = 0
+
+    for eml_path in sorted(source_dir.rglob("*.eml")):
+        with eml_path.open("rb") as fh:
+            message = email.message_from_binary_file(fh, policy=policy.default)
+        for part in message.walk():
+            filename = part.get_filename()
+            if not filename or Path(filename).suffix.lower() not in INVOICE_EXTENSIONS:
+                continue
+            payload = part.get_payload(decode=True)
+            if not payload:
+                continue
+            subject = safe_filename(str(message.get("subject", "")))[:80]
+            dest = unique_dest(dest_dir / safe_filename(f"{subject}_{filename}"))
+            dest.write_bytes(payload)
+            extracted += 1
+
+    print(f"extracted={extracted}")
+    print(f"output={dest_dir}")
+
+
+def match_invoices_to_tasks(tasks: list[dict[str, str]], invoice_dir: Path) -> list[dict[str, str]]:
+    invoice_files = [p for p in sorted(invoice_dir.rglob("*")) if p.is_file() and p.suffix.lower() in INVOICE_EXTENSIONS]
+    unmatched = invoice_files.copy()
+
+    for task in tasks:
+        if task.get("发票文件路径"):
+            continue
+        candidates = []
+        passenger = task.get("乘车人", "")
+        ticket_ref = task.get("票号/订单标识", "")
+        for invoice in unmatched:
+            score = 0
+            if passenger and passenger in invoice.name:
+                score += 2
+            if ticket_ref and ticket_ref in invoice.name:
+                score += 3
+            if score:
+                candidates.append((score, invoice))
+        if not candidates:
+            continue
+        candidates.sort(reverse=True, key=lambda item: item[0])
+        chosen = candidates[0][1]
+        task["发票文件路径"] = str(chosen.relative_to(PROJECT_ROOT))
+        task["状态"] = "已收票"
+        task["失败原因"] = ""
+        task["下一步动作"] = "财务验真/归档"
+        task["开票时间"] = task.get("开票时间") or datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+        unmatched.remove(chosen)
+
+    return tasks
+
+
+def validate_tasks(tasks: list[dict[str, str]]) -> list[str]:
+    errors: list[str] = []
+    for task in tasks:
+        prefix = f"{task.get('task_id', '<missing>')}: "
+        if not task.get("公司抬头") or task.get("公司抬头") == "请填写公司全称":
+            errors.append(prefix + "缺公司抬头")
+        if not task.get("税号") or task.get("税号") == "请填写统一社会信用代码":
+            errors.append(prefix + "缺税号")
+        if not task.get("接收邮箱") or task.get("接收邮箱") == "invoice@example.com":
+            errors.append(prefix + "缺接收邮箱")
+        if task.get("状态") in {"已开票", "已收票"} and not task.get("发票文件路径"):
+            errors.append(prefix + "已开票/已收票但缺发票文件路径")
+    return errors
+
+
+def export_summary(args: argparse.Namespace) -> None:
+    ensure_dirs()
+    tasks = match_invoices_to_tasks(read_tasks(), project_path(args.invoice_dir))
+    write_tasks(tasks)
+    output = project_path(args.output)
+    output.parent.mkdir(parents=True, exist_ok=True)
+    if Workbook is None:
+        raise RuntimeError("openpyxl 不可用，无法导出 xlsx")
+
+    wb = Workbook()
+    ws = wb.active
+    ws.title = "发票汇总"
+    ws.append(TASK_HEADERS)
+    for task in tasks:
+        ws.append([task.get(key, "") for key in TASK_HEADERS])
+    ws.freeze_panes = "A2"
+    for column in ws.columns:
+        max_length = max(len(str(cell.value or "")) for cell in column)
+        ws.column_dimensions[column[0].column_letter].width = min(max(max_length + 2, 10), 36)
+
+    missing = wb.create_sheet("缺票清单")
+    missing.append(TASK_HEADERS)
+    for task in tasks:
+        if not task.get("发票文件路径"):
+            missing.append([task.get(key, "") for key in TASK_HEADERS])
+
+    issues = wb.create_sheet("合规检查")
+    issues.append(["问题"])
+    for issue in validate_tasks(tasks):
+        issues.append([issue])
+    if issues.max_row == 1:
+        issues.append(["未发现基础字段问题"])
+
+    wb.save(output)
+    print(f"summary={output}")
+    print(f"tasks={TASKS_CSV}")
+
+
+def rpa_plan(args: argparse.Namespace) -> None:
+    ensure_dirs()
+    tasks = read_tasks()
+    runnable = [
+        task
+        for task in tasks
+        if task.get("状态") == "待网页开票" and task.get("开票码/链接", "").startswith(("http://", "https://"))
+    ]
+    output = project_path(args.output)
+    output.parent.mkdir(parents=True, exist_ok=True)
+    rows = []
+    for task in runnable:
+        rows.append(
+            "<tr>"
+            f"<td>{html.escape(task['task_id'])}</td>"
+            f"<td>{html.escape(task.get('乘车人', ''))}</td>"
+            f"<td>{html.escape(task.get('票号/订单标识', ''))}</td>"
+            f"<td>{html.escape(task.get('公司抬头', ''))}</td>"
+            f"<td>{html.escape(task.get('税号', ''))}</td>"
+            f"<td>{html.escape(task.get('接收邮箱', ''))}</td>"
+            f"<td><a href=\"{html.escape(task.get('开票码/链接', ''))}\" target=\"_blank\">打开官方页面</a></td>"
+            "</tr>"
+        )
+
+    page = f"""<!doctype html>
+<html lang="zh-CN">
+<head>
+  <meta charset="utf-8">
+  <title>铁路发票网页辅助开票</title>
+  <style>
+    body {{ font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; margin: 32px; color: #1f2933; }}
+    table {{ border-collapse: collapse; width: 100%; }}
+    th, td {{ border: 1px solid #d0d7de; padding: 8px; font-size: 14px; vertical-align: top; }}
+    th {{ background: #f6f8fa; text-align: left; }}
+    code {{ background: #f6f8fa; padding: 2px 4px; border-radius: 4px; }}
+  </style>
+</head>
+<body>
+  <h1>铁路发票网页辅助开票</h1>
+  <p>先手动登录 12306 并完成身份核验。本页只打开官方页面，不保存账号密码，不绕过验证码。</p>
+  <p>打开页面后，把下表中的公司抬头、税号、邮箱复制到官方页面并提交；提交成功后在 <code>work/invoice_tasks.csv</code> 更新状态，或运行收票汇总命令自动回写。</p>
+  <table>
+    <thead><tr><th>任务</th><th>乘车人</th><th>票号/订单</th><th>抬头</th><th>税号</th><th>邮箱</th><th>操作</th></tr></thead>
+    <tbody>{''.join(rows)}</tbody>
+  </table>
+</body>
+</html>
+"""
+    output.write_text(page, encoding="utf-8")
+    print(f"runnable={len(runnable)}")
+    print(f"helper={output}")
+
+
+def validate_command(_: argparse.Namespace) -> None:
+    errors = validate_tasks(read_tasks())
+    if errors:
+        for error in errors:
+            print(error)
+        raise SystemExit(1)
+    print("ok")
+
+
+def init_project(_: argparse.Namespace) -> None:
+    ensure_dirs()
+    if not CONFIG_EXAMPLE_PATH.exists():
+        CONFIG_EXAMPLE_PATH.write_text(
+            json.dumps(
+                {
+                    "company_title": "请填写公司全称",
+                    "tax_id": "请填写统一社会信用代码",
+                    "receiver_email": "invoice@example.com",
+                },
+                ensure_ascii=False,
+                indent=2,
+            )
+            + "\n",
+            encoding="utf-8",
+        )
+    manual = PROJECT_ROOT / "data" / "input" / "开票码批次" / "manual_codes.csv"
+    if not manual.exists():
+        manual.write_text(
+            "source_file,passenger,ticket_ref,code\n",
+            encoding="utf-8",
+        )
+    print("initialized")
+    print(f"config_example={CONFIG_EXAMPLE_PATH}")
+    print(f"config_local={CONFIG_LOCAL_PATH}")
+    print(f"manual_codes={manual}")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description="铁路系统发票批量处理本地工具")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    p_init = subparsers.add_parser("init", help="创建本地目录和配置模板")
+    p_init.set_defaults(func=init_project)
+
+    p_import = subparsers.add_parser("import-codes", help="从二维码图片/PDF/文本/手工CSV生成开票任务")
+    p_import.add_argument("--input", default="data/input/开票码批次")
+    p_import.add_argument("--config", default="config.local.json")
+    p_import.set_defaults(func=import_codes)
+
+    p_mail = subparsers.add_parser("collect-mail", help="从 .eml 邮件中提取 PDF/OFD/XML 发票附件")
+    p_mail.add_argument("--input", default="data/mail")
+    p_mail.add_argument("--output", default="output/invoices")
+    p_mail.set_defaults(func=collect_mail)
+
+    p_attach = subparsers.add_parser("collect-attachments", help="从附件目录复制 PDF/OFD/XML 到发票归档目录")
+    p_attach.add_argument("--input", default="data/attachments")
+    p_attach.add_argument("--output", default="output/invoices")
+    p_attach.set_defaults(func=collect_attachments)
+
+    p_export = subparsers.add_parser("export-summary", help="匹配发票附件并导出 Excel 汇总")
+    p_export.add_argument("--invoice-dir", default="output/invoices")
+    p_export.add_argument("--output", default="output/发票汇总.xlsx")
+    p_export.set_defaults(func=export_summary)
+
+    p_rpa = subparsers.add_parser("rpa-plan", help="生成网页辅助开票 HTML")
+    p_rpa.add_argument("--output", default="output/rpa_helper.html")
+    p_rpa.set_defaults(func=rpa_plan)
+
+    p_validate = subparsers.add_parser("validate", help="检查台账基础字段")
+    p_validate.set_defaults(func=validate_command)
+
+    p_roster = subparsers.add_parser("import-roster", help="从 Excel/CSV 名单导入姓名和身份证后8位")
+    p_roster.add_argument("--input", required=True)
+    p_roster.set_defaults(func=import_roster)
+
+    p_match = subparsers.add_parser("match-roster", help="用脱敏姓名匹配名单中的身份证后8位")
+    p_match.add_argument("--masked-name", required=True)
+    p_match.add_argument("--roster", default="work/passenger_roster.csv")
+    p_match.set_defaults(func=match_roster_command)
+
+    p_enrich = subparsers.add_parser("enrich-tasks", help="用名单补全台账里的身份证后8位")
+    p_enrich.add_argument("--roster", default="work/passenger_roster.csv")
+    p_enrich.set_defaults(func=enrich_tasks_with_roster)
+
+    p_adb_dump = subparsers.add_parser("android-dump", help="读取当前 Android 页面可见文字")
+    p_adb_dump.add_argument("--output", default="")
+    p_adb_dump.set_defaults(func=android_dump)
+
+    p_adb_id = subparsers.add_parser("android-type-id", help="从当前 Android 页面识别脱敏姓名并输入身份证后8位")
+    p_adb_id.add_argument("--roster", default="work/passenger_roster.csv")
+    p_adb_id.add_argument("--masked-name", default="")
+    p_adb_id.add_argument("--click-text", default="")
+    p_adb_id.add_argument("--contains", action="store_true")
+    p_adb_id.add_argument("--tap", default="", help="输入前点击坐标，格式 x,y")
+    p_adb_id.set_defaults(func=android_type_id)
+
+    p_adb_flow = subparsers.add_parser("android-run-flow", help="按 JSON 步骤执行 Android ADB 自动化")
+    p_adb_flow.add_argument("--flow", default="templates/android_flow.example.json")
+    p_adb_flow.add_argument("--roster", default="work/passenger_roster.csv")
+    p_adb_flow.set_defaults(func=android_run_flow)
+
+    p_invoice_step = subparsers.add_parser("android-invoice-step", help="按当前 12306 页面状态执行一步开票自动化")
+    p_invoice_step.add_argument("--roster", default="work/passenger_roster.csv")
+    p_invoice_step.add_argument("--send-email", action="store_true", help="成功页优先点击发送至邮箱；不传则点击继续开票")
+    p_invoice_step.add_argument("--invoice-success-action", choices=["download", "email", "continue"], default="", help="成功页动作: download=下载发票,email=发送邮箱,continue=仅继续")
+    p_invoice_step.add_argument("--invoice-output-dir", default="", help="PDF/OFD/XML 保存到电脑本地目录")
+    p_invoice_step.add_argument("--download-wait", type=float, default=5.0, help="点击下载后等待手机写入文件的秒数")
+    p_invoice_step.add_argument("--wait-primary", type=int, default=10)
+    p_invoice_step.add_argument("--wait-secondary", type=int, default=20)
+    p_invoice_step.add_argument("--short-wait", type=int, default=2)
+    p_invoice_step.add_argument("--fast", action="store_true")
+    p_invoice_step.set_defaults(func=android_invoice_step)
+
+    p_page_queue = subparsers.add_parser("android-build-page-queue", help="抓当前扫码列表页，生成本页可处理人员队列")
+    p_page_queue.add_argument("--roster", default="work/passenger_roster.csv")
+    p_page_queue.set_defaults(func=android_build_page_queue)
+
+    p_page_step = subparsers.add_parser("android-page-step", help="按本页队列点击下一个可处理人员；非列表页时执行普通单步状态机")
+    p_page_step.add_argument("--roster", default="work/passenger_roster.csv")
+    p_page_step.add_argument("--send-email", action="store_true")
+    p_page_step.add_argument("--wait-primary", type=int, default=10)
+    p_page_step.add_argument("--wait-secondary", type=int, default=20)
+    p_page_step.add_argument("--short-wait", type=int, default=2)
+    p_page_step.add_argument("--fast", action="store_true")
+    p_page_step.add_argument("--rebuild", action="store_true")
+    p_page_step.add_argument("--auto-next", action="store_true", help="本页无 pending 时自动上滑并重建队列")
+    p_page_step.add_argument("--swipe-x", type=int, default=630)
+    p_page_step.add_argument("--swipe-start-y", type=int, default=2300)
+    p_page_step.add_argument("--swipe-end-y", type=int, default=700)
+    p_page_step.add_argument("--swipe-duration-ms", type=int, default=700)
+    p_page_step.add_argument("--after-swipe", type=float, default=2.0)
+    p_page_step.set_defaults(func=android_page_step)
+
+    p_page_run = subparsers.add_parser("android-page-run", help="连续执行多次 android-page-step，加快整页处理")
+    p_page_run.add_argument("--roster", default="work/passenger_roster.csv")
+    p_page_run.add_argument("--send-email", action="store_true")
+    p_page_run.add_argument("--wait-primary", type=int, default=10)
+    p_page_run.add_argument("--wait-secondary", type=int, default=20)
+    p_page_run.add_argument("--short-wait", type=int, default=2)
+    p_page_run.add_argument("--fast", action="store_true")
+    p_page_run.add_argument("--rebuild", action="store_true")
+    p_page_run.add_argument("--auto-next", action="store_true")
+    p_page_run.add_argument("--swipe-x", type=int, default=630)
+    p_page_run.add_argument("--swipe-start-y", type=int, default=2300)
+    p_page_run.add_argument("--swipe-end-y", type=int, default=700)
+    p_page_run.add_argument("--swipe-duration-ms", type=int, default=700)
+    p_page_run.add_argument("--after-swipe", type=float, default=1.2)
+    p_page_run.add_argument("--steps", type=int, default=12)
+    p_page_run.add_argument("--between-steps", type=float, default=0.4)
+    p_page_run.set_defaults(func=android_page_run)
+
+    p_page_next = subparsers.add_parser("android-page-next", help="扫码列表页上滑到下一页，并可重建队列")
+    p_page_next.add_argument("--roster", default="work/passenger_roster.csv")
+    p_page_next.add_argument("--x", type=int, default=630)
+    p_page_next.add_argument("--start-y", type=int, default=2300)
+    p_page_next.add_argument("--end-y", type=int, default=700)
+    p_page_next.add_argument("--duration-ms", type=int, default=700)
+    p_page_next.add_argument("--after", type=float, default=2.0)
+    p_page_next.add_argument("--rebuild", action="store_true")
+    p_page_next.set_defaults(func=android_page_next)
+
+    p_vision_run = subparsers.add_parser("android-vision-page-run", help="视觉驱动批量开票:截图识别 -> anchor 去重 -> 按页批次 tap -> 子流程 -> 滑动")
+    p_vision_run.add_argument("--roster", default="work/passenger_roster.csv")
+    p_vision_run.add_argument("--send-email", action="store_true")
+    p_vision_run.add_argument("--fast", action="store_true")
+    p_vision_run.add_argument("--dry-run", action="store_true", help="只识别+匹配,不真 tap;用于验证视觉精度")
+    p_vision_run.add_argument("--no-precheck", dest="precheck", action="store_false", help="跳过开始前的视觉自检")
+    p_vision_run.add_argument("--max-batches", type=int, default=40, help="最多处理多少批(页),兜底防死循环")
+    p_vision_run.add_argument("--max-actions", type=int, default=0, help="本次最多 tap 几行(>0 生效);用于单人/小样测试")
+    p_vision_run.add_argument("--sub-max-steps", type=int, default=12, help="单行子流程最多走多少步还没回列表就放弃")
+    p_vision_run.add_argument("--wait-primary", type=int, default=5, help="主等待秒数(发票开具中)")
+    p_vision_run.add_argument("--wait-secondary", type=int, default=10, help="扩展等待秒数")
+    p_vision_run.add_argument("--short-wait", type=int, default=1, help="短等待秒数(页面切换)")
+    p_vision_run.add_argument("--between-steps", type=float, default=0.3)
+    p_vision_run.add_argument("--swipe-x", type=int, default=630)
+    p_vision_run.add_argument("--swipe-start-y", type=int, default=2300)
+    p_vision_run.add_argument("--swipe-end-y", type=int, default=200)
+    p_vision_run.add_argument("--swipe-duration-ms", type=int, default=700)
+    p_vision_run.add_argument("--after-swipe", type=float, default=1.5)
+    p_vision_run.set_defaults(func=android_vision_page_run, precheck=True)
+
+    p_h5_run = subparsers.add_parser("android-h5-page-run", help="H5扫码开票单视觉驱动:截屏识别 -> 逐人开具 -> 子流程 -> 滚动")
+    p_h5_run.add_argument("--roster", default="work/passenger_roster.csv")
+    p_h5_run.add_argument("--send-email", action="store_true")
+    p_h5_run.add_argument("--invoice-success-action", choices=["download", "email", "continue"], default="", help="成功页动作: download=下载发票,email=发送邮箱,continue=仅继续")
+    p_h5_run.add_argument("--invoice-output-dir", default="", help="PDF/OFD/XML 保存到电脑本地目录")
+    p_h5_run.add_argument("--download-wait", type=float, default=5.0, help="点击下载后等待手机写入文件的秒数")
+    p_h5_run.add_argument("--fast", action="store_true")
+    p_h5_run.add_argument("--dry-run", action="store_true", help="只识别+匹配,不真 tap")
+    p_h5_run.add_argument("--no-precheck", dest="precheck", action="store_false", help="跳过开始前的视觉自检")
+    p_h5_run.add_argument("--max-batches", type=int, default=40, help="最多轮次,兜底防死循环")
+    p_h5_run.add_argument("--max-actions", type=int, default=0, help="本次最多 tap 几人(>0 生效)")
+    p_h5_run.add_argument("--sub-max-steps", type=int, default=12, help="单行子流程最多走多少步")
+    p_h5_run.add_argument("--wait-primary", type=int, default=5, help="主等待秒数(发票开具中)")
+    p_h5_run.add_argument("--wait-secondary", type=int, default=10, help="扩展等待秒数")
+    p_h5_run.add_argument("--short-wait", type=int, default=1, help="短等待秒数(页面切换)")
+    p_h5_run.add_argument("--between-steps", type=float, default=0.3)
+    p_h5_run.add_argument("--retry-failed-once", dest="retry_failed_once", type=int, default=1, help="当前运行内对可见 failed/error 人员最多重试次数")
+    p_h5_run.add_argument("--no-resume-after-last-progress", dest="resume_after_last_progress", action="store_false", help="不按进度表最后处理人定位续跑")
+    # H5 滚动参数(页面内滚动,不是翻页)
+    p_h5_run.add_argument("--h5-scroll-x", type=int, default=630)
+    p_h5_run.add_argument("--h5-scroll-start-y", type=int, default=2400)
+    p_h5_run.add_argument("--h5-scroll-end-y", type=int, default=600)
+    p_h5_run.add_argument("--h5-scroll-duration-ms", type=int, default=800)
+    p_h5_run.add_argument("--h5-scroll-after", type=float, default=2.0)
+    p_h5_run.set_defaults(func=android_h5_page_run, precheck=True)
+
+    p_page_top = subparsers.add_parser("android-page-top", help="反复下滑回到扫码列表顶部")
+    p_page_top.add_argument("--x", type=int, default=630)
+    p_page_top.add_argument("--start-y", type=int, default=700)
+    p_page_top.add_argument("--end-y", type=int, default=2300)
+    p_page_top.add_argument("--duration-ms", type=int, default=600)
+    p_page_top.add_argument("--after", type=float, default=0.8)
+    p_page_top.add_argument("--max-iterations", type=int, default=40)
+    p_page_top.set_defaults(func=android_page_top)
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    args.func(args)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
diff --git a/scripts/record_step.py b/scripts/record_step.py
new file mode 100644
index 0000000..6741ca6
--- /dev/null
+++ b/scripts/record_step.py
@@ -0,0 +1,152 @@
+#!/usr/bin/env python3
+"""录制一次"用户操作"前后的手机状态。
+
+用法:
+  python3 scripts/record_step.py "label"            # 记一次状态,自动序号
+  python3 scripts/record_step.py --new "first label" # 开新 session,清重置
+  python3 scripts/record_step.py --list             # 列出当前 session 已记的步骤
+
+每次调用会在 work/replay/<session_ts>/<NN_label>/ 下产出:
+  - ui.xml          adb uiautomator dump
+  - screen.png      adb 截屏
+  - meta.json       时间戳 + label + 屏幕分辨率
+  - texts.txt       从 xml 抽出的所有可见 text(后续 diff 用)
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import subprocess
+import sys
+import time
+from pathlib import Path
+
+PROJECT_ROOT = Path(__file__).resolve().parents[1]
+REPLAY_ROOT = PROJECT_ROOT / "work" / "replay"
+CURRENT_SESSION_POINTER = REPLAY_ROOT / "_current_session"
+
+
+def latest_session() -> Path | None:
+    if CURRENT_SESSION_POINTER.exists():
+        target = Path(CURRENT_SESSION_POINTER.read_text().strip())
+        if target.exists():
+            return target
+    return None
+
+
+def new_session() -> Path:
+    REPLAY_ROOT.mkdir(parents=True, exist_ok=True)
+    ts = time.strftime("%Y%m%d_%H%M%S")
+    session = REPLAY_ROOT / ts
+    session.mkdir(parents=True, exist_ok=False)
+    CURRENT_SESSION_POINTER.write_text(str(session))
+    return session
+
+
+def next_step_index(session: Path) -> int:
+    existing = sorted(p.name for p in session.iterdir() if p.is_dir())
+    n = 0
+    for name in existing:
+        m = re.match(r"(\d+)_", name)
+        if m:
+            n = max(n, int(m.group(1)))
+    return n + 1
+
+
+def slugify(label: str) -> str:
+    label = re.sub(r"\s+", "_", label.strip())
+    return re.sub(r"[^a-zA-Z0-9_一-鿿-]+", "", label)[:60] or "step"
+
+
+def dump_ui_xml(target: Path) -> None:
+    subprocess.run(["adb", "shell", "uiautomator", "dump", "/sdcard/_record.xml"], check=True, capture_output=True)
+    subprocess.run(["adb", "pull", "/sdcard/_record.xml", str(target)], check=True, capture_output=True)
+
+
+def take_screenshot(target: Path) -> None:
+    result = subprocess.run(["adb", "exec-out", "screencap", "-p"], capture_output=True, check=True)
+    target.write_bytes(result.stdout)
+
+
+def extract_texts(xml_path: Path) -> list[str]:
+    xml = xml_path.read_text(encoding="utf-8", errors="ignore")
+    return [t for t in re.findall(r'text="([^"]+)"', xml) if t.strip()]
+
+
+def png_dimensions(path: Path) -> tuple[int, int]:
+    data = path.read_bytes()
+    if data[:8] == b"\x89PNG\r\n\x1a\n":
+        return int.from_bytes(data[16:20], "big"), int.from_bytes(data[20:24], "big")
+    return 0, 0
+
+
+def record(session: Path, label: str) -> Path:
+    idx = next_step_index(session)
+    folder = session / f"{idx:02d}_{slugify(label)}"
+    folder.mkdir(parents=True, exist_ok=False)
+
+    xml_path = folder / "ui.xml"
+    png_path = folder / "screen.png"
+    dump_ui_xml(xml_path)
+    take_screenshot(png_path)
+
+    texts = extract_texts(xml_path)
+    (folder / "texts.txt").write_text("\n".join(texts), encoding="utf-8")
+
+    w, h = png_dimensions(png_path)
+    meta = {
+        "label": label,
+        "index": idx,
+        "timestamp": time.strftime("%Y-%m-%d %H:%M:%S"),
+        "screen_w": w,
+        "screen_h": h,
+        "text_count": len(texts),
+    }
+    (folder / "meta.json").write_text(json.dumps(meta, ensure_ascii=False, indent=2), encoding="utf-8")
+    return folder
+
+
+def cmd_list(session: Path) -> None:
+    for folder in sorted(session.iterdir()):
+        if folder.is_dir():
+            meta_path = folder / "meta.json"
+            if meta_path.exists():
+                meta = json.loads(meta_path.read_text())
+                print(f"  {folder.name:30s} {meta.get('timestamp','')}  text_count={meta.get('text_count')}")
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="录制手机操作前后状态")
+    parser.add_argument("label", nargs="?", help="本步骤的描述,作为目录名一部分")
+    parser.add_argument("--new", dest="new", action="store_true", help="开新 session")
+    parser.add_argument("--list", dest="list_only", action="store_true", help="列出当前 session 已记的步骤")
+    args = parser.parse_args(argv)
+
+    if args.list_only:
+        session = latest_session()
+        if not session:
+            print("no_session")
+            return 1
+        print(f"session={session}")
+        cmd_list(session)
+        return 0
+
+    if args.new or latest_session() is None:
+        session = new_session()
+        print(f"new_session={session}")
+    else:
+        session = latest_session()
+
+    if not args.label:
+        print("error: label required", file=sys.stderr)
+        return 2
+
+    folder = record(session, args.label)
+    print(f"recorded={folder.name} session={session.name}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
diff --git a/scripts/vision_fallback.py b/scripts/vision_fallback.py
new file mode 100644
index 0000000..787d172
--- /dev/null
+++ b/scripts/vision_fallback.py
@@ -0,0 +1,259 @@
+#!/usr/bin/env python3
+"""视觉 fallback: 截屏 + 调豆包视觉 API,做"当前是哪一页 / 找哪个按钮"判断."""
+
+from __future__ import annotations
+
+import argparse
+import base64
+import json
+import subprocess
+import sys
+import tempfile
+import time
+from pathlib import Path
+
+import requests
+
+PROJECT_ROOT = Path(__file__).resolve().parent.parent
+CONFIG_LOCAL = PROJECT_ROOT / "config.local.json"
+WORK_DIR = PROJECT_ROOT / "work"
+
+
+def load_vision_config() -> dict:
+    if not CONFIG_LOCAL.exists():
+        raise RuntimeError(f"配置文件不存在: {CONFIG_LOCAL}")
+    cfg = json.loads(CONFIG_LOCAL.read_text(encoding="utf-8"))
+    vision = cfg.get("vision")
+    if not vision:
+        raise RuntimeError("config.local.json 缺 vision 段")
+    for key in ("base_url", "api_key", "model"):
+        if not vision.get(key):
+            raise RuntimeError(f"vision.{key} 未配置")
+    return vision
+
+
+def adb_screenshot(output: Path) -> Path:
+    output.parent.mkdir(parents=True, exist_ok=True)
+    result = subprocess.run(
+        ["adb", "exec-out", "screencap", "-p"],
+        capture_output=True,
+        check=False,
+    )
+    if result.returncode != 0:
+        raise RuntimeError(f"adb screencap 失败: {result.stderr.decode('utf-8', 'ignore')}")
+    output.write_bytes(result.stdout)
+    return output
+
+
+def call_vision(image_path: Path, prompt: str, vision_cfg: dict, timeout: int = 60) -> dict:
+    image_b64 = base64.b64encode(image_path.read_bytes()).decode("ascii")
+    payload = {
+        "model": vision_cfg["model"],
+        "messages": [
+            {
+                "role": "user",
+                "content": [
+                    {"type": "image_url", "image_url": {"url": f"data:image/png;base64,{image_b64}"}},
+                    {"type": "text", "text": prompt},
+                ],
+            }
+        ],
+        "temperature": 0.1,
+    }
+    headers = {
+        "Authorization": f"Bearer {vision_cfg['api_key']}",
+        "Content-Type": "application/json",
+    }
+    url = vision_cfg["base_url"].rstrip("/") + "/chat/completions"
+    start = time.time()
+    response = requests.post(url, json=payload, headers=headers, timeout=timeout)
+    elapsed = time.time() - start
+    if response.status_code >= 300:
+        raise RuntimeError(f"vision_api status={response.status_code} body={response.text[:500]}")
+    data = response.json()
+    content = data.get("choices", [{}])[0].get("message", {}).get("content", "")
+    usage = data.get("usage", {})
+    return {
+        "content": content,
+        "usage": usage,
+        "elapsed_seconds": round(elapsed, 2),
+        "raw": data,
+    }
+
+
+PAGE_DETECT_PROMPT = """这是手机 12306 App 的一张截图。请只用一个 JSON 对象回答(不要 markdown 代码块),字段如下:
+
+{
+  "page": "<one of: list / verify / invoice_info / invoice_confirm / success / email_confirm / mail_sent / no_ticket / launcher / other>",
+  "summary": "<简短描述当前看到的内容,不超过 30 字>",
+  "actionable_buttons": ["<可点击的关键按钮文字,如 开具/确认/提交/继续开票/确定/发送至邮箱>"],
+  "scroll_position": "<top / middle / bottom / unknown>"
+}
+
+页面对应关系:
+- list = 扫码开票单列表(显示多个 X*Y 脱敏姓名 + 开具按钮)
+- verify = 请输入乘车人 + 证件号码后8位的核验弹窗
+- invoice_info = 发票信息页(有抬头/税号/金额/提交按钮)
+- invoice_confirm = 发票信息确认弹窗
+- success = 发票开具成功页(有 继续开票 / 发送至邮箱)
+- email_confirm = 邮箱地址确认
+- mail_sent = 邮件发送完成提示
+- no_ticket = 发票管理页 + 您没有可开具电子发票的客票
+- launcher = 桌面 / 不在 12306 内
+- other = 其他识别不出的页面
+"""
+
+
+LIST_ROWS_PROMPT_TEMPLATE = """这是手机 12306 App 扫码开票单列表页的一张截图。
+请自上而下识别屏幕上所有"乘客行"(每行有一个脱敏姓名如 张*岩、王*平,行尾右侧有"开具"按钮)。
+**坐标系约定**:所有 bbox 用 0-1000 归一化坐标返回(x 用 [0,1000] 横向占比,y 用 [0,1000] 纵向占比),不要返回原始像素。
+
+只用一个 JSON 对象回答(不要 markdown 代码块、不要解释),字段如下:
+{{
+  "rows": [
+    {{
+      "masked_name": "<脱敏姓名,如 张*岩;只用一个 ASCII * 号,不要 ＊>",
+      "id_first": "<身份证首位,看不见就空串>",
+      "id_last": "<身份证末位,看不见就空串>",
+      "button_bbox": [x1, y1, x2, y2]  // 该行"开具"按钮的 0-1000 归一化 bbox,整数
+    }}
+  ],
+  "scroll_position": "<top / middle / bottom>",  // bottom = 看到列表底部边缘或"没有更多了"提示
+  "page_ok": <true/false>  // 当前是不是扫码开票单列表页;不是请置 false 并把 rows 留空
+}}
+
+注意:
+- 只识别完整可见的行;只露出半截的行不要加进 rows
+- masked_name 用半角 * 号(不要全角 ＊)
+- 没看到"开具"按钮的行不算"乘客行",跳过
+- bbox 数值范围 [0, 1000],整数
+"""
+
+
+def screenshot_size(image_path: Path) -> tuple[int, int]:
+    data = image_path.read_bytes()
+    if len(data) >= 24 and data[:8] == b"\x89PNG\r\n\x1a\n":
+        width = int.from_bytes(data[16:20], "big")
+        height = int.from_bytes(data[20:24], "big")
+        return width, height
+    return 0, 0
+
+
+def parse_json_lenient(content: str) -> dict:
+    text = content.strip()
+    if text.startswith("```"):
+        text = text.strip("`")
+        if text.startswith("json"):
+            text = text[4:]
+    start = text.find("{")
+    end = text.rfind("}")
+    if start == -1 or end == -1:
+        raise RuntimeError(f"无法从模型输出里抽出 JSON: {content[:300]}")
+    return json.loads(text[start:end + 1])
+
+
+def denormalize_bboxes(parsed: dict, width: int, height: int) -> dict:
+    """把模型返回的 0-1000 归一化 bbox 换算成截图绝对像素。
+
+    判定规则:
+      - max(bbox) 明显小于 min(image_w, image_h) 的一半,几乎不可能是绝对像素 -> 归一化
+      - max(bbox) <= 1100(允许 Qwen-VL rounding 飘到 1000-1030)且图比 1100 大 -> 归一化
+      - 否则按绝对像素原样保留
+    **就地**修改 parsed 并返回。
+    """
+    rows = parsed.get("rows") or []
+    if not rows or width <= 0 or height <= 0:
+        return parsed
+    flat = []
+    for row in rows:
+        bbox = row.get("button_bbox") or []
+        if len(bbox) == 4:
+            flat.extend(bbox)
+    if not flat:
+        return parsed
+    max_v = max(flat)
+    img_min = min(width, height)
+    is_normalized = max_v <= 1100 and img_min > 1100
+    if not is_normalized:
+        return parsed
+    for row in rows:
+        bbox = row.get("button_bbox") or []
+        if len(bbox) != 4:
+            continue
+        x1, y1, x2, y2 = bbox
+        row["button_bbox"] = [
+            int(round(x1 * width / 1000)),
+            int(round(y1 * height / 1000)),
+            int(round(x2 * width / 1000)),
+            int(round(y2 * height / 1000)),
+        ]
+        cx = (row["button_bbox"][0] + row["button_bbox"][2]) // 2
+        cy = (row["button_bbox"][1] + row["button_bbox"][3]) // 2
+        row["tap_point"] = [cx, cy]
+    parsed["bbox_denormalized"] = True
+    return parsed
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="vision fallback 测试入口")
+    sub = parser.add_subparsers(dest="cmd", required=True)
+
+    p_ping = sub.add_parser("ping", help="不截屏,只发一张本地图测试 API 通路")
+    p_ping.add_argument("--image", required=True, help="本地图片路径")
+    p_ping.add_argument("--prompt", default="一句话描述这张图")
+
+    p_detect = sub.add_parser("detect-page", help="adb 截屏 + 让豆包判断当前是哪一页")
+    p_detect.add_argument("--save", default="work/last_screenshot.png", help="截屏保存路径")
+
+    p_ask = sub.add_parser("ask", help="adb 截屏 + 自定义 prompt")
+    p_ask.add_argument("--prompt", required=True)
+    p_ask.add_argument("--save", default="work/last_screenshot.png")
+
+    p_rows = sub.add_parser("list-rows", help="adb 截屏 + 让豆包识别列表页所有可见乘客行")
+    p_rows.add_argument("--save", default="work/last_screenshot.png", help="截屏保存路径")
+    p_rows.add_argument("--image", default=None, help="指定已有图片,跳过 adb 截屏(调试用)")
+
+    args = parser.parse_args(argv)
+    vision_cfg = load_vision_config()
+
+    if args.cmd == "ping":
+        image = Path(args.image).expanduser()
+        if not image.is_absolute():
+            image = PROJECT_ROOT / image
+        result = call_vision(image, args.prompt, vision_cfg)
+    elif args.cmd == "list-rows":
+        if args.image:
+            save_path = Path(args.image)
+            if not save_path.is_absolute():
+                save_path = PROJECT_ROOT / save_path
+        else:
+            save_path = Path(args.save)
+            if not save_path.is_absolute():
+                save_path = PROJECT_ROOT / save_path
+            adb_screenshot(save_path)
+        width, height = screenshot_size(save_path)
+        prompt = LIST_ROWS_PROMPT_TEMPLATE.format(width=width, height=height)
+        result = call_vision(save_path, prompt, vision_cfg)
+        result["screenshot"] = str(save_path)
+        result["image_size"] = {"width": width, "height": height}
+        try:
+            parsed = parse_json_lenient(result["content"])
+            denormalize_bboxes(parsed, width, height)
+            result["parsed"] = parsed
+        except Exception as exc:
+            result["parse_error"] = str(exc)
+    else:
+        save_path = Path(args.save)
+        if not save_path.is_absolute():
+            save_path = PROJECT_ROOT / save_path
+        adb_screenshot(save_path)
+        prompt = PAGE_DETECT_PROMPT if args.cmd == "detect-page" else args.prompt
+        result = call_vision(save_path, prompt, vision_cfg)
+        result["screenshot"] = str(save_path)
+
+    print(json.dumps(result, ensure_ascii=False, indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())
diff --git a/scripts/web_ui.py b/scripts/web_ui.py
new file mode 100644
index 0000000..2a43745
--- /dev/null
+++ b/scripts/web_ui.py
@@ -0,0 +1,1025 @@
+#!/usr/bin/env python3
+"""Local web UI for railway invoice automation."""
+
+from __future__ import annotations
+
+import base64
+import cgi
+import csv
+import json
+import re
+import sys
+import shutil
+import subprocess
+import threading
+import time
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from pathlib import Path
+from urllib.parse import urlparse
+
+import invoice_tool
+
+PROJECT_ROOT = invoice_tool.PROJECT_ROOT
+PYTHON = sys.executable
+
+RUNNER: subprocess.Popen[str] | None = None
+RUNNER_LOCK = threading.Lock()
+RUNNER_LOG = PROJECT_ROOT / "work" / "web_runner.log"
+UPLOAD_DIR = PROJECT_ROOT / "data" / "input"
+
+
+def csv_rows(path: Path) -> list[dict[str, str]]:
+    if not path.exists():
+        return []
+    with path.open("r", encoding="utf-8-sig", newline="") as fh:
+        return list(csv.DictReader(fh))
+
+
+def write_json(handler: BaseHTTPRequestHandler, data: object, status: int = 200) -> None:
+    body = json.dumps(data, ensure_ascii=False).encode("utf-8")
+    handler.send_response(status)
+    handler.send_header("Content-Type", "application/json; charset=utf-8")
+    handler.send_header("Content-Length", str(len(body)))
+    handler.end_headers()
+    handler.wfile.write(body)
+
+
+def device_status() -> dict[str, object]:
+    state = invoice_tool.run_adb(["get-state"], check=False)
+    connected = state.returncode == 0 and state.stdout.strip() == "device"
+    status: dict[str, object] = {
+        "connected": connected,
+        "state": state.stdout.strip() or "unknown",
+        "current_package": "",
+        "current_activity": "",
+        "in_12306": False,
+        "message": "手机已连接" if connected else (state.stderr.strip() or state.stdout.strip() or "未检测到手机"),
+    }
+    if not connected:
+        return status
+
+    window = invoice_tool.run_adb(["shell", "dumpsys", "window"], check=False)
+    focus_lines = [line.strip() for line in window.stdout.splitlines() if "mCurrentFocus=" in line or "mFocusedApp=" in line]
+    focus_text = " ".join(focus_lines)
+    match = re.search(r"u0\s+([^/\s]+)/([^\s}]+)", focus_text)
+    if match:
+        status["current_package"] = match.group(1)
+        status["current_activity"] = match.group(2)
+        status["in_12306"] = match.group(1) == "com.MobileTicket"
+        status["message"] = "当前在 12306" if status["in_12306"] else f"当前在 {match.group(1)}"
+    else:
+        status["message"] = "手机已连接，未识别当前前台 App"
+    return status
+
+
+PROGRESS_LABELS = {
+    "completed": {"text": "已开票", "tone": "ok", "reason": ""},
+    "no_ticket": {"text": "无可开票", "tone": "muted", "reason": "12306 未查询到可开发票客票"},
+    "in_progress": {"text": "处理中", "tone": "info", "reason": ""},
+    "failed": {"text": "失败", "tone": "bad", "reason": "上次运行未完成"},
+    "error": {"text": "运行错误", "tone": "bad", "reason": "脚本异常"},
+    "pending": {"text": "未操作", "tone": "pending", "reason": ""},
+}
+
+MATCH_REASON = {
+    "no_match": "名单里没有这个脱敏名",
+    "ambiguous": "同名多人，无法唯一匹配",
+    "no_button": "未识别到「开具」按钮",
+}
+
+
+def label_for_queue_row(row: dict[str, str], progress_by_key: dict, progress_by_masked: dict) -> dict[str, str]:
+    masked = row.get("masked_name", "")
+    real = row.get("real_name", "")
+    id8 = row.get("id_last8", "")
+    queue_status = row.get("queue_status", "")
+    match_status = row.get("match_status", "")
+
+    progress_row: dict[str, str] | None = None
+    if real and id8:
+        progress_row = progress_by_key.get((real, id8))
+    if progress_row is None and masked:
+        progress_row = progress_by_masked.get(masked)
+    pstatus = progress_row.get("status", "") if progress_row else ""
+
+    if pstatus == "completed":
+        return {"display": "已开票", "tone": "ok", "reason": "总进度表已完成"}
+    if pstatus == "no_ticket":
+        return {"display": "无可开票", "tone": "muted", "reason": "12306 未查询到可开发票客票"}
+    if pstatus == "in_progress" or queue_status == "clicked":
+        return {"display": "处理中", "tone": "info", "reason": "脚本正在处理这行"}
+    if pstatus == "failed":
+        return {"display": "失败", "tone": "bad", "reason": "上次运行未完成"}
+    if pstatus == "error":
+        return {"display": "运行错误", "tone": "bad", "reason": "脚本异常"}
+
+    if match_status in MATCH_REASON:
+        return {"display": "识别问题", "tone": "warn", "reason": MATCH_REASON[match_status]}
+    if match_status == "runtime_error":
+        return {"display": "运行错误", "tone": "bad", "reason": "上次处理异常"}
+    if match_status == "skip_progress":
+        return {"display": "已处理", "tone": "muted", "reason": "进度表已记录，跳过"}
+    if match_status == "resume_in_progress":
+        return {"display": "继续中", "tone": "info", "reason": "上次未完成，本次继续"}
+
+    if queue_status == "pending":
+        return {"display": "待处理", "tone": "pending", "reason": ""}
+    if queue_status == "skipped":
+        return {"display": "跳过", "tone": "muted", "reason": match_status or ""}
+    return {"display": queue_status or "未知", "tone": "muted", "reason": match_status or ""}
+
+
+def status_payload() -> dict[str, object]:
+    roster = csv_rows(invoice_tool.ROSTER_CSV)
+    progress = csv_rows(invoice_tool.PROGRESS_CSV)
+    queue_raw = csv_rows(invoice_tool.PAGE_QUEUE_CSV)
+    by_person_key = {
+        (row.get("real_name", ""), row.get("id_last8", "")): row
+        for row in progress
+        if row.get("real_name") or row.get("id_last8")
+    }
+    by_real_name = {row.get("real_name", ""): row for row in progress if row.get("real_name")}
+    by_masked = {row.get("masked_name", ""): row for row in progress if row.get("masked_name")}
+    roster_status = []
+    counts = {"total": len(roster), "completed": 0, "failed": 0, "in_progress": 0, "pending": 0}
+
+    queue = []
+    for row in queue_raw:
+        label = label_for_queue_row(row, by_person_key, by_masked)
+        item = dict(row)
+        item["display_status"] = label["display"]
+        item["display_tone"] = label["tone"]
+        item["display_reason"] = label["reason"]
+        queue.append(item)
+
+    counts["no_ticket"] = 0
+    for person in roster:
+        person_key = (person.get("姓名", ""), person.get("身份证后8位", ""))
+        progress_row = by_person_key.get(person_key) or by_real_name.get(person.get("姓名", ""))
+        status = progress_row.get("status", "pending") if progress_row else "pending"
+        label = PROGRESS_LABELS.get(status, {"text": status or "未操作", "tone": "pending", "reason": ""})
+        if status == "completed":
+            counts["completed"] += 1
+        elif status == "no_ticket":
+            counts["no_ticket"] += 1
+        elif status in {"failed", "error"}:
+            counts["failed"] += 1
+        elif status == "in_progress":
+            counts["in_progress"] += 1
+        else:
+            counts["pending"] += 1
+        roster_status.append(
+            {
+                "name": person.get("姓名", ""),
+                "id_last8": person.get("身份证后8位", ""),
+                "status": status,
+                "display_status": label["text"],
+                "display_tone": label["tone"],
+                "masked_name": progress_row.get("masked_name", "") if progress_row else "",
+                "updated_at": progress_row.get("updated_at", "") if progress_row else "",
+            }
+        )
+
+    with RUNNER_LOCK:
+        running = RUNNER is not None and RUNNER.poll() is None
+        return_code = None if RUNNER is None else RUNNER.poll()
+
+    log_tail = ""
+    if RUNNER_LOG.exists():
+        log_tail = "\n".join(RUNNER_LOG.read_text(encoding="utf-8", errors="ignore").splitlines()[-80:])
+
+    runner_status = "running" if running else "stopped"
+    if (not running) and return_code not in (None, 0):
+        runner_status = "failed"
+
+    config = invoice_tool.load_config(invoice_tool.CONFIG_LOCAL_PATH)
+    return {
+        "counts": counts,
+        "roster": roster_status,
+        "queue": queue,
+        "progress": progress,
+        "runner": {"running": running, "status": runner_status, "return_code": return_code, "log_tail": log_tail},
+        "device": device_status(),
+        "config": {
+            "company_title": config.company_title,
+            "tax_id": config.tax_id,
+            "receiver_email": config.receiver_email,
+            "invoice_output_dir": config.invoice_output_dir,
+            "invoice_success_action": config.invoice_success_action,
+            "invoice_output_absolute_dir": str(invoice_tool.project_path(config.invoice_output_dir)),
+        },
+        "files": {
+            "roster": str(invoice_tool.ROSTER_CSV),
+            "progress": str(invoice_tool.PROGRESS_CSV),
+            "queue": str(invoice_tool.PAGE_QUEUE_CSV),
+        },
+    }
+
+
+def save_invoice_settings(invoice_success_action: str, invoice_output_dir: str) -> dict[str, object]:
+    allowed_actions = {"download", "email", "continue"}
+    action = invoice_success_action if invoice_success_action in allowed_actions else "download"
+    output_dir = invoice_output_dir.strip() or "output/invoices"
+    config_path = invoice_tool.CONFIG_LOCAL_PATH
+    data: dict[str, object] = {}
+    if config_path.exists():
+        data = json.loads(config_path.read_text(encoding="utf-8"))
+    data["invoice_success_action"] = action
+    data["invoice_output_dir"] = output_dir
+    config_path.write_text(json.dumps(data, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+    project_dir = invoice_tool.project_path(output_dir)
+    project_dir.mkdir(parents=True, exist_ok=True)
+    return {"saved": True, "invoice_success_action": action, "invoice_output_dir": output_dir, "absolute_dir": str(project_dir)}
+
+
+def start_runner(max_batches: int, max_actions: int, send_email: bool, fast: bool, dry_run: bool = False, scroll_top_first: bool = True, mode: str = "native", invoice_success_action: str = "", invoice_output_dir: str = "") -> dict[str, object]:
+    global RUNNER
+    with RUNNER_LOCK:
+        if RUNNER is not None and RUNNER.poll() is None:
+            return {"started": False, "reason": "runner_already_running"}
+        RUNNER_LOG.parent.mkdir(parents=True, exist_ok=True)
+        RUNNER_LOG.write_text("", encoding="utf-8")
+        log_fh = RUNNER_LOG.open("a", encoding="utf-8")
+
+        prelude: list[str] = []
+        if scroll_top_first:
+            top_result = subprocess.run(
+                [PYTHON, "scripts/invoice_tool.py", "android-page-top"],
+                cwd=PROJECT_ROOT, capture_output=True, text=True, check=False,
+            )
+            log_fh.write(f"[prelude] android-page-top rc={top_result.returncode}\n{top_result.stdout}{top_result.stderr}\n")
+            log_fh.flush()
+            prelude.append(f"scroll_top: {top_result.stdout.strip().splitlines()[-1] if top_result.stdout.strip() else 'no_output'}")
+
+        if mode == "h5":
+            sub_cmd = "android-h5-page-run"
+        else:
+            sub_cmd = "android-vision-page-run"
+
+        cmd = [PYTHON, "-u", "scripts/invoice_tool.py", sub_cmd, "--max-batches", str(max_batches)]
+        if max_actions > 0:
+            cmd += ["--max-actions", str(max_actions)]
+        if send_email:
+            cmd.append("--send-email")
+        if invoice_success_action:
+            cmd += ["--invoice-success-action", invoice_success_action]
+        if invoice_output_dir:
+            cmd += ["--invoice-output-dir", invoice_output_dir]
+        if fast:
+            cmd.append("--fast")
+        if dry_run:
+            cmd.append("--dry-run")
+        RUNNER = subprocess.Popen(cmd, cwd=PROJECT_ROOT, stdout=log_fh, stderr=subprocess.STDOUT, text=True)
+        return {"started": True, "pid": RUNNER.pid, "cmd": cmd, "prelude": prelude, "mode": mode}
+
+
+def stop_runner() -> dict[str, object]:
+    global RUNNER
+    with RUNNER_LOCK:
+        if RUNNER is None or RUNNER.poll() is not None:
+            return {"stopped": False, "reason": "runner_not_running"}
+        RUNNER.terminate()
+        for _ in range(10):
+            if RUNNER.poll() is not None:
+                return {"stopped": True}
+            time.sleep(0.2)
+        RUNNER.kill()
+        return {"stopped": True, "killed": True}
+
+
+def build_vision_page_queue() -> dict[str, object]:
+    """用视觉 API 截屏识别当前页乘客,匹配名单+进度,返回队列数据。"""
+    try:
+        parsed = invoice_tool.vision_list_rows()
+    except Exception as exc:
+        return {"error": str(exc), "rows": [], "meta": f"视觉识别失败: {exc}"}
+
+    if not parsed.get("page_ok"):
+        return {"error": "not_on_list_page", "rows": [], "meta": "当前不在扫码开票单列表页"}
+
+    rows = parsed.get("rows") or []
+    roster = invoice_tool.read_roster()
+    skip_names = invoice_tool.progress_names({"completed", "no_ticket", "failed", "in_progress"})
+    queue = []
+    for row in rows:
+        masked = row.get("masked_name", "")
+        id_first = row.get("id_first", "") or ""
+        id_last = row.get("id_last", "") or ""
+
+        real = ""
+        id8 = ""
+        if masked in skip_names:
+            status, tone, reason = "已处理", "muted", "进度表已完成或跳过"
+        else:
+            matches = invoice_tool.match_roster(masked, roster, id_first, id_last)
+            if not matches and (id_first or id_last):
+                matches = invoice_tool.match_roster(masked, roster)
+            if len(matches) == 1:
+                status, tone, reason = "待处理", "pending", f"匹配: {matches[0].get('姓名', '')}"
+                real = matches[0].get("姓名", "")
+                id8 = matches[0].get("身份证后8位", "")
+            elif len(matches) > 1:
+                status, tone, reason = "识别问题", "warn", f"同名 {len(matches)} 人"
+            else:
+                status, tone, reason = "识别问题", "warn", "不在名单中"
+
+        queue.append({
+            "masked_name": masked,
+            "real_name": real,
+            "id_last8": id8,
+            "id_first": id_first,
+            "id_last": id_last,
+            "display_status": status,
+            "display_tone": tone,
+            "display_reason": reason,
+        })
+
+    # 同步写入 page_queue CSV,防止定时 refresh() 覆盖
+    now = invoice_tool.datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+    csv_rows = []
+    for q in queue:
+        csv_rows.append({
+            "page_id": f"vision_{now}",
+            "masked_name": q["masked_name"],
+            "id_first": q.get("id_first", ""),
+            "id_last": q.get("id_last", ""),
+            "real_name": q.get("real_name", ""),
+            "id_last8": q.get("id_last8", ""),
+            "button_bounds": "",
+            "match_status": "matched" if q["display_tone"] == "pending" else "skip_progress",
+            "queue_status": "pending" if q["display_tone"] == "pending" else "skipped",
+            "attempts": "0",
+            "updated_at": now,
+        })
+    invoice_tool.write_page_queue(csv_rows)
+
+    return {
+        "rows": queue,
+        "meta": f"本页 {len(rows)} 人 · scroll={parsed.get('scroll_position', '?')} · pending={sum(1 for q in queue if q['display_tone'] == 'pending')}",
+        "scroll_position": parsed.get("scroll_position"),
+    }
+
+
+def launch_railway_app() -> dict[str, object]:
+    result = invoice_tool.run_adb(
+        ["shell", "monkey", "-p", "com.MobileTicket", "-c", "android.intent.category.LAUNCHER", "1"],
+        check=False,
+    )
+    if result.returncode == 0:
+        time.sleep(1)
+    return {
+        "return_code": result.returncode,
+        "stdout": result.stdout.strip(),
+        "stderr": result.stderr.strip(),
+        "package": "com.MobileTicket",
+        "device": device_status(),
+    }
+
+
+INDEX_HTML = r"""<!doctype html>
+<html lang="zh-CN">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>铁路系统发票批量开票</title>
+  <style>
+    :root { color-scheme: light; --blue: #2563eb; --green: #16803c; --red: #b42318; --amber: #a15c00; --border: #d7dee8; }
+    body { margin: 0; font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; background: #f5f7fa; color: #1f2937; }
+    header { background: #fff; border-bottom: 1px solid var(--border); padding: 18px 24px; display: flex; align-items: center; justify-content: space-between; gap: 16px; }
+    h1 { font-size: 20px; margin: 0; letter-spacing: 0; }
+    .statusbar { display: flex; flex-wrap: wrap; gap: 8px; justify-content: flex-end; align-items: center; }
+    .pill { border: 1px solid var(--border); border-radius: 999px; padding: 4px 10px; background: #fff; color: #4b5563; font-size: 13px; }
+    .pill.ok { background: #dcfce7; color: var(--green); border-color: #bbf7d0; }
+    .pill.warn { background: #fef3c7; color: var(--amber); border-color: #fde68a; }
+    .pill.bad { background: #fee2e2; color: var(--red); border-color: #fecaca; }
+    main { padding: 20px 24px 40px; display: grid; gap: 16px; }
+    section { background: #fff; border: 1px solid var(--border); border-radius: 8px; padding: 16px; }
+    h2 { font-size: 16px; margin: 0 0 12px; }
+    .stats { display: grid; grid-template-columns: repeat(auto-fit, minmax(120px, 1fr)); gap: 12px; }
+    .stat { border: 1px solid var(--border); border-radius: 8px; padding: 12px; background: #fbfcfe; }
+    .stat b { display: block; font-size: 24px; margin-bottom: 4px; }
+    .controls { display: flex; flex-wrap: wrap; gap: 10px; align-items: center; }
+    button, input::file-selector-button { border: 1px solid var(--border); background: #fff; border-radius: 6px; padding: 8px 12px; font-size: 14px; cursor: pointer; }
+    button.primary { background: var(--blue); color: #fff; border-color: var(--blue); }
+    button.danger { color: #fff; background: var(--red); border-color: var(--red); }
+    input[type="number"] { width: 72px; padding: 8px; border: 1px solid var(--border); border-radius: 6px; }
+    input[type="text"], select { padding: 8px; border: 1px solid var(--border); border-radius: 6px; background: #fff; }
+    .path-input { min-width: 360px; flex: 1 1 360px; }
+    label { font-size: 14px; color: #374151; }
+    table { width: 100%; border-collapse: collapse; font-size: 13px; }
+    th, td { border-bottom: 1px solid #edf0f5; text-align: left; padding: 8px; white-space: nowrap; }
+    th { background: #f8fafc; position: sticky; top: 0; }
+    .table-wrap { max-height: 430px; overflow: auto; border: 1px solid var(--border); border-radius: 8px; }
+    .queue-title { display: flex; align-items: flex-start; justify-content: space-between; gap: 12px; }
+    .queue-title-main { min-width: 0; }
+    .queue-actions { display: flex; flex: 0 0 auto; gap: 6px; }
+    .queue-actions button { font-size: 12px; padding: 4px 10px; white-space: nowrap; }
+    .queue-table { min-width: 620px; }
+    .badge { display: inline-block; padding: 2px 10px; border-radius: 999px; font-size: 12px; background: #e5e7eb; color: #4b5563; }
+    .badge.tone-ok { background: #dcfce7; color: var(--green); }
+    .badge.tone-bad { background: #fee2e2; color: var(--red); }
+    .badge.tone-warn { background: #fef3c7; color: var(--amber); }
+    .badge.tone-info { background: #dbeafe; color: var(--blue); }
+    .badge.tone-muted { background: #f3f4f6; color: #4b5563; }
+    .badge.tone-pending { background: #f3f4f6; color: #6b7280; border: 1px dashed #d1d5db; }
+    .reason-cell { color: #6b7280; font-size: 12px; max-width: 280px; white-space: normal; }
+    .dropzone { border: 2px dashed #c7d2e0; border-radius: 8px; padding: 14px 16px; background: #fbfcfe; display: flex; align-items: center; gap: 12px; cursor: pointer; transition: all 0.15s; flex: 1 1 320px; min-width: 280px; }
+    .dropzone:hover { border-color: var(--blue); background: #f0f6ff; }
+    .dropzone.dragover { border-color: var(--blue); background: #e0ecff; border-style: solid; }
+    .dropzone-text { font-size: 13px; color: #4b5563; flex: 1; }
+    .dropzone strong { color: #1f2937; }
+    .dropzone input[type=file] { display: none; }
+    .paste-zone { border: 2px dashed #c7d2e0; border-radius: 8px; padding: 14px 16px; background: #fbfcfe; cursor: pointer; transition: all 0.15s; text-align: center; outline: none; margin-top: 10px; }
+    .paste-zone:hover, .paste-zone:focus { border-color: var(--blue); background: #f0f6ff; }
+    .paste-zone.success { border-color: var(--green); background: #dcfce7; border-style: solid; }
+    .paste-zone.error { border-color: var(--red); background: #fee2e2; border-style: solid; }
+    .paste-zone-text { font-size: 13px; color: #4b5563; }
+    .paste-zone strong { color: #1f2937; }
+    .qr-result { display: flex; align-items: center; gap: 10px; margin-top: 10px; padding: 10px 14px; background: #f0f6ff; border: 1px solid #bbd6fe; border-radius: 8px; flex-wrap: wrap; }
+    .qr-result code { flex: 1; font-size: 13px; word-break: break-all; color: #1e40af; background: transparent; padding: 0; min-width: 200px; }
+    pre { margin: 0; background: #111827; color: #e5e7eb; padding: 12px; border-radius: 8px; max-height: 260px; overflow: auto; font-size: 12px; }
+    .muted { color: #6b7280; font-size: 13px; }
+    .grid2 { display: grid; grid-template-columns: minmax(0, 1fr) minmax(0, 1fr); gap: 16px; }
+    @media (max-width: 900px) { .stats, .grid2 { grid-template-columns: 1fr; } header { align-items: flex-start; flex-direction: column; } }
+  </style>
+</head>
+<body>
+  <header>
+    <h1>铁路系统发票批量开票</h1>
+    <div class="statusbar">
+      <span class="pill" id="runnerState">读取中</span>
+      <span class="pill" id="deviceState">手机状态读取中</span>
+      <span class="pill" id="deviceApp">当前 App 读取中</span>
+    </div>
+  </header>
+  <main>
+    <section>
+      <h2>名单上传与运行</h2>
+      <div class="controls">
+        <label class="dropzone" id="dropzone">
+          <input type="file" id="rosterFile" name="file" accept=".xlsx,.xlsm,.csv">
+          <span class="dropzone-text"><strong>拖拽名单</strong>到此处，或点击选择文件 <span class="muted">(.xlsx / .xlsm / .csv)</span><br><span class="muted" id="dropzoneHint">未选择文件</span></span>
+        </label>
+        <button id="launch12306">启动 12306</button>
+        <button id="reopenQr">重新进入开票页</button>
+        <button id="buildQueue">抓当前页队列</button>
+        <label>最多页数 <input id="maxBatches" type="number" min="1" max="200" value="20"></label>
+        <label>最多 N 人 <input id="maxActions" type="number" min="0" max="200" value="0" title="0 = 不限"></label>
+        <label><input id="sendEmail" type="checkbox"> 兼容旧流程：发送邮箱</label>
+        <label><input id="fast" type="checkbox" checked> 快速模式</label>
+        <label><input id="dryRun" type="checkbox"> dry-run</label>
+        <label><input id="scrollTopFirst" type="checkbox"> 开始前回顶</label>
+        <label>模式 <select id="runMode"><option value="native">列表页(视觉)</option><option value="h5">H5开票单</option></select></label>
+        <button class="primary" id="startRun">开始运行</button>
+        <button class="danger" id="stopRun">停止</button>
+        <button id="scrollTop">回到顶部</button>
+        <button id="nextPage">上滑下一页</button>
+      </div>
+      <div class="paste-zone" id="pasteZone" tabindex="0">
+        <span class="paste-zone-text"><strong>📋 粘贴二维码截图</strong> — 在此处 Ctrl+V / Cmd+V 粘贴<br><span class="muted" id="pasteHint">支持截图中的二维码自动识别，解码后可在手机打开</span></span>
+        <img id="qrPreview" style="display:none; max-width:180px; max-height:180px; border-radius:6px; margin-top:8px; border:1px solid var(--border);">
+      </div>
+      <div id="qrResult" style="display:none;" class="qr-result">
+        <code id="qrUrl"></code>
+        <button id="openOnPhone">📱 在手机打开</button>
+        <button id="copyQrUrl">📋 复制链接</button>
+      </div>
+      <p class="muted" id="message"></p>
+    </section>
+
+    <section>
+      <h2>保存设置</h2>
+      <div class="controls">
+        <label>开票成功后
+          <select id="invoiceSuccessAction">
+            <option value="download">下载 PDF/OFD/XML 到电脑</option>
+            <option value="email">发送至邮箱</option>
+            <option value="continue">仅继续开票</option>
+          </select>
+        </label>
+        <label>保存目录 <input id="invoiceOutputDir" class="path-input" type="text" placeholder="output/invoices"></label>
+        <button id="saveSettings">保存设置</button>
+      </div>
+      <p class="muted" id="settingsHint">保存目录可填相对项目路径或绝对路径。</p>
+    </section>
+
+    <section class="stats">
+      <div class="stat"><b id="total">0</b><span>名单人数</span></div>
+      <div class="stat"><b id="completed">0</b><span>已开票</span></div>
+      <div class="stat"><b id="noTicket">0</b><span>无可开票</span></div>
+      <div class="stat"><b id="failed">0</b><span>失败</span></div>
+      <div class="stat"><b id="inProgress">0</b><span>处理中</span></div>
+      <div class="stat"><b id="pending">0</b><span>未操作</span></div>
+    </section>
+
+    <div class="grid2">
+      <section>
+        <h2 class="queue-title"><span class="queue-title-main">当前页队列 <span class="muted" id="queueMeta"></span></span><span class="queue-actions"><button id="markCheckedDone">✅ 标记已完成</button><button id="refreshQueue">🔄 刷新当前页</button></span></h2>
+        <div class="table-wrap"><table class="queue-table"><thead><tr><th>✓</th><th>状态</th><th>原因</th><th>脱敏名</th><th>姓名</th><th>后8位</th></tr></thead><tbody id="queueBody"></tbody></table></div>
+      </section>
+      <section>
+        <h2>运行日志</h2>
+        <pre id="log"></pre>
+      </section>
+    </div>
+
+    <section>
+      <h2>总进度 <a class="muted" href="/api/progress-csv" target="_blank">下载进度表</a></h2>
+      <div class="table-wrap"><table><thead><tr><th>状态</th><th>姓名</th><th>脱敏名</th><th>身份证后8位</th><th>更新时间</th></tr></thead><tbody id="rosterBody"></tbody></table></div>
+    </section>
+  </main>
+  <script>
+    const $ = (id) => document.getElementById(id);
+    let settingsDirty = false;
+    function h(value) {
+      return String(value ?? '').replace(/[&<>"']/g, c => ({'&':'&amp;', '<':'&lt;', '>':'&gt;', '"':'&quot;', "'":'&#39;'}[c]));
+    }
+    function badge(text, tone) {
+      const cls = tone ? `tone-${tone}` : 'tone-pending';
+      return `<span class="badge ${cls}">${h(text || '未操作')}</span>`;
+    }
+    async function api(path, options={}) {
+      const res = await fetch(path, options);
+      const data = await res.json();
+      if (!res.ok) throw new Error(data.error || res.statusText);
+      return data;
+    }
+    async function refresh() {
+      const data = await api('/api/status');
+      $('total').textContent = data.counts.total;
+      $('completed').textContent = data.counts.completed;
+      $('noTicket').textContent = data.counts.no_ticket || 0;
+      $('failed').textContent = data.counts.failed;
+      $('inProgress').textContent = data.counts.in_progress;
+      $('pending').textContent = data.counts.pending;
+      $('runnerState').textContent = data.runner.status === 'running' ? '运行中' : (data.runner.status === 'failed' ? '异常退出' : '已停止');
+      $('runnerState').className = data.runner.status === 'running' ? 'pill ok' : (data.runner.status === 'failed' ? 'pill bad' : 'pill');
+      $('deviceState').textContent = data.device.connected ? '手机已连接' : '手机未连接';
+      $('deviceState').className = data.device.connected ? 'pill ok' : 'pill bad';
+      $('deviceApp').textContent = data.device.message || '';
+      $('deviceApp').className = data.device.in_12306 ? 'pill ok' : (data.device.connected ? 'pill warn' : 'pill bad');
+      if (data.config) {
+        if (!settingsDirty && document.activeElement !== $('invoiceOutputDir')) {
+          $('invoiceSuccessAction').value = data.config.invoice_success_action || 'download';
+          $('invoiceOutputDir').value = data.config.invoice_output_dir || 'output/invoices';
+          $('sendEmail').checked = (data.config.invoice_success_action || 'download') === 'email';
+        }
+        $('settingsHint').textContent = `当前保存到：${data.config.invoice_output_absolute_dir || data.config.invoice_output_dir || 'output/invoices'}`;
+      }
+      $('log').textContent = data.runner.log_tail || '';
+      $('queueBody').innerHTML = data.queue.map((r, i) => `<tr><td><input type="checkbox" class="queueCb" data-idx="${i}" data-masked="${h(r.masked_name)}" data-real="${h(r.real_name)}" data-id8="${h(r.id_last8)}"></td><td>${badge(r.display_status, r.display_tone)}</td><td class="reason-cell">${h(r.display_reason)}</td><td>${h(r.masked_name)}</td><td>${h(r.real_name)}</td><td>${h(r.id_last8)}</td></tr>`).join('');
+      const queueCounts = data.queue.reduce((acc, r) => { acc[r.display_status] = (acc[r.display_status] || 0) + 1; return acc; }, {});
+      $('queueMeta').textContent = data.queue.length ? `本页 ${data.queue.length} 人 · ` + Object.entries(queueCounts).map(([k,v]) => `${k} ${v}`).join(' / ') : '尚未抓取本页队列';
+      $('rosterBody').innerHTML = data.roster.map(r => `<tr><td>${badge(r.display_status, r.display_tone)}</td><td>${h(r.name)}</td><td>${h(r.masked_name)}</td><td>${h(r.id_last8)}</td><td>${h(r.updated_at)}</td></tr>`).join('');
+    }
+    function summarize(path, data) {
+      try {
+        if (path === '/api/launch-12306') {
+          if (data && data.device && data.device.in_12306) return '12306 已启动并位于前台';
+          if (data && data.return_code === 0) return '已发送启动指令';
+          return '启动失败：' + (data && (data.stderr || data.stdout) || '未知错误');
+        }
+        if (path === '/api/build-queue') {
+          const stdout = (data && data.stdout) || '';
+          const rowsMatch = stdout.match(/rows=(\d+) pending=(\d+)/);
+          if (rowsMatch) return `已抓取本页 ${rowsMatch[1]} 人，pending ${rowsMatch[2]} 待处理`;
+          if (data && data.return_code !== 0) return '抓队列失败：' + ((data.stderr || '').split('\n').pop() || '未知');
+          return '已抓取队列';
+        }
+        if (path === '/api/start') {
+          if (data && data.started) {
+            const prelude = (data.prelude || []).join(' | ');
+            return `已开始运行 (PID ${data.pid})${prelude ? ' — ' + prelude : ''}`;
+          }
+          if (data && data.reason === 'runner_already_running') return '已在运行中，无需重复启动';
+          return '启动失败';
+        }
+        if (path === '/api/stop') {
+          if (data && data.stopped) return data.killed ? '已强制停止' : '已停止';
+          if (data && data.reason === 'runner_not_running') return '当前没有运行中的批处理';
+          return '停止失败';
+        }
+        if (path === '/api/next-page') {
+          if (data && data.return_code === 0) return '已上滑下一页';
+          return '翻页失败：' + ((data && data.stderr || '').split('\n').pop() || '未知');
+        }
+        if (path === '/api/scroll-top') {
+          const stdout = (data && data.stdout) || '';
+          const m = stdout.match(/at_top iterations=(\d+)/);
+          if (m) return `已回到顶部 (滑了 ${m[1]} 次)`;
+          if (stdout.includes('max_iterations_reached')) return '已尽量回顶,但未稳定 — 请人工检查';
+          return '回顶部失败：' + ((data && data.stderr || '').split('\n').pop() || '未知');
+        }
+        if (path === '/api/upload-roster') {
+          const stdout = (data && data.stdout) || '';
+          const rowsMatch = stdout.match(/roster_rows=(\d+)/);
+          if (rowsMatch) return `名单已上传并导入，共 ${rowsMatch[1]} 条`;
+          if (data && data.return_code !== 0) return '导入失败：' + ((data.stderr || '').split('\n').pop() || '未知');
+          return '名单已上传';
+        }
+      } catch (e) { /* fall through */ }
+      return '操作完成';
+    }
+    async function postJson(path, body={}) {
+      const data = await api(path, { method: 'POST', headers: {'Content-Type': 'application/json'}, body: JSON.stringify(body) });
+      $('message').textContent = summarize(path, data);
+      await refresh();
+    }
+    async function uploadRoster(file) {
+      if (!file) return;
+      $('dropzoneHint').textContent = `上传中：${file.name}`;
+      const form = new FormData();
+      form.append('file', file, file.name);
+      const res = await fetch('/api/upload-roster', { method: 'POST', body: form });
+      const data = await res.json();
+      $('message').textContent = summarize('/api/upload-roster', data);
+      $('dropzoneHint').textContent = `已选：${file.name}`;
+      await refresh();
+    }
+    const dropzone = $('dropzone');
+    const rosterInput = $('rosterFile');
+    rosterInput.addEventListener('change', () => uploadRoster(rosterInput.files[0]));
+    ['dragenter', 'dragover'].forEach(evt => dropzone.addEventListener(evt, (e) => {
+      e.preventDefault(); e.stopPropagation(); dropzone.classList.add('dragover');
+    }));
+    ['dragleave', 'drop'].forEach(evt => dropzone.addEventListener(evt, (e) => {
+      e.preventDefault(); e.stopPropagation(); dropzone.classList.remove('dragover');
+    }));
+    dropzone.addEventListener('drop', (e) => {
+      const files = e.dataTransfer && e.dataTransfer.files;
+      if (!files || !files.length) return;
+      const file = files[0];
+      if (!/\.(xlsx|xlsm|csv)$/i.test(file.name)) {
+        $('message').textContent = '只支持 .xlsx / .xlsm / .csv';
+        return;
+      }
+      uploadRoster(file);
+    });
+    $('launch12306').onclick = async () => {
+      await postJson('/api/launch-12306');
+      setTimeout(refresh, 1000);
+    };
+    $('reopenQr').onclick = async () => {
+      $('message').textContent = '正在手机重新进入开票页...';
+      const data = await api('/api/reopen-qr', { method: 'POST', headers: {'Content-Type': 'application/json'}, body: '{}' });
+      $('message').textContent = data.reopened ? '已重新进入' : '重进失败: 请先在粘贴区解码一个二维码';
+      await refresh();
+    };
+    $('buildQueue').onclick = () => postJson('/api/build-queue');
+    $('markCheckedDone').onclick = async () => {
+      const cbs = document.querySelectorAll('.queueCb:checked');
+      if (!cbs.length) { $('message').textContent = '请先勾选要标记的人'; return; }
+      const names = Array.from(cbs).map(cb => ({ masked: cb.dataset.masked, real: cb.dataset.real, id8: cb.dataset.id8 }));
+      $('message').textContent = `正在标记 ${names.length} 人...`;
+      try {
+        const res = await fetch('/api/mark-completed', {
+          method: 'POST', headers: {'Content-Type': 'application/json'},
+          body: JSON.stringify({ rows: names }),
+        });
+        const data = await res.json();
+        $('message').textContent = `已标记 ${data.marked || 0} 人为人工完成`;
+        await refresh();
+      } catch (err) {
+        $('message').textContent = '标记失败: ' + (err.message || '网络错误');
+      }
+    };
+    $('refreshQueue').onclick = async () => {
+      $('refreshQueue').textContent = '⏳ 识别中...';
+      $('refreshQueue').disabled = true;
+      try {
+        const data = await api('/api/vision-page-queue', { method: 'POST', headers: {'Content-Type': 'application/json'}, body: '{}' });
+        if (data.rows) {
+          $('queueBody').innerHTML = data.rows.map(r => `<tr><td>${badge(r.display_status, r.display_tone)}</td><td class="reason-cell">${h(r.display_reason)}</td><td>${h(r.masked_name)}</td><td>${h(r.real_name)}</td><td>${h(r.id_last8)}</td></tr>`).join('');
+          $('queueMeta').textContent = data.meta || '';
+          $('message').textContent = '已刷新: ' + (data.meta || '');
+        } else {
+          $('message').textContent = '刷新失败: ' + (data.error || '未知错误');
+        }
+      } catch (err) {
+        $('message').textContent = '刷新失败: ' + (err.message || '网络错误');
+      }
+      $('refreshQueue').textContent = '🔄 刷新当前页';
+      $('refreshQueue').disabled = false;
+    };
+    $('invoiceOutputDir').addEventListener('input', () => { settingsDirty = true; });
+    $('invoiceSuccessAction').onchange = () => { settingsDirty = true; $('sendEmail').checked = $('invoiceSuccessAction').value === 'email'; };
+    $('sendEmail').onchange = () => { settingsDirty = true; if ($('sendEmail').checked) $('invoiceSuccessAction').value = 'email'; };
+    $('saveSettings').onclick = async () => {
+      const data = await api('/api/settings', {
+        method: 'POST', headers: {'Content-Type': 'application/json'},
+        body: JSON.stringify({ invoice_success_action: $('invoiceSuccessAction').value, invoice_output_dir: $('invoiceOutputDir').value })
+      });
+      $('message').textContent = data.saved ? `设置已保存：${data.absolute_dir}` : '设置保存失败';
+      settingsDirty = false;
+      await refresh();
+    };
+    $('startRun').onclick = () => postJson('/api/start', { max_batches: Number($('maxBatches').value), max_actions: Number($('maxActions').value), send_email: $('sendEmail').checked, fast: $('fast').checked, dry_run: $('dryRun').checked, scroll_top_first: $('scrollTopFirst').checked, mode: $('runMode').value, invoice_success_action: $('invoiceSuccessAction').value, invoice_output_dir: $('invoiceOutputDir').value });
+    $('stopRun').onclick = () => postJson('/api/stop');
+    $('nextPage').onclick = () => postJson('/api/next-page');
+    $('scrollTop').onclick = () => postJson('/api/scroll-top');
+
+    // --- 粘贴二维码 ---
+    const pasteZone = $('pasteZone');
+    const pasteHint = $('pasteHint');
+    const qrPreview = $('qrPreview');
+    const qrResult = $('qrResult');
+    const qrUrl = $('qrUrl');
+    let lastDecodedUrl = '';
+
+    pasteZone.addEventListener('click', () => pasteZone.focus());
+
+    pasteZone.addEventListener('paste', async (e) => {
+      e.preventDefault();
+      const items = e.clipboardData && e.clipboardData.items;
+      if (!items) return;
+
+      let imageFile = null;
+      for (const item of items) {
+        if (item.type.startsWith('image/')) {
+          imageFile = item.getAsFile();
+          break;
+        }
+      }
+      if (!imageFile) {
+        pasteHint.textContent = '未检测到图片，请确认已截图并复制到剪贴板';
+        pasteZone.classList.add('error');
+        setTimeout(() => pasteZone.classList.remove('error'), 2000);
+        return;
+      }
+
+      // 显示预览
+      const reader = new FileReader();
+      reader.onload = async (ev) => {
+        const base64 = ev.target.result;
+        qrPreview.src = base64;
+        qrPreview.style.display = 'inline-block';
+        pasteHint.textContent = '解码中...';
+        pasteZone.classList.remove('error', 'success');
+        qrResult.style.display = 'none';
+
+        try {
+          const res = await fetch('/api/decode-qr', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ image: base64 }),
+          });
+          const data = await res.json();
+          if (data.results && data.results.length > 0) {
+            lastDecodedUrl = data.results[0];
+            qrUrl.textContent = lastDecodedUrl;
+            qrResult.style.display = 'flex';
+            pasteHint.textContent = `已识别 ${data.results.length} 个二维码`;
+            pasteZone.classList.add('success');
+            setTimeout(() => pasteZone.classList.remove('success'), 3000);
+          } else {
+            qrResult.style.display = 'none';
+            pasteHint.textContent = data.error || '未识别到二维码';
+            pasteZone.classList.add('error');
+            setTimeout(() => pasteZone.classList.remove('error'), 2000);
+          }
+        } catch (err) {
+          qrResult.style.display = 'none';
+          pasteHint.textContent = '解码请求失败: ' + (err.message || '网络错误');
+          pasteZone.classList.add('error');
+          setTimeout(() => pasteZone.classList.remove('error'), 2000);
+        }
+      };
+      reader.readAsDataURL(imageFile);
+    });
+
+    $('openOnPhone').onclick = async () => {
+      if (!lastDecodedUrl) return;
+      $('message').textContent = '正在手机打开...';
+      try {
+        const res = await fetch('/api/open-on-phone', {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({ url: lastDecodedUrl }),
+        });
+        const data = await res.json();
+        if (data.return_code === 0) {
+          $('message').textContent = '已在手机打开: ' + lastDecodedUrl;
+        } else {
+          $('message').textContent = '手机打开失败: ' + (data.stderr || data.stdout || '未知错误');
+        }
+        await refresh();
+      } catch (err) {
+        $('message').textContent = '请求失败: ' + (err.message || '网络错误');
+      }
+    };
+
+    $('copyQrUrl').onclick = () => {
+      if (!lastDecodedUrl) return;
+      navigator.clipboard.writeText(lastDecodedUrl).then(() => {
+        $('message').textContent = '链接已复制到剪贴板';
+      }).catch(() => {
+        $('message').textContent = '复制失败，请手动复制';
+      });
+    };
+
+    refresh();
+    setInterval(refresh, 2000);
+  </script>
+</body>
+</html>
+"""
+
+
+class Handler(BaseHTTPRequestHandler):
+    def log_message(self, fmt: str, *args: object) -> None:
+        return
+
+    def do_HEAD(self) -> None:
+        parsed = urlparse(self.path)
+        if parsed.path == "/":
+            body = INDEX_HTML.encode("utf-8")
+            self.send_response(200)
+            self.send_header("Content-Type", "text/html; charset=utf-8")
+            self.send_header("Content-Length", str(len(body)))
+            self.end_headers()
+        elif parsed.path == "/api/progress-csv" and invoice_tool.PROGRESS_CSV.exists():
+            self.send_response(200)
+            self.send_header("Content-Type", "text/csv; charset=utf-8")
+            self.send_header("Content-Disposition", f'attachment; filename="{invoice_tool.PROGRESS_CSV.name}"')
+            self.send_header("Content-Length", str(invoice_tool.PROGRESS_CSV.stat().st_size))
+            self.end_headers()
+        elif parsed.path == "/api/status":
+            self.send_response(200)
+            self.send_header("Content-Type", "application/json; charset=utf-8")
+            self.end_headers()
+        elif parsed.path in {"/api/decode-qr", "/api/open-on-phone", "/api/reopen-qr", "/api/vision-page-queue", "/api/mark-completed"}:
+            self.send_response(200)
+            self.send_header("Content-Type", "application/json; charset=utf-8")
+            self.end_headers()
+        else:
+            self.send_response(404)
+            self.end_headers()
+
+    def do_GET(self) -> None:
+        parsed = urlparse(self.path)
+        if parsed.path == "/":
+            body = INDEX_HTML.encode("utf-8")
+            self.send_response(200)
+            self.send_header("Content-Type", "text/html; charset=utf-8")
+            self.send_header("Content-Length", str(len(body)))
+            self.end_headers()
+            self.wfile.write(body)
+        elif parsed.path == "/api/status":
+            write_json(self, status_payload())
+        elif parsed.path == "/api/device-status":
+            write_json(self, device_status())
+        elif parsed.path == "/api/progress-csv":
+            self.send_file(invoice_tool.PROGRESS_CSV, "text/csv; charset=utf-8")
+        else:
+            write_json(self, {"error": "not_found"}, 404)
+
+    def do_POST(self) -> None:
+        parsed = urlparse(self.path)
+        try:
+            if parsed.path == "/api/upload-roster":
+                self.handle_upload_roster()
+            elif parsed.path == "/api/start":
+                body = self.read_json()
+                write_json(self, start_runner(
+                    int(body.get("max_batches", 20)),
+                    int(body.get("max_actions", 0)),
+                    bool(body.get("send_email", True)),
+                    bool(body.get("fast", True)),
+                    bool(body.get("dry_run", False)),
+                    bool(body.get("scroll_top_first", True)),
+                    str(body.get("mode", "native")),
+                    str(body.get("invoice_success_action", "")),
+                    str(body.get("invoice_output_dir", "")),
+                ))
+            elif parsed.path == "/api/stop":
+                write_json(self, stop_runner())
+            elif parsed.path == "/api/settings":
+                body = self.read_json()
+                write_json(self, save_invoice_settings(
+                    str(body.get("invoice_success_action", "download")),
+                    str(body.get("invoice_output_dir", "output/invoices")),
+                ))
+            elif parsed.path == "/api/launch-12306":
+                result = launch_railway_app()
+                write_json(self, result, 200 if result["return_code"] == 0 else 500)
+            elif parsed.path == "/api/build-queue":
+                result = subprocess.run([PYTHON, "scripts/invoice_tool.py", "android-build-page-queue"], cwd=PROJECT_ROOT, capture_output=True, text=True, check=False)
+                write_json(self, {"return_code": result.returncode, "stdout": result.stdout, "stderr": result.stderr}, 200 if result.returncode == 0 else 500)
+            elif parsed.path == "/api/next-page":
+                result = subprocess.run([PYTHON, "scripts/invoice_tool.py", "android-page-next", "--rebuild"], cwd=PROJECT_ROOT, capture_output=True, text=True, check=False)
+                write_json(self, {"return_code": result.returncode, "stdout": result.stdout, "stderr": result.stderr}, 200 if result.returncode == 0 else 500)
+            elif parsed.path == "/api/scroll-top":
+                result = subprocess.run([PYTHON, "scripts/invoice_tool.py", "android-page-top"], cwd=PROJECT_ROOT, capture_output=True, text=True, check=False)
+                write_json(self, {"return_code": result.returncode, "stdout": result.stdout, "stderr": result.stderr}, 200 if result.returncode == 0 else 500)
+            elif parsed.path == "/api/decode-qr":
+                self.handle_decode_qr()
+            elif parsed.path == "/api/open-on-phone":
+                self.handle_open_on_phone()
+            elif parsed.path == "/api/reopen-qr":
+                result = invoice_tool.reopen_qr_url()
+                write_json(self, {"reopened": result, "device": device_status()})
+            elif parsed.path == "/api/vision-page-queue":
+                write_json(self, build_vision_page_queue())
+            elif parsed.path == "/api/mark-completed":
+                self.handle_mark_completed()
+            else:
+                write_json(self, {"error": "not_found"}, 404)
+        except Exception as exc:
+            write_json(self, {"error": str(exc)}, 500)
+
+    def read_json(self) -> dict[str, object]:
+        length = int(self.headers.get("Content-Length", "0"))
+        if not length:
+            return {}
+        return json.loads(self.rfile.read(length).decode("utf-8"))
+
+    def send_file(self, path: Path, content_type: str) -> None:
+        if not path.exists():
+            write_json(self, {"error": "file_not_found", "file": str(path)}, 404)
+            return
+        body = path.read_bytes()
+        self.send_response(200)
+        self.send_header("Content-Type", content_type)
+        self.send_header("Content-Disposition", f'attachment; filename="{path.name}"')
+        self.send_header("Content-Length", str(len(body)))
+        self.end_headers()
+        self.wfile.write(body)
+
+    def handle_upload_roster(self) -> None:
+        form = cgi.FieldStorage(fp=self.rfile, headers=self.headers, environ={"REQUEST_METHOD": "POST", "CONTENT_TYPE": self.headers.get("Content-Type", "")})
+        item = form["file"]
+        filename = Path(item.filename or "roster.xlsx").name
+        UPLOAD_DIR.mkdir(parents=True, exist_ok=True)
+        dest = UPLOAD_DIR / filename
+        with dest.open("wb") as fh:
+            shutil.copyfileobj(item.file, fh)
+        result = subprocess.run([PYTHON, "scripts/invoice_tool.py", "import-roster", "--input", str(dest)], cwd=PROJECT_ROOT, capture_output=True, text=True, check=False)
+        write_json(self, {"file": str(dest), "return_code": result.returncode, "stdout": result.stdout, "stderr": result.stderr}, 200 if result.returncode == 0 else 500)
+
+    def handle_decode_qr(self) -> None:
+        body = self.read_json()
+        image_b64 = str(body.get("image", "")).strip()
+        if not image_b64:
+            write_json(self, {"results": [], "error": "未收到图片数据"}, 400)
+            return
+
+        # 去掉 data URL 前缀 (data:image/png;base64,...)
+        if "," in image_b64 and image_b64.startswith("data:"):
+            image_b64 = image_b64.split(",", 1)[1]
+
+        try:
+            image_bytes = base64.b64decode(image_b64)
+        except Exception:
+            write_json(self, {"results": [], "error": "图片数据解码失败，请重试"}, 400)
+            return
+
+        result = invoice_tool.decode_qr_image(image_bytes)
+        # 保存解码结果,供脚本自动重进使用
+        if result.get("results"):
+            invoice_tool.save_qr_url(result["results"][0])
+            result["qr_pushed"] = invoice_tool.generate_and_push_qr()
+            result["saved"] = True
+        write_json(self, dict(result))
+
+    def handle_mark_completed(self) -> None:
+        body = self.read_json()
+        rows = body.get("rows") or []
+        marked = 0
+        for item in rows:
+            masked = item.get("masked", "")
+            real = item.get("real", "")
+            id8 = item.get("id8", "")
+            if masked or real:
+                invoice_tool.update_progress(masked, real, id8, "completed")
+                marked += 1
+        write_json(self, {"marked": marked})
+
+    def handle_open_on_phone(self) -> None:
+        body = self.read_json()
+        url = str(body.get("url", "")).strip()
+        if not url:
+            write_json(self, {"return_code": -1, "stdout": "", "stderr": "未提供 URL", "device": device_status()}, 400)
+            return
+
+        adb_result = invoice_tool.run_adb(
+            ["shell", "am", "start", "-a", "android.intent.action.VIEW", "-d", url],
+            check=False,
+        )
+        time.sleep(0.5)
+        write_json(self, {
+            "return_code": adb_result.returncode,
+            "stdout": adb_result.stdout.strip(),
+            "stderr": adb_result.stderr.strip(),
+            "device": device_status(),
+        }, 200 if adb_result.returncode == 0 else 500)
+
+
+def main() -> None:
+    invoice_tool.ensure_dirs()
+    server = ThreadingHTTPServer(("127.0.0.1", 8765), Handler)
+    print("UI: http://127.0.0.1:8765")
+    server.serve_forever()
+
+
+if __name__ == "__main__":
+    main()
diff --git a/templates/android_flow.example.json b/templates/android_flow.example.json
new file mode 100644
index 0000000..4f5eee6
--- /dev/null
+++ b/templates/android_flow.example.json
@@ -0,0 +1,54 @@
+{
+  "description": "12306 App 开票页面示例流程。先用 android-dump 校准真实按钮文字或坐标后再复制修改。",
+  "steps": [
+    {
+      "action": "click_contains",
+      "text": "证件",
+      "after": 0.5
+    },
+    {
+      "action": "input_id8_for_visible_masked_name",
+      "after": 0.8
+    },
+    {
+      "action": "click_contains",
+      "text": "下一步",
+      "after": 1.2
+    },
+    {
+      "action": "click_contains",
+      "text": "抬头",
+      "after": 0.5
+    },
+    {
+      "action": "input_config",
+      "field": "company_title",
+      "after": 0.5
+    },
+    {
+      "action": "click_contains",
+      "text": "税号",
+      "after": 0.5
+    },
+    {
+      "action": "input_config",
+      "field": "tax_id",
+      "after": 0.5
+    },
+    {
+      "action": "click_contains",
+      "text": "邮箱",
+      "after": 0.5
+    },
+    {
+      "action": "input_config",
+      "field": "receiver_email",
+      "after": 0.5
+    },
+    {
+      "action": "click_contains",
+      "text": "开具",
+      "after": 2
+    }
+  ]
+}