salen-project-finance-tracker

个人财务管理 v2.0，支持支出记录、定期订阅、储蓄目标、多币种换算与智能消费洞察。命令行工具 finance 提供报表、预算、资产组合等完整功能。

## 概述（中文）

个人财务管理 v2.0，支持支出记录、定期订阅、储蓄目标、多币种换算与智能消费洞察。命令行工具 finance 提供报表、预算、资产组合等完整功能。

## 技能正文

# 财务追踪器 v2.0

完整的个人财务管理。追踪支出、定期订阅、储蓄目标、多币种支持及智能洞察。

## 安装

```bash
clawdhub install finance-tracker
```

或添加到 PATH：
```bash
export PATH="$PATH:/path/to/finance-tracker/bin"
```

## 快速开始

```bash
# 记录一笔支出
finance add 50k "lunch at cafe"

# 带货币换算的记录
finance add $20 "online purchase"

# 查看支出
finance report week

# 获取智能洞察
finance insights
```

---

## 核心命令

### 添加支出

```bash
finance add <amount> "<description>"
```

**金额格式：**
- `50000` — 纯数字
- `50k` — k 后缀（= 50,000）
- `$50` — 美元，自动换算为本币
- `€100` — 欧元
- `100 USD` — 显式指定货币

**示例：**
```bash
finance add 50000 "lunch"
finance add 50k "groceries"
finance add $25 "Netflix subscription"
```

### 撤销与编辑

```bash
# 删除最近一笔交易
finance undo

# 编辑交易
finance edit <id> --amount=60000
finance edit <id> --desc="dinner with friends"
finance edit <id> --category=food

# 删除指定交易
finance delete <id>
```

### 查看与搜索

```bash
finance report [period]    # today, week, month, year, all
finance recent [n]         # 最近 n 笔交易
finance search "food"      # 关键词搜索
```

---

## 🔄 定期支出

自动追踪重复出现的订阅与账单。

### 添加定期项

```bash
finance recurring add <amount> "<description>" <frequency> [--day=N]
```

**频率：** daily, weekly, biweekly, monthly, quarterly, yearly

**示例：**
```bash
finance recurring add 110k "mobile provider" monthly --day=1
finance recurring add 50k "Netflix" monthly
finance recurring add 200k "gym membership" monthly --day=15
```

### 管理定期项

```bash
finance recurring              # 列出全部
finance recurring list         # 同上
finance recurring due          # 显示今日到期项
finance recurring process      # 自动记录所有到期支出
finance recurring remove <id>  # 停用
```

### 工作原理

- 定期支出追踪下次到期日
- 每日（或心跳中）运行 `finance recurring process` 自动记账
- 每笔记录出现在常规交易中
- 定期报表显示月度合计

---

## 🎯 储蓄目标

设定目标并追踪财务目标进度。

### 添加目标

```bash
finance goal add "<name>" <target> [--by=DATE] [--current=X]
```

**示例：**
```bash
finance goal add "New Laptop" 5000000 --by=2026-06-01
finance goal add "Emergency Fund" 10000000
finance goal add "Vacation" 3000000 --by=2026-08-01 --current=500000
```

### 追踪进度

```bash
# 向目标追加金额
finance goal update "Laptop" 500k

# 设置精确金额
finance goal set "Laptop" 2000000

# 查看所有目标
finance goal
finance goal list
```

### 目标特性

- **截止日期追踪** — 显示剩余天数
- **日/周/月储蓄目标** — 按期达成需存多少
- **优先级** — 高、中、低
- **完成追踪** — 达成目标时庆祝！

---

## 💱 多币种

实时汇率自动换算。

### 查看汇率

```bash
finance rates              # 显示所有常用汇率
finance rates USD          # 指定货币汇率
finance rates EUR
```

### 换算

```bash
finance convert 100 USD UZS
finance convert 50 EUR USD
```

### 支出中自动换算

```bash
# 以下自动换算为默认货币（UZS）
finance add $50 "Amazon purchase"
finance add €30 "App subscription"
finance add 100 USD "Online course"
```

### 设置默认货币

```bash
finance currency         # 显示当前货币
finance currency USD     # 更改默认货币
```

**汇率缓存：** 每 6 小时自动刷新。

---

## 💡 智能洞察

AI 驱动的支出分析与提醒。

```bash
finance insights    # 完整洞察报告
finance summary     # 快速每日摘要
finance digest      # 每周摘要
```

### 洞察内容

- **支出速度** — 日/周/月均值
- **期间对比** — 本周 vs 上周
- **分类变化** — 哪些分类上升/下降
- **异常检测** — 标记异常大额支出
- **目标进度** — 每日需存多少
- **定期到期** — 今日到期的订阅

### 输出示例

