# qingtian

**Repository Path**: king_nd/qingtian

## Basic Information

- **Project Name**: qingtian
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MPL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-12
- **Last Updated**: 2026-06-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 晴天 · 发票助手

<p align="center">
  <img src="logo/晴天系统.png" alt="晴天发票助手产品海报" width="760" />
</p>

<p align="center">
  <strong>☀️ 智能发票管理，让报销更简单，让财务更高效。</strong>
</p>

<p align="center">
  <img alt="Python" src="https://img.shields.io/badge/Python-3.11+-2563EB?style=flat-square" />
  <img alt="PySide6" src="https://img.shields.io/badge/PySide6-Desktop-22C55E?style=flat-square" />
  <img alt="Platform" src="https://img.shields.io/badge/Platform-Windows-0EA5E9?style=flat-square" />
  <img alt="License" src="https://img.shields.io/badge/License-MIT-F59E0B?style=flat-square" />
</p>

---

## ✨ 产品定位

**晴天 · 发票助手** 是面向企业内部财务报销场景打造的 Windows 桌面工具，围绕“发票识别、智能分类、报销单生成、PDF 归档”形成一套完整闭环。

它将分散的 PDF、图片、行程单和发票材料统一导入，通过自动识别与规则分类，快速生成符合财务报销要求的 Excel 报销单和 PDF 汇总文件，减少人工录入、降低分类差错、提升报销处理效率。

> 🛡️ 云基华海内部工具，为企业财务数字化保驾护航。

## 🚀 核心能力

| 能力 | 说明 |
|---|---|
| 📂 发票扫描 | 选择目录后一键导入 PDF、OFD、图片和扫描件，支持递归扫描与批量处理 |
| 🔍 智能识别 | 提取文本层 PDF 信息，图片类材料自动进入 OCR 识别流程 |
| 🧠 智能分类 | 自动识别火车票、机票、市内交通、住宿、保险、退票、票务服务费等类型 |
| 📊 报销单生成 | 基于 Excel 模板生成差旅费报销单、费用报销单、公共交通明细单 |
| 📎 PDF 合并归档 | 自动重命名、合并发票与附件材料，便于打印、归档和提交 |
| 👁️ 内置预览 | 应用内直接预览 PDF，支持翻页与缩放，无需切换外部软件 |
| 🔒 本地处理 | 数据在本地完成识别、分类与生成，适合企业内部报销资料处理 |

## 🔄 业务流程

```text
选择发票目录
    ↓
扫描并识别发票
    ↓
自动分类与人工核对
    ↓
生成 Excel 报销单
    ↓
合并 PDF 并归档输出
```

## 📦 报销输出

| 输出文件 | 用途 |
|---|---|
| 🧾 差旅费报销单 | 汇总火车、飞机、市内交通、住宿、保险、退票、票务服务费和误餐补贴 |
| 💼 费用报销单 | 汇总非差旅类费用；勾选“强制费用报销”后可将全部票据走费用报销 |
| 🚌 公共交通明细单 | 展示市内交通逐笔明细，作为差旅报销附件材料 |
| 📑 发票汇总 PDF | 合并可报销发票，形成统一打印文件 |
| 📁 材料汇总 PDF | 合并行程单、说明材料、附件材料等佐证文件 |

## 🎫 支持票据类型

| 类型 | 识别说明 | 默认归类 |
|---|---|---|
| 🚄 铁路电子客票 | 火车票、铁路退票费 | 交通费(火车) / 退票费 |
| ✈️ 航空票据 | 机票款、代订机票、航空运输服务 | 交通费(飞机) |
| 🎟️ 票务服务费 | 代理服务费、代订附加费、订票服务费 | 差旅报销单其他费用 |
| 🛡️ 保险费 | 航空意外险、延误险、人身保险、保单号等保险类费用 | 差旅报销单其他费用 |
| 🚕 市内交通 | 滴滴、出租车、长安通、客运服务 | 公共交通明细单 |
| 🏨 住宿发票 | 酒店、宾馆、旅馆、住宿服务 | 住宿费 |
| 📎 附件说明 | 行程单、水单/账单、预订凭证、审批截图、无发票号图片、差旅表等材料 | 材料汇总 PDF |
| 🧩 其他费用 | 餐饮、办公采购及其他非差旅费用 | 费用报销单 |

