Skip to content

xdt11/finance

BranchesTags

Repository files navigation

💰 个人财务管理系统 (Personal Finance Management System)

Java 17 Spring Boot Vue 3 TypeScript PostgreSQL MIT License

📖 项目简介

这是一个面向个人、家庭和小型团队的现代化财务管理系统，采用前后端分离架构，提供灵活、直观的财务记录与分析功能。

✨ 核心特性

  • 📝 日常记账 - 记录工资、衣食住行等日常流水
  • 💹 理财投资 - 独立管理投资资产、交易记录和持仓信息 (FIFO)
  • 👨‍👩‍👧‍👦 群组协作 - 支持家庭/团队共享财务数据
  • 📊 统计分析 - 直观的图表展示收支趋势和资产分布
  • 🎨 有机设计 - 柔和、温暖、自然的用户界面

🛠️ 技术栈

后端

技术 版本 说明
Spring Boot 3.2.12 后端框架
Java 17 编程语言
MyBatis-Plus 3.5.5 ORM 框架
Spring Security 6.x 安全框架
JWT - 认证方案
PostgreSQL 14+ 数据库
Maven 3.8+ 构建工具

前端

技术 版本 说明
Vue 3.4 前端框架
TypeScript 5.6 编程语言
Vite 6.0 构建工具
Tailwind CSS 3.4 CSS 框架
Headless UI - 无样式组件库
Pinia 2.2 状态管理
Axios 1.7 HTTP 客户端

📁 项目结构

finance-app/
├── finance-common/       # 公共模块 (工具类、常量、异常)
├── finance-core/         # 核心模块 (实体、Repository、Service)
├── finance-api/          # API模块 (Controller、DTO、安全配置)
├── finance-web/          # Web入口 (启动类、配置)
├── finance-frontend/     # 前端项目 (Vue3 + TypeScript)
├── docs/                 # 文档
├── .github/              # GitHub Actions CI/CD
├── .do/                  # DigitalOcean 部署配置
├── Dockerfile            # Docker 构建文件
├── docker-compose.yml    # Docker Compose 配置
└── pom.xml               # Maven 父 POM

🚀 快速开始

前置要求

  • Java 17+
  • Node.js 18+
  • PostgreSQL 14+ (或使用 Supabase)
  • Maven 3.8+

方式一: 本地开发

1. 克隆项目

git clone https://github.com/your-username/finance-app.git
cd finance-app

2. 配置数据库

编辑 finance-web/src/main/resources/application.yml:

spring:
  datasource:
    url: jdbc:postgresql://localhost:5432/finance_db
    username: your_username
    password: your_password

3. 启动后端

# Windows
set TUSHARE_TOKEN=你的_tushare_token_不要提交到仓库
.\mvnw.cmd clean install -DskipTests
.\mvnw.cmd spring-boot:run -pl finance-web

# Linux/Mac
export TUSHARE_TOKEN=你的_tushare_token_不要提交到仓库
./mvnw clean install -DskipTests
./mvnw spring-boot:run -pl finance-web

后端运行在: http://localhost:8080/api

4. 启动前端

cd finance-frontend
npm install
npm run dev

前端运行在: http://localhost:5173

方式二: Docker 部署

# 1) 复制并填写环境变量（不要把 token 提交到仓库）
#    参考: docs/env.example
#
# 2) 启动所有服务 (后端 + PostgreSQL)
docker-compose up -d

# 查看日志
docker-compose logs -f backend

☁️ 云部署 (DigitalOcean App Platform)

详尽的部署与环境说明请见 docs/DEPLOYMENT.md（包含 OAuth、Secrets、local testing、数据库迁移脚本与 DigitalOcean 配置）。

新增: OAuth2 (Google / GitHub) 支持 ✅

  • 本项目已集成 OAuth2 登录流程（后端自动生成 ClientRegistrationRepository 依赖于 spring-boot-starter-oauth2-client）。
  • 请在 docs/DEPLOYMENT.md 中查看：本地/生产回调 URL、在 OAuth 提供商（GitHub/Google）中配置回调、以及在 DigitalOcean 控制台中设置 OAUTH_* secrets 的详细步骤。

部署步骤

  1. Fork 本仓库 到你的 GitHub

  2. 创建 DigitalOcean 账号 并进入 App Platform

  3. 创建新应用

    • 选择 GitHub 作为源
    • 授权并选择你 fork 的仓库
    • 选择 main 分支

  4. 配置环境变量 (在 App Platform 控制台设置):

