# college-helper-web

**Repository Path**: MineLX/college-helper-web

## Basic Information

- **Project Name**: college-helper-web
- **Description**: 高校交互系统web服务
- **Primary Language**: Unknown
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-24
- **Last Updated**: 2026-06-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# College Helper Web - 高校教学管理系统

## 📚 项目概述

College Helper Web 是一个基于 Spring Boot + MyBatis 的高校教学管理 Web 应用，为教师和学生提供课程管理、课堂签到、文件共享、作业管理等一站式教学辅助功能。

### 核心特性

- ✅ **RESTful API 设计**：前后端分离架构
- ✅ **JWT 无状态认证**：Token 有效期 24 小时，支持 Header 和 URL 参数两种传递方式
- ✅ **角色权限控制**：管理员（ADMIN）、教师（TEACHER）、学生（STUDENT）
- ✅ **数据完整性保障**：外键约束、唯一索引、级联删除
- ✅ **事务管理**：保证数据一致性
- ✅ **分页查询**：支持大数据量场景
- ✅ **文件管理**：上传、下载、在线查看、视频流式播放
- ✅ **学生互评系统**：防作弊机制、自动统计平均分

---

## 🛠️ 技术栈

### 后端技术
- **框架**：Spring Boot 4.0.5
- **持久层**：MyBatis 4.0.0
- **数据库**：MySQL 9.7.0
- **开发语言**：Java 19
- **认证**：JWT (io.jsonwebtoken jjwt 0.12.3)
- **构建工具**：Maven

### 开发环境
- **JDK**：19+
- **Maven**：3.6+
- **MySQL**：8.0+
- **IDE**：IntelliJ IDEA（推荐）

---

## 📋 项目需求

### 业务需求

#### 1. 用户管理
- 支持三类用户角色：管理员、教师、学生
- JWT Token 登录认证
- 用户信息与真实身份绑定

#### 2. 班级管理
- 创建和管理行政班级
- 班级信息管理（名称、专业、年级、学院）
- 班主任分配
- 批量导入学生

#### 3. 课程管理
- 教师创建课程（课程代码、名称、学分、学时）
- 学生选课加入课程
- 按班级批量添加学生
- 课程与授课教师关联

#### 4. 课堂签到
- 教师发起课堂会话
- 学生扫码或输入签到码签到
- 记录签到时间，统计出勤情况
- 生成考勤报表

#### 5. 文件管理
- 文件上传（最大 10MB）
- 文件重命名、删除
- 分享文件到指定课程
- 获取课程文件列表
- 文件下载（attachment 模式）
- 在线查看（inline 模式，支持视频流式播放）

#### 6. 作业管理
- 教师发布作业（标题、内容、截止时间、满分值）
- 支持 HTML 富文本作业描述
- 学生提交作业
- 教师批改作业并给出分数和反馈
- **学生互评功能**：
  - 开启互评的作业，学生需评审指定数量的同学作业
  - 防作弊机制（不能评自己、不能重复评审）
  - 自动计算互评平均分
  - 实时统计互评完成进度

#### 7. 学生信息查询
- 查看学生基本信息
- 查询学生所在班级
- 查看学生选课情况
- 查看学生作业提交记录

---

## 🏗️ 项目设计

### 系统架构

```
┌─────────────────────────────────────────┐
│          前端客户端 (Browser)             │
└──────────────┬──────────────────────────┘
               │ HTTP/REST API
               │ Authorization: Bearer {token}
┌──────────────▼──────────────────────────┐
│      Spring Boot Application             │
│  ┌────────────────────────────────┐     │
│  │   Controller Layer (控制器层)    │     │
│  │  - AssignmentController        │     │
│  │  - FileController              │     │
│  │  - CourseController            │     │
│  │  - SessionController           │     │
│  │  - StudentController           │     │
│  │  - UserController              │     │
│  └──────────┬─────────────────────┘     │
│             │                           │
│  ┌──────────▼─────────────────────┐     │
│  │   Service Layer (业务逻辑层)     │     │
│  │  - AssignmentServiceImpl       │     │
│  │  - FileServiceImpl             │     │
│  │  - CourseServiceImpl           │     │
│  │  - ClassSessionServiceImpl     │     │
│  │  - StudentServiceImpl          │     │
│  └──────────┬─────────────────────┘     │
│             │                           │
│  ┌──────────▼─────────────────────┐     │
│  │   DAO Layer (数据访问层)         │     │
│  │  - AssignmentDao               │     │
│  │  - FileDao                     │     │
│  │  - CourseDao                   │     │
│  │  - StudentDao                  │     │
│  └──────────┬─────────────────────┘     │
│             │                           │
│  ┌──────────▼─────────────────────┐     │
│  │   Interceptor (拦截器)           │     │
│  │  - JwtInterceptor (认证)        │     │
│  └────────────────────────────────┘     │
└──────────────┬──────────────────────────┘
               │ JDBC
┌──────────────▼──────────────────────────┐
│         MySQL Database                   │
│  - sys_user, student, teacher          │
│  - course, class_info                  │
│  - assignment, submission              │
│  - file_info, course_file              │
│  - attendance_record, class_session    │
└─────────────────────────────────────────┘
```

