# edu-analytics

**Repository Path**: ch1ller/edu-analytics

## Basic Information

- **Project Name**: edu-analytics
- **Description**: 一款集成学业预测功能的教务管理平台，覆盖完整教务管理业务模块，同时支持基于 Kaggle 学生课堂行为数据集的学业表现预测；采用 Spring Boot + Python + FastAPI + MySQL + HTML 的前后端分离微服务架构，通过集成 5 种经典分类算法实现集成学习，依托多数投票机制提升预测效果。
- **Primary Language**: Java
- **License**: AGPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-23
- **Last Updated**: 2026-01-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: Java, Python, FastAPI, SpringBoot, HTML

## README

# 教育数据分析与预测系统

## 项目简介

本系统是一款集成学业预测功能的教务管理平台，覆盖完整教务管理业务模块，同时支持基于 Kaggle 学生课堂行为数据集的学业表现预测；采用 Spring Boot + Python + FastAPI + MySQL + HTML 的前后端分离微服务架构，通过集成 5 种经典分类算法实现集成学习，依托多数投票机制提升预测效果。

### 主要技术栈

- **后端**：Java 21 + Spring Boot 3.2.0 + MySQL 8.0 + JPA + Thymeleaf
- **机器学习**：Python + FastAPI + scikit-learn + pandas + NumPy
- **前端**：HTML5 + CSS3 + JavaScript + Thymeleaf

### 核心功能

- **学生成绩预测**：基于课堂行为数据，使用 5 种机器学习算法（决策树、随机森林、感知机、逻辑回归、神经网络）进行成绩预测
- **教务管理**：完整的学生、教师、课程、成绩管理
- **数据分析可视化**：多维度数据统计与图表展示
- **角色权限管理**：支持管理员、教师、学生三种角色
- **批量预测**：支持单个和批量学生成绩预测

## 系统截图

### 登录功能

![登录成功界面](screenshots/login-success.png)

登录成功后的界面展示，系统支持管理员、教师、学生三种角色登录。

### 前端筛选功能

![教师筛选功能](screenshots/filter-teacher.png)

前端提供筛选功能，支持按教师、班级、用户类型等多维度筛选，快速定位所需数据。

### 学生界面

![学生成绩总分计算](screenshots/student-dashboard-3.png)

学生可查看个人成绩记录，系统自动计算各科成绩总分及加权平均分，实时了解学习进度。

### 教师界面

![教师打分和总分计算](screenshots/teacher-dashboard-4.png)

教师可为学生录入成绩，系统自动计算总分，实现自动化成绩管理。

### 数据库联动功能

#### 添加用户

![添加用户](screenshots/add-user.png)

管理员可以添加新用户，系统自动验证数据完整性并保存到数据库。

#### 编辑用户

![编辑用户](screenshots/edit-user.png)

支持实时编辑用户信息，数据库即时更新，保证数据同步。

### 管理员界面

![用户管理界面](screenshots/admin-dashboard-2.png)

管理员可统一管理所有用户账户，包括所有身份账号的创建、编辑和删除。

### 成绩预测功能

![成绩预测-模型选择](screenshots/admin-dashboard-5-1.png)

集成5种机器学习算法（决策树、随机森林、感知机、逻辑回归、神经网络）进行成绩预测，采用多数投票机制提高预测准确率。

![成绩预测-结果展示](screenshots/admin-dashboard-5-2.png)

基于课堂行为数据（举手次数、资源访问、讨论互动、出勤情况）进行智能预测，输出成绩等级：H（优秀）、M（中等）、L（需改进），并提供详细的预测分析报告。

## 系统架构

```
┌─────────────┐          ┌──────────────┐         ┌─────────────┐
│   Browser   │────────▶│  Spring Boot │────────▶│   FastAPI   │
│   (Web UI)  │◀────────│    Backend   │◀────────│   ML Service│
└─────────────┘          └──────────────┘         └─────────────┘
                               │                         │
                               └─────────┬───────────────┘
                                         ▼
                                  ┌─────────────┐
                                  │  MySQL 8.0  │
                                  │  Database   │
                                  └─────────────┘
```

### 技术栈

