# 校园活动组织与报名系统

基于 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` 脚本创建数据库和表：

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

### 3. 配置数据库连接

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

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

### 4. 运行项目

```bash
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