介绍
# watch-my-money
分析交易、分类支出、跟踪预算、标记超支。
## 工作流
### 1. 获取交易
向用户索要银行/信用卡的 CSV 导出文件或粘贴的文本。
常见来源： - 从您的银行在线门户下载 CSV - 从预算应用导出 - 从对账单复制/粘贴交易
支持的格式： - 任何包含日期、描述、金额列的 CSV - 粘贴的文本："2026-01-03 Starbucks -5.40 CHF"
### 2. 解析与标准化
读取输入，将其标准化为标准格式： - 自动检测分隔符（逗号、分号、制表符） - 解析日期（YYYY-MM-DD、DD/MM/YYYY、MM/DD/YYYY） - 标准化金额（支出为负，收入为正） - 从描述中提取商户 - 检测循环交易（订阅）
### 3. 交易分类
为每笔交易分配类别：
**类别：** - rent, utilities, subscriptions, groceries, eating_out - transport, travel, shopping, health - income, transfers, other
分类顺序： 1. 检查已保存的商户覆盖设置 2. 应用确定性关键词规则（参见 [common-merchants.md](references/common-merchants.md)） 3. 模式匹配（订阅、公用事业） 4. 启发式回退
对于歧义商户（一批 5-10 个），请用户确认。 为未来的运行保存覆盖设置。
### 4. 检查预算
将支出与用户定义的预算进行比较。
警报阈值： - 80% - 接近限额（黄色） - 100% - 达到限额（红色） - 120% - 超出预算（红色，紧急）
有关建议的预算，请参阅 [budget-templates.md](references/budget-templates.md)。
### 5. 检测异常
标记异常支出： - 类别激增：支出 > 基准 1.5 倍 且 差异 > 50 - 订阅增长：订阅增加 > 20% - 新的昂贵商户：首次出现 且 支出 > 30 - 潜在订阅：相同金额的循环扣款
基准 = 前 3 个月的平均值（如果没有历史记录，则为当前月份）。
### 6. 生成 HTML 报告
创建本地 HTML 文件，其中包含： - 月度摘要（收入、支出、净额） - 带预算状态的类别细分 - 顶级商户 - 警报部分 - 检测到的循环交易 - 隐私开关（模糊金额/商户）
复制 [template.html](assets/template.html) 并注入数据。
### 7. 保存状态
持久化到 `~/.watch_my_money/`： - `state.json` - 预算、商户覆盖设置、历史记录 - `reports/YYYY-MM.json` - 机器可读的月度数据 - `reports/YYYY-MM.html` - 交互式报告
## CLI 命令
```bash # Analyze CSV python -m watch_my_money analyze --csv path/to/file.csv --month 2026-01
# Analyze from stdin cat transactions.txt | python -m watch_my_money analyze --stdin --month 2026-01 --default-currency CHF
# Compare months python -m watch_my_money compare --months 2026-01 2025-12
# Set budget python -m watch_my_money set-budget --category groceries --amount 500 --currency CHF
# View budgets python -m watch_my_money budgets
# Export month data python -m watch_my_money export --month 2026-01 --out summary.json
# Reset all state python -m watch_my_money reset-state ```
## 输出结构
控制台显示： - 带有收入/支出/净额的月度摘要 - 支出与预算对比的类别表 - 检测到的循环交易 - 前 5 个商户 - 警报以项目符号形式列出
写入的文件： - `~/.watch_my_money/state.json` - `~/.watch_my_money/reports/2026-01.json` - `~/.watch_my_money/reports/2026-01.html`
## HTML 报告功能
- 可折叠的类别部分 - 预算进度条 - 循环交易列表 - 环比比较 - 隐私开关（模糊敏感数据） - 深色模式（遵循系统偏好） - 悬浮操作按钮 - 适合截图的布局 - 自动隐藏空部分
## 隐私
所有数据保留在本地。无网络调用。无外部 API。 交易数据在本地分析，仅存储在 `~/.watch_my_money/` 中。