# 个人记账与预算管理系统 > 一款帮助用户管理日常收支、控制消费预算的财务管理工具。 [![Node.js Version](https://img.shields.io/badge/node-%3E%3D18.0-brightgreen)](https://nodejs.org/) [![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE) [![Version](https://img.shields.io/badge/version-1.0.0-orange)]() --- ## 项目简介 个人记账与预算管理系统是一个基于 **React 18 + Node.js** 的全栈应用，帮助用户： - **记录每一笔收支**，清晰了解资金流向 - **设置预算额度**，有效控制消费 - **统计报表可视化**，帮助合理规划财务 ### 目标用户 - 需要管理日常收支的个人用户 - 希望控制消费、规划预算的用户 - 需要统计报表和数据导出的用户 --- ## 功能特性 | 模块 | 功能 | 说明 | |------|------|------| | **仪表盘** | 余额总览 | 显示所有账户总余额 | | | 本月收支 | 当月收入、支出、结余 | | | 预算使用率 | 各分类预算进度条 + 预警 | | **记账** | 收入/支出记录 | 支持金额、分类、日期、备注 | | | 多账户体系 | 支付宝/微信/银行卡等 | | | 记录筛选 | 按账户/类型/分类/日期筛选 | | | 余额联动 | 创建/更新/删除记录自动更新余额 | | **预算管理** | 月度预算 | 按分类设置每月支出限额 | | | 进度追踪 | 实时显示预算使用率 | | | 预警提醒 | 80% 警告 / 100% 超额 | | **统计报表** | 月度统计 | 总收入/支出/结余 + 分类占比饼图 | | | 趋势分析 | 日级收支折线图/柱状图 | | | 月度对比 | 本月 vs 上月环比分析 | | **数据导出** | Excel 导出 | 导出账单记录为 Excel 文件 | --- ## 技术架构 ### 前端 | 技术 | 版本 | 用途 | |------|------|------| | 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. 克隆项目 ```bash git clone cd personal-finance-budget-system ``` ### 2. 安装后端依赖 ```bash cd backend npm install ``` ### 3. 初始化数据库 ```bash # 生成 Prisma 客户端 npm run db:generate # 推送数据库结构（首次运行创建 SQLite 数据库文件） npm run db:push ``` ### 4. 启动后端服务 ```bash # 开发模式（自动重启） npm run dev # 生产模式 npm start ``` 后端服务启动后默认监听 `http://localhost:3001`。首次启动会自动创建测试数据。 ### 5. 安装前端依赖并启动 ```bash 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 脚本 ```bash cd backend npm run db:seed ``` ### 查看数据库 使用 Prisma Studio 可视化查看数据库： ```bash cd backend npm run db:studio ``` 浏览器将自动打开 `http://localhost:5555`。 --- ## 开发模式 ### 同时启动前后端 **方式一：两个终端** ```bash # 终端 1 - 后端 cd backend && npm run dev # 终端 2 - 前端 cd frontend && npm run dev ``` **方式二：使用 concurrently（需安装）** ```bash npm install -g concurrently # 项目根目录执行 concurrently "cd backend && npm run dev" "cd frontend && npm run dev" ``` --- ## 构建部署 ### 前端构建 ```bash cd frontend npm run build ``` 构建产物输出到 `frontend/dist/` 目录。 ### 生产环境部署 #### 方式一：静态文件 + Node 服务 1. 前端构建后，将 `frontend/dist/` 部署到 Nginx 或其他静态服务器 2. 后端使用 PM2 启动： ```bash cd backend npm install --production pm2 start src/index.js --name finance-backend ``` #### 方式二：一体化部署 将前端构建产物放在后端 `public/` 目录下，由 Express 同时提供静态文件和 API 服务。 ### 环境变量配置 生产环境需要配置以下环境变量： **后端 `.env`**: ```env DATABASE_URL="file:./prod.db" PORT=3001 ``` **前端 `.env.production`**: ```env 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](docs/API.md) ### 快速参考 | 模块 | 基础路径 | 说明 | |------|---------|------| | 健康检查 | `GET /health` | 服务状态检查 | | 用户 | `POST /api/users` | 创建用户（临时接口） | | 账户 | `/api/accounts` | 账户 CRUD | | 记录 | `/api/records` | 交易记录 CRUD + 余额联动 | | 预算 | `/api/budgets` | 月度预算管理 | | 统计 | `/api/statistics/*` | 月度/趋势/对比统计 | | 仪表盘 | `/api/dashboard/summary` | 首页聚合数据 | ### 测试 API ```bash # 健康检查 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'" ```bash cd backend npm run db:generate ``` ### Q: 数据库文件在哪里？ 默认位于 `backend/prisma/dev.db`。如需重置数据库： ```bash cd backend rm prisma/dev.db # 删除数据库 npm run db:push # 重新创建 npm run db:seed # 重新填充数据 ``` ### Q: 前端页面显示 "连接后端失败" 1. 确认后端服务已启动（访问 `http://localhost:3001/health`） 2. 检查前端 `.env` 中的 `VITE_API_BASE_URL` 是否正确 3. 修改 `.env` 后需要重启前端开发服务器 ### Q: 日期显示不对 / 差一天 后端已处理时区偏移问题。如仍有异常，请检查系统时区设置是否为 UTC+8。 --- ## 测试 ### 前端截图测试 ```bash cd frontend node verify-pages.cjs ``` 测试截图将保存到 `frontend/test-screenshots/` 目录。 ### API 测试 ```bash cd backend node test-api.js ``` --- ## License [MIT](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