---

### 数据库设计

#### 核心表结构（共 14 张表）

##### 用户相关表
1. **sys_user** - 系统用户表
   - 主键：id | 唯一索引：username
   - 字段：username, password, real_name, role, email, phone, class_id

2. **student** - 学生信息表
   - 主键：id | 唯一索引：student_no
   - 字段：student_no, name, gender, age, class_id, class_name, email, phone, grade

3. **teacher** - 教师信息表
   - 主键：id | 唯一索引：teacher_no
   - 字段：teacher_no, name, gender, department, title, email, phone

4. **user_student_binding** - 用户-学生绑定表
   - 作用：将登录用户与学生信息关联

##### 课程相关表
5. **course** - 课程表
   - 外键：teacher_id → teacher(id)
   - 字段：course_code, course_name, credit, hours, description

6. **class_info** - 班级信息表
   - 外键：teacher_id → teacher(id)（班主任）
   - 字段：class_name, grade, major, department, description

7. **course_student** - 课程-学生关联表
   - 唯一索引：(course_id, student_id)
   - 级联删除：ON DELETE CASCADE

##### 课堂相关表
8. **class_session** - 课堂会话表
   - 外键：course_id → course(id) ON DELETE CASCADE
   - 字段：start_time, end_time, status（IN_PROGRESS / ENDED）

9. **attendance_record** - 考勤记录表
   - 唯一索引：(session_id, student_id)
   - 字段：sign_in_time, status（PRESENT / ABSENT / LATE）

##### 文件相关表
10. **file_info** - 文件信息表
    - 外键：uploader_id → sys_user(id) ON DELETE CASCADE
    - 字段：file_name, original_name, file_path, file_size, file_type

11. **course_file** - 课程-文件关联表
    - 唯一索引：(course_id, file_id)
    - 级联删除：ON DELETE CASCADE

##### 作业相关表
12. **assignment** - 作业表
    - 外键：course_id → course(id), created_by → sys_user(id)
    - 字段：title, content, deadline, max_score, peer_review_enabled, reviews_per_student

13. **submission** - 作业提交表
    - 唯一索引：(assignment_id, student_id)
    - 字段：content, score, feedback, peer_review_average_score, peer_review_count, peer_review_completed

14. **peer_review** - 互评记录表
    - 唯一索引：(submission_id, reviewer_id)
    - 字段：score, feedback, reviewed_at

---

### API 接口设计

#### 认证模块
| 接口 | 方法 | 路径 | 说明 |
|------|------|------|------|
| 登录 | POST | `/api/auth/login` | 用户名密码登录，返回 JWT Token |

#### 课程模块
| 接口 | 方法 | 路径 | 说明 |
|------|------|------|------|
| 获取课程列表 | GET | `/api/courses` | 分页查询，支持按教师筛选 |
| 获取课程详情 | GET | `/api/courses/{courseId}` | 根据 ID 查询 |
| 创建课程 | POST | `/api/courses` | 教师创建新课程 |
| 更新课程 | PUT | `/api/courses/{courseId}` | 修改课程信息 |
| 删除课程 | DELETE | `/api/courses/{courseId}` | 软删除 |
| 添加学生到课程 | POST | `/api/courses/{courseId}/students` | 单个或批量添加 |
| 获取课程学生列表 | GET | `/api/courses/{courseId}/students` | 查看选课学生 |
| 获取课程文件列表 | GET | `/api/courses/{courseId}/files` | 查看课程共享文件 |

#### 文件模块
| 接口 | 方法 | 路径 | 说明 |
|------|------|------|------|
| 获取文件列表 | GET | `/api/files` | 分页查询用户上传的文件 |
| 上传文件 | POST | `/api/files/upload` | 单文件上传，最大 10MB |
| 删除文件 | DELETE | `/api/files/{fileId}` | 删除文件和物理文件 |
| 重命名文件 | PUT | `/api/files/{fileId}/rename` | 修改文件显示名称 |
| 分享文件到课程 | POST | `/api/files/{fileId}/share` | 建立课程-文件关联 |
| 下载文件 | GET | `/api/files/{fileId}/download` | attachment 模式下载 |
| 在线查看文件 | GET | `/api/files/{fileId}/view` | inline 模式，支持视频流 |

