diff --git a/README.md b/README.md index 4c1996f..67b83e0 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,434 @@ -# gerenjizhang0429 +# 个人记账与预算管理系统 -个人记账系统 \ No newline at end of file +> 一款帮助用户管理日常收支、控制消费预算的财务管理工具。 + +[![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 +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