#### 后端服务 (Java)

- **Java 21** + **Spring Boot 3.2.0**
- **Spring Data JPA** - ORM 框架
- **Thymeleaf** - 模板引擎
- **MySQL 8.0** - 数据库
- **Maven** - 项目构建

#### 机器学习服务 (Python)

- **FastAPI** - Web 框架
- **Scikit-learn** - 机器学习库
- **Pandas/NumPy** - 数据处理
- **SQLAlchemy** - ORM

#### 前端

- **HTML5/CSS3/JavaScript**
- **Thymeleaf** - 服务器端渲染

## 快速开始

### 环境要求

- JDK 21+
- Python 3.8+
- MySQL 8.0+
- Maven 3.6+

### 安装步骤

#### 1. 克隆项目

```bash
git clone https://gitee.com/ch1ller/edu-analytics.git
cd edu-analytics
```

#### 2. 配置数据库

**创建数据库**：

```sql
CREATE DATABASE edu_system_v2 CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
```

**导入数据库数据**：

**方法1：使用命令行导入**

```bash
# 进入 MySQL 命令行
mysql -u root -p

# 选择数据库
USE edu_system_v2;

# 导入数据（Windows 路径示例）
SOURCE f:/edu-analytics/java-service/src/main/resources/database/edu_system_v2_dump.sql;

# 或者直接在命令行导入
mysql -u root -p edu_system_v2 < java-service/src/main/resources/database/edu_system_v2_dump.sql
```

**方法2：使用 MySQL Workbench 或其他 GUI 工具**

1. 打开 MySQL Workbench
2. 连接到本地 MySQL 服务器
3. 选择 `edu_system_v2` 数据库
4. 打开 `java-service/src/main/resources/database/edu_system_v2_dump.sql` 文件
5. 执行 SQL 脚本

数据库包含以下表：

- `admins` - 管理员表
- `courses` - 课程表
- `course_students` - 课程学生关系表
- `grades` - 成绩表
- `homeworks` - 作业表
- `homework_submissions` - 作业提交表
- `student_performance` - 学生表现数据表（预测模型使用）
- `students` - 学生表
- `teachers` - 教师表
- `users` - 用户表
- `user_sequence` - 用户序列表

#### 3. 安装 Python 依赖

```bash
cd python-service
pip install -r requirements.txt
```

#### 4. 启动项目

**Windows 用户**：直接双击运行 `start.bat`

**手动启动**：

```bash
# 终端 1 - 启动 Python 机器学习服务
cd python-service
python main.py

# 终端 2 - 启动 Spring Boot 后端服务
cd java-service
mvn spring-boot:run
```

#### 5. 访问系统

打开浏览器访问：http://localhost:8081

### 默认账户

| 角色   | 用户名   | 密码       |
| ------ | -------- | ---------- |
| 管理员 | admin    | admin123   |
| 教师   | teacher1 | teacher123 |
| 学生   | student1 | student123 |

## 项目结构

```
edu-analytics/
├── java-service/               # Spring Boot 后端服务
│   ├── src/main/java/com/edu/
│   │   ├── controller/         # 控制器层
│   │   ├── dto/                # 数据传输对象
│   │   ├── entity/             # 实体类
│   │   ├── repository/         # 数据访问层
│   │   ├── service/            # 业务逻辑层
│   │   └── filter/             # 拦截器
│   ├── src/main/resources/
│   │   ├── application.yml     # 应用配置
│   │   ├── static/             # 静态资源
│   │   └── templates/          # HTML 模板
│   └── pom.xml                 # Maven 依赖配置
│
├── python-service/              # Python 机器学习服务
│   ├── main.py                 # FastAPI 主应用
│   ├── models/
│   │   └── model_manager.py    # 模型管理器
│   ├── db_loader.py            # 数据库加载器
│   ├── generate_charts.py      # 图表生成
│   ├── schemas.py              # 数据模型
│   ├── Data.csv                # 训练数据集
│   └── requirements.txt        # Python 依赖
│
└── start.bat                   # 项目启动脚本
```

## 数据来源

本系统使用的训练数据集 `Data.csv` 来自公开的学术数据集：

