## 2026-06-18 #chore scope:delivery - 整理最终交付目录

- Why: 交付前需要把最终 Excel、PDF 和同步报告集中到一处,PDF 文件名只保留带真实全名的版本,并按 PDF 正文姓名去重
- 产出: `out/all/5月22日成都北京5月18日对高二年级川渝研学_最终交付.xlsx`、`out/all/pdf/`、`out/all/pdf_manifest.csv`、`out/all/sync_out3_report.csv`
- 同步: `out/2/5月22日成都北京5月18日对高二年级川渝研学_已更新.xlsx` 的发票文件名列改为 `../all/pdf/...` 相对链接
- 备份: `out/2/5月22日成都北京5月18日对高二年级川渝研学_已更新.before_all_links_20260618_133435.xlsx`

## 2026-06-18 #chore scope:invoice-files - 同步手机补下载发票到最终表

- Why: 手机今天下载的发票需要补乘车人姓名到文件名,并只把最终表中尚未登记发票的人复制到 `out/22/`
- 产出: `out/22/` 新增 12 张缺失发票,`out/22/sync_out3_report.csv` 记录 25 张 PDF 的提取与同步结果
- 同步: `out/2/5月22日成都北京5月18日对高二年级川渝研学_已更新.xlsx` 更新 12 人为已出票并写入发票文件名
- 备份: `out/2/5月22日成都北京5月18日对高二年级川渝研学_已更新.before_out22_sync_20260618_125248.xlsx`

## 2026-06-18 #chore scope:invoice-status - 从最新总表生成待处理名单并同步状态

- Why: 手动下载补票后,需要以最新 `_已更新.xlsx` 为准排除已出票和无证件验证号人员,让后续自动化只处理剩余 44 人
- 产出: `out/2/待处理人名单_去已完成_去无证件验证号.csv`、`out/2/无证件验证号_已排除.csv`、`out/2/最新表格同步状态.csv`
- 同步: `work/passenger_roster.csv` 重建为 44 个待处理人,`work/android_invoice_progress.csv` 重建为 105 个 completed,`work/android_page_queue.csv` 和 `work/qr_page_order.csv` 清空旧队列/旧顺序
- 备份: `archive/status_sync_20260618_111408/`

## 2026-06-12 #chore scope:invoice-files - 批量给铁路发票文件名补乘车人姓名

- Why: QQ 邮箱归集出的 93 张 PDF 仅靠日期/金额/序号不便人工归档和核对,需要从发票正文提取姓名写入文件名
- 详见: scripts/add_invoice_passenger_name.py:1

## 2026-06-12 #fix scope:web-ui scope:android-h5-automation - UI 启动不按旧进度锚点续跑

- Why: 点开始后旧进度表里的最后处理人会触发 resume_seek,表现成先扫全表；UI 启动 H5 应从当前页边处理边建核查表
- 详见: scripts/web_ui.py:325

## 2026-06-12 #fix scope:android-h5-automation - 开始运行边处理边建立核查表

- Why: UI 点开始后不应先全量扫描到底；应从当前页开始处理,过程中陆续补齐本二维码核查表
- 详见: scripts/invoice_tool.py:1987

## 2026-06-12 #fix scope:web-ui - 启动前备份运行表并区分手动停止

- Why: 批处理运行前必须保留现场,用户手动停止不应显示为脚本失败
- 详见: scripts/web_ui.py:26, scripts/web_ui.py:273

## 2026-06-12 #fix scope:web-ui - 重启时清理散落 watchdog/server 进程

- Why: 多个 watchdog 会抢占端口并导致 UI 空响应
- 详见: scripts/restart_web_ui.sh:24

## 2026-06-12 #fix scope:android-h5-automation scope:web-ui - 固化批次/单位/复查/三表同步契约

- Why: 一个二维码一批、当前页为单位,复查只碰未成功项且保留失败原因
- 详见: scripts/invoice_tool.py:64, scripts/invoice_tool.py:524

## 2026-06-12 #fix scope:android-h5-automation - 复查回顶不再清空二维码核查表

- Why: 复查流程必须保留已开票/无票状态,只跳过已处理并重试失败或待处理项
- 详见: scripts/invoice_tool.py:2026

