# 校园活动组织与报名系统 - 开发任务清单

## 项目概述

基于Spring Boot 3.x的前后端分离架构，实现校园活动的发布、报名、签到、评价及统计功能。

---

## 阶段一：项目初始化与基础架构

### 1.1 项目搭建
- [ ] 使用Spring Initializr创建Spring Boot 3.x项目
- [ ] 配置pom.xml，添加所需依赖
  - Spring Boot Starter Web
  - Spring Boot Starter Security
  - Spring Boot Starter Validation
  - MyBatis-Plus Boot Starter
  - MySQL Connector
  - JWT (jjwt)
  - Knife4j (API文档)
  - Lombok
  - Hutool
- [ ] 创建项目目录结构
- [ ] 配置application.yml（开发/生产环境）

### 1.2 数据库初始化
- [ ] 创建MySQL数据库 `campus_activity`
- [ ] 执行建表SQL脚本
- [ ] 插入测试数据（管理员账号）
- [ ] 验证数据库连接

### 1.3 基础配置类
- [ ] 配置MyBatis-Plus（分页插件、逻辑删除）
- [ ] 配置跨域CORS
- [ ] 配置Jackson日期格式化
- [ ] 配置Knife4j API文档

### 1.4 公共模块开发
- [ ] 统一响应类 `Result<T>`
- [ ] 分页响应类 `PageResult<T>`
- [ ] 状态码枚举 `ResultCode`
- [ ] 自定义业务异常 `BusinessException`
- [ ] 全局异常处理器 `GlobalExceptionHandler`

---

## 阶段二：安全认证模块

### 2.1 JWT工具类
- [ ] JWT Token生成方法
- [ ] JWT Token解析方法
- [ ] JWT Token验证方法
- [ ] Refresh Token逻辑

### 2.2 Spring Security配置
- [ ] SecurityConfig安全配置类
- [ ] JwtAuthenticationFilter过滤器
- [ ] UserDetailsServiceImpl用户详情服务
- [ ] 配置接口权限规则
- [ ] 配置密码加密器BCrypt

### 2.3 认证接口开发
- [ ] **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` - 修改密码

---

## 阶段三：活动管理模块

### 3.1 实体与数据层
- [ ] Activity实体类
- [ ] ActivityMapper接口
- [ ] ActivityMapper.xml（复杂查询）

### 3.2 服务层
- [ ] ActivityService接口定义
- [ ] ActivityServiceImpl实现
  - [ ] 创建活动
  - [ ] 更新活动
  - [ ] 删除活动（逻辑删除）
  - [ ] 查询活动详情
  - [ ] 分页查询活动列表
  - [ ] 日历视图查询
  - [ ] 时间冲突检测
  - [ ] 活动状态自动更新（定时任务）

### 3.3 控制层
- [ ] ActivityController
- [ ] ActivityCreateRequest DTO
- [ ] ActivityUpdateRequest DTO
- [ ] ActivityVO 视图对象
- [ ] 参数校验注解

### 3.4 接口开发
- [ ] **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` - 时间冲突检测

---

## 阶段四：报名管理模块

### 4.1 实体与数据层
- [ ] Registration实体类
- [ ] RegistrationMapper接口

### 4.2 服务层
- [ ] RegistrationService接口
- [ ] RegistrationServiceImpl实现
  - [ ] 报名活动
  - [ ] 取消报名
  - [ ] 检查是否已报名
  - [ ] 检查报名人数上限
  - [ ] 检查时间冲突（与已报名活动）
  - [ ] 生成电子票唯一码

### 4.3 电子票功能
- [ ] 电子票唯一码生成（UUID或雪花算法）
- [ ] 二维码生成工具类（ZXing）
- [ ] PDF电子票生成（iText）
  - [ ] 包含活动信息
  - [ ] 包含学生姓名
  - [ ] 包含二维码

### 4.4 接口开发
- [ ] **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

---

## 阶段五：签到管理模块

### 5.1 实体与数据层
- [ ] CheckIn实体类
- [ ] CheckInMapper接口

### 5.2 服务层
- [ ] CheckInService接口
- [ ] CheckInServiceImpl实现
  - [ ] 生成活动签到二维码
  - [ ] 学生扫码签到
  - [ ] 管理员扫票签到
  - [ ] 签到状态查询

### 5.3 二维码功能
- [ ] 签到二维码生成（含活动ID、时间戳、签名）
- [ ] 二维码内容解析与验证
- [ ] 二维码有效期控制

