# invoice-hub

**Repository Path**: l3008_admin/invoice-hub-setup

## Basic Information

- **Project Name**: invoice-hub
- **Description**: 发票助手 · Invoice Hub
一套**本地运行、开箱即用**的发票识别与台账管理系统：把散落在文件夹里的发票图片和 PDF 批量识别成结构化数据，统一管理、核对、补录，并一键导出 Excel。

- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-11-11
- **Last Updated**: 2026-11-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 发票助手 · Invoice Hub

> 一套**本地运行、开箱即用**的发票识别与台账管理系统：把散落在文件夹里的发票图片和 PDF 批量识别成结构化数据，统一管理、核对、补录，并一键导出 Excel。

---

## 一、解决什么问题

财务与报销场景里，发票往往以截图、JPG、电子 PDF、扫描件混在一起：

- 手工录入发票号码、购销方、税额、明细行，既慢又容易出错；
- 事后要按部门、报销人、开票日期或入库时间统计时，还得重新翻原始文件；
- 常见的 SaaS 票据服务需要把发票上传到云端，很多单位并不接受；
- 识别工具一换环境就要装 Python、装依赖、配模型，交付给同事很麻烦。

Invoice Hub 的选择是：**全部在本机跑**。不依赖云服务、不上传任何票据、不需要部署数据库；识别结果和原始文件都留在本地，任何字段都能人工校正。最终交付是解压即用的绿色程序，双击后浏览器自动打开首页。

---

## 二、核心功能

| 模块 | 能力 |
| --- | --- |
| 发票识别 | 目录批量 / 单文件 / 页面上传，图片与 PDF 混合批次；每次生成唯一**批次号**与进度轮询；按「机构 + 发票号码 + 发票代码 + 文件名」去重，可选择覆盖重跑；PDF 逐页识别 |
| 票面结构化 | 票据头、购买方/销售方各 4 项、密码区、备注、收款人/复核/开票人、金额与税额、价税合计、项目明细全量留存；**OCR 原文与坐标一并入库** |
| 人工校正 | 识别不准的发票标记「待核对」，在详情弹窗里可修改全部票面字段与明细行；**原始文件永不修改或删除** |
| 发票台账 | 关键字 / 批次号 / 开票日期 / 入库时间 / 识别状态 / 部门 / 报销人多维筛选；表格合计行按**筛选条件全量**汇总税额与价税合计 |
| 组织与补录 | 多机构数据隔离，每个机构一棵独立部门树；「当前机构 → 部门 → 报销人」级联补录，兼容历史自由文本 |
| 工作台 | 金额与数量趋势、识别状态占比、最近发票与批次、热门销方；**全部来自真实业务表，无模拟数据** |
| Excel 导出 | 发票信息、项目明细两个 sheet，筛选口径与页面完全一致，末尾追加加粗合计行；明细导出自动排除票面合计行，避免重复累加 |
| 系统能力 | 用户与权限、机构切换、亮色/暗色主题、健康检查、SQLite / PostgreSQL 双支持 |

### 识别上的两个特点

1. **电子发票 PDF 走文本层快路径**：用 `pypdfium2` 按坐标还原文本框，把竖排拆开的单字合并成完整标签，再交给统一的版面解析器。这类 PDF **不加载 OCR 模型**，从数十秒降到毫秒级，字段也更准——这就是「仅 PDF 版」可以做到 51 MB 的原因。
2. **图片多策略惰性重试**：低分辨率截图先裁纯色边框并放大锐化，按「增强图 → 原图 → 灰度自动对比度」依次尝试，用发票号码、关键字段、假明细行与置信度打分择优；质量达标立即停止，好图只跑一次 OCR。货物名称折行会自动合并，不会多出没有金额的假明细。

---

## 三、两个可分发版本

| 版本 | 识别范围 | 压缩包 | 适用 |
| --- | --- | --- | --- |
| **仅 PDF 版** | 电子发票 PDF（文件自带文字层） | `invoice-hub-pdf-only.zip`，51 MB | 只需处理电子发票 PDF，追求轻量、启动快 |
| **PDF + 图片版** | PDF、扫描件 PDF、JPG/PNG 截图 | `invoice-hub-pdf-image.zip`，429 MB | 需要处理扫描件和图片发票 |

