# finance_manager

**Repository Path**: eternalmascot/finance_manager

## Basic Information

- **Project Name**: finance_manager
- **Description**: 个人财务管理系统``
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 3
- **Forks**: 0
- **Created**: 2026-01-12
- **Last Updated**: 2026-01-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Finance Manager

一个自托管的个人财务管理系统，定位为“个人 / 家庭小范围自用”。后端采用 FastAPI + SQLAlchemy，前端采用 Vue 3 + Vite，默认使用 SQLite 存储，并提供 WebDAV 数据库同步、定时备份、到期提醒与通知日志等能力。

如果你正在找一套「简单、可控、数据在自己手里」的财务记录工具，这个项目的目标是：尽量少的依赖、尽量顺滑的使用体验、尽量透明的本地数据。

## 功能概览

- 账户与鉴权：JWT 登录，默认初始化管理员账号
- 收支管理：交易记录、分类管理、仪表盘汇总
- 预算管理：预算设置与进度跟踪
- 存款管理：银行与存款（到期日、利率、预期收益等）
- 通知系统：到期提醒、系统通知日志（支持 Server酱）
- 自动备份：每日增量、每周全量备份
- WebDAV 同步：多设备安全同步 SQLite 数据库文件
- “全栈合一”：生产模式下后端直接托管前端 `dist`

## 技术栈

- 后端：FastAPI、SQLAlchemy、APScheduler、python-jose、passlib/bcrypt、webdav4
- 前端：Vue 3、Vite、Vue Router、Pinia、Element Plus、ECharts、Axios
- 数据库：SQLite（默认），数据库文件以单文件形式存储

## 快速开始（推荐）

本项目在 Windows 下提供了“一键启动”体验：启动后会自动初始化数据库、拉起后端服务，并在系统托盘提供图标菜单（打开网页 / 隐藏控制台 / 退出）。

- 启动方式：
  - Windows：双击 `start.bat`（如果有）或执行 `python start.py`
  - 其他系统：执行 `python start.py`（托盘功能可能不可用，但后端服务可正常启动）

- 默认访问地址：
  - Web：`http://localhost:8000`
  - API Docs：`http://localhost:8000/docs`

## 安装与手动运行（开发 / 自定义部署）

### 1) 后端（FastAPI）

1. 进入后端目录：
   - `cd backend`
2. 创建虚拟环境并安装依赖：
   - `python -m venv venv`
   - `venv\\Scripts\\python -m pip install -r requirements.txt`（Windows）
   - 其他系统按对应路径执行 `pip install -r requirements.txt`
3. 配置环境变量：
   - 在 `backend/.env` 中配置必要字段（见下方“配置说明”）
4. 初始化数据库（会创建默认分类与管理员账号）：
   - `python -m app.db.init_db`
5. 启动后端：
   - `python -m uvicorn app.main:app --host 0.0.0.0 --port 8000`

### 2) 前端（Vue 3 + Vite）

- 开发模式（热更新）：
  - `cd frontend`
  - `npm install`
  - `npm.cmd run dev`（Windows 推荐，避免 `npm.ps1` 执行策略问题）

- 生产构建（由后端托管 `frontend/dist`）：
  - `cd frontend`
  - `npm install`
  - `npm.cmd run build`

说明：生产模式下，后端会托管 `frontend/dist`，因此你无需单独启动前端服务。

## 配置说明（backend/.env）

后端通过 `backend/.env` 读取配置（见 [config.py](file:///c:/Users/dft20/Desktop/python/finance_manager/backend/app/core/config.py)）。其中以下字段为必填：

- `SECRET_KEY`：JWT 签名密钥
- `DATABASE_URL`：数据库连接串（SQLite 推荐使用 `sqlite:///./finance_manager.db`）
- `ENCRYPTION_KEY`：用于加密存储敏感配置（例如 WebDAV 密码、Server酱 SendKey）

可选字段：

- `PORT`：`start.py` 会读取该值作为启动端口（默认 8000）
- `BACKUP_DIR`：备份输出目录（默认 `../backups`）
- `SERVER_CHAN_SEND_KEY`：Server酱 SendKey（也可在系统设置中配置并加密落库）

示例（请替换为你自己的值）：

```env
PORT=8000
DATABASE_URL=sqlite:///./finance_manager.db
SECRET_KEY=please_change_me
ENCRYPTION_KEY=please_change_me_too
BACKUP_DIR=../backups
# SERVER_CHAN_SEND_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

## 默认账号与安全建议

初始化脚本会创建默认管理员账号（见 [init_db.py](file:///c:/Users/dft20/Desktop/python/finance_manager/backend/app/db/init_db.py)）：

- 用户名：`admin`
- 密码：`admin123`

开源/部署前强烈建议：

- 第一次登录后立即修改密码（或直接在数据库初始化阶段自定义）
- 为 `SECRET_KEY` 与 `ENCRYPTION_KEY` 使用高强度随机值
- 不要将真实 `.env`（含密钥）提交到公开仓库

## 数据、备份与计划任务

- SQLite 数据库文件默认在：`backend/finance_manager.db`
- 备份目录默认在：`backups/`（可通过 `BACKUP_DIR` 修改）
- 定时任务（见 [scheduler.py](file:///c:/Users/dft20/Desktop/python/finance_manager/backend/app/core/scheduler.py)）：
  - 每日 02:00：增量备份
  - 每周日 03:00：全量备份
  - 每日 08:00：检查到期存款并发送提醒
  - 每小时：重试失败通知
  - 每 1 分钟：检查 WebDAV 自动同步条件

## WebDAV 同步（多设备）

本项目的 WebDAV 同步以“数据库文件同步”为核心：把 `finance_manager.db` 作为一个整体上传/下载。

建议用法：

- 单设备写入 / 多设备查看更安全；如果要多设备写入，尽量避免同时操作
- 养成“操作前下载、操作后上传”的习惯，降低冲突概率
- 自动同步为“低打扰”策略：只有检测到数据变更且空闲一段时间后才会尝试上传

## 通知（Server酱）

支持通过 Server酱推送提醒，同时系统会记录通知日志（便于排查是否发送成功）。Server酱 SendKey 可在设置页面配置，也可通过环境变量 `SERVER_CHAN_SEND_KEY` 提供兜底值。

## 常见问题

- 控制台窗口打开时“系统卡死、右键控制台才恢复”：
  - 这通常是 Windows 控制台的 QuickEdit Mode 导致进程被挂起。可在控制台属性里关闭 QuickEdit Mode。

- PowerShell 执行 `npm run build` 提示禁止运行脚本：
  - Windows 下优先使用 `npm.cmd run build` / `npm.cmd run dev`。

- 日志出现 `/vite.svg` 或 `/favicon.ico` 的 404：
  - 通常是浏览器默认尝试加载站点图标，属于无害请求。生产模式可通过编译后的 `index.html` 或后端静态路由规避此类日志噪音。

## 贡献

欢迎提交 Issue / PR。为了便于维护，请在提交前尽量：

- 描述复现步骤与期望行为
- 提供关键日志（脱敏后）
- 保持改动范围清晰、提交信息可读

## License

暂未附带 License 文件。准备开源发布时建议补充常见开源协议（如 MIT / Apache-2.0 / GPL-3.0 等），并在仓库根目录加入对应的 `LICENSE` 文件。请根据你的开源意图选择合适协议。