campus-activity-system/server/README.md

校园活动组织与报名系统

基于 Spring Boot 3.x 的校园活动组织与报名系统后端项目。

技术栈

• Java 21
• Spring Boot 3.2.5
• Spring Security 6.x
• MyBatis-Plus 3.5.5
• MySQL 8.0+
• JWT (jjwt 0.12.5)
• Knife4j 4.4.0
• Hutool 5.8.25
• ZXing 3.5.2 (二维码)
• iText 8.0.2 (PDF)
• EasyExcel 3.3.4

项目结构

campus-activity-system/
├── src/main/java/com/campus/activity/
│   ├── CampusActivityApplication.java    # 启动类
│   ├── config/                           # 配置类
│   ├── controller/                       # 控制器层
│   ├── service/                          # 服务层
│   ├── mapper/                           # 数据访问层
│   ├── entity/                           # 实体类
│   ├── dto/                              # 数据传输对象
│   ├── vo/                               # 视图对象
│   ├── common/                           # 公共模块
│   ├── exception/                        # 异常处理
│   ├── security/                         # 安全模块
│   └── util/                             # 工具类
├── src/main/resources/
│   ├── application.yml
│   └── mapper/                           # MyBatis XML映射文件
├── docs/
│   └── init.sql                          # 数据库初始化脚本
└── pom.xml

快速开始

1. 环境要求

• JDK 21+
• MySQL 8.0+
• Maven 3.6+

2. 数据库初始化

执行 docs/init.sql 脚本创建数据库和表：

mysql -u root -p < docs/init.sql

3. 配置数据库连接

修改 src/main/resources/application.yml 中的数据库配置：

spring:
  datasource:
    url: jdbc:mysql://localhost:3306/campus_activity?useUnicode=true&characterEncoding=utf8&serverTimezone=Asia/Shanghai
    username: root
    password: your_password

4. 运行项目

mvn spring-boot:run

或者在 IDE 中运行 CampusActivityApplication.java。

5. 访问 API 文档

启动成功后，访问 Knife4j API 文档：

http://localhost:8080/doc.html

默认账号

• 管理员账号：admin / admin123

API 接口

认证模块

• POST /api/v1/auth/register - 用户注册
• POST /api/v1/auth/login - 用户登录
• POST /api/v1/auth/refresh - 刷新Token
• GET /api/v1/auth/me - 获取当前用户信息
• PUT /api/v1/auth/password - 修改密码

活动模块

• GET /api/v1/activities - 活动列表
• GET /api/v1/activities/{id} - 活动详情
• POST /api/v1/activities - 创建活动（管理员）
• PUT /api/v1/activities/{id} - 更新活动（管理员）
• DELETE /api/v1/activities/{id} - 删除活动（管理员）
• GET /api/v1/activities/calendar - 日历视图
• POST /api/v1/activities/check-conflict - 时间冲突检测

报名模块

• POST /api/v1/registrations - 报名活动
• DELETE /api/v1/registrations/{id} - 取消报名
• GET /api/v1/registrations/my - 我的报名列表
• GET /api/v1/registrations/activity/{activityId} - 活动报名列表（管理员）
• GET /api/v1/registrations/{id}/ticket - 下载电子票PDF

签到模块

• POST /api/v1/checkin/qrcode/{activityId} - 生成签到二维码（管理员）
• POST /api/v1/checkin/scan - 学生扫码签到
• POST /api/v1/checkin/ticket - 管理员扫票签到
• GET /api/v1/checkin/activity/{activityId} - 签到列表（管理员）

评价模块

• POST /api/v1/reviews - 提交评价
• GET /api/v1/reviews/activity/{activityId} - 活动评价列表
• GET /api/v1/reviews/my - 我的评价列表

统计模块

• GET /api/v1/statistics/activity/{activityId} - 活动统计（管理员）
• GET /api/v1/statistics/activity/{activityId}/export - 导出活动数据（管理员）
• GET /api/v1/statistics/overview - 总体统计（管理员）

开发说明

代码规范

• 遵循阿里巴巴 Java 开发手册
• 使用 Lombok 简化代码
• 统一异常处理
• 统一响应格式

安全说明

• 使用 JWT 进行身份认证
• 密码使用 BCrypt 加密存储
• 接口权限控制基于角色

许可证

Apache License 2.0