435 lines
10 KiB
Markdown
435 lines
10 KiB
Markdown
# 个人记账与预算管理系统
|
||
|
||
> 一款帮助用户管理日常收支、控制消费预算的财务管理工具。
|
||
|
||
[](https://nodejs.org/)
|
||
[](LICENSE)
|
||
[]()
|
||
|
||
---
|
||
|
||
## 项目简介
|
||
|
||
个人记账与预算管理系统是一个基于 **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. 克隆项目
|
||
|
||
```bash
|
||
git clone <your-repo-url>
|
||
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
|