Metadata-Version: 2.4
Name: invoice-amount-tool
Version: 0.1.0
Summary: Extract, deduplicate, categorise, and summarise Chinese PDF/OFD invoice amounts.
Project-URL: Homepage, https://github.com/wikieden/invoice-amount-tool
Project-URL: Repository, https://github.com/wikieden/invoice-amount-tool
Project-URL: Issues, https://github.com/wikieden/invoice-amount-tool/issues
Author: Invoice Amount Tool contributors
License-Expression: MIT
License-File: LICENSE
Keywords: cli,expense,invoice,ofd,pdf
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Financial :: Accounting
Requires-Python: >=3.10
Requires-Dist: pypdf>=4.0
Description-Content-Type: text/markdown

# invoice-amount-tool

一个用于统计发票金额的命令行工具。它可以读取目录、单个 PDF/OFD 文件，或 `.zip` / `.7z` 压缩包，提取发票金额，按发票号去重，并按分类汇总导出。

当前内置分类包括：

- 房租
- 火车票
- 机票
- 餐饮
- Apple 礼品卡
- 其他

## 金额口径

- 中文普通/专用发票：取含税总额，也就是价税合计小写金额。
- 火车票：取票价。
- 机票：取合计金额，不取单独票价。
- Apple 发票：保留 USD，不做汇率换算。
- 同一发票号同时存在 PDF/OFD 时只统计一次，并优先采用结构化 OFD 字段。

## 安装

从 PyPI 安装：

```bash
python -m pip install invoice-amount-tool
```

或安装成独立命令行工具：

```bash
pipx install invoice-amount-tool
```

从 GitHub Release 安装 wheel：

```bash
python -m pip install https://github.com/wikieden/invoice-amount-tool/releases/download/v0.1.0/invoice_amount_tool-0.1.0-py3-none-any.whl
```

用 `pipx` 安装成独立命令行工具：

```bash
pipx install https://github.com/wikieden/invoice-amount-tool/releases/download/v0.1.0/invoice_amount_tool-0.1.0-py3-none-any.whl
```

从源码安装：

```bash
python -m pip install .
```

开发模式：

```bash
python -m pip install -e .
```

`.7z` 压缩包需要系统里有 `7zz`、`7z` 或 `bsdtar` 任意一个命令。也可以先手动解压，然后把目录传给工具。

## 使用

导出 Excel：

```bash
invoice-totaler ~/Desktop/发票.7z -o 发票金额分类统计.xlsx
```

导出 CSV：

```bash
invoice-totaler ~/Desktop/发票.7z --format csv -o 发票金额分类统计.csv
```

导出 JSON：

```bash
invoice-totaler ~/Desktop/发票.7z --format json -o 发票金额分类统计.json
```

也可以直接处理目录：

```bash
invoice-totaler ./发票 -o 发票金额分类统计.xlsx
```

或处理单个 PDF/OFD 文件：

```bash
invoice-totaler ./发票/火车票/26949134178000969211.ofd -o 单张发票统计.xlsx
```

输出的 Excel 包含 3 个页签：

- `总览`：分类汇总和币种总计
- `明细`：去重后的每张发票
- `重复文件`：被合并的重复 PDF/OFD 文件

## 开发

运行测试：

```bash
PYTHONPATH=src python -m unittest discover -s tests
```

本地用样例压缩包验证：

```bash
PYTHONPATH=src python -m invoice_amount_tool ~/Desktop/发票.7z -o /tmp/invoice-summary.xlsx
```

## GitHub 发布建议

```bash
git init
git add .
git commit -m "Package invoice amount summariser as a CLI tool"
git branch -M main
git remote add origin git@github.com:<your-name>/invoice-amount-tool.git
git push -u origin main
```

## PyPI 发布

仓库包含 `.github/workflows/publish-pypi.yml`，支持 PyPI Trusted Publishing。

首次发布新项目时，在 PyPI 账号的 Publishing 页面添加 Pending Publisher：

- PyPI project name: `invoice-amount-tool`
- Owner: `wikieden`
- Repository name: `invoice-amount-tool`
- Workflow name: `publish-pypi.yml`
- Environment name: `pypi`

保存后，到 GitHub Actions 里手动运行 `Publish to PyPI` 工作流即可发布当前版本。

## 限制

- PDF 文本抽取依赖 `pypdf`。如果 PDF 是纯图片扫描件，当前版本不会做 OCR。
- OFD 解析优先读取常见税务/铁路/航空结构化字段；非常规 OFD 模板可能需要补充字段映射。
- Excel 输出使用标准库生成，偏重可读数据表，不做复杂样式。
