seceremrecan/financial-pdf-parser

## ✨ 项目简介 大多数“银行流水解析器”在处理真实世界的 PDF 时都会遇到困难 —— 例如带有子集字体（导致 `pdfplumber` 返回像 `(cid:N)` 这样的乱码字形）的土耳其银行流水、欧洲数字格式（`1.679,96` 对比 `1,679.96`）、或者商户名称被淹没在 `A101 9937 0911 A101 FEVZI` 这样的字符串中的收据。本项目能够处理所有这些问题： - **字体乱码？** 检测它（基于 cid 数量 + 可打印字节比率），将页面渲染为 PNG，然后发送给 **vision LLM** 处理。在真实的 4-5 页流水上，端到端召回率从 **~85% 提升到了 96%+**。 - **硬编码的供应商列表？** 绝不。使用两个 **数据库驱动的引擎**（用于分类的 `category_mappings` 和用于规范化的 `enrichment_rules`），只需通过 INSERT 就能接入新的供应商，而无需重新部署。 - **被锁定在单一的 LLM 上？** 并没有。采用 **4 提供商抽象层** —— 只需在 `.env` 中修改 `LLM_PROVIDER=anthropic|openai|gemini|groq`，代码完全通用。 - **可用于生产环境？** 支持 JWT 身份验证、多用户数据隔离、237 个通过的测试、Docker Compose、支持 Supabase 的 schema 以及 RLS 和 Edge Function 示例。 ## 🎬 快速演示

截图占位符

``` docs/ screenshots/ dashboard.png ← KPIs + category pie + anomalies card transactions.png ← inline category dropdown + sortable headers upload.png ← bulk queue with progress bars mobile.png ← responsive view on iPhone ```

