# 铁路系统发票

铁路系统发票专项工作区，用于沉淀铁路系统相关发票资料、处理脚本、核对记录和衍生产出。

> 🤖 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)