- **数据集名称**: xAPI-Edu-Data
- **数据来源**: [Kaggle - xAPI-Edu-Data](https://www.kaggle.com/datasets/aljarah/xAPI-Edu-Data/data)
- **数据规模**: 包含 480 条学生记录
- **数据内容**: 学生课堂行为数据（举手次数、资源访问、讨论互动、出勤情况等）与学业成绩等级

该数据集通过学习管理系统（LMS）追踪学生在课堂上的各种行为表现，用于预测学生的最终学业等级（H-优秀、M-中等、L-需改进）。

## 机器学习模型

### 特征工程

系统使用以下 4 个主要特征进行预测：

- **raised_hands** - 课堂举手次数
- **visited_resources** - 访问学习资源次数
- **discussion** - 讨论区参与次数
- **student_absence_days** - 缺勤天数

### 预测模型

集成 5 种机器学习算法，采用多数投票机制：

1. **决策树 (Decision Tree)** - 快速决策，可解释性强
2. **随机森林 (Random Forest)** - 高准确率，抗过拟合
3. **感知机 (Perceptron)** - 线性分类器
4. **逻辑回归 (Logistic Regression)** - 概率预测
5. **神经网络 (Neural Network)** - 复杂模式识别

### 预测结果

输出学生成绩等级：

- **H (High)** - 优秀
- **M (Middle)** - 中等
- **L (Low)** - 需要改进

## 功能模块

### 管理员功能

- 用户管理（学生、教师账号）
- 成绩预测管理
- 数据分析图表查看
- 系统配置管理

### 教师功能

- 查看班级学生信息
- 成绩录入与管理
- 批量学生成绩预测
- 查看预测分析报告

### 学生功能

- 查看个人信息
- 查看成绩记录
- 查看个人成绩预测

## API 文档

### Python 机器学习服务 (端口 8000)

#### 预测单个学生

```http
POST /predict
Content-Type: application/json

{
  "raised_hands": 50,
  "visited_resources": 80,
  "discussion": 30,
  "student_absence_days": 2
}
```

#### 批量预测

```http
POST /predict/batch
Content-Type: application/json

{
  "students": [
    {
      "raised_hands": 50,
      "visited_resources": 80,
      "discussion": 30,
      "student_absence_days": 2
    }
  ]
}
```

#### 模型训练

```http
POST /train
```

#### 从数据库加载并训练

```http
POST /train/from-db
```

### Spring Boot 后端服务 (端口 8081)

- `/` - 登录页面
- `/admin/*` - 管理员功能
- `/teacher/*` - 教师功能
- `/student/*` - 学生功能
- `/api/predict/*` - 预测接口

## 数据可视化

系统自动生成多种数据分析图表：

- **相关性热力图** - 展示各特征与成绩的相关性
- **班级成绩分布图** - 按班级展示成绩分布
- **多维分析图** - 按性别、年级、学期等维度分析

图表保存在 `python-service/static/charts/` 目录，可通过 Web 界面查看。

## 配置说明

### Spring Boot 配置

修改 [java-service/src/main/resources/application.yml](java-service/src/main/resources/application.yml):

```yaml
server:
  port: 8081

spring:
  datasource:
    url: jdbc:mysql://localhost:3306/edu_system_v2
    username: root
    password: 123456

python:
  service:
    url: http://localhost:8000  # Python 服务地址
```

### Python 服务配置

修改 [python-service/main.py](python-service/main.py) 中的数据库连接：

```python
DATABASE_URL = "mysql+pymysql://root:123456@localhost:3306/edu_system_v2"
```

## 开发指南

### 添加新的预测模型

1. 在 [python-service/models/model_manager.py](python-service/models/model_manager.py) 中添加新模型
2. 更新模型训练和预测逻辑
3. 重新训练模型并保存

### 扩展预测特征

1. 修改 [python-service/schemas.py](python-service/schemas.py) 中的数据模型
2. 更新训练数据集
3. 重新训练所有模型

### 自定义图表

修改 [python-service/generate_charts.py](python-service/generate_charts.py)，添加新的可视化逻辑。

⭐ 如果这个项目对你有帮助，请给个 Star！