## 🧠 技术亮点 ### 1. 针对 PDF 乱码的 Vision-LLM 回退机制 [`pdf_parser.py`](backend/app/services/pdf_parser.py) 中的一个启发式算法会对提取质量进行评分： ``` cid_count = len(_CID_RE.findall(text)) printable_ratio = sum(c in PRINTABLE for c in text[:5000]) / 5000 ``` 如果文本“乱码”，页面将被渲染为 PNG，并带有一定的垂直重叠分割（上半部分 + 下半部分），然后并行发送给支持视觉的 LLM。按半页分割能持续提升密集表格的召回率 —— 因为模型一次看到的行数更少时，跳过行的可能性也会降低。由重叠引起的重复项会通过 `(date, merchant, amount)` 去重机制移除。 ### 2. 可配置的规则引擎（无硬编码） | 表名 | 功能 | 示例行 | |---|---|---| | `category_mappings` | 将原始文本/商户映射到分类 | `('Migros', contains, Groceries, prio=10)` | | `enrichment_rules` | 规范化 / 标记字段 | `match merchant regex "^A101\s+\d+" → set merchant = "A101"` | 两者都在 LLM 分类调用之前运行，因此 LLM 只会接收到干净且规范的商户名称。要增加对新银行的支持，只需在 Supabase Studio 中或通过 REST API 执行几次 INSERT 操作。 ### 3. 与提供商无关的 LLM 层 ``` LLM_PROVIDER=anthropic # native Messages API (sk-ant-...) LLM_PROVIDER=openai # gpt-4o-mini, gpt-5, etc. LLM_PROVIDER=gemini # via OpenAI-compatible endpoint LLM_PROVIDER=groq # Llama 4 Scout vision (free tier) ``` [`llm_categorizer.py`](backend/app/services/llm_categorizer.py) 保留了一个带有分支初始化的单一服务类，因此切换提供商只需更改一个环境变量。测试通过 `unittest.mock` 覆盖了 Anthropic 分支，因此它们可以离线运行且零成本。 ### 4. 真正有价值的分析数据 (KPIs) - **异常检测** —— 针对每个类别的修正 z-score + 中位数倍数防护机制（`amt > p99 AND amt > 3 × median`），这样小型的均匀分布数据集就不会在其最大值上出现误报。 - **预测** —— Prophet（首选）→ scikit-learn LinearRegression（回退）→ 朴素最后值（数据点少于 3 个的冷启动）。 - **趋势** —— 使用 Postgres 的 `to_char(date, 'YYYY-MM')` 进行月度聚合。 - **订阅泄漏检测** —— 按商户对交易进行分组，拟合扣款间隔的频率（从每周到每年不等），将每项订阅统一折算为月度成本，并标记异常情况：静默涨价、已失效的频率（被遗忘/已取消）以及同一类别下的重复服务。混合置信度得分（间隔规律性 + 金额稳定性 + 重复次数）可以将像日常杂货这种不规律的支出排除在外。用户可以对每一项进行确认 / 取消 / 忽略，保存的判定结果将实时反映在“每月泄漏 ₺X”的标题中。 - **手动订阅账本** —— 除了自动检测外，用户还可以手动输入包含完整细节（金额、计费周期、下次扣款日期、免费试用结束时间、预期金额）的订阅，并逐月进行追踪。系统包含一个合并层来核对这些数据：手动录入作为真实来源，流水会对其进行*验证*（在流水上打勾，对比预期价格上涨），并且任何尚未在账本中的检测到的扣费都将变成一键“添加此项”的建议 —— 因此不会重复计算。它会在统一的“经常性支出与账单”面板上显示即将到期和试用即将结束的提醒。 - **分期计划 + 按卡分组** —— 同一个账本还能追踪特定期限的分期消费（即一笔消费被分成 N 笔相等的月度扣款）。该服务会推导出剩余期数、剩余余额、进度（例如 3/12）和预计结束日期 —— 已完成的计划会自动从每月总计中移除。每个条目都可以添加自定义文本的卡片/账户标签（例如“Garanti Bonus”），这样各项支出承诺就能汇总到每张卡的月度负担中，这与信用卡账单的打包呈现方式如出一辙。 ### 5. 真正的生产级强化 - JWT (passlib + python-jose)，24 小时有效期，通过 `secrets.token_urlsafe(48)` 轮换密钥 - 每个租户查询都会根据 `current_user.id` 进行过滤；14 个跨用户隔离测试 - `AUTH_ENABLED=false` 可在不修改代码的情况下开启无登录验证模式 - Supabase RLS 策略使同样的隔离方案可移植到 Supabase 上 - 上传时的 SHA-256 重复检测、MIME + 大小验证 - 前端 axios 拦截器：自动附加 bearer token，遇到 401 广播时实现静默登出 ## 🧱 技术栈 | 层级 | 技术 | |---|---| | **后端** | FastAPI 0.115 · SQLAlchemy 2.x · Alembic · Pydantic 2 | | **PDF 解析** | pdfplumber 0.11 · PyMuPDF 1.24 (文本 + 视觉渲染) | | **LLM** | Anthropic SDK · OpenAI SDK (OpenAI/Gemini/Groq 通过 OpenAI 兼容) | | **机器学习 (ML)** | scikit-learn · pandas · Prophet | | **数据库** | PostgreSQL 16 · Alembic 数据迁移 | | **身份验证** | passlib[bcrypt] · python-jose · email-validator | | **前端** | React 18 · Vite 5 · Recharts · Axios · react-router 6 | | **测试** | pytest 8 · pytest-asyncio · httpx | | **容器** | Docker Compose (数据库 + 后端 + 前端) | | **云端就绪** | Supabase schema + RLS 策略 + TypeScript Edge Function 示例 | ## 🏗 架构 ``` ┌──────────────────────────┐ ┌────────────────────────────┐ ┌────────────────────┐ │ React (Vite) — SPA │───▶│ FastAPI │───▶│ PostgreSQL 16 │ │ · Bulk upload + queue │ │ · Auth (JWT) │ │ · users │ │ · Inline category edit │ │ · Upload + ingest │ │ · transactions │ │ · Sortable tables │◀───│ · Analytics endpoints │◀───│ · categories │ │ · CSV/XLSX export │ │ · Anomaly + forecast │ │ · category_maps │ │ · Mobile responsive │ │ · CRUD: enrichment rules │ │ · enrichment_rules│ └──────────────────────────┘ └─────────────┬──────────────┘ └────────────────────┘ │ text good ──┴── text garbled │ │ ▼ ▼ ┌──────────────┐ ┌─────────────────────────────┐ │ pdfplumber │ │ render pages → split halves │ │ + tables │ │ → parallel vision call │ └──────┬───────┘ └────────────┬────────────────┘ │ │ └─────────┬─────────────┘ ▼ ┌────────────────────────────┐ │ Enrichment rules │ │ (normalize merchant, │ │ currency, tag, note) │ └────────────┬───────────────┘ ▼ ┌────────────────────────────┐ │ Category mapper │ │ (deterministic) → fallback│ │ to LLM category string │ └────────────┬───────────────┘ ▼ ┌────────────────────────────┐ │ Dedupe + insert │ └────────────────────────────┘ ``` ## 🚀 快速开始 ### 前置条件 - Docker Desktop - 一个 LLM API key —— 推荐：从 获取免费的 Groq key ### 1. 配置 ``` git clone https://github.com//financial-pdf-parser.git cd financial-pdf-parser cp .env.example .env cp backend/.env.example backend/.env cp frontend/.env.example frontend/.env ``` 编辑 [`backend/.env`](backend/.env.example) —— 至少需要设置： ``` LLM_PROVIDER=groq GROQ_API_KEY=gsk_your_key_here JWT_SECRET= ``` ### 2. 运行 ``` docker compose up --build docker compose exec backend alembic upgrade head docker compose exec backend python -m app.scripts.seed_categories ``` - API + Swagger → http://localhost:8000/docs - 前端 → http://localhost:5173 ### 3. 使用 1. 注册一个账户 → http://localhost:5173/register 2. 将一个或多个 PDF 拖放到上传页面 3. 观察仪表盘自动填充各类别、趋势和异常信息 4. 点击表格中的任意类别即可重新分类；从工具栏下载 CSV/Excel ## ⚙️ 提供商矩阵 | 提供商 | 设置 | 视觉能力 | 免费层级 | 最适合 | |---|---|---|---|---| | **Anthropic Claude** | `LLM_PROVIDER=anthropic` + `ANTHROPIC_API_KEY` | ✅ 原生 | ❌ | **生产环境** —— 对财务文档的提取质量最佳 | | **OpenAI** | `LLM_PROVIDER=openai` + `OPENAI_API_KEY` | ✅ | ❌ (付费) | 经受住实战检验，gpt-4o-mini 便宜且可靠 | | **Google Gemini** | `LLM_PROVIDER=gemini` + `GEMINI_API_KEY` | ✅ | 受区域限制 | 在有免费层级可用时成本最低 | | **Groq** | `LLM_PROVIDER=groq` + `GROQ_API_KEY` | ✅ Llama 4 Scout | **提供慷慨的免费额度** | 开发与演示 | 默认随附 Groq，以便贡献者可以免费进行端到端测试。 ## 📡 API 交互式文档位于 `/docs` (Swagger UI)。亮点： ``` POST /api/auth/register # { email, password } → { access_token, user } POST /api/auth/login # { email, password } → { access_token, user } GET /api/auth/me # bearer → { id, email, ... } POST /api/upload # multipart pdf → { upload_id, status, transaction_count } GET /api/transactions # ?category_id=&merchant=&date_from=&date_to=&limit= GET /api/transactions/export?format=csv|xlsx PUT /api/transactions/{id} # { category_id, merchant, amount, ... } POST /api/transactions/bulk-categorize # { transaction_ids, category_id, apply_to_merchants, create_rules } GET /api/categories POST /api/categories # custom categories DELETE /api/categories/{id} # delete a non-system category GET /api/categories/mappings # all keyword → category mappings POST /api/categories/{id}/mappings # add a mapping DELETE /api/categories/mappings/{id} # remove a mapping GET/POST/PUT/DELETE /api/enrichment/rules # full CRUD for the rule engine GET /api/analytics/summary # per-category totals GET /api/analytics/trends # monthly aggregates GET /api/analytics/forecast?horizon_months=3 GET /api/analytics/anomalies?limit=10 GET /api/analytics/cashflow # income vs expense + net, by month GET /api/budgets # monthly category caps + spend / projection status POST /api/budgets # { category_id, amount, currency } — create or update a cap PUT /api/budgets/{id} # { amount } DELETE /api/budgets/{id} GET /api/subscriptions # detected recurring charges + leak summary PUT /api/subscriptions/override # { merchant_key, status: confirmed|cancelled|ignored } DELETE /api/subscriptions/override/{merchant_key} GET /api/subscriptions/insights # money-coach headline: leaking/mo, total saved, health score GET /api/subscriptions/alerts # prioritized feed: trials ending, payments due, price hikes GET /api/subscriptions/ledger # manual entries (statement-verified) + suggestions + summary POST /api/subscriptions/manual # add a hand-entered subscription PUT /api/subscriptions/manual/{id} # edit one DELETE /api/subscriptions/manual/{id} # remove one POST /api/subscriptions/manual/from-suggestion # { merchant_key } — promote a detected charge into the ledger GET /api/subscriptions/cards # per-card monthly load + next statement/due projection PUT /api/subscriptions/cards # { name, statement_day, due_day } DELETE /api/subscriptions/cards/{name} # clear a card's statement config GET /api/notifications # sync alerts + list (unread count) POST /api/notifications/{id}/read # mark read POST /api/notifications/read-all # mark all read DELETE /api/notifications/{id} # dismiss GET/PUT /api/notifications/preferences # { email_enabled, min_severity } POST /api/notifications/deliver-now # send the email digest now (test) ```