变量名 说明 示例
SPRING_DATASOURCE_URL 数据库连接 URL jdbc:postgresql://xxx.pooler.supabase.com:5432/postgres
SPRING_DATASOURCE_USERNAME 数据库用户名 postgres.xxxxx
SPRING_DATASOURCE_PASSWORD 数据库密码 your-password
JWT_SECRET JWT 密钥 (至少 256 位) your-256-bit-secret-key

  1. 部署 - 点击 Deploy，等待构建完成

  2. 访问应用 - 使用 DigitalOcean 分配的域名

使用 Supabase 作为数据库

推荐使用 Supabase 的免费 PostgreSQL：

OAuth 回呼 URL 提示：如果你启用第三方登录（GitHub / Google），请在提供商控制台注册以下后端回调：

  • GitHub: https://<your-domain>/api/login/oauth2/code/github
  • Google: https://<your-domain>/api/login/oauth2/code/google

并把前端回调（接收 token）设置为： https://<your-domain>/auth/callback。

  1. 创建 Supabase 项目
  2. 进入 Settings → Database → Connection string
  3. 选择 Session Pooler 模式 (兼容 IPv4)
  4. 复制连接信息填入环境变量

📡 API 文档

认证 API

方法 路径 说明 认证
POST /api/v1/auth/register 用户注册 ❌
POST /api/v1/auth/login 用户登录 ❌
GET /api/v1/auth/me 获取当前用户 ✅

流水 API

方法 路径 说明
GET /api/v1/flows 获取流水列表
POST /api/v1/flows 添加流水
PUT /api/v1/flows/{id} 更新流水
DELETE /api/v1/flows/{id} 删除流水
GET /api/v1/flows/range 按时间范围查询流水，接受 startTime / endTime（ISO 8601）

更多 API

  • /api/v1/categories - 分类管理
  • /api/v1/budgets - 预算管理
  • /api/v1/assets - 资产管理
  • /api/v1/transactions - 交易记录
  • /api/v1/groups - 群组管理

前端/后端协作注意事项（近期变更）

  • 前端已迁移为以 Pinia 为主的集中式状态管理：useFlowStore、useAssetStore 等负责缓存与增量更新；页面组件应优先从 store 读取数据。
  • 新增后端接口 /api/v1/flows/range 用于按时间范围高效查询大量流水数据，前端会在筛选有时间范围时使用该接口。
  • 交易与流水的前端 API 已支持按时间范围查询（例如 startDate/endDate）——部署后请确保后端支持这些 query 参数。

在你要把这些变更推送到远端并部署前，请先运行 TypeScript 类型检查并进行一次端到端测试（推荐在 staging 环境）：

cd finance-frontend
npm install
npx vue-tsc --noEmit
npm run build
cd ..
# 后端构建
.\mvnw.cmd clean install -DskipTests

🔧 开发配置

PowerShell API 测试

# 注册用户
$body = @{userName="testuser"; password="Test123456"; email="test@example.com"} | ConvertTo-Json
Invoke-RestMethod -Uri "http://localhost:8080/api/v1/auth/register" -Method POST -Body $body -ContentType "application/json"

# 登录获取 Token
$body = @{userName="testuser"; password="Test123456"} | ConvertTo-Json
$response = Invoke-RestMethod -Uri "http://localhost:8080/api/v1/auth/login" -Method POST -Body $body -ContentType "application/json"
$token = $response.data.token

# 带 Token 请求
$headers = @{Authorization = "Bearer $token"}
Invoke-RestMethod -Uri "http://localhost:8080/api/v1/auth/me" -Headers $headers

健康检查

curl http://localhost:8080/api/actuator/health

📋 开发进度

✅ 已完成

  • Maven 多模块架构
  • 11 个实体类 + Repository
  • Spring Security + JWT 认证
  • CORS 跨域配置
  • 统一响应封装 + 全局异常处理
  • 前端 Vue3 项目 (登录/注册/仪表盘/流水/资产/预算页面)
  • 10 个 UI 组件库
  • Docker 容器化配置
  • DigitalOcean 部署配置
  • GitHub Actions CI/CD

⏳ 待开发

  • FIFO 持仓计算逻辑
  • 盈亏统计功能
  • 单元测试覆盖
  • Swagger API 文档
  • 图表统计功能

🤝 贡献指南

  1. Fork 本仓库
  2. 创建特性分支 (git checkout -b feature/amazing-feature)
  3. 提交更改 (git commit -m 'Add amazing feature')
  4. 推送到分支 (git push origin feature/amazing-feature)
  5. 提交 Pull Request

📄 许可证

MIT License

📞 联系方式

  • 项目: Personal Finance Management System
  • 版本: 1.0.0-SNAPSHOT
  • 更新日期: 2025-12-08

Made with ❤️ by Finance Team

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

No packages published

Languages