Overspending Fit Calou

个人支出跟踪器

一个自托管的个人理财应用程序，用于导入银行交易、分类和分析支出模式。作为Finary有限预算工具的替代品而构建。

为什么存在

• 拆分交易 --共同购买和报销是头等公民
• 去重 --导入重叠的CSV导出，无重复项
• 确定性规则 --根据模式自动对交易进行分类
• 朋友圈 --将特定活动（度假、搬家等）的支出与常规类别分开标记
• MCP 服务器 --直接从任何MCP主机（如Claude或Codex）查询和管理您的财务

特性

• CSV导入 --拖放BoursoBank CSV导出，在重叠的日期范围内进行自动重复数据删除
• 分类账视图 --浏览、筛选和搜索所有交易
• 分割分配 --跨多个类别分配单个交易
• 智能分类 --按收款人、标签或金额模式自动对交易进行分类的规则引擎
• 收款人管理 --将原始银行标签清理成有意义的收款人名称
• 朋友圈 --将日期范围标记为事件（假期、搬家、项目）并覆盖支出分析
• 分析 --按类别、收款人和时间段分列的支出明细
• 内部账户 --在不污染分析的情况下跟踪您自己账户之间的转账

技术栈

快速开始

Docker（推荐）

git clone https://github.com/CalixtheMattei/overspending-fit-calou.git
cd overspending-fit-calou
docker compose up --build

• 应用程序： http://localhost:5173
• API文件： http://localhost:8000/docs

启动顺序是健康驱动的：

• db 必须成为 healthy
• migrate 运行一次并带代码退出 0
• backend 开始并成为 healthy
• frontend 在后端运行状况通过后开始

通过以下方式检查状态：

docker compose ps

Docker开发循环（热重载）

docker compose -f docker-compose.yml -f docker-compose.dev.yml up --build

将其用于前端和后端的绑定挂载和实时重新加载的日常编码。

私有VPS部署（主机Nginx+Tailscale）

当主机级Nginx拥有端口时使用此选项 80/443 以及本地Docker端口的代理。

# 1) Install Docker + Compose plugin (Ubuntu)
curl -fsSL https://get.docker.com | sh

# 2) Clone project
git clone https://github.com/CalixtheMattei/overspending-fit-calou.git
cd overspending-fit-calou

# 3) Create deployment env file
cp .env.example .env
# Edit .env and set strong POSTGRES_PASSWORD before first deploy
# Optionally set DATABASE_URL; if omitted, backend builds it from POSTGRES_*

# 4) Deploy with VPS override (localhost-only published ports)
docker compose -f docker-compose.yml -f docker-compose.vps.yml up -d --build

日志和状态：

docker compose -f docker-compose.yml -f docker-compose.vps.yml ps
docker compose -f docker-compose.yml -f docker-compose.vps.yml logs -f
docker compose -f docker-compose.yml -f docker-compose.vps.yml logs -f backend frontend db

手动设置

先决条件： Node.js 20+，Python 3.11+，PostgreSQL 16

# 1. Start the database
docker compose up -d db

# 2. Backend
cd backend
python -m venv .venv && source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -e ".[dev]"
cp .env.example .env                               # Edit POSTGRES_* (or optional DATABASE_URL)
alembic upgrade head
uvicorn app.main:app --reload                      # http://localhost:8000

# 3. Frontend (in a new terminal)
cd frontend
npm install
npm run dev                                        # http://localhost:5173

MCP 服务器

MCP服务器将后端公开为 模型上下文协议 工具，这样克劳德就可以直接查询和管理您的财务，而无需将数据复制粘贴到提示中。

6个领域的14个工具：

克劳德代码/克劳德桌面（stdio）

创建一个 .mcp.json 在repo根目录下（gitignored--根据您的环境调整Python命令）：

{
  "mcpServers": {
    "personal-expense": {
      "command": "python",
      "args": ["mcp-server/server.py"],
      "env": { "API_BASE_URL": "http://localhost:8000" }
    }
  }
}

后端必须在Claude Code启动之前运行，才能激活工具。

Docker（SSE）

这 mcp 服务包含在 docker-compose.yml 并在端口3001上运行：

docker compose up mcp        # alongside the rest of the stack

将任何支持SSE的MCP客户端指向 http://localhost:3001/sse.

安全： MCP服务器没有内置身份验证。在专用网络（Tailscale、localhost、内部Docker网络）上运行它。请勿将端口3001暴露于公共互联网。

配置

复制 .env.example 到 .env 并根据需要调整值：

cp .env.example .env

对于Docker，通过环境变量覆盖数据库凭据：

POSTGRES_PASSWORD=my_secure_password docker compose up --build

不保留默认值 postgres/postgres 仅限本地开发之外的证书。

项目结构

overspending-fit-calou/
├── frontend/src/
│   ├── pages/          # ImportsPage, LedgerPage, RulesPage, AnalyticsPage, MomentsPage
│   ├── components/     # Untitled UI component library
│   └── services/       # API client layer (one service per domain)
├── backend/app/
│   ├── models/         # SQLAlchemy ORM models
│   ├── routers/        # FastAPI REST endpoints
│   └── services/       # Business logic (CSV parsing, dedup, rules engine)
├── mcp-server/
│   └── tools/          # One module per domain (transactions, analytics, moments, …)
├── docs/               # PRDs and contributor guides
├── docker-compose.yml      # Production-like deployment
└── docker-compose.dev.yml  # Dev overrides (hot reload, exposed ports)

CSV格式

设计用于 布尔索银行 以制表符分隔的CSV导出，采用法国十进制格式：

其他采用类似CSV格式的法国银行可能只需稍加调整即可工作。

路线图

• \[x\] M0 --项目框架（Docker、Alembic、路由）
• \[x\] M1 --CSV导入，带重复数据删除功能
• \[x\] 平方米 --分类账、拆分和收款人
• \[x\] 立方米 --自动分类规则引擎
• \[x\] M4 --分析仪表板
• \[x\] M5 --瞬间叠加

文档

• 贡献.md --开发设置、编码约定、PR指南
• CLAUDE.md --AI助手指导
• docs/AGENTS.md --贡献者指南和不变量
• docs/PRD-*.md --功能规格

贡献

看 贡献.md 用于开发设置、编码约定和PR指南。

许可证

麻省理工学院