#### 课堂模块
| 接口 | 方法 | 路径 | 说明 |
|------|------|------|------|
| 创建课堂会话 | POST | `/api/sessions` | 教师发起新课堂 |
| 结束课堂会话 | PUT | `/api/sessions/{sessionId}/end` | 结束课堂 |
| 学生签到 | POST | `/api/sessions/{sessionId}/signin` | 学生扫码或输入签到码 |
| 获取课堂详情 | GET | `/api/sessions/{sessionId}` | 包含签到统计 |
| 获取课堂签到列表 | GET | `/api/sessions/{sessionId}/attendance` | 查看每个学生签到状态 |

#### 作业模块
| 接口 | 方法 | 路径 | 说明 |
|------|------|------|------|
| 创建作业 | POST | `/api/assignments` | 教师发布作业 |
| 获取作业列表 | GET | `/api/assignments` | 分页查询，支持按课程筛选 |
| 获取作业详情 | GET | `/api/assignments/{assignmentId}` | 包含提交状态 |
| 更新作业 | PUT | `/api/assignments/{assignmentId}` | 修改作业信息 |
| 删除作业 | DELETE | `/api/assignments/{assignmentId}` | 级联删除提交和互评 |
| 提交作业 | POST | `/api/assignments/{assignmentId}/submit` | 学生提交作业内容 |
| 批改作业 | POST | `/api/assignments/{assignmentId}/grade` | 教师打分和反馈 |
| 获取学生作业列表 | GET | `/api/assignments/student` | 查询课程内所有作业 |
| 提交互评 | POST | `/api/assignments/{assignmentId}/peer-review` | 学生评审同学作业 |
| 获取互评列表 | GET | `/api/assignments/{assignmentId}/peer-reviews` | 查看某作业的互评 |
| 获取互评进度 | GET | `/api/assignments/{assignmentId}/peer-review-stats` | 统计完成情况 |

#### 学生模块
| 接口 | 方法 | 路径 | 说明 |
|------|------|------|------|
| 获取学生列表 | GET | `/api/students` | 分页查询 |
| 获取学生详情 | GET | `/api/students/{studentId}` | 详细信息 |
| 创建学生 | POST | `/api/students` | 录入新学生 |
| 更新学生 | PUT | `/api/students/{studentId}` | 修改信息 |
| 删除学生 | DELETE | `/api/students/{studentId}` | 软删除 |

---

### 安全设计

#### JWT Token 机制

**Token 结构**：
```json
{
  "id": 7,
  "username": "student4",
  "realName": "赵六",
  "role": "STUDENT",
  "classId": 1,
  "password": "123456",
  "email": "zhaoliu@example.com",
  "phone": "13800138004",
  "iat": 1779450776,
  "exp": 1779537176
}
```

**有效期**：24 小时（86400 秒）

**Token 传递方式**：
1. **HTTP Header（推荐）**
   ```
   Authorization: Bearer eyJhbGci...
   ```

2. **URL 参数（方便视频播放）**
   ```
   GET /api/files/2/view?token=eyJhbGci...
   ```

#### 拦截器配置

所有 `/api/**` 路径都需要 JWT 认证，除了 `/api/auth/login` 登录接口。

---

## 💻 项目实现

### 核心技术实现

#### 1. JWT 认证

**JwtUtil.java**
- `createToken(Map<String, Object> claims)` - 生成 Token
- `validateToken(String token)` - 验证 Token
- `getUserIdFromToken(String token)` - 提取用户 ID

**JwtInterceptor.java**
- 优先从 HTTP Header 获取 Token
- 降级从 URL 参数获取 Token
- 验证失败返回 401 Unauthorized

#### 2. 文件上传与下载

**文件上传**
- 生成 UUID 唯一文件名
- 保存到配置的上传目录（`D:/my-uploads`）
- 记录文件元数据到数据库

**文件下载**
- `download` 接口：attachment 模式，触发浏览器下载
- `view` 接口：inline 模式，支持视频流式播放
- 根据文件扩展名设置 Content-Type

#### 3. 学生互评算法

**防作弊机制**
- 检查是否是自己提交的作业
- 检查是否已评审过该作业
- 唯一索引约束防止重复评审

**自动统计**
- 每次提交互评时触发统计更新
- 动态计算平均分
- 实时更新互评完成状态

#### 4. 作业查询优化

**getStudentAssignments 接口**
- 先通过 `course_student` 表获取学生所在课程
- 再查询这些课程的所有作业
- 关联返回提交状态（hasSubmitted）
- 确保学生能看到课程内所有作业，而不仅是已提交的

