31 KiB
31 KiB
校园活动组织与报名系统 - 前端开发计划
1. 项目概述
1.1 项目背景
本项目为校园活动组织与报名系统的前端部分，采用前后端分离架构，对接已完成的 Spring Boot 后端 API。
1.2 系统目标
实现活动从 发布 → 报名 → 签到 → 评价 → 统计分析 的一体化管理前端界面。
1.3 用户角色
| 角色 | 权限说明 |
|---|---|
| 普通学生 | 浏览活动、报名/取消报名、签到、评价活动 |
| 活动管理员 | 发布活动、管理报名、查看签到、统计分析、导出数据 |
2. 技术选型
2.1 核心框架
| 技术 | 版本 | 说明 |
|---|---|---|
| Vue.js | 3.4+ | 渐进式 JavaScript 框架 |
| Vite | 5.x | 下一代前端构建工具 |
| TypeScript | 5.x | JavaScript 超集，类型安全 |
| Vue Router | 4.x | 官方路由管理 |
| Pinia | 2.x | 官方状态管理 |
2.2 UI 组件库
| 技术 | 说明 |
|---|---|
| Vant 4 | 轻量、可靠的移动端 Vue 组件库（小程序风格） |
| @vant/use | Vant 组合式 API 工具库 |
2.3 工具库
| 技术 | 说明 |
|---|---|
| Axios | HTTP 请求库 |
| Day.js | 轻量日期处理库 |
| vue-qrcode-reader | 二维码扫描组件 |
| html2canvas | 截图/生成图片 |
| @vueuse/core | Vue 组合式工具集 |
2.4 开发工具
| 技术 | 说明 |
|---|---|
| ESLint | 代码规范检查 |
| Prettier | 代码格式化 |
| Husky | Git Hooks 工具 |
| lint-staged | 暂存区代码检查 |
3. 项目结构设计
campus-activity-frontend/
├── public/ # 静态资源
│ └── favicon.ico
├── src/
│ ├── api/ # API 接口层
│ │ ├── index.ts # Axios 实例配置
│ │ ├── auth.ts # 认证相关 API
│ │ ├── activity.ts # 活动相关 API
│ │ ├── registration.ts # 报名相关 API
│ │ ├── checkin.ts # 签到相关 API
│ │ ├── review.ts # 评价相关 API
│ │ └── statistics.ts # 统计相关 API
│ │
│ ├── assets/ # 静态资源
│ │ ├── images/ # 图片资源
│ │ └── styles/ # 全局样式
│ │ ├── variables.scss # SCSS 变量
│ │ ├── mixins.scss # SCSS 混入
│ │ └── global.scss # 全局样式
│ │
│ ├── components/ # 公共组件
│ │ ├── common/ # 通用组件
│ │ │ ├── NavBar.vue # 导航栏
│ │ │ ├── TabBar.vue # 底部标签栏
│ │ │ ├── Empty.vue # 空状态
│ │ │ ├── Loading.vue # 加载状态
│ │ │ └── ErrorPage.vue # 错误页面
│ │ │
│ │ ├── activity/ # 活动相关组件
│ │ │ ├── ActivityCard.vue # 活动卡片
│ │ │ ├── ActivityList.vue # 活动列表
│ │ │ ├── ActivityFilter.vue # 活动筛选
│ │ │ └── CalendarView.vue # 日历视图
│ │ │
│ │ ├── registration/ # 报名相关组件
│ │ │ ├── TicketCard.vue # 电子票卡片
│ │ │ └── RegistrationList.vue # 报名列表
│ │ │
│ │ ├── review/ # 评价相关组件
│ │ │ ├── ReviewCard.vue # 评价卡片
│ │ │ ├── ReviewForm.vue # 评价表单
│ │ │ └── RatingStars.vue # 评分星星
│ │ │
│ │ └── statistics/ # 统计相关组件
│ │ ├── StatCard.vue # 统计卡片
│ │ └── ChartView.vue # 图表视图
│ │
│ ├── composables/ # 组合式函数
│ │ ├── useAuth.ts # 认证相关
│ │ ├── useActivity.ts # 活动相关
│ │ ├── useRegistration.ts # 报名相关
│ │ ├── usePagination.ts # 分页相关
│ │ └── useToast.ts # 提示消息
│ │
│ ├── layouts/ # 布局组件
│ │ ├── DefaultLayout.vue # 默认布局
│ │ ├── AdminLayout.vue # 管理员布局
│ │ └── BlankLayout.vue # 空白布局
│ │
│ ├── router/ # 路由配置
│ │ ├── index.ts # 路由入口
│ │ ├── routes.ts # 路由定义
│ │ └── guards.ts # 路由守卫
│ │
│ ├── stores/ # 状态管理
│ │ ├── index.ts # Store 入口
│ │ ├── user.ts # 用户状态
│ │ ├── activity.ts # 活动状态
│ │ └── app.ts # 应用状态
│ │
│ ├── types/ # TypeScript 类型定义
│ │ ├── api.d.ts # API 响应类型
│ │ ├── user.d.ts # 用户类型
│ │ ├── activity.d.ts # 活动类型
│ │ ├── registration.d.ts # 报名类型
│ │ ├── checkin.d.ts # 签到类型
│ │ ├── review.d.ts # 评价类型
│ │ └── statistics.d.ts # 统计类型
│ │
│ ├── utils/ # 工具函数
│ │ ├── request.ts # 请求封装
│ │ ├── storage.ts # 本地存储
│ │ ├── format.ts # 格式化工具
│ │ ├── validate.ts # 校验工具
│ │ └── constant.ts # 常量定义
│ │
│ ├── views/ # 页面视图
│ │ ├── auth/ # 认证页面
│ │ │ ├── Login.vue # 登录
│ │ │ └── Register.vue # 注册
│ │ │
│ │ ├── home/ # 首页
│ │ │ └── Index.vue # 首页
│ │ │
│ │ ├── activity/ # 活动页面
│ │ │ ├── List.vue # 活动列表
│ │ │ ├── Detail.vue # 活动详情
│ │ │ ├── Calendar.vue # 日历视图
│ │ │ └── Search.vue # 搜索页面
│ │ │
│ │ ├── registration/ # 报名页面
│ │ │ ├── MyList.vue # 我的报名
│ │ │ └── Ticket.vue # 电子票详情
│ │ │
│ │ ├── checkin/ # 签到页面
│ │ │ └── Scan.vue # 扫码签到
│ │ │
│ │ ├── review/ # 评价页面
│ │ │ ├── Write.vue # 写评价
│ │ │ └── MyList.vue # 我的评价
│ │ │
│ │ ├── user/ # 用户页面
│ │ │ ├── Profile.vue # 个人中心
│ │ │ ├── Settings.vue # 设置
│ │ │ └── ChangePassword.vue # 修改密码
│ │ │
│ │ └── admin/ # 管理员页面
│ │ ├── Dashboard.vue # 数据面板
│ │ ├── ActivityManage.vue # 活动管理
│ │ ├── ActivityForm.vue # 活动表单(新增/编辑)
│ │ ├── RegistrationManage.vue # 报名管理
│ │ ├── CheckInManage.vue # 签到管理
│ │ ├── QRCodeGenerate.vue # 生成签到码
│ │ ├── ReviewManage.vue # 评价管理
│ │ ├── Statistics.vue # 统计分析
│ │ └── Export.vue # 数据导出
│ │
│ ├── App.vue # 根组件
│ └── main.ts # 入口文件
│
├── .env # 环境变量
├── .env.development # 开发环境变量
├── .env.production # 生产环境变量
├── .eslintrc.cjs # ESLint 配置
├── .prettierrc # Prettier 配置
├── index.html # HTML 入口
├── package.json # 项目依赖
├── tsconfig.json # TypeScript 配置
├── vite.config.ts # Vite 配置
└── README.md # 项目说明
4. 页面设计规划
4.1 页面清单
公共页面
| 页面 | 路由 | 说明 |
|---|---|---|
| 登录 | /login | 用户登录 |
| 注册 | /register | 用户注册 |
学生端页面
| 页面 | 路由 | 说明 |
|---|---|---|
| 首页 | / | 推荐活动、快捷入口 |
| 活动列表 | /activities | 活动列表（筛选、搜索） |
| 活动详情 | /activities/:id | 活动详细信息、报名入口 |
| 日历视图 | /calendar | 按日历展示活动 |
| 我的报名 | /my/registrations | 已报名活动列表 |
| 电子票 | /ticket/:id | 电子票详情、二维码 |
| 扫码签到 | /checkin/scan | 扫码签到页面 |
| 写评价 | /review/:activityId | 活动评价表单 |
| 我的评价 | /my/reviews | 我的评价列表 |
| 个人中心 | /profile | 个人信息 |
| 修改密码 | /change-password | 修改密码 |
管理员页面
| 页面 | 路由 | 说明 |
|---|---|---|
| 数据面板 | /admin/dashboard | 统计概览 |
| 活动管理 | /admin/activities | 活动列表管理 |
| 创建活动 | /admin/activities/create | 新建活动 |
| 编辑活动 | /admin/activities/:id/edit | 编辑活动 |
| 报名管理 | /admin/activities/:id/registrations | 活动报名列表 |
| 签到管理 | /admin/activities/:id/checkin | 签到管理、生成二维码 |
| 评价管理 | /admin/activities/:id/reviews | 活动评价列表 |
| 统计分析 | /admin/statistics/:id | 活动数据统计 |
| 数据导出 | /admin/export | 导出 Excel |
4.2 UI 风格设计（小程序风格）
配色方案
// 主色调
$primary-color: #07C160; // 微信绿
$primary-light: #E8F8ED; // 浅绿背景
// 功能色
$success-color: #07C160; // 成功
$warning-color: #FFA500; // 警告
$error-color: #EE0A24; // 错误
$info-color: #1989FA; // 信息
// 中性色
$text-primary: #323233; // 主要文字
$text-secondary: #969799; // 次要文字
$text-placeholder: #C8C9CC; // 占位文字
$border-color: #EBEDF0; // 边框颜色
$background-color: #F7F8FA; // 页面背景
// 活动状态色
$status-pending: #909399; // 未开始
$status-open: #07C160; // 报名中
$status-ongoing: #1989FA; // 进行中
$status-ended: #C8C9CC; // 已结束
设计原则
- 简洁清晰: 界面简洁，信息层级分明
- 圆角卡片: 使用圆角卡片承载内容，间距 12px
- 底部安全区: 适配各种手机底部安全区域
- 下拉刷新: 列表页支持下拉刷新
- 骨架屏: 加载时显示骨架屏，优化体验
- 空状态: 无数据时显示友好的空状态提示
5. 核心功能模块设计
5.1 认证模块
登录页面
┌─────────────────────────────────┐
│ 校园活动 │
│ │
│ ┌─────────────────────┐ │
│ │ 👤 请输入用户名 │ │
│ └─────────────────────┘ │
│ ┌─────────────────────┐ │
│ │ 🔒 请输入密码 │ │
│ └─────────────────────┘ │
│ │
│ ┌─────────────────────┐ │
│ │ 登 录 │ │
│ └─────────────────────┘ │
│ │
│ 还没有账号？去注册 │
└─────────────────────────────────┘
Token 管理
- Access Token 存储在 localStorage
- Refresh Token 存储在 localStorage
- Token 过期前自动刷新
- 401 响应自动跳转登录页
5.2 活动模块
活动列表页
┌─────────────────────────────────┐
│ 🔍 搜索活动 │
├─────────────────────────────────┤
│ [全部] [报名中] [进行中] [已结束]│
├─────────────────────────────────┤
│ ┌─────────────────────────────┐ │
│ │ 🖼️ 封面图 │ │
│ │ 校园篮球赛 │ │
│ │ 📅 2025-06-01 09:00 │ │
│ │ 📍 体育馆 │ │
│ │ ⭐ 4.5 👥 45/100 │ │
│ │ [报名中] │ │
│ └─────────────────────────────┘ │
│ ┌─────────────────────────────┐ │
│ │ ... │ │
│ └─────────────────────────────┘ │
├─────────────────────────────────┤
│ 🏠 📅 ✉️ 👤 │
└─────────────────────────────────┘
活动详情页
┌─────────────────────────────────┐
│ ← 活动详情 │
├─────────────────────────────────┤
│ ┌─────────────────────────────┐ │
│ │ 封面图片 │ │
│ └─────────────────────────────┘ │
│ │
│ 校园篮球赛 │
│ [体育] [报名中] │
│ │
│ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ │
│ 📅 活动时间 │
│ 2025-06-01 09:00-17:00 │
│ │
│ 📍 活动地点 │
│ 体育馆A区 │
│ │
│ 👥 报名人数 │
│ 45/100（剩余55个名额） │
│ │
│ ⏰ 报名截止 │
│ 2025-05-30 23:59 │
│ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ │
│ │
│ 活动详情 │
│ 年度篮球比赛详细介绍... │
│ │
│ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ │
│ 评价 (20条) ⭐ 4.5 │
│ ┌─────────────────────────┐ │
│ │ 张三 ⭐⭐⭐⭐⭐ │ │
│ │ 活动组织得很好！ │ │
│ └─────────────────────────┘ │
│ │
├─────────────────────────────────┤
│ ┌─────────────────────────────┐ │
│ │ 立即报名 │ │
│ └─────────────────────────────┘ │
└─────────────────────────────────┘
5.3 报名模块
我的报名列表
┌─────────────────────────────────┐
│ ← 我的报名 │
├─────────────────────────────────┤
│ [全部] [待签到] [已签到] [已取消]│
├─────────────────────────────────┤
│ ┌─────────────────────────────┐ │
│ │ 🖼️ 校园篮球赛 │ │
│ │ 📅 2025-06-01 09:00 │ │
│ │ 📍 体育馆 │ │
│ │ 票号: TK20250601001 │ │
│ │ [待签到] [查看电子票] → │ │
│ └─────────────────────────────┘ │
└─────────────────────────────────┘
电子票页面
┌─────────────────────────────────┐
│ ← 电子票 │
├─────────────────────────────────┤
│ │
│ ┌─────────────────────────┐ │
│ │ │ │
│ │ ┌───────────┐ │ │
│ │ │ QR码 │ │ │
│ │ │ │ │ │
│ │ └───────────┘ │ │
│ │ │ │
│ │ 票号: TK20250601001 │ │
│ │ ───────────────────── │ │
│ │ 活动: 校园篮球赛 │ │
│ │ 时间: 2025-06-01 09:00│ │
│ │ 地点: 体育馆 │ │
│ │ 姓名: 张三 │ │
│ │ 学号: 2021001001 │ │
│ │ │ │
│ └─────────────────────────┘ │
│ │
│ ┌─────────────────────────┐ │
│ │ 下载电子票 │ │
│ └─────────────────────────┘ │
│ │
│ ┌─────────────────────────┐ │
│ │ 取消报名 │ │
│ └─────────────────────────┘ │
└─────────────────────────────────┘
5.4 签到模块
扫码签到页面
┌─────────────────────────────────┐
│ ← 扫码签到 │
├─────────────────────────────────┤
│ │
│ │
│ ┌─────────────────────┐ │
│ │ │ │
│ │ 相机取景框 │ │
│ │ 扫描二维码 │ │
│ │ │ │
│ └─────────────────────┘ │
│ │
│ 将二维码放入框内扫描 │
│ │
└─────────────────────────────────┘
5.5 评价模块
写评价页面
┌─────────────────────────────────┐
│ ← 活动评价 │
├─────────────────────────────────┤
│ │
│ 校园篮球赛 │
│ │
│ 评分 │
│ ⭐ ⭐ ⭐ ⭐ ⭐ │
│ │
│ 评价内容 │
│ ┌─────────────────────────┐ │
│ │ 请输入您的评价... │ │
│ │ │ │
│ │ │ │
│ │ │ │
│ └─────────────────────────┘ │
│ │
├─────────────────────────────────┤
│ ┌─────────────────────────────┐ │
│ │ 提交评价 │ │
│ └─────────────────────────────┘ │
└─────────────────────────────────┘
5.6 管理员模块
数据面板
┌─────────────────────────────────┐
│ 数据面板 👤 │
├─────────────────────────────────┤
│ ┌───────┐ ┌───────┐ ┌───────┐ │
│ │ 活动 │ │ 报名 │ │ 签到 │ │
│ │ 50 │ │ 1200 │ │ 1050 │ │
│ └───────┘ └───────┘ └───────┘ │
│ │
│ ┌───────┐ ┌───────┐ │
│ │ 评价 │ │ 平均分 │ │
│ │ 800 │ │ 4.3 │ │
│ └───────┘ └───────┘ │
│ │
│ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ │
│ 本月活动趋势 │
│ ┌─────────────────────────┐ │
│ │ 📊 图表 │ │
│ └─────────────────────────┘ │
│ │
│ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ │
│ 快捷操作 │
│ [+创建活动] [📊统计] [📥导出] │
├─────────────────────────────────┤
│ 🏠 📋 📊 👤 │
└─────────────────────────────────┘
活动管理页面
┌─────────────────────────────────┐
│ 活动管理 [+] │
├─────────────────────────────────┤
│ 🔍 搜索活动 │
│ [全部] [报名中] [进行中] [已结束]│
├─────────────────────────────────┤
│ ┌─────────────────────────────┐ │
│ │ 校园篮球赛 │ │
│ │ 📅 2025-06-01 │ │
│ │ 👥 45/100 [报名中] │ │
│ │ ────────────────────────── │ │
│ │ [报名] [签到] [评价] [统计]│ │
│ │ [编辑] [删除] │ │
│ └─────────────────────────────┘ │
└─────────────────────────────────┘
6. API 对接规划
6.1 请求封装
// src/utils/request.ts
import axios from 'axios'
import type { AxiosInstance, AxiosRequestConfig } from 'axios'
const instance: AxiosInstance = axios.create({
baseURL: import.meta.env.VITE_API_BASE_URL,
timeout: 10000,
headers: {
'Content-Type': 'application/json'
}
})
// 请求拦截器：添加 Token
instance.interceptors.request.use(config => {
const token = localStorage.getItem('accessToken')
if (token) {
config.headers.Authorization = `Bearer ${token}`
}
return config
})
// 响应拦截器：处理错误
instance.interceptors.response.use(
response => response.data,
error => {
if (error.response?.status === 401) {
// Token 过期，尝试刷新或跳转登录
}
return Promise.reject(error)
}
)
6.2 API 模块划分
| 模块 | 文件 | API 数量 | 说明 |
|---|---|---|---|
| 认证 | api/auth.ts | 5 | 登录、注册、刷新 Token、获取用户信息、修改密码 |
| 活动 | api/activity.ts | 7 | 活动 CRUD、列表、日历、冲突检测 |
| 报名 | api/registration.ts | 5 | 报名、取消、我的报名、活动报名列表、电子票 |
| 签到 | api/checkin.ts | 4 | 生成二维码、扫码签到、扫票签到、签到列表 |
| 评价 | api/review.ts | 3 | 提交评价、活动评价列表、我的评价 |
| 统计 | api/statistics.ts | 3 | 活动统计、总体统计、数据导出 |
7. 状态管理设计
7.1 用户状态 (stores/user.ts)
interface UserState {
token: string | null
refreshToken: string | null
userInfo: UserInfo | null
isLoggedIn: boolean
}
// Actions
- login(username, password)
- logout()
- refreshToken()
- getUserInfo()
- updateUserInfo()
7.2 活动状态 (stores/activity.ts)
interface ActivityState {
activities: Activity[]
currentActivity: Activity | null
loading: boolean
filters: ActivityFilters
pagination: Pagination
}
// Actions
- fetchActivities(params)
- fetchActivityDetail(id)
- createActivity(data)
- updateActivity(id, data)
- deleteActivity(id)
7.3 应用状态 (stores/app.ts)
interface AppState {
loading: boolean
tabBarActive: string
theme: 'light' | 'dark'
}
8. 路由守卫设计
// 路由守卫逻辑
router.beforeEach((to, from, next) => {
const userStore = useUserStore()
// 白名单路由
const whiteList = ['/login', '/register']
if (userStore.isLoggedIn) {
if (to.path === '/login') {
next('/')
} else {
// 检查权限
if (to.meta.requiresAdmin && userStore.userInfo?.role !== 1) {
next('/403')
} else {
next()
}
}
} else {
if (whiteList.includes(to.path)) {
next()
} else {
next(`/login?redirect=${to.path}`)
}
}
})
9. 错误处理设计
9.1 全局错误处理
- 网络错误：显示"网络异常，请稍后重试"
- 401 错误：跳转登录页
- 403 错误：显示"无权限访问"
- 404 错误：显示"资源不存在"
- 409 错误：显示业务冲突信息（如"已报名"）
- 500 错误：显示"服务器异常"
9.2 表单校验
使用 Vant 内置的表单校验 + 自定义校验规则
10. 性能优化方案
10.1 代码分割
- 路由懒加载
- 组件按需导入
- Vant 组件按需加载
10.2 资源优化
- 图片懒加载
- 列表虚拟滚动（大数据量）
- 骨架屏优化首屏体验
10.3 缓存策略
- 活动列表数据缓存
- 用户信息缓存
- API 请求去重
11. 移动端适配
11.1 Viewport 配置
<meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=0">
11.2 PostCSS 配置
// postcss.config.js
module.exports = {
plugins: {
'postcss-pxtorem': {
rootValue: 37.5, // Vant 官方推荐
propList: ['*'],
},
},
}
11.3 安全区适配
// 底部安全区
.safe-area-bottom {
padding-bottom: constant(safe-area-inset-bottom);
padding-bottom: env(safe-area-inset-bottom);
}
12. 部署方案
12.1 构建命令
# 开发
npm run dev
# 构建
npm run build
# 预览
npm run preview
12.2 环境变量
# .env.development
VITE_API_BASE_URL=http://localhost:8080/api/v1
# .env.production
VITE_API_BASE_URL=/api/v1
12.3 Nginx 配置示例
server {
listen 80;
server_name example.com;
root /usr/share/nginx/html;
index index.html;
# 前端路由
location / {
try_files $uri $uri/ /index.html;
}
# API 代理
location /api {
proxy_pass http://backend:8080;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
}
}
13. 项目初始化命令
# 创建项目
npm create vite@latest campus-activity-frontend -- --template vue-ts
# 进入目录
cd campus-activity-frontend
# 安装依赖
npm install
# 安装 UI 组件库
npm install vant @vant/use
# 安装路由和状态管理
npm install vue-router pinia
# 安装工具库
npm install axios dayjs @vueuse/core
# 安装 SCSS
npm install -D sass
# 安装 ESLint + Prettier
npm install -D eslint prettier eslint-plugin-vue @typescript-eslint/eslint-plugin @typescript-eslint/parser
# 安装移动端适配
npm install -D postcss-pxtorem amfe-flexible
# 安装二维码相关
npm install vue-qrcode-reader qrcode
14. 总结
本前端开发计划基于后端 API 接口设计，采用 Vue 3 + TypeScript + Vant 4 技术栈，实现符合中国小程序风格的校园活动管理系统。
核心特点：
- 完整覆盖所有后端 API 接口
- 清晰的项目结构和模块划分
- 规范的 TypeScript 类型定义
- 小程序风格的 UI 设计
- 完善的错误处理机制
- 良好的移动端适配方案
下一步：
- 制定详细的开发规范文档
- 分解具体开发任务清单