个人记账与预算管理系统
一款帮助用户管理日常收支、控制消费预算的财务管理工具。
项目简介
个人记账与预算管理系统是一个基于 React 18 + Node.js 的全栈应用，帮助用户：
- 记录每一笔收支，清晰了解资金流向
- 设置预算额度，有效控制消费
- 统计报表可视化，帮助合理规划财务
目标用户
- 需要管理日常收支的个人用户
- 希望控制消费、规划预算的用户
- 需要统计报表和数据导出的用户
功能特性
| 模块 | 功能 | 说明 |
|---|---|---|
| 仪表盘 | 余额总览 | 显示所有账户总余额 |
| 本月收支 | 当月收入、支出、结余 | |
| 预算使用率 | 各分类预算进度条 + 预警 | |
| 记账 | 收入/支出记录 | 支持金额、分类、日期、备注 |
| 多账户体系 | 支付宝/微信/银行卡等 | |
| 记录筛选 | 按账户/类型/分类/日期筛选 | |
| 余额联动 | 创建/更新/删除记录自动更新余额 | |
| 预算管理 | 月度预算 | 按分类设置每月支出限额 |
| 进度追踪 | 实时显示预算使用率 | |
| 预警提醒 | 80% 警告 / 100% 超额 | |
| 统计报表 | 月度统计 | 总收入/支出/结余 + 分类占比饼图 |
| 趋势分析 | 日级收支折线图/柱状图 | |
| 月度对比 | 本月 vs 上月环比分析 | |
| 数据导出 | Excel 导出 | 导出账单记录为 Excel 文件 |
页面预览
仪表盘
显示余额总览、本月收入/支出/结余、预算进度条、预警提示、最近记录
记账
账单列表展示、按类型筛选（全部/支出/收入）、悬浮按钮新增记录
新增记录弹窗：支持收入/支出切换、分类选择、金额输入、日期选择、账户关联
预算管理
预算列表、进度条展示使用率、超预算预警提示、未设置预算提醒
统计报表
图表类型切换（折线图/柱状图/饼图）、月度分类占比、日级趋势、本月 vs 上月对比
技术架构
前端
| 技术 | 版本 | 用途 |
|---|---|---|
| React | 18.3 | UI 框架 |
| TypeScript | 5.6 | 类型系统 |
| Vite | 6.0 | 构建工具 |
| TailwindCSS | 3.4 | 样式框架 |
| Zustand | 5.0 | 状态管理 |
| React Router | 7.14 | 路由管理 |
| ECharts | 6.0 | 图表渲染 |
| XLSX | 0.18 | Excel 导出 |
后端
| 技术 | 版本 | 用途 |
|---|---|---|
| Node.js | >=18 | 运行时 |
| Express | 4.21 | Web 框架 |
| Prisma | 6.5 | ORM / 数据库管理 |
| SQLite | - | 嵌入式数据库 |
| CORS | 2.8 | 跨域处理 |
环境要求
| 依赖 | 最低版本 | 推荐版本 |
|---|---|---|
| Node.js | 18.0 | 20.x LTS |
| npm | 9.0 | 10.x |
| Git | 2.0 | 最新版 |
Windows 用户: 确保使用 PowerShell 或 CMD 运行命令，不支持 Git Bash 中的某些路径格式。
快速开始
1. 克隆项目
git clone <your-repo-url>
cd personal-finance-budget-system
2. 安装后端依赖
cd backend
npm install
3. 初始化数据库
# 生成 Prisma 客户端
npm run db:generate
# 推送数据库结构（首次运行创建 SQLite 数据库文件）
npm run db:push
4. 启动后端服务
# 开发模式（自动重启）
npm run dev
# 生产模式
npm start
后端服务启动后默认监听 http://localhost:3001。首次启动会自动创建测试数据。
5. 安装前端依赖并启动
cd ../frontend
npm install
npm run dev
前端开发服务器默认运行在 http://localhost:5173。
6. 访问应用
打开浏览器访问 http://localhost:5173，即可看到应用界面。
数据库初始化
方式一：自动初始化（推荐）
后端服务首次启动时，如果数据库为空，会自动创建以下测试数据：
- 1 个测试用户（测试用户 / test@example.com）
- 3 个账户（支付宝 / 微信钱包 / 招商银行）
- 6 笔交易记录（2 收入 + 4 支出）
- 4 笔预算（餐饮 / 交通 / 购物 / 娱乐）
方式二：手动初始化
启动后端后，访问以下接口手动触发初始化：
GET http://localhost:3001/api/init-test-data
方式三：使用 Seed 脚本
cd backend
npm run db:seed
查看数据库
使用 Prisma Studio 可视化查看数据库：
cd backend
npm run db:studio
浏览器将自动打开 http://localhost:5555。
开发模式
同时启动前后端
方式一：两个终端
# 终端 1 - 后端
cd backend && npm run dev
# 终端 2 - 前端
cd frontend && npm run dev
方式二：使用 concurrently（需安装）
npm install -g concurrently
# 项目根目录执行
concurrently "cd backend && npm run dev" "cd frontend && npm run dev"
构建部署
前端构建
cd frontend
npm run build
构建产物输出到 frontend/dist/ 目录。
生产环境部署
方式一：静态文件 + Node 服务
- 前端构建后，将
frontend/dist/部署到 Nginx 或其他静态服务器 - 后端使用 PM2 启动：
cd backend
npm install --production
pm2 start src/index.js --name finance-backend
方式二：一体化部署
将前端构建产物放在后端 public/ 目录下，由 Express 同时提供静态文件和 API 服务。
环境变量配置
生产环境需要配置以下环境变量：
后端 .env:
DATABASE_URL="file:./prod.db"
PORT=3001
前端 .env.production:
VITE_API_BASE_URL=http://your-api-domain.com
项目结构
personal-finance-budget-system/
├── backend/ # 后端服务
│ ├── prisma/
│ │ ├── schema.prisma # 数据库模型定义
│ │ ├── seed.js # 种子数据脚本
│ │ └── dev.db # SQLite 数据库文件
│ ├── src/
│ │ └── index.js # 后端服务入口
│ ├── package.json # 后端依赖
│ └── .env # 环境变量
├── frontend/ # 前端应用
│ ├── src/
│ │ ├── components/
│ │ │ └── layout/ # 布局组件（侧边栏/底栏）
│ │ ├── pages/ # 页面组件
│ │ │ ├── Dashboard/ # 仪表盘
│ │ │ ├── Record/ # 记账页面
│ │ │ ├── Budget/ # 预算管理
│ │ │ └── Statistics/ # 统计报表
│ │ ├── services/ # API 请求服务
│ │ ├── stores/ # Zustand 状态管理
│ │ ├── types/ # TypeScript 类型定义
│ │ └── utils/ # 工具函数
│ ├── public/ # 静态资源
│ ├── package.json # 前端依赖
│ └── vite.config.js # Vite 配置
├── docs/ # 项目文档
│ └── API.md # API 接口文档
└── README.md # 本文件
API 文档
完整的 API 接口文档请查看：docs/API.md
快速参考
| 模块 | 基础路径 | 说明 |
|---|---|---|
| 健康检查 | GET /health |
服务状态检查 |
| 用户 | POST /api/users |
创建用户（临时接口） |
| 账户 | /api/accounts |
账户 CRUD |
| 记录 | /api/records |
交易记录 CRUD + 余额联动 |
| 预算 | /api/budgets |
月度预算管理 |
| 统计 | /api/statistics/* |
月度/趋势/对比统计 |
| 仪表盘 | /api/dashboard/summary |
首页聚合数据 |
测试 API
# 健康检查
curl http://localhost:3001/health
# 获取账户列表（假设 userId=1）
curl http://localhost:3001/api/accounts?userId=1
# 获取仪表盘数据
curl http://localhost:3001/api/dashboard/summary?userId=1
已知限制（MVP 阶段）
当前版本为 MVP（最小可行产品），以下功能待完善：
| 限制 | 说明 | 计划 |
|---|---|---|
| 无用户认证 | 使用 userId 查询参数做数据隔离 |
接入 JWT 鉴权 |
| SQLite 数据库 | 单文件数据库，适合开发/个人使用 | 支持 PostgreSQL/MySQL |
| 无分页 | 数据全量返回，前端分页 | 后端分页支持 |
| 无请求限流 | 无 Rate Limit 保护 | 增加限流中间件 |
| CORS 全开放 | 开发环境允许所有来源 | 限制为前端域名 |
| 无数据备份 | 手动拷贝 dev.db 文件 |
自动备份机制 |
常见问题
Q: 启动时报错 "Cannot find module '@prisma/client'"
cd backend
npm run db:generate
Q: 数据库文件在哪里？
默认位于 backend/prisma/dev.db。如需重置数据库：
cd backend
rm prisma/dev.db # 删除数据库
npm run db:push # 重新创建
npm run db:seed # 重新填充数据
Q: 前端页面显示 "连接后端失败"
- 确认后端服务已启动（访问
http://localhost:3001/health） - 检查前端
.env中的VITE_API_BASE_URL是否正确 - 修改
.env后需要重启前端开发服务器
Q: 日期显示不对 / 差一天
后端已处理时区偏移问题。如仍有异常，请检查系统时区设置是否为 UTC+8。
测试
前端截图测试
cd frontend
node verify-pages.cjs
测试截图将保存到 frontend/test-screenshots/ 目录。
API 测试
cd backend
node test-api.js
License
更新日志
| 日期 | 版本 | 变更内容 |
|---|---|---|
| 2026-04-27 | v1.0.0 | 初始版本，完成 MVP 功能开发 |
| 2026-04-27 | v1.0.1 | 修复记录排序字段（date → createdAt） |
| 2026-04-27 | v1.0.2 | 增加日期安全解析逻辑，修复时区偏移 |
最后更新: 2026-04-28