介绍
# refund-radar
扫描银行对账单以检测周期性扣费，标记可疑交易，识别重复项和费用，起草退款请求模板，并生成交互式 HTML 审计报告。
## Triggers
- “scan my bank statement for refunds”（扫描我的银行对账单以查找退款） - “analyze my credit card transactions”（分析我的信用卡交易） - “find recurring charges in my statement”（在我的对账单中查找周期性扣费） - “check for duplicate or suspicious charges”（检查重复或可疑的扣费） - “help me dispute a charge”（帮我争议一笔扣费） - “generate a refund request”（生成退款请求） - “audit my subscriptions”（审计我的订阅）
## Workflow
### 1. Get Transaction Data
询问用户的银行/卡 CSV 导出文件或粘贴的文本。常见来源：
- Apple Card: Wallet → Card Balance → Export - Chase: Accounts → Download activity → CSV - Mint: Transactions → Export - Any bank: Download as CSV from transaction history（任何银行：从交易历史下载为 CSV）
或接受粘贴的文本格式： ``` 2026-01-03 Spotify -11.99 USD 2026-01-15 Salary +4500 USD ```
### 2. Parse and Normalize
对其数据运行解析器：
```bash python -m refund_radar analyze --csv statement.csv --month 2026-01 ```
或对于粘贴的文本： ```bash python -m refund_radar analyze --stdin --month 2026-01 --default-currency USD ```
解析器自动检测： - Delimiter (comma, semicolon, tab)（分隔符：逗号、分号、制表符） - Date format (YYYY-MM-DD, DD/MM/YYYY, MM/DD/YYYY)（日期格式） - Amount format (single column or debit/credit)（金额格式：单列或借/贷） - Currency（货币）
### 3. Review Recurring Charges
工具通过以下方式识别周期性订阅： - Same merchant >= 2 times in 90 days（同一商户在 90 天内 >= 2 次） - Similar amounts (within 5% or $2)（金额相似：在 5% 或 2 美元以内） - Consistent cadence (weekly, monthly, yearly)（一致的节奏：每周、每月、每年） - Known subscription keywords (Netflix, Spotify, etc.)（已知订阅关键词，如 Netflix、Spotify 等）
输出显示： - Merchant name（商户名称） - Average amount and cadence（平均金额和节奏） - Last charge date（最后扣费日期） - Next expected charge（预计下次扣费）
### 4. Flag Suspicious Charges
工具自动标记：
| Flag Type | Trigger | Severity | |-----------|---------|----------| | Duplicate | Same merchant + amount within 2 days（同一商户 + 2 天内相同金额） | HIGH | | Amount Spike | > 1.8x baseline, delta > $25（> 1.8 倍基准，差额 > 25 美元） | HIGH | | New Merchant | First time + amount > $30（首次出现 + 金额 > 30 美元） | MEDIUM | | Fee-like | Keywords (FEE, ATM, OVERDRAFT) + > $3（关键词如 FEE, ATM, OVERDRAFT + > 3 美元） | LOW | | Currency Anomaly | Unusual currency or DCC（异常货币或 DCC） | LOW |
### 5. Clarify with User
对于标记的项目，按每批 5-10 个进行询问：
- Is this charge legitimate?（这笔扣费合法吗？） - Should I mark this merchant as expected?（我应该将此商户标记为预期的吗？） - Do you want a refund template for this?（你想要为此生成退款模板吗？）
根据答案更新状态： ```bash python -m refund_radar mark-expected --merchant "Costco" python -m refund_radar mark-recurring --merchant "Netflix" ```
### 6. Generate HTML Report
报告保存至 `~/.refund_radar/reports/YYYY-MM.html`
复制 [template.html](assets/template.html) 结构。章节包括： - **Summary**（摘要）：交易计数、总支出、周期性计数、标记计数 - **Recurring Charges**（周期性扣费）：包含商户、金额、节奏、预计下次日期的表格 - **Unexpected Charges**（异常扣费）：带有严重程度和原因的标记项目 - **Duplicates**（重复项）：同日重复扣费 - **Fee-like Charges**（类费用）：ATM 费、外汇费、服务费 - **Refund Templates**（退款模板）：可供复制的电子邮件/聊天/争议消息
功能： - Privacy toggle (blur merchant names)（隐私开关：模糊商户名称） - Dark/light mode（深色/浅色模式） - Collapsible sections（可折叠章节） - Copy buttons on templates（模板上的复制按钮） - Auto-hide empty sections（自动隐藏空章节）
### 7. Draft Refund Requests
对于每个标记的扣费，生成三种模板类型： - **Email**（电子邮件）：正式退款请求 - **Chat**（聊天）：用于实时支持的快速消息 - **Dispute**（争议）：银行争议表单文本
每种类型包含三种语气变体： - Concise (default)（简洁，默认） - Firm (assertive)（坚定，强势） - Friendly (polite)（友好，礼貌）
模板包括： - Merchant name and date（商户名称和日期） - Charge amount（扣费金额） - Dispute reason based on flag type（基于标记类型的争议原因） - Placeholders for card last 4, reference number（卡号后四位、参考号的占位符）
**Important**（重要）：任何生成的文本中均不包含撇号。
## CLI Reference
```bash # Analyze statement python -m refund_radar analyze --csv file.csv --month 2026-01
# Analyze from stdin python -m refund_radar analyze --stdin --month 2026-01 --default-currency CHF
# Mark merchant as expected python -m refund_radar mark-expected --merchant "Amazon"
# Mark merchant as recurring python -m refund_radar mark-recurring --merchant "Netflix"
# List expected merchants python -m refund_radar expected
# Reset learned state python -m refund_radar reset-state
# Export month data python -m refund_radar export --month 2026-01 --out data.json ```
## Files Written
| Path | Purpose | |------|---------| | `~/.refund_radar/state.json` | Learned preferences, merchant history（学习到的偏好、商户历史） | | `~/.refund_radar/reports/YYYY-MM.html` | Interactive audit report（交互式审计报告） | | `~/.refund_radar/reports/YYYY-MM.json` | Raw analysis data（原始分析数据） |
## Privacy
- **No network calls.**（无网络调用。）Everything runs locally.（所有操作均在本地运行。） - **No external APIs.**（无外部 API。）No Plaid, no cloud services.（不使用 Plaid，不使用云服务。） - **Your data stays on your machine.**（你的数据保留在你的机器上。） - **Privacy toggle in reports.**（报告中的隐私开关。）Blur merchant names with one click.（一键模糊商户名称。）
## Requirements
- Python 3.9+ - No external dependencies（无外部依赖）
## Repository
https://github.com/andreolf/refund-radar