两个包都是**绿色免安装**：解压整个文件夹 → 双击 `invoice-hub.exe` → 浏览器自动打开首页 → 默认账号 `invoice` / `invoice`。完整版内置 PaddleOCR 3.7 与约 133 MB 离线模型，首次识别时自动安装到用户目录，**目标机零联网、零 pip install**。

> exe 内没有 Python/pip 运行时，PaddleOCR 这类约 400 MB 的编译扩展不可能在运行时补装，因此两个版本体积相差约 9 倍。仅 PDF 版遇到图片或扫描件时会提示「引擎未安装」，属预期行为。

---

## 四、技术架构

| 层 | 选型 | 说明 |
| --- | --- | --- |
| 后端 | FastAPI + SQLAlchemy 2.x + Pydantic v2 + uvicorn | 实体层独立，统一使用跨方言类型（String/Text/Numeric/DateTime/Boolean/Integer），主键为字符串 UUID |
| 识别 | PaddleOCR 3.7 + PaddlePaddle 3.3、`pypdfium2`、Pillow | 识别跑在 `spawn` 独立子进程，避免 CPU 推理阻塞 Web 事件循环 |
| 数据 | SQLite（默认）/ PostgreSQL | `DATABASE_URL` 一行切换；启动时幂等建表、结构升级前自动备份 SQLite |
| 导出 | openpyxl | 两个 sheet + 合计行 |
| 前端 | Vue 3.5 + Vite 6 + TypeScript + Pinia + Arco Design Vue 2.59 | Arco Pro 风格，组件与图标按需引入；echarts 仅工作台按路由懒加载 |
| 分发 | setuptools wheel + PyInstaller | 前端 `dist` 作为 package data 打进 Python 包；exe 内托管页面，无需 Node.js |

**数据位置**：所有业务数据、上传文件、导出文件与离线模型都落在用户目录 `~/.invoice-hub/`，不写注册表、不装系统服务，程序目录保持只读也能运行。

---

## 五、设计原则

1. **本地优先**：无云端依赖、无遥测、无外部账号；完整版可完全离线运行。
2. **可核查**：OCR 原文与坐标全量留存；工作台、列表合计、Excel 导出三处口径完全一致。
3. **不破坏现场**：结构升级前自动备份数据库；原始发票文件只读。
4. **交付简单**：不需要 Docker、Node.js 或 Python 环境，拿到发布包解压双击即可。
5. **克制专业**：面向财务与报销人员的本地后台工具，高信息密度、无花哨装饰。

---

## 六、快速开始

**使用发布包（推荐）**

1. 解压 `publish/` 下对应的 zip 到固定位置（不要只复制 `invoice-hub.exe`，`_internal/` 里有前端页面与依赖）。
2. 双击 `invoice-hub.exe`，保留黑色控制台窗口（它是服务）。
3. 浏览器自动打开首页，用 `invoice` / `invoice` 登录。

**源码开发**

```bat
:: 后端
cd backend
.venv\Scripts\python.exe -m pip install -r requirements.txt
.venv\Scripts\python.exe run.py        :: http://127.0.0.1:18080

:: 前端（另一个终端）
cd frontend
npm install
npm run dev                            :: http://127.0.0.1:5173
```

`npm run build` 后也可只开后端一个端口，由后端直接托管前端产物。

---

## 七、文档索引

| 文档 | 内容 |
| --- | --- |
| `README.md` | 完整功能、目录结构、接口清单、识别原理、部署与数据库配置 |
| `项目介绍.md` | 本文，面向使用者/同事的项目概览 |
| `publish/打包方法.md` | 从源码构建到生成两个发布包的完整流程、开关速查、验证命令与已知坑 |
| `publish/使用说明.txt`（在各包内） | 给最终使用者的启动、默认账号、端口、数据与卸载说明 |
| `backend/.env.example` | 端口、令牌有效期、OCR、扫描目录白名单等配置项 |

---

*本项目为本地单机工具，默认账号请在正式使用前修改。识别结果不保证 100% 准确，重要票据请人工核对。*