## 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 / 本文件