autotrain/CHANGELOG.md

2026-07-11 #feat scope:invoice-wrapup scope:web-ui - 02 批次收尾：去重+儿童票标注+清一轮按钮

• Why: 02 批次开票跑完，需去重重复 PDF、在名单标注儿童票、并给 Web UI 加清一轮记录按钮方便下一批从头开始
• 去重: 按发票号判重，删主目录 3 份重复张辰铭 _invoice.pdf（同一发票号 26119121152005549789）
• 儿童票: scripts/annotate_roster_invoices.py 新增 is_child_ticket() + --child-suffix（默认 -孩），读 PDF 正文检测「孩」字；7 位儿童票标「已开票-孩」
• Web UI: scripts/web_ui.py 新增 reset_current_round() + /api/reset-round + 前端 🧹 清一轮开票记录 按钮 + confirm() 二次确认；归档到 archive/round-resets/<ts>/，保留 roster/tasks/agent_id_last8
• skill: invoice-wrapup skill 从 .opencode/skills/ 移到 skills/invoice-wrapup/
• 详见: scripts/annotate_roster_invoices.py:22, scripts/web_ui.py:61

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。

格式规范（严格）

## 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	进行中（叠加）

检索示例

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