## 2026-06-12 #fix scope:android-h5-automation - resume_seek 滚动参与同屏到底检测

- Why: 断点续跑找不到锚点时也必须能用同屏重复判断到底并继续收尾
- 详见: scripts/invoice_tool.py:1955

## 2026-06-12 #fix scope:android-h5-automation - 失败重试允许用进度表身份兜底

- Why: 二次查缺时名单或视觉轻微不一致不能让失败项被 no_match 跳过
- 详见: scripts/invoice_tool.py:412, scripts/invoice_tool.py:1976

## 2026-06-12 #fix scope:android-h5-automation scope:web-ui - 二维码核查表实时同步进度

- Why: 长批次中断时也要保留当前二维码顺序、完成状态和失败项
- 详见: scripts/invoice_tool.py:416, scripts/web_ui.py:560

## 2026-06-12 #fix scope:web-ui scope:android-vision-automation - 网页默认走 H5 并补同屏到底兜底

- Why: 当前二维码开票单是 H5 单页,旧视觉路径会在底部同屏循环不触发收尾
- 详见: scripts/web_ui.py:270, scripts/invoice_tool.py:1646

## 2026-06-11 #feat scope:android-h5-automation scope:web-ui - H5 批处理后自动输出二维码顺序核查表

- Why: 跑完后人工核查失败项需要按列表顺序定位，而非按名单排序
- 详见: scripts/invoice_tool.py:441, scripts/invoice_tool.py:1220, scripts/web_ui.py:144, scripts/web_ui.py:632

## 2026-06-11 #fix scope:web-ui scope:android-h5-automation - 代理人验证码输入 + 二维码唯一文件名

- Why: 新扫码开票后会进入代办人身份核验页，且手机相册容易保留旧二维码
- 详见: scripts/web_ui.py:170, scripts/invoice_tool.py:40, scripts/invoice_tool.py:1416

## 2026-06-11 #fix scope:web-ui scope:android-h5-automation - 重进开票页改走扫码路径

- Why: 新批次二维码应走 12306 内部扫码链路,不能直接 intent 打开链接
- 详见: scripts/invoice_tool.py:1219, scripts/web_ui.py:795

## 2026-06-11 #feat scope:android-h5-automation - H5 到底后自动回顶查缺补漏

- Why: 列表跑完后仍需二次确认未成功项,并明确通知用户本轮已收尾
- 详见: scripts/invoice_tool.py:393, scripts/invoice_tool.py:1646

## 2026-06-11 #refactor scope:web-ui - 二维码批次入口靠近扫码区

- Why: 每组二维码切换是批次操作,入口应贴近截图粘贴区域减少误点
- 详见: scripts/web_ui.py:545

## 2026-06-11 #fix scope:web-ui - 用 watchdog 保活本地服务

- Why: Codex 启动的后台进程会被会话回收,需要独立父进程自动拉起
- 详见: scripts/restart_web_ui.sh:1, scripts/web_ui_watchdog.sh:1

## 2026-06-11 #chore scope:web-ui scope:docs - 增加稳定重启入口

- Why: 手动重启易让服务随终端退出,导致浏览器显示拒绝连接
- 详见: scripts/restart_web_ui.sh:1, docs/usage.md:91, INDEX.md:59

## 2026-06-11 #refactor scope:web-ui - 重排本地 UI 布局层级

- Why: 批量开票操作项过于拥挤,需按名单/参数/二维码分区降低误操作
- 详见: scripts/web_ui.py:386

## 2026-06-11 #fix scope:web-ui - 保存后当前路径即时跟随输入值

- Why: 用户需要看到“当前保存到”随保存动作立刻更新,而不是被轮询刷新打回
- 详见: scripts/web_ui.py:546, scripts/web_ui.py:715

## 2026-06-11 #fix scope:web-ui - 保存结果独立显示避免被刷新覆盖

- Why: 保存设置后的路径提示会被状态刷新覆盖,需要稳定可见的生效反馈
- 详见: scripts/web_ui.py:497, scripts/web_ui.py:705

## 2026-06-11 #fix scope:web-ui - 保存设置后显示生效路径

- Why: 用户点击保存目录后缺少明确反馈,容易误判设置没有生效
- 详见: scripts/web_ui.py:403, scripts/web_ui.py:704

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