---

## 🚀 快速开始

### 1. 环境准备

确保已安装以下软件：
- JDK 19+
- Maven 3.6+
- MySQL 8.0+

### 2. 数据库配置

创建数据库并执行初始化脚本：

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

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

# 使用数据库
USE school_db;

# 执行初始化脚本
source src/main/resources/schema.sql;
```

### 3. 修改配置文件

编辑 `src/main/resources/application.properties`：

```properties
# 数据库配置
spring.datasource.url=jdbc:mysql://localhost:3306/school_db?useSSL=false&serverTimezone=UTC&characterEncoding=utf8
spring.datasource.username=root
spring.datasource.password=你的密码

# 文件上传路径
file.upload.path=D:/my-uploads
```

### 4. 编译运行

```bash
# 编译项目
mvn clean package

# 运行应用
mvn spring-boot:run
```

或者直接运行 `DemoApplication.java` 主类。

### 5. 测试接口

应用启动后，访问：
```
http://localhost:8080
```

**登录示例**：
```bash
curl -X POST http://localhost:8080/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"student1","password":"123456"}'
```

返回 JWT Token 后，在后续请求中携带：
```bash
curl -X GET http://localhost:8080/api/courses \
  -H "Authorization: Bearer {your_token}"
```

---

## 📁 项目结构

```
college-helper-web/
├── src/
│   ├── main/
│   │   ├── java/com/example/demo/
│   │   │   ├── common/           # 通用类（PageResult）
│   │   │   ├── config/           # 配置类（CORS, WebConfig）
│   │   │   ├── controller/       # 控制器层（9个Controller）
│   │   │   ├── dao/              # 数据访问层（11个DAO）
│   │   │   ├── dto/              # 数据传输对象
│   │   │   ├── interceptor/      # 拦截器（JwtInterceptor）
│   │   │   ├── pojo/             # 实体类（11个POJO）
│   │   │   ├── service/          # 服务层接口
│   │   │   ├── service/impl/     # 服务层实现
│   │   │   ├── util/             # 工具类（JwtUtil）
│   │   │   └── DemoApplication.java  # 启动类
│   │   └── resources/
│   │       ├── mapper/           # MyBatis XML 映射文件
│   │       ├── application.properties  # 配置文件
│   │       └── schema.sql        # 数据库初始化脚本
│   └── test/                     # 单元测试
├── pom.xml                       # Maven 配置
└── README.md                     # 项目文档
```

---

## 🔧 配置说明

### application.properties

```properties
# 应用名称
spring.application.name=demo

# 数据库配置
spring.datasource.url=jdbc:mysql://localhost:3306/school_db
spring.datasource.username=root
spring.datasource.password=12345
spring.datasource.driver-class-name=com.mysql.cj.jdbc.Driver

# MyBatis 配置
mybatis.mapper-locations=classpath:mapper/*.xml
mybatis.type-aliases-package=com.example.demo.pojo
mybatis.configuration.map-underscore-to-camel-case=true

# 文件上传配置
spring.servlet.multipart.max-file-size=10MB
spring.servlet.multipart.max-request-size=10MB
file.upload.path=D:/my-uploads
```

---

## 📊 测试数据

项目包含以下测试数据：

### 用户账号
- **管理员**：admin / 123456
- **教师**：teacher1 / 123456, teacher2 / 123456
- **学生**：student1~student4 / 123456

### 课程
- CS101 - 计算机科学导论
- CS102 - 数据结构
- CS103 - 操作系统
- CS104 - 计算机网络
- CS105 - 数据库系统

### 班级
- 计算机科学与技术2024级1班
- 软件工程2024级1班
- 网络工程2024级1班

---

## ⚠️ 注意事项

### 安全性
- ⚠️ **当前密码为明文存储**，生产环境需要使用 BCrypt 等加密算法
- ⚠️ JWT Secret Key 应使用环境变量配置，不要硬编码
- ⚠️ 建议添加 HTTPS 支持

### 性能优化
- 大文件上传建议使用分片上传
- 视频文件建议使用 CDN 加速
- 可以添加 Redis 缓存热点数据

### 待改进功能
- [ ] 密码加密存储
- [ ] 全局异常处理（@ControllerAdvice）
- [ ] 更细粒度的权限控制
- [ ] 操作日志记录
- [ ] 数据备份与恢复

---

## 🤝 贡献指南

欢迎提交 Issue 和 Pull Request！

---

## 📄 许可证

本项目仅供学习交流使用。

---

## 📞 联系方式

如有问题，请提交 Issue 或通过以下方式联系。

---

**最后更新时间**：2026-05-22