示例：订阅响应

``` { "currency": "TRY", "summary": { "active_count": 4, "leak_count": 2, "monthly_recurring_total": "264.15", "estimated_monthly_waste": "159.98", "estimated_monthly_savings": "0.00", "estimated_yearly_waste": "1919.76" }, "subscriptions": [ { "merchant": "Netflix", "cadence": "monthly", "occurrences": 5, "monthly_cost": "99.99", "last_charge": "2026-05-04", "next_charge_estimate": "2026-06-03", "confidence": 0.94, "status": "detected", "is_leak": true, "leaks": [ { "type": "price_hike", "detail": "Charge rose ~50% (typ 99.99 → last 149.99 TRY)" }, { "type": "duplicate_service", "detail": "2 subscriptions in Entertainment (also: Spotify)" } ] } ] } ```

示例：创建 enrichment 规则

``` curl -X POST http://localhost:8000/api/enrichment/rules \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "Normalize A101 stores", "match_field": "merchant", "match_type": "regex", "pattern": "^A101\\s+\\d+", "set_field": "merchant", "set_value": "A101", "priority": 10 }' ``` 此规则存在后，任何提取出来的类似 `A101 9937 0911 FEVZI` 的商户，在运行分类映射*之前*都会被规范化为干净的 `A101`。