```
💡 Smart Insights
━━━━━━━━━━━━━━━━━━━━━

📈 Spending Velocity
   Daily avg: 85,000 UZS
   This month so far: 1,200,000 UZS
   Projected month total: 2,550,000 UZS

📊 This Week vs Last Week
   📈 Spending UP 23%
   This week: 595,000 UZS
   Last week: 484,000 UZS

🏷️ Notable Category Changes
   🍔 food: ↑ 45%
   🚗 transport: ↓ 20%

⚠️ Alerts
   • Unusually large expense: 350,000 on electronics

🎯 Savings Goals
   Need to save: 50,000 UZS/day
   Next deadline: Laptop in 45 days
```

---

## 收入与资产

### 记录收入

```bash
finance income 5000000 "salary"
finance income 500k "freelance project"
```

收入类型自动识别：salary, freelance, business, investment, gift

### 管理资产

```bash
finance asset add "Bank Account" 10000000 cash
finance asset add "Stocks" 5000000 stocks
finance asset add "Bitcoin" 2000000 crypto
finance asset remove "Old Account"
finance asset list
finance portfolio          # 净资产摘要
```

资产类型：cash, stocks, crypto, realestate, savings, investments

---

## 分析

```bash
finance trends [days]      # 支出趋势
finance compare [days]     # 对比当前与上一期间
finance budget <daily>     # 对照每日预算
```

### 预算检查

```bash
finance budget 100k
```

显示：
- 今日支出 vs 预算
- 本周支出 vs 周预算（7×每日）
- 剩余额度
- 超支警告

---

## 分类

从描述自动识别：

| Category | Keywords |
|----------|----------|
| 🍔 Food | lunch, dinner, cafe, restaurant, grocery |
| 🚗 Transport | taxi, uber, bus, metro, fuel |
| 🛍️ Shopping | clothes, shoes, shopping |
| 📱 Tech | phone, laptop, headphones |
| 🎮 Entertainment | movie, game, netflix, spotify |
| 📚 Education | book, course, school |
| 💊 Health | medicine, pharmacy, doctor, gym |
| 🏠 Home | rent, utility, furniture, internet |
| 💇 Personal | haircut, barber, salon |
| 🎁 Gifts | gift, present |
| ✈️ Travel | travel, flight, hotel |
| 🔄 Subscriptions | subscription, monthly, plan |

---

## 数据存储

所有数据本地存储于 `~/.finance-tracker/`：

```
~/.finance-tracker/
├── transactions.json     # 所有支出
├── FINANCE_LOG.md        # 人类可读日志
├── portfolio.json        # 资产
├── income.json           # 收入记录
├── recurring.json        # 定期支出
├── goals.json            # 储蓄目标
└── exchange_rates.json   # 缓存汇率
```

## 导出

```bash
finance export csv
finance export json
```

---

## Telegram 集成

聊天中快速记账的常用模式：

```
"spent 50k lunch" → finance add 50000 "lunch"
"taxi 15k"        → finance add 15000 "taxi"
"coffee 8k"       → finance add 8000 "coffee"
```

### 心跳集成

添加到 HEARTBEAT.md 以实现自动化处理：

```markdown
## Finance (daily)
- Run: finance recurring process
- Run: finance summary
```

---

## 完整命令参考

```
EXPENSES:
  finance add <amt> "<desc>"        Log expense
  finance undo                      Remove last
  finance edit <id> [--amount=X]    Edit transaction
  finance delete <id>               Delete transaction
  finance report [period]           Spending report
  finance recent [n]                Recent transactions
  finance search "<query>"          Search

RECURRING:
  finance recurring                 List all
  finance recurring add ...         Add subscription
  finance recurring remove <id>     Remove
  finance recurring process         Log due items
  finance recurring due             Show due today

GOALS:
  finance goal                      List goals
  finance goal add "<name>" <target> [--by=DATE]
  finance goal update "<name>" <amt>
  finance goal set "<name>" <amt>
  finance goal remove "<name>"

CURRENCY:
  finance rates [currency]          Exchange rates
  finance convert <amt> <from> <to>
  finance currency [code]           Get/set currency

INCOME & ASSETS:
  finance income <amt> "<desc>"
  finance asset add/remove/list
  finance portfolio

ANALYSIS:
  finance insights                  Smart analysis
  finance summary                   Daily summary
  finance digest                    Weekly digest
  finance trends [days]
  finance compare [days]
  finance budget <daily>

OTHER:
  finance categories
  finance export [csv|json]
  finance help
```

---

## 技巧

1. **用 k 表示千** — `50k` 比 `50000` 更快
2. **货币前缀** — `$50` 自动换算
3. **每日检查定期项** — 在心跳中运行 `finance recurring process`
4. **每周洞察** — 运行 `finance digest` 获取摘要
5. **目标追踪** — 存钱时更新目标
6. **预算提醒** — 运行 `finance budget 100k` 保持正轨

---

Made with 🦞 by Salen