模块	功能	说明
仪表盘	余额总览	显示所有账户总余额
	本月收支	当月收入、支出、结余
	预算使用率	各分类预算进度条 + 预警
记账	收入/支出记录	支持金额、分类、日期、备注
	多账户体系	支付宝/微信/银行卡等
	记录筛选	按账户/类型/分类/日期筛选
	余额联动	创建/更新/删除记录自动更新余额
预算管理	月度预算	按分类设置每月支出限额
	进度追踪	实时显示预算使用率
	预警提醒	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. 克隆项目

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

MIT

更新日志

日期	版本	变更内容
2026-04-27	v1.0.0	初始版本，完成 MVP 功能开发
2026-04-27	v1.0.1	修复记录排序字段（date → createdAt）
2026-04-27	v1.0.2	增加日期安全解析逻辑，修复时区偏移

最后更新: 2026-04-28

README.md Unescape Escape

个人记账与预算管理系统

项目简介

目标用户

功能特性