## 🖥️ 界面与体验

- 左侧导航保留清晰的业务模块入口：发票处理、差旅报销单、费用报销单、公共交通明细单、设置
- 发票处理页按照“选择目录 → 识别与分类 → 生成报销单”组织，流程明确
- 识别过程中提供等待蒙版与进度提示，避免误操作
- 发票类型、金额、日期支持人工修正，修正行会突出显示
- 生成前自动归档旧输出；遇到 Excel 文件占用时给出前台提示，不中断主流程

## ⚡ 快速开始

### 方式一：启动桌面界面

```bash
python main.py --gui
```

### 方式二：命令行处理目录

```bash
python main.py --dir "示例数据2" --person "晴天" --dept "财务部"
```

### 首次配置

程序首次运行会自动读取或生成 `config.json`，可配置：

```json
{
  "department": "研发中心",
  "person_name": "晴天",
  "company_name": "云基华海",
  "subsidy_rate": 80
}
```

## 🗂️ 项目结构

```text
├── main.py                 # 程序入口：GUI / CLI 双模式
├── src/                    # 核心业务层
│   ├── scanner.py          # 文件扫描与提取编排
│   ├── classifier.py       # 发票自动分类规则
│   ├── models.py           # 统一数据模型与汇总计算
│   ├── merger.py           # PDF 合并归档
│   ├── renamer.py          # 发票文件重命名
│   ├── extractors/         # PDF / 发票解析器
│   └── excel_gen/          # Excel 报销单生成器
├── ui/                     # PySide6 桌面界面
│   ├── app.py              # 主窗口与帮助中心
│   ├── controllers.py      # 控制器与任务编排
│   ├── pages/              # 页面模块
│   └── widgets/            # 表格、导航、预览、卡片等组件
├── 模板/                   # Excel 报销单模板
├── logo/                   # 产品 Logo、图标与海报素材
└── docs/                   # 开发、发布与业务规则文档
```

## 🧱 技术架构

| 层级 | 技术 | 说明 |
|---|---|---|
| 🪟 桌面界面 | PySide6 | Windows 原生桌面体验 |
| 📄 PDF 文本提取 | pdfplumber | 解析文本层 PDF 发票 |
| 🤖 图片识别 | EasyOCR | 处理扫描件与图片类材料，发布包内置 OCR 模型 |
| 🔎 PDF 预览 | PyMuPDF | 内置预览、翻页与缩放 |
| 📗 Excel 生成 | openpyxl | 基于模板复制、填充与公式生成 |
| 🧵 后台任务 | QThread | 扫描、识别、生成过程不卡界面 |
| 🧭 架构模式 | MVC | GUI 与核心业务分层，便于维护扩展 |

## 🔔 发布与升级

项目内置版本号与更新检查逻辑，发布流程见：

- [`docs/RELEASE.md`](docs/RELEASE.md)
- [`docs/发布清单.md`](docs/发布清单.md)

当前版本号维护在：

```text
src/version.py
```

## 🧪 开发检查

```bash
python -m py_compile main.py src/*.py ui/*.py ui/*/*.py
python main.py --gui
```

## 🌟 价值总结

晴天 · 发票助手聚焦企业内部报销链路，将大量重复、易错、耗时的票据整理工作自动化：

- 更高效：批量识别、自动分类、模板生成，减少手工整理时间
- 更准确：规则分类 + 人工复核，降低金额、类型和附件遗漏风险
- 更安全：本地处理企业报销资料，减少数据外流风险
- 更专业：输出统一、命名规范、归档清晰，符合企业财务管理要求