# 毕设

**Repository Path**: frankGallagher/graduation-project

## Basic Information

- **Project Name**: 毕设
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 2
- **Forks**: 0
- **Created**: 2026-05-09
- **Last Updated**: 2026-06-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<p align="center">
  <h1 align="center">校园志愿服务管理平台</h1>
  <p align="center">Campus Volunteer Service Management Platform</p>
  <p align="center">
    <img src="https://img.shields.io/badge/Vue-3.3-4FC08D?style=flat&logo=vue.js" />
    <img src="https://img.shields.io/badge/Element Plus-2.4-409EFF?style=flat" />
    <img src="https://img.shields.io/badge/Express-4.18-000000?style=flat&logo=express" />
    <img src="https://img.shields.io/badge/MySQL-8.0-4479A1?style=flat&logo=mysql" />
    <img src="https://img.shields.io/badge/Node.js-18+-339933?style=flat&logo=node.js" />
    <img src="https://img.shields.io/badge/License-MIT-blue?style=flat" />
  </p>
</p>

---

## 目录

- [项目简介](#项目简介)
- [在线演示](#在线演示)
- [核心功能](#核心功能)
- [技术栈](#技术栈)
- [项目结构](#项目结构)
- [环境要求](#环境要求)
- [快速开始](#快速开始)
- [部署指南](#部署指南)
- [测试账号](#测试账号)
- [API 接口](#api-接口)
- [设计规范](#设计规范)
- [常见问题](#常见问题)
- [贡献指南](#贡献指南)
- [许可证](#许可证)
- [联系方式](#联系方式)

---

## 项目简介

本项目是一个面向高校的**志愿服务全流程数字化管理平台**，旨在解决校园志愿服务信息分散、流程不规范、记录不透明、统计困难等问题。平台为**学生志愿者**、**组织负责人**和**校级管理员**三类角色提供统一、高效、透明的管理服务。

**核心价值：**
- 规范志愿项目的发布、报名、审核、记录与认证流程
- 实现志愿服务时长的自动化记录与统计
- 为管理决策提供可视化的数据支持
- 生成标准化的志愿服务证书

---

## 在线演示

- **访问地址：** [http://8.160.124.24/](http://8.160.124.24/)

---

## 核心功能

### 用户端（学生志愿者）

| 功能模块 | 功能说明 |
|---------|---------|
| 项目浏览 | 按分类、状态筛选志愿项目，支持关键词搜索 |
| 在线报名 | 一键报名参与志愿活动，实时查看审核状态 |
| 时长记录 | 提交志愿服务时长，等待组织确认 |
| 个人中心 | 查看参与统计、报名记录、服务时长 |
| 证书管理 | 申请并下载志愿服务证明 |
| 评价反馈 | 对参与的项目进行评分和评价 |
| 消息通知 | 接收报名审核、时长确认等系统通知 |

### 管理端（组织负责人 / 校级管理员）

| 功能模块 | 功能说明 |
|---------|---------|
| 项目管理 | 创建、编辑、发布志愿项目 |
| 报名审核 | 审核学生报名申请，通过或拒绝 |
| 时长确认 | 确认学生提交的志愿服务时长 |
| 用户管理 | 管理平台用户账号与角色权限 |
| 数据统计 | 可视化图表展示平台运营数据 |
| 机构管理 | 管理志愿服务组织机构信息 |
| 操作日志 | 查看系统关键操作的审计日志 |
| 证书审核 | 审核并发放志愿服务证书 |

---

## 技术栈

### 前端

| 技术 | 版本 | 用途 |
|------|------|------|
| Vue 3 | 3.3+ | 渐进式 JavaScript 框架（组合式 API） |
| Element Plus | 2.4+ | UI 组件库 |
| Pinia | 2.1+ | 状态管理（含持久化插件） |
| Vue Router | 4.2+ | 前端路由 |
| Axios | 1.6+ | HTTP 请求库 |
| ECharts | 5.4+ | 数据可视化图表 |
| Vite | 4.5+ | 构建工具 |
| Sass | 1.69+ | CSS 预处理器 |

### 后端

| 技术 | 版本 | 用途 |
|------|------|------|
| Node.js | 18+ | JavaScript 运行时 |
| Express | 4.18+ | Web 应用框架 |
| MySQL2 | 3.6+ | 数据库驱动 |
| JWT | 9.0+ | 身份认证 |
| bcryptjs | 2.4+ | 密码加密 |
| Helmet | 7.1+ | 安全 HTTP 头 |
| express-validator | 7.0+ | 请求参数校验 |
| Multer | 1.4+ | 文件上传处理 |

### 数据库与部署

| 技术 | 用途 |
|------|------|
| MySQL 8.0 | 关系型数据库 |
| Nginx | 反向代理与静态资源服务 |
| PM2 | Node.js 进程管理 |
| 宝塔面板 | 服务器运维管理 |

---

## 项目结构

```
VolunteerSystem/
├── frontend/                    # 前端项目
│   ├── src/
│   │   ├── api/                 # API 请求封装
│   │   ├── assets/              # 静态资源
│   │   │   ├── images/          # 背景图片素材
│   │   │   ├── styles/          # 全局样式（设计规范）
│   │   │   ├── bg-*.svg         # SVG 背景图案
│   │   │   └── ...
│   │   ├── components/          # 通用组件
│   │   ├── layouts/             # 布局组件
│   │   │   ├── MainLayout.vue   # 公共页面布局
│   │   │   ├── UserLayout.vue   # 用户中心布局
│   │   │   └── AdminLayout.vue  # 管理后台布局
│   │   ├── router/              # 路由配置
│   │   ├── stores/              # Pinia 状态管理
│   │   ├── views/               # 页面组件
│   │   │   ├── admin/           # 管理后台页面
│   │   │   ├── user/            # 用户中心页面
│   │   │   ├── LoginPage.vue    # 登录页
│   │   │   ├── ProjectListPage.vue
│   │   │   ├── ProjectDetailPage.vue
│   │   │   └── ...
│   │   ├── App.vue              # 根组件
│   │   └── main.js              # 入口文件
│   ├── vite.config.js           # Vite 配置
│   └── package.json
│
├── backend/                     # 后端项目
│   ├── src/
│   │   ├── controllers/         # 路由控制器
│   │   ├── models/              # 数据库模型
│   │   ├── middlewares/         # 中间件（认证、权限）
│   │   ├── routes/              # API 路由定义
│   │   ├── services/            # 业务逻辑层
│   │   ├── utils/               # 工具函数
│   │   └── app.js               # Express 应用入口
│   ├── config/                  # 配置文件（数据库连接）
│   ├── database/                # 数据库脚本
│   ├── uploads/                 # 文件上传目录
│   ├── .env                     # 环境变量
│   └── package.json
│
├── database/                    # 数据库脚本
│   ├── schema.sql               # 表结构定义
│   └── seed.sql                 # 初始数据
│
├── docs/                        # 项目文档
│   ├── PRD.md                   # 产品需求文档
│   ├── Frontend.md              # 前端技术文档
│   ├── Backend.md               # 后端技术文档
│   ├── API.md                   # API 接口文档
│   ├── task.md                  # 开发任务清单
│   └── context_state.md         # 项目状态追踪
│
└── README.md                    # 项目说明文件
```

---

## 环境要求

| 环境 | 最低版本 | 推荐版本 |
|------|---------|---------|
| Node.js | 18.0.0 | 18.x LTS |
| MySQL | 8.0 | 8.0+ |
| npm | 8.0.0 | 9.x |
| 操作系统 | Windows 10 / macOS 12 / Ubuntu 20.04 | - |

---

## 快速开始

### 1. 克隆项目

```bash
git clone https://gitee.com/frankGallagher/graduation-project.git
cd graduation-project
```

### 2. 数据库初始化

```bash
# 登录 MySQL
mysql -u root -p

# 创建数据库
CREATE DATABASE volunteer_db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

# 导入表结构
mysql -u root -p volunteer_db < database/schema.sql

# 导入初始数据（含测试账号）
mysql -u root -p volunteer_db < database/seed.sql
```

### 3. 后端启动

```bash
cd backend

# 安装依赖
npm install

# 配置环境变量（修改 .env 文件中的数据库连接信息）
# DB_HOST=localhost
# DB_PORT=3306
# DB_USER=root
# DB_PASSWORD=你的数据库密码
# DB_NAME=volunteer_db

# 开发模式启动（自动重启）
npm run dev

# 或生产模式启动
npm start
```

后端服务默认运行在 `http://localhost:3000`

### 4. 前端启动

```bash
cd frontend

# 安装依赖
npm install

# 开发模式启动
npm run dev
```

前端开发服务器默认运行在 `http://localhost:5173`

### 5. 访问应用

打开浏览器访问 `http://localhost:5173`，使用测试账号登录即可。

---

## 部署指南

### 前端打包

```bash
cd frontend
npm run build
```

打包产物位于 `frontend/dist/` 目录，将其中的所有文件上传到 Web 服务器根目录。

### Nginx 配置

```nginx
server {
    listen 80;
    server_name your-domain.com;

    root /www/wwwroot/volunteer-frontend;
    index index.html;

    # SPA 路由回退
    location / {
        try_files $uri $uri/ /index.html;
    }

    # API 反向代理
    location /api/ {
        proxy_pass http://127.0.0.1:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }

    # 上传文件代理
    location /uploads/ {
        proxy_pass http://127.0.0.1:3000;
    }

    # 静态资源缓存
    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg)$ {
        expires 7d;
        add_header Cache-Control "public, immutable";
    }

    # Gzip 压缩
    gzip on;
    gzip_types text/plain text/css application/json application/javascript;
}
```

### PM2 进程管理

```bash
cd /www/wwwroot/volunteer-backend
npm install --production

# 使用 PM2 启动
pm2 start src/app.js --name "volunteer-api"

# 设置开机自启
pm2 startup
pm2 save
```

---

## 测试账号

初始数据导入后，可使用以下账号登录：

| 角色 | 用户名 | 密码 | 说明 |
|------|--------|------|------|
| 系统管理员 | admin | admin123 | 拥有所有管理权限 |
| 组织负责人 | org001 | org123 | 可发布项目、审核报名 |
| 学生志愿者 | student001 | stu123 | 可浏览项目、报名参与 |

> 以上为开发测试账号，生产环境请务必修改密码并删除测试数据。

---

## API 接口

### 基础信息

- **基础 URL：** `/api/v1`
- **认证方式：** JWT Bearer Token
- **请求格式：** JSON
- **响应格式：**

```json
{
  "code": 20000,
  "message": "操作成功",
  "data": {}
}
```

### 接口列表

| 模块 | 接口 | 方法 | 说明 | 认证 |
|------|------|------|------|------|
| 认证 | `/auth/login` | POST | 用户登录 | 否 |
| 认证 | `/auth/register` | POST | 用户注册 | 否 |
| 用户 | `/users/me` | GET | 获取当前用户信息 | 是 |
| 项目 | `/projects` | GET | 获取项目列表 | 否 |
| 项目 | `/projects` | POST | 创建项目 | 是(管理员) |
| 项目 | `/projects/:id` | GET | 获取项目详情 | 否 |
| 项目 | `/projects/:id` | PUT | 更新项目 | 是(管理员) |
| 报名 | `/projects/:id/applications` | POST | 提交报名 | 是 |
| 报名 | `/applications` | GET | 获取报名列表 | 是 |
| 报名 | `/applications/:id/review` | POST | 审核报名 | 是(管理员) |
| 时长 | `/hours` | POST | 提交时长记录 | 是 |
| 时长 | `/hours/:id/confirm` | POST | 确认时长 | 是(管理员) |
| 统计 | `/statistics/overview` | GET | 获取总览统计 | 是(管理员) |
| 统计 | `/statistics/user/:id` | GET | 获取用户统计 | 是 |
| 证书 | `/certificates` | GET | 获取证书列表 | 是 |
| 证书 | `/certificates/:id/download` | GET | 下载证书 | 是 |
| 通知 | `/notifications` | GET | 获取通知列表 | 是 |
| 反馈 | `/feedbacks` | POST | 提交评价 | 是 |

### 错误码说明

| 错误码 | 说明 |
|--------|------|
| 20000 | 操作成功 |
| 40001 | 请求参数错误 |
| 40101 | 未登录或 Token 过期 |
| 40301 | 权限不足 |
| 40401 | 资源不存在 |
| 50000 | 服务器内部错误 |

---

## 设计规范

### 色彩系统

| 用途 | 色值 | 说明 |
|------|------|------|
| 主色 | `#3FBFAB` | 青绿色品牌色 |
| 主色-浅 | `#E6F7F4` | 背景、标签 |
| 主色-深 | `#35A695` | hover 状态 |
| 强调色 | `#F5A65B` | 暖琥珀色 |
| 成功色 | `#67C23A` | 状态标签 |
| 警告色 | `#E6A23C` | 进行中状态 |
| 危险色 | `#F56C6C` | 错误提示 |
| 背景色 | `#F5F7FA` | 页面背景 |

### 设计风格

- **清新质感** — 低饱和度色彩，柔和阴影
- **微交互** — hover 上浮、点击按压、焦点发光
- **细节高级感** — 12px 圆角卡片、极淡纹理背景、动态粒子

---

## 常见问题

### Q: 数据库连接失败怎么办？

检查 `.env` 文件中的数据库配置是否正确，确保 MySQL 服务已启动，用户名密码无误。

### Q: 前端页面刷新后 404？

确保 Nginx 配置了 SPA 路由回退：`try_files $uri $uri/ /index.html;`

### Q: 图片/头像无法显示？

检查 `uploads/` 目录是否存在且有写入权限：`chmod -R 755 uploads/`

### Q: 如何修改端口？

- 后端：修改 `.env` 中的 `PORT=3000`
- 前端开发：修改 `vite.config.js` 中的 `server.port`

### Q: 如何部署到宝塔面板？

请参考上方 [部署指南](#部署指南) 部分，或查阅 `docs/` 目录下的详细文档。

---

## 贡献指南

1. Fork 本仓库
2. 创建特性分支：`git checkout -b feature/your-feature`
3. 提交更改：`git commit -m 'feat: 添加某功能'`
4. 推送分支：`git push origin feature/your-feature`
5. 提交 Pull Request

### 提交规范

| 类型 | 说明 |
|------|------|
| feat | 新功能 |
| fix | 修复 Bug |
| docs | 文档更新 |
| style | 代码格式调整 |
| refactor | 代码重构 |
| test | 测试相关 |
| chore | 构建/工具变动 |

---

## 许可证

本项目基于 [MIT License](LICENSE) 开源。

---

## 联系方式

- **项目地址：** [https://gitee.com/frankGallagher/graduation-project](https://gitee.com/frankGallagher/graduation-project)
- **在线演示：** [http://8.160.124.24/](http://8.160.124.24/)
- **问题反馈：** 请通过 Gitee Issues 提交

---

<p align="center">如果这个项目对你有帮助，请给一个 Star 支持一下！</p>