snowgitea/gerenjizhang0429
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore: add README.md

Browse Source
This commit is contained in:
snowgitea
2026-04-29 10:53:12 +08:00
parent eb3c3bb727
commit d705423291
1 changed files with 433 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+433 -2
View File
@@ -1,3 +1,434 @@
# gerenjizhang0429
# 个人记账与预算管理系统
个人记账系统
> 一款帮助用户管理日常收支、控制消费预算的财务管理工具。
[![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 文件 |
---
## 页面预览
### 仪表盘
![仪表盘](docs/images/dashboard.png)
> 显示余额总览、本月收入/支出/结余、预算进度条、预警提示、最近记录
### 记账
![记账页](docs/images/record.png)
> 账单列表展示、按类型筛选（全部/支出/收入）、悬浮按钮新增记录
![记账表单](docs/images/record-form.png)
> 新增记录弹窗：支持收入/支出切换、分类选择、金额输入、日期选择、账户关联
### 预算管理
![预算管理](docs/images/budget.png)
> 预算列表、进度条展示使用率、超预算预警提示、未设置预算提醒
### 统计报表
![统计报表](docs/images/statistics.png)
> 图表类型切换（折线图/柱状图/饼图）、月度分类占比、日级趋势、本月 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