示例：异常响应

``` { "currency": "TRY", "count": 3, "anomalies": [ { "merchant": "AIRBNB HMS123", "amount": "3706.76", "category_name": "Entertainment", "score": 23.5, "reason": "Entertainment z-score +23.5; top 1% overall (3707)" }, ... ] } ```

## 🗄 数据库 Schema ``` users (id, email, hashed_password, is_active, created_at) │ ├─ transactions (id, user_id, raw_text, merchant, amount, currency, │ direction, category_id, transaction_date, source_file, │ confidence_score, tag, note, created_at) │ (direction ∈ debit | credit — defaults to debit) │ └─ uploaded_files (id, user_id, filename, file_hash, status, transaction_count, error_message, created_at) categories (id, name, parent_id, color, icon, is_system, created_at) │ └─ category_mappings (id, keyword, category_id, match_type, priority, created_at) (match_type ∈ exact | contains | regex) enrichment_rules (id, name, match_field, match_type, pattern, set_field, set_value, priority, is_active, created_at) (match_type ∈ exact | contains | regex | startswith | endswith) (set_field ∈ merchant | currency | category | tag | note) subscription_overrides (id, user_id, merchant_key, status, note, created_at, updated_at) (status ∈ confirmed | cancelled | ignored) (unique per user_id + merchant_key) manual_subscriptions (id, user_id, name, merchant_key, kind, amount, currency, cadence, total_installments, paid_installments, card, category, next_payment_date, start_date, trial_end_date, expected_amount, note, is_active, created_at, updated_at) (kind ∈ subscription | installment) (cadence ∈ weekly | biweekly | monthly | quarterly | yearly) (merchant_key links a manual entry to a detected statement charge) (installment remaining / progress / end date are derived, not stored) cards (id, user_id, name, statement_day, due_day, created_at, updated_at) (statement/due day ∈ 1..31, clamped to month length when projecting) (matched to a commitment by its free-text card label) budgets (id, user_id, category_id, amount, currency, created_at, updated_at) (one monthly cap per user + category + currency) (spend / remaining / projection computed against the current month) notifications (id, user_id, alert_key, type, severity, title, detail, read_at, dismissed_at, notified_at, created_at) (one row per user + alert_key; alerts auto-resolve when they stop firing) notification_preferences (id, user_id, email_enabled, min_severity, ...) (consulted by the opt-in scheduler before emailing a digest) ``` Alembic 迁移文件位于 [`backend/alembic/versions/`](backend/alembic/versions/) 目录下。 ## 🧪 测试 ``` docker compose exec backend pytest -q # 237 个通过，耗时约 16 秒 ``` ### 测试覆盖范围 | 类别 | 文件 | 测试方法 | |---|---|---| | 异常检测器 | `tests/unit/test_anomaly_detector.py` | 极端数学情况 —— 小样本、同质数据、p99 防护机制 | | 订阅检测器 | `tests/unit/test_subscription_detector.py` | 频率拟合、月度标准化、泄漏标记、覆盖应用 | | 订阅账本 | `tests/unit/test_subscription_ledger.py` | 手动/流水匹配、到期与试用提醒、实际与预期价格涨幅对比、分期进度/结束日期/完成情况、按卡分组、汇总金额 | | 订阅洞察 | `tests/unit/test_subscription_insights.py` | 健康得分区间、数月累计节省金额、头条数据 | | 订阅提醒 | `tests/unit/test_subscription_alerts.py` | 试用/到期/涨价/分期提醒生成、严重性排序、已处理扣费抑制 | | 服务目录 | `tests/unit/test_service_catalog.py` | 已知服务查询 —— 子串/大小写/噪音容忍度、取消链接解析 | | 分期检测器 | `tests/unit/test_installment_detector.py` | "N/M" 解析、日期与计数器消歧（关键字 / 序列）、分组、完成情况 | | 账单预测 | `tests/unit/test_card_projection.py` | 下一个账单/到期日顺延、月份长度截断、总额/配置合并 | | 预算状态 | `tests/unit/test_budget_status.py` | 月份边界、正常/警告/超额区间、月末预测、零预算防护 | | 现金流 | `tests/unit/test_cash_flow.py` | 收入/支出关键字分类 (TR + EN)、借/贷方聚合、月度净额 | | 通知同步 | `tests/unit/test_notification_sync.py` | 提醒 → 通知核对（创建/解决）、已忽略项不再重新创建 | | 邮件摘要 | `tests/unit/test_email_sender.py` | 严重性阈值、摘要主题/正文组合 | | | `tests/unit/test_schemas.py` | 灵活的日期解析器（6 种格式）、空字符串处理 | | PDF 质量 | `tests/unit/test_pdf_parser.py` | 乱码与干净文本分类 | | 预测器 | `tests/unit/test_forecaster.py` | 朴素 / 线性 / Prophet 回退链 | | 安全性 | `tests/unit/test_security.py` | 密码散列、JWT 往返测试、篡改检测 | | LLM 分类器 | `tests/unit/test_llm_categorizer.py` | **模拟 Anthropic SDK** —— 完整的提供商分支、JSON 边界剥离 | | API 端点 | `tests/integration/test_api_endpoints.py` | 针对 Postgres 实时数据库的 TestClient、回滚测试夹具 | | 身份验证流程 | `tests/integration/test_api_auth.py` | 注册/登录/me + 受保护路由强制执行 | | 数据隔离 | `tests/integration/test_api_auth.py::TestDataIsolation` | 用户 A 无法看到用户 B 的交易 | 每个集成测试都在一个 SAVEPOINT 中运行，并在测试结束时进行回退，因此绝对不会触碰开发者的真实数据库。 ## ☁️ Supabase 部署 该 schema 已支持 RLS。完整指南请参见 [`supabase/README.md`](supabase/README.md)。快速版本如下： ``` supabase link --project-ref supabase db push # applies all 3 SQL migrations supabase functions deploy spending-summary # example Edge Function ``` | 表名 | 租户模式 | |---|---| | `transactions`, `uploaded_files` | 每个用户独立 (`auth.uid() = user_id`) | | `categories`, `category_mappings`, `enrichment_rules` | 共享，租户只读 | 示例 [`spending-summary` Edge Function](supabase/functions/spending-summary/index.ts) 展示了计算字段的设计模式 —— 传入用户的 JWT，该函数会调用一个 SECURITY-INVOKER RPC，RLS 会自动限定结果范围。 ## 🛣 路线图 - [x] **订阅泄漏检测** —— 检测经常性扣费，标记价格上涨 / 遗忘的会员 / 重复服务，追踪取消情况。 - [x] **手动订阅账本** —— 手动录入并追踪订阅，具备流水核对、到期/试用提醒以及一键建议功能。 - [x] **分期计划 + 按卡分组** —— 追踪按卡/账户分组的 N 个月分期消费（自动推导剩余/进度/结束日期）。 - [x] **理财教练 UI 与提醒** —— 储蓄核心指标、0-100 健康度评分、滚动“已节省”计数器，以及优先排序的应用内提醒流（试用即将结束、即将付款、价格上涨、最后几期分期）。 - [x] **已知服务目录** —— 为常见服务（Netflix、Spotify 等）提供可识别的图标、规范的类别，以及一键“如何取消”的链接。 - [x] **自动分期解析** —— 检测流水中的 "N/M" 分期账单（通过关键字 + 计数器序列进行日期与计数器消歧），并将其以一键“添加为分期”的建议形式展示。 - [x] **按卡账单预测** —— 为一张卡附加账单日 + 还款日，并预测其下一次的账单日期、金额和还款截止日期。 - [x] **每月类别预算** —— 设定各类别的上限，以此为基准跟踪本月的支出，并在您超支之前获得预警提示。 - [x] **批量分类** —— 多选行记录，一键将类别应用于来自同一商户的所有记录，并可选择将其作为规则记住。 - [x] **收支与现金流** —— 每一笔流水都带有借/贷方向（上传时自动分类，支持一键修复）；现金流视图按月份拆分资金的流入 / 流出 / 净额，且支出聚合会自动排除收入。 - [x] **分类与规则管理 UI** —— 通过一个专用界面管理分类、关键字 → 类别的映射，以及 enrichment 规则（开启/添加/删除）。 - [x] **仪表盘周期选择器** —— 将支出摘要、分类图表和现金流过滤筛选至特定月份（或所有时间段）。 - [x] **通知中心 + 邮件发送** —— 提醒将作为通知保留下来（应用内带未读徽章的小铃铛，支持已读/忽略）；一个可选 SMTP 的摘要功能和用户可选的后台调度程序会根据用户偏好发送电子邮件。 - [ ] **第二阶段**（位于开发分支）：按租户设置的 enrichment 规则、银行 API 集成（开放银行）、预算规划与提醒。 - [ ] **移动应用**（基于 React Native / Expo），复用同一个 FastAPI。 - [ ] **多币种仪表盘**，支持入账时的外汇换算。 - [ ] **Webhook 输出** —— 将每一笔新增的交易 POST 到一个可配置的 URL，以实现下游自动化。 有想要的功能吗？欢迎提交 issue！ ## 📜 许可证 [MIT](LICENSE) —— 随意使用，只需保留版权声明即可。 ## 🙋 作者 由 **Emre Seçer** 构建。诚接自由职业项目 —— 财务文档处理流水线、LLM 集成、FastAPI / Supabase 后端。 - 📨 seceremrecan@gmail.com - 💼 LinkedIn / Upwork / Bionluk 主页 如果这个项目对您有帮助，请给仓库点个 ⭐！

标签：AV绕过, DLL 劫持, FastAPI, PDF解析, React, Syscalls, 大语言模型, 异常检测, 测试用例, 请求拦截, 逆向工具, 金融数据分析