# 发票管理 **Repository Path**: ddwanglife/invoice-management-util ## Basic Information - **Project Name**: 发票管理 - **Description**: 桌面端发票管理小工具 - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-10-13 - **Last Updated**: 2026-10-13 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # 发票管理助手 桌面端**本地离线**发票管理工具:把散落在邮箱、微信、网盘里的发票批量收拢,自动识别票面字段并完成分类,按需一键打包导出用于报销,全程数据留在本机,不联网、不上传。 核心解决报销场景里最折腾的四件事:**找票难、重名看不懂、重复报销、缺明细清单**。 --- ## 一、它能做什么 | 能力 | 说明 | | --- | --- | | 批量导入 | 文件 / 文件夹 / ZIP 附件包直接拖拽,目录递归扫描(深度 ≤ 8),ZIP 自动递归解压(嵌套 ≤ 3 层) | | 自动识别 | 读取 PDF / OFD 自带文字层,正则 + 关键词抽取票面字段,判定票种与费用类别 | | 自动重命名归档 | 原始文件名通常是 `INV20260101.pdf`,归档后统一变为 `2026-08-12_某某酒店管理有限公司_364.15.pdf` | | 双重查重 | 文件哈希 + 发票号码(代码)两道校验,同一张票不会重复入库、不会重复报销 | | 一键打包导出 | 多维筛选后勾选导出,生成 ZIP(按模板重命名)+ Excel 台账(自动合计) | | 批次留痕 | 每次导出固化批次号、筛选条件、发票清单、金额快照、文件路径,事后可回溯、可再导 | | 状态管理 | `未使用 → 已使用 → 作废` 状态机,支持批量标记与用途备注;导出后可自动标记已使用 | | 越用越准 | 手工纠正类别时自动记录「开票方 → 类别」映射,下次同类发票直接命中 | | 统计看板 | 发票总数 / 未使用 / 已使用 / 待补录四项指标 + 近 12 个月金额趋势 + 类别分布 | --- ## 二、技术栈 | 层面 | 选型 | 备注 | | --- | --- | --- | | 桌面框架 | Electron 44 + electron-vite 5 | 主窗口 1360×880,单实例锁 | | 前端 | Vue 3.5 + TypeScript 5.9 + Vite 7 | vue-router(hash 模式)+ Pinia | | UI | Ant Design Vue 4 | | | 本地数据库 | SQLite(`node:sqlite`) | Electron 44 内置 Node 可直接启用 WAL;内置不可用时自动回退 `better-sqlite3` | | PDF 文本提取 | pdfjs-dist | 只读文字层,不做 OCR | | OFD 解析 | adm-zip + fast-xml-parser | OFD 本质是 ZIP 容器 + XML,无需厂商 SDK | | 导出打包 | archiver 8 | 纯 ESM,主进程侧以动态 `import()` 方式加载 | | Excel 台账 | exceljs | 生成带表头样式、金额格式与合计行的 xlsx | | 打包发布 | electron-builder | 产出 NSIS 安装包 + 便携版(仅 Windows) | **刻意不引入** OCR 引擎、云端 API、第三方 SDK —— 保证零依赖、零外传、启动快。 --- ## 三、快速开始 ### 环境要求 - Node.js **≥ 22.18**(依赖 Electron 44 内置 Node 与 `node:sqlite`;推荐 Node 22 LTS) - Windows x64(当前仅在 Windows 上打包与验证) ### 安装与运行 ```bash git clone https://gitee.com/ddwanglife/invoice-management-util.git cd invoice-management-util npm install npm run dev # 开发模式,自动拉起桌面窗口 ``` > `npm run dev` 走 `scripts/dev.mjs` 启动器,会先剔除宿主注入的 `ELECTRON_RUN_AS_NODE` 环境变量,避免在部分 IDE 终端里出现「窗口拉不起来、app 为 undefined」的问题。 ### 其他命令 | 命令 | 作用 | | --- | --- | | `npm run typecheck` | 类型检查(renderer 用 vue-tsc,main/preload 用 tsc),改动后必须全绿 | | `npm run verify:runtime` | 探测主进程环境下 `node:sqlite` 与 pdfjs 是否可用 | | `npm run verify:parser` | 解析引擎断言校验(28 项) | | `npm run verify:e2e` | 真实主进程跑通「导入 → 归类 → 导出」全链路(24 项断言) | | `npm run build` | 仅编译产物到 `out/` | | `npm run build:win` | 编译 + 用 electron-builder 打出 Windows 安装包与便携版到 `release/` | | `npm run build:dir` | 编译 + 打出免安装目录版(便于快速验证) | ### 如果 `node:sqlite` 不可用 设置页顶部的「当前存储引擎」会显示实际驱动。若退化到 `better-sqlite3`,需要安装原生依赖: ```bash npm install better-sqlite3 --save-optional ``` --- ## 四、数据放在哪 默认数据根目录为 `%APPDATA%\invoice-manager\`(Electron `userData`),可在「设置 → 存储位置」改到网盘目录做多端同步。结构如下: ``` <数据根目录>/ ├─ db/invoices.db # SQLite 数据库,WAL 模式 ├─ files/YYYY/MM/ # 归档的原始发票文件,按开票月份分目录 └─ exports/<批次号>_<批次名>/ # 导出文件夹(重命名后的发票 + Excel 台账) └─ <批次号>.zip # 同时生成的 ZIP 包 %APPDATA%\invoice-manager/config.json # 应用配置(不随数据根目录迁移) ``` > 修改数据根目录需**重启应用**生效,旧目录不会自动迁移,请手动拷贝 `db` / `files` / `exports` 三个子目录。 数据表:`invoice`(发票)、`category`(费用类别)、`export_batch`(导出批次)、`batch_invoice`(批次-发票关联,含金额快照与序号)、`import_task`(导入任务)、`seller_mapping`(开票方→类别自学习映射)、`app_meta`。迁移基于 SQLite `user_version` 做版本化管理。 --- ## 五、解析与识别 单个文件的处理链路(`src/main/parser/Pipeline.ts`): ``` 类型探测 → 文本提取 → 字段抽取 → 票种/类别判定 → 置信度评分 → 状态分级 ``` - **支持的输入格式**:PDF、OFD、ZIP(自动解压其中的发票文件)、图片(jpg/png/bmp/gif/webp) - **识别到的字段**:发票类型、发票代码、发票号码、开票日期、开票方名称及税号、购买方名称及税号、不含税金额、税额、价税合计、项目名称、校验码 - **内置票种规则**:增值税专用发票、增值税(电子)普通发票、全电发票(数电票)、电子发票(铁路电子客票)、航空运输电子客票行程单、出租车票、定额发票、机动车销售统一发票 - **费用类别**:交通 / 住宿 / 餐饮 / 办公 / 通讯 / 会务 / 差旅 / 其他(可在「分类与标签」页增删) - **解析状态**:由置信度自动分级,核心四字段(票号、日期、价税合计、开票方)命中率加权得出 0~1 分 - `≥ 0.75` → **已解析**(parsed) - `0.25 ~ 0.75` → **部分解析**(partial) - `< 0.25` → **待补录**(manual) **关键设计:识别失败的票绝不丢弃。** 图片、扫描件、纯图片型 PDF 没有文字层,会以「待补录」状态入库,在详情页对照原文手工补录字段;只有真正重复的文件才被拒收。 --- ## 六、命名模板 归档与导出时按模板重命名,占位符可在「设置 → 文件命名模板」自由组合: | 占位符 | 含义 | 占位符 | 含义 | | --- | --- | --- | --- | | `{date}` | 开票日期 | `{seq}` | 批次内序号(两位补零) | | `{seller}` | 开票方(截断 30 字) | `{category}` | 费用类别 | | `{buyer}` | 购买方(截断 20 字) | `{type}` | 发票类型 | | `{amount}` | 价税合计(两位小数) | `{code}` | 发票代码 | | `{number}` | 发票号码 | | | 默认归档模板 `{date}_{seller}_{amount}`,导出包内默认 `{seq}_{date}_{seller}_{amount}`。占位符取不到值时会被整体移除并自动压缩多余分隔符,文件名非法字符自动清洗,重名自动追加序号。 --- ## 七、查重策略 | 场景 | 严格模式(默认) | 宽松模式 | | --- | --- | --- | | 文件哈希相同(内容完全一致) | 拒收 | 拒收 | | 同一批导内重复 | 拒收 | 拒收 | | 库中已存在同一票号 | **拒收** | 加副本后缀入库,并在备注里提示「请人工确认是否重复报销」 | 查重严格度在「设置 → 导入与查重」切换;数据库层另有 `(invoice_code, invoice_number)` 部分唯一索引兜底。 --- ## 八、导出与台账 一次导出 = 一个按模板重命名的发票文件夹 + 一份 Excel 台账 + 一个 ZIP + 一条批次记录。 - **Excel 台账**:序号、开票日期、发票类型、发票代码/号码、开票方、项目名称、不含税金额、税额、价税合计、费用类别、备注,末行自动合计并附批次号与批次备注 - **批次记录**:固化批次号、批次名称、筛选条件快照、发票清单、金额快照、文件路径与备注,可在「导出批次」页查看明细、打开所在文件夹、补写备注 - **联动状态**:导出时可勾选「自动标记为已使用」,已报销的票不会再混进下一次报销清单 --- ## 九、目录结构 ``` invoice-management-util/ ├─ electron.vite.config.ts # main / preload / renderer 三端构建配置 ├─ scripts/ │ ├─ dev.mjs # 开发启动器(清理 ELECTRON_RUN_AS_NODE) │ ├─ verify-runtime.mjs # 运行环境探测 │ ├─ verify-parser.mjs # 解析引擎断言校验 │ ├─ run-e2e.mjs # 导入→导出全链路验证 │ └─ make-sample-pdf.mjs # 生成测试用样例发票 PDF ├─ src/ │ ├─ main/ # 主进程(持有全部本地 IO 能力) │ │ ├─ index.ts # 窗口创建、生命周期、单实例 │ │ ├─ config.ts # 配置读写(userData/config.json) │ │ ├─ db/ # 驱动抽象、连接、版本化迁移、schema(SQL 内联) │ │ ├─ importer/ # 文件扫描(含 ZIP 递归解压)与导入编排 │ │ ├─ parser/ # detect / pdf / ofd / rules / classify / confidence / Pipeline │ │ ├─ exporter/ # 打包 + Excel 台账 + 批次写入 │ │ ├─ repo/ # 数据访问层(invoice / batch / category / task / stats) │ │ ├─ ipc/ # IPC handler,按域分文件注册 │ │ └─ util/ # hash / naming / notify │ ├─ preload/index.ts # contextBridge 暴露受控 API 白名单 │ ├─ renderer/ # Vue3 渲染层 │ │ ├─ views/ # 发票库 / 导入中心 / 导出批次 / 分类与标签 / 统计看板 / 设置 │ │ ├─ components/ # ExportDialog / InvoiceDetailDrawer │ │ ├─ layout/ router/ stores/ utils/ styles/ │ └─ shared/types.ts # 三端共享类型定义 └─ doc/ # 设计文档与说明 ``` **安全边界**:`contextIsolation: true`、`nodeIntegration: false`、`webSecurity: true`,渲染层只能通过 preload 白名单调用主进程能力,外链走系统浏览器打开。 --- ## 十、开发约定(踩过的坑) 1. **传给 `window.api.*` 的参数必须是纯数据**。Vue `ref` / `reactive` 是 Proxy,Electron IPC 的结构化克隆不支持 Proxy,会直接报 `An object could not be cloned`。数组用展开 `[...x.value]`,对象元素逐个 `{...s}` 展开(`filter` / `slice` 之后的元素依旧是 Proxy)。 2. **SQL 必须以 TS 常量内联**,不能放外部 `.sql` 文件 —— 打包成 asar 后无法按相对路径读取。 3. **archiver 8 是纯 ESM 且移除了 `archiver(format)` 工厂函数**,主进程产物是 CJS,必须用动态 `import()` + `new ZipArchive()`,否则运行时抛 `ERR_REQUIRE_ESM`。 4. **`.mjs` 的类型声明后缀必须是 `.d.mts`**(`moduleResolution: Bundler` 下的要求)。 5. **不要修改 `doc/example/` 与 `scripts/` 下的样例发票**:含真实发票号码与税号,已在 `.gitignore` 排除,禁止入库。 --- ## 十一、已知边界 - **无 OCR**:只能读取 PDF / OFD 自带文字层。扫描件、拍照件、纯图片型 PDF 会落入「待补录」,需人工补录字段。 - **仅 Windows x64**:当前只在 Windows 上做打包与验证;macOS / Linux 未适配(打包目标、窗口菜单等均未处理)。 - **单机自用**:没有多用户与权限体系,换机时整体拷贝数据根目录即可。 - **导入为串行处理**:逐文件解析,超大批量导入时以毫秒级单文件耗时累加,导入期间请勿关闭应用。 --- ## 十二、许可 MIT License。 > 详细的产品设计与实现取舍见 [`设计方案.md`](./设计方案.md)。 ## 十三、授权许可 启动时需要有效许可;未激活、已过期、机器码不符、签名无效或系统时间回拨时显示激活页,业务 IPC 同时拒绝访问。运行期间每分钟复核,在“设置 → 授权许可”可查看、更新或移除许可。 激活页可复制本机机器码,粘贴许可内容或选择 `.lic` 文件。许可和时钟记录保存在应用的用户数据目录,不随发票数据根目录变更。更新失败不会覆盖现有有效许可,移除许可不删除发票数据。 公钥、机器码算法及 `AWD LICENSE` 格式沿用 `amazon-awd-cost-analysis/app`,共用其 public 公钥。管理员继续使用该项目的 `create-licence` 签发工具,无需新建密钥;同一机器的有效许可可分别激活两个应用。私钥不随发票系统分发。许可到期日当天有效,次日失效。 运行 `npm run verify:license` 验证授权校验;构建后运行 `npm run verify:license:ui` 验证真实 Electron 的激活、业务接口、设置页和移除许可流程。测试只使用临时生成的密钥,不读取管理员私钥,也不修改已有用户许可。