# InvoiceAssist

**Repository Path**: jezzhu/InvoiceAssist

## Basic Information

- **Project Name**: InvoiceAssist
- **Description**: 发票助手
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-11-25
- **Last Updated**: 2025-11-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 发票统计工具

一个用于统计当前目录下发票 PDF 的小工具。按照文件名中的“类别”汇总发票数量与金额，并在末尾输出总计；同时提示所有文件名不符合约定格式的 PDF 文件。

## 功能概述
- 遍历当前目录（忽略子目录）中的 `.pdf` 文件
- 文件名格式为：`[类别]--[发票号码]--[金额].pdf`
- 按类别输出：`类别：XX张发票，总共金额为 YYY.YY 元。`
- 末尾输出整体总计行：`总计：XX张发票，总共金额为 YYY.YY 元。`
- 列出所有文件名不符合格式的 PDF 文件，便于修正（仅提示，不打包）
- 生成 CSV（`yyyyMMdd_HHmmss.csv`），三列：`类别,数量,金额`
- 将符合命名规则的 PDF 与 CSV 一并打包为 ZIP：`yyyyMMdd_HHmmss--{总计金额}.zip`
- 金额解析支持 `¥`、`￥`、`元`、千分位逗号；金额累计使用高精度 `Decimal` 并四舍五入到两位

## 文件命名要求
- 采用双破折号 `--` 分隔为三段：
  1. 类别（如：餐饮、汽油、滴滴、火车...）
  2. 发票号码（自由格式，建议仅使用数字或字母）
  3. 金额（支持形如 `4753.40`、`¥2,594.55`、`￥1544.20元` 等）
- 示例：
  - `餐饮--1234567890--4753.40.pdf`
  - `滴滴--DD202311--¥2,594.55.pdf`
  - `电话--TEL001--￥1544.20元.pdf`

不符合该命名格式的 `.pdf` 文件会被统计时跳过，并在结果末尾统一列出其文件名与数量。

## 环境要求
- Python 3.9 及以上（脚本使用了现代类型注解与 `decimal` 库）

## 使用方法
1. 将脚本与发票 PDF 放在同一目录（子目录不参与统计）
2. 在该目录执行：
   ```bash
   python3 stat_fapiao.py
   ```
3. 控制台会输出各类别统计、总计与不合规文件提示；同时在当前目录生成 ZIP，内含同名时间戳的 CSV 与所有有效 PDF。

## 输出示例
控制台示例：
```text
餐饮：30张发票，总共金额为 4753.40 元。
汽油：25张发票，总共金额为 7395.80 元。
滴滴：5张发票，总共金额为 2594.55 元。

总计：74张发票，总共金额为 19368.34 元。
有 2 个文件名不符合格式：[类别]--[发票号码]--[金额].pdf
  餐饮-错误格式-001.pdf
  other.pdf
```

CSV 内容示例（打包进 ZIP）：
```csv
类别,数量,金额
餐饮,30,4753.40
汽油,25,7395.80
滴滴,5,2594.55
总计,74,19368.34
```

## 常见问题
- 为什么不统计子目录？
  - 为了避免扫描过多无关文件，当前版本仅统计脚本所在目录下的 `.pdf` 文件；如需支持子目录，可后续扩展为递归扫描。
- `.gitignore` 忽略了 `*.pdf`/`*.zip` 会影响统计吗？
  - 不会。忽略仅影响 Git 追踪，不影响脚本读取与生成本地文件。
- 金额解析包含哪些格式？
  - 纯数字、小数、含货币符号 `¥/￥`、含尾部 `元`、含千分位逗号均可；无法解析时记为 0。

## 贡献
欢迎提 PR 或提交 Issue，改进文件格式校验、递归扫描、生成分类报表等。

## 许可证
本项目以开源方式发布，许可证可根据需要调整；如默认使用 MIT 许可，请在提交前确认并添加对应 LICENSE 文件。