内容
<!-- markdownlint-disable MD033 MD040 MD041 -->
<div align="center">
# CMB Credit Card Statement Parser
**OCR 不使用！** 准确、快速地，将招商银行信用卡账单 PDF 解析为结构化数据，附带电子签名验证
[](https://www.python.org/) [](https://github.com/astral-sh/ruff) [](https://fastapi.tiangolo.com/) [](LICENSE)
</div>
<details>
<summary>CLI 示例</summary>
</details>
[CSV 示例](examples/transactions.example.csv)
## 安装
```bash
uv sync
```
## CLI 用法
```bash
# 账单摘要（含签名验证）
uv run cmb-credit-parse examples/2026年07月信用卡账单.pdf
# 账单摘要（跳过签名验证）
uv run cmb-credit-parse --no-sig examples/2026年07月信用卡账单.pdf
# JSON 输出（含签名验证）
uv run cmb-credit-parse --json examples/2026年07月信用卡账单.pdf
# JSON 输出，跳过签名验证
uv run cmb-credit-parse --json --no-sig examples/2026年07月信用卡账单.pdf
# CSV 导出
uv run cmb-credit-parse --csv transactions.csv examples/2026年07月信用卡账单.pdf
# CSV 导出，反转收支符号
uv run cmb-credit-parse --csv transactions.csv --invert-sign examples/2026年07月信用卡账单.pdf
```
## 选项
| 选项 | 说明 |
| ----------------- | ----------------------------------------------------------- |
| `--json` | 输出 JSON 格式的 FullResponse（包含 statement + signature） |
| `--csv` | 导出交易记录为 CSV 文件 |
| `--invert-sign` | 反转 CSV 中收入和支出的符号 |
| `--no-sig` | 跳过签名验证 |
## API 服务
启动 FastAPI + FastMCP 服务器：
```bash
uv run uvicorn cmb_credit_parse.server:app --host 0.0.0.0 --port 8454
```
### 环境变量
创建 `.env` 文件配置服务器地址提示，这会被用于 MCP 服务的调用提示：
```env
BASE_URL=http://localhost:8454
```
### FastAPI 端点
| 端点 | 方法 | 参数 | 说明 |
| ---------------- | ---- | --------------------------- | -------------------------------- |
| `/api/parse` | POST | `file` (form-data) | 上传 PDF 文件，返回 FullResponse |
| `/api/parse/csv` | POST | `file` (form-data), `invert_sign` (query, 可选) | 上传 PDF 文件，返回 CSV 下载 |
### FastMCP 工具
| 路径 | 说明 |
| ------ | ------------ |
| `/mcp` | MCP 协议端点 |
MCP 工具：
- `parse_credit_statement(pdf_path: str)` — 引导使用 HTTP API 上传 PDF 文件
## 功能
- **账单解析**: 提取持卡人、地址、账单日、到期日、信用额度
- **交易提取**: 支持消费、退款、还款、其他 4 种分类
- **账务摘要**: 上期账单、本期还款、新增、调整、循环利息、本期账单、最低还款
- **签名验证**: 验证 PDF 电子签名、证书链有效性
- **Rich 输出**: 彩色面板和表格显示，未知值红色高亮
- **CSV 导出**: 一键导出交易记录
## 项目结构
```
src/cmb_credit_parse/
├── __init__.py # 空文件
├── models.py # Pydantic 数据模型
├── parser.py # PDF 账单解析逻辑
├── signature.py # PDF 电子签名验证
├── cli.py # typer CLI 入口
└── server.py # FastAPI + FastMCP 服务器
```
## 技术栈
- Python >=3.14
- pdfplumber (PDF 提取)
- pypdf + cryptography (签名解析)
- Pydantic v2 (数据模型)
- typer + rich (CLI 和输出)
- FastAPI (HTTP API)
- FastMCP (MCP 工具)
- pydantic-settings + dotenv (配置管理)
- Ruff (代码检查)
## 开发
```bash
# 代码检查
uv run ruff check src/
# 自动修复
uv run ruff check src/ --fix
# 运行示例
uv run python examples/usage.py
```
## Docker
```bash
# 本地构建并启动
docker compose up --build
# 或手动构建
docker build -t cmb-credit-parse .
docker run -p 8454:8454 -e TZ=Asia/Shanghai cmb-credit-parse
```
预构建镜像：`ghcr.io/serinanya/cmb-credit-parse`
## TODO
- [ ] 美元账单支持（缺少示例文件）