### 5.4 接口开发
- [ ] **POST** `/api/v1/checkin/qrcode/{activityId}` - 生成签到二维码（管理员）
- [ ] **POST** `/api/v1/checkin/scan` - 学生扫码签到
- [ ] **POST** `/api/v1/checkin/ticket` - 管理员扫票签到
- [ ] **GET** `/api/v1/checkin/activity/{activityId}` - 签到列表（管理员）

---

## 阶段六：评价管理模块

### 6.1 实体与数据层
- [ ] Review实体类
- [ ] ReviewMapper接口

### 6.2 服务层
- [ ] ReviewService接口
- [ ] ReviewServiceImpl实现
  - [ ] 提交评价
  - [ ] 检查是否已评价
  - [ ] 检查是否参加过活动
  - [ ] 计算平均评分

### 6.3 接口开发
- [ ] **POST** `/api/v1/reviews` - 提交评价
- [ ] **GET** `/api/v1/reviews/activity/{activityId}` - 活动评价列表
- [ ] **GET** `/api/v1/reviews/my` - 我的评价列表

---

## 阶段七：数据统计与导出

### 7.1 统计服务
- [ ] StatisticsService接口
- [ ] StatisticsServiceImpl实现
  - [ ] 活动统计（报名人数、签到率、平均评分）
  - [ ] 评分分布统计
  - [ ] 总体统计数据
  - [ ] 月度统计数据

### 7.2 数据导出
- [ ] Excel导出工具类（EasyExcel）
- [ ] CSV导出工具类
- [ ] 报名数据导出模板
- [ ] 签到数据导出模板

### 7.3 接口开发
- [ ] **GET** `/api/v1/statistics/activity/{activityId}` - 活动统计
- [ ] **GET** `/api/v1/statistics/activity/{activityId}/export` - 导出活动数据
- [ ] **GET** `/api/v1/statistics/overview` - 总体统计

---

## 阶段八：功能完善与优化

### 8.1 定时任务
- [ ] 配置Spring Task
- [ ] 活动状态自动更新任务
  - [ ] 报名截止 → 更新状态
  - [ ] 活动开始 → 更新状态
  - [ ] 活动结束 → 更新状态

### 8.2 文件上传
- [ ] 文件上传配置
- [ ] 活动封面图片上传
- [ ] 用户头像上传
- [ ] 文件存储路径管理

### 8.3 日志与监控
- [ ] 配置日志级别
- [ ] 关键操作日志记录
- [ ] 接口访问日志

---

## 阶段九：测试与部署

### 9.1 单元测试
- [ ] Service层单元测试
- [ ] 工具类单元测试

### 9.2 接口测试
- [ ] 使用Knife4j/Swagger测试所有接口
- [ ] 编写Postman测试集合

### 9.3 部署准备
- [ ] 生产环境配置文件
- [ ] 打包配置
- [ ] 数据库初始化脚本整理

---

## 任务优先级说明

| 优先级 | 阶段 | 说明 |
|--------|------|------|
| P0 | 阶段一、二 | 基础架构，必须首先完成 |
| P1 | 阶段三、四 | 核心业务功能 |
| P2 | 阶段五、六 | 重要辅助功能 |
| P3 | 阶段七 | 数据分析功能 |
| P4 | 阶段八、九 | 优化与部署 |

---

## 技术难点提示

### 1. 时间冲突检测
检查用户报名的活动是否与新报名活动时间重叠：
```sql
SELECT * FROM activity a
INNER JOIN registration r ON a.id = r.activity_id
WHERE r.user_id = ? AND r.status = 1
  AND ((a.start_time <= ? AND a.end_time >= ?)
    OR (a.start_time <= ? AND a.end_time >= ?)
    OR (a.start_time >= ? AND a.end_time <= ?))
```

### 2. 电子票二维码
- 内容格式：`TICKET:{ticketCode}:{userId}:{activityId}`
- 使用签名防止伪造

### 3. 签到二维码
- 内容格式：`CHECKIN:{activityId}:{timestamp}:{signature}`
- 建议设置有效期（如5分钟）
- 管理员可刷新生成新二维码

### 4. 并发报名控制
- 使用数据库乐观锁或悲观锁
- 或使用Redis分布式锁
- 防止超额报名

---

## 文档清单

| 文档名称 | 状态 | 说明 |
|----------|------|------|
| 需求文档.md | ✅ 已有 | 原始需求 |
| 后端开发规范.md | ✅ 完成 | 技术选型与编码规范 |
| 数据库设计.md | ✅ 完成 | 表结构与SQL脚本 |
| API接口设计.md | ✅ 完成 | RESTful API文档 |
| 开发任务清单.md | ✅ 完成 | 本文档 |
