qf-invoice-processor

## 〇、专家级路由（v2.1.0） **专家定位**：发票/票据批量识别汇总器——本地离线抽取结构化字段、一键出 13 列 Excel，以"金额与税号人工抽验后可入账"为验收标准。 **五维评估**： - 适用场景：①一批发票/收据 PDF·图片批量识别 ②抽字段导 Excel 汇总 ③区分专票/普票/数电票 - 能力边界：不做发票查验真伪（→税务平台）；不做会计入账凭证（→财务）；不做合同/公文 OCR（→textin-xparse） - 依赖资产：`scripts/invoice_tool.py`（ocr/excel 两子命令，禁改）、rapidocr-onnxruntime、PyMuPDF、Pillow、openpyxl - 交付质量：13 列汇总表、末行合计价税合计；电子发票 PDF 优先文字层；金额与税号人工抽验 - 性能表现：批量递归识别；数电票文字层准确率远高于 OCR **四级响应（L1-L4）**： - L1 轻量问答 → 直接答：支持票种/格式、字段清单、命令 - L2 标准任务 → 单命令出件：`ocr 目录 -o x.json` 或 `excel x.json -o x.xlsx` - L3 复杂任务 → 分步+质量门：ocr→excel→重点字段（金额/税号）抽验 - L4 专家任务 → 全流程+交付物：批量识别+Excel 汇总+核验表交接 **黄金窗口**：单批发票（目录递归）；模糊/倾斜件按提高 DPI 或裁剪重试处理。 **专家件索引**：`references/case-library.md`（批量识别场景案例）、`references/writing-templates.md`（汇总表字段说明/核验表/操作单）、`references/quality-checklist.md`（交付前质检），`scripts/invoice_tool.py`。 # Invoice Processor（发票/票据识别与汇总） 批量把发票 / 票据的 **PDF、图片** 识别成结构化数据，导出 **Excel 汇总表**。全程本地离线，不外传、不需要 API Key。 ## 环境（本沙箱已就绪） - 路径：本技能目录，主脚本 `scripts/invoice_tool.py` - 依赖：`rapidocr-onnxruntime`（本地 OCR，已装）、`PyMuPDF`（PDF→图）、`Pillow`、`numpy`、`openpyxl`（均可用） ## 何时使用 用户提到"发票 / 识别发票 / 处理发票 / 提取发票信息 / 发票转 Excel / 票据识别 / 报销单据 / 发票汇总"等，或提供一批发票文件要整理成表。 ## 用法 ```bash T=scripts/invoice_tool.py # ① 批量识别（输入可为单个文件，或一个目录，自动递归 PDF/JPG/PNG…） python3 $T ocr /path/to/发票目录 -o invoice_results.json python3 $T ocr /path/to/一张发票.pdf -o one.json --dpi 200 # ② 生成 Excel 汇总表 python3 $T excel invoice_results.json -o invoice_results.xlsx ``` **输出** - `invoice_results.json`：每张发票的 OCR 原文（含每行文字与坐标）+ 抽取字段； - `invoice_results.xlsx`：**13 列**汇总表 —— 文件名、**发票类型**、发票代码、发票号码、开票日期、购买方名称、购买方税号、销售方名称、销售方税号、金额(不含税)、税额、价税合计、状态；末行自动汇总**价税合计**合计。 - **发票类型栏**按票面文字判定，取值：增值税专用发票 / 增值税普通发票 / 电子发票（专用发票）/ 电子发票（普通发票）/ 增值税电子专用发票 / 增值税电子普通发票 / 机动车销售统一发票 / 二手车销售统一发票 / 区块链电子发票 / 其他发票（票种未识别）；含"专用"的行标**红字**、含"普通"的行标**蓝字**，便于一眼区分票种。 ## 工作流（六步出件） 1. 收件：把待处理票据收进一个目录，单文件也可；确认票据为自有或已获授权。 2. 摸底：先看 PDF 是否有文字层（数电票走文字层，扫描件走 OCR），决定是否加 `--dpi`。 3. 识别：跑 `ocr` 子命令，递归输出 `invoice_results.json`，记录每张的 `source` 字段（text-layer / ocr）。 4. 抽验：按 `references/quality-checklist.md` 抽验金额与税号，票种为"其他发票（票种未识别）"的行单独标记待确认。 5. 汇总：跑 `excel` 子命令出 13 列 `invoice_results.xlsx`，核对末行价税合计等于明细加总。 6. 交接：按 `references/writing-templates.md` 出核验表/操作单，交付物＝JSON + Excel + 核验表三项。 ```bash # 扫描件/模糊件：提高 DPI 后重跑（默认 200，扫描件常用 300） python3 $T ocr /path/to/扫描件目录 -o res300.json --dpi 300 # 已有 JSON 时只重跑 Excel 步骤（断点续跑，不重复 OCR） python3 $T excel res300.json -o res300.xlsx ``` **输入/输出**：输入＝票据目录或单个 PDF/JPG/PNG；输出＝逐张 OCR 原文 JSON + 13 列 Excel 汇总表 + 抽验记录。 ## 支持与限制 - 支持：**增值税专用发票、增值税普通发票、电子发票（数电票）** 等主流票种，抽取发票类型、代码、号码、日期、购/销方、金额、税额、价税合计。 - **电子发票 PDF 优先读取文字层**（准确率远高于 OCR），无文字层（扫描件/图片）再走本地 OCR；结果 JSON 的 `source` 字段标注来源（text-layer / ocr）。 - 抽取为**正则 + OCR** 的尽力识别，识别结果**须人工抽验重点字段**（金额、税号）后再入账。 - PDF 自动转图（默认 200 DPI，可 `--dpi` 调整）；图片按清晰、正向、无严重倾斜提供。 - 若 OCR 后字段为空，多半是发票版式特殊或图片模糊——按换更高 DPI（`--dpi 300`）或裁剪后重试处理；也可由宿主模型直接读原图人工补录。 - 仅用于处理用户自有或已获授权的票据。 ## 失败模式与降级路径 | 触发条件 | 失败模式 | 改用方案（降级路径） | |---|---|---| | PDF 无文字层（扫描件/图片） | 直接读文字层得到空字段 | 降级走本地 OCR：`ocr` 子命令 + `--dpi 300` | | OCR 后字段大面积为空 | 按空值写进 Excel，形成脏数据 | 回退重试：换更高 DPI 或裁剪票据区域后重跑；仍为空则人工补录 | | 票种文字识别不出 | 误并入专票或普票统计 | 兜底归入"其他发票（票种未识别）"，在核验表标记待确认 | | 金额与税号抽验不一致 | 错误汇总进入报销流程 | 停止出 Excel，先人工核对原图，改完 JSON 再跑 `excel` | | 目录内混入非票据文件（如合同 PDF） | 报错中断或产出噪声行 | 跳过该文件并在日志列出，本技能不做合同/公文 OCR（转 textin-xparse） | | rapidocr 依赖缺失或导入失败 | 整批失败 | 回退只读文字层（数电票可用），扫描件提示装依赖后再跑 | | Excel 目标文件被占用 | 写盘异常 | 换输出路径重试（`-o res_v2.xlsx`） | | 批量处理中断 | 从头重跑，浪费 OCR 时间 | 断点续跑：复用已生成的 `invoice_results.json` 只重跑 `excel` 步骤 | ## 检查点（🔴 停下确认） - 🔴 识别前：确认票据为自有或已获授权；来源不明先问再处理。 - 🔴 写 Excel 前：金额与税号两类重点字段已抽验，未抽验不得出表。 - 🔴 票种未识别行：标记"待确认"后才可并入汇总，不得直接计入专票。 - 🔴 交付前：末行价税合计须等于明细加总，不等即回查 JSON。 - 🔴 入账用途：确认汇总表交财务复核，本技能只出汇总表与核验表，不出记账凭证。 ## 反例与黑名单（不要做） - 不要用本技能查验发票真伪，查真伪一律转税务平台/发票查验系统。 - 不要处理来源不明或未获授权的票据。 - 不要把 OCR 结果不经抽验直接入账或提交报销。 - 不要对模糊/倾斜件只跑一次默认 DPI 就放弃，先按 `--dpi 300` 或裁剪重试。 - 不要把"其他发票（票种未识别）"当作专票统计，不得据未确认票种做税额抵扣判断。 - 不要改 `scripts/invoice_tool.py`（禁改）；需要新字段时改在汇总说明里补录。 - 不要用本技能 OCR 合同、公文或证件，那是 textin-xparse 的范围。 - 不要跳过核验表直接交 Excel，交付物须三项齐备（JSON + Excel + 核验表）。 - 不要在本技能内做会计凭证、税务申报与抵扣计算。 ## 版本与变更记录 - **v2.1.0（2026-09-12）**：新增「工作流（六步出件）」「失败模式与降级路径」「检查点（🔴 停下确认）」「反例与黑名单」四节；清理软性措辞。 - **v2.0.0（2026-09-07）**：增补专家级路由区块与版本记录；13 列汇总表与票种判定逻辑保留。 - **v1.x**：本地离线发票识别初版（`scripts/invoice_tool.py` 两子命令）。 ## 依赖与失败模式 - 关键依赖：rapidocr-onnxruntime、PyMuPDF、openpyxl、Pillow - 失败模式与防护：启动即预检依赖，缺失则列出对应 pip 安装命令并以退出码 2 终止。 - 原则：依赖缺失或输入非法时**显式报错并非零退出**，绝不静默降级，也绝不输出空结果或假结论。