# score-prediction-system

**Repository Path**: ch1ller/score-prediction-system

## Basic Information

- **Project Name**: score-prediction-system
- **Description**: 一款基于机器学习的学生成绩预测系统，核心围绕 Kaggle 学生课堂行为数据集分析实现学业表现精准预测；采用 Vue 3 + Spring Boot + Python + FastAPI + MySQL 的前后端分离微服务架构，集成 5 种经典分类算法构建集成学习模型，通过多数投票机制提升预测准确率。
- **Primary Language**: Python
- **License**: AGPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 6
- **Forks**: 1
- **Created**: 2026-01-23
- **Last Updated**: 2026-03-22

## Categories & Tags

**Categories**: Uncategorized

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

## README

# 学生成绩预测系统

## 项目简介

本系统是一款基于机器学习的学生成绩预测系统，核心围绕 Kaggle 学生课堂行为数据集分析实现学业表现精准预测；采用 Vue 3 + Spring Boot + Python + FastAPI + MySQL 的前后端分离微服务架构，集成 5 种经典分类算法构建集成学习模型，通过多数投票机制提升预测准确率。

系统基于4个关键行为特征进行预测：举手次数、资源访问次数、讨论参与度和缺勤情况。支持单个和批量预测，并提供完整的数据增强（4倍数据集扩展）、模型训练和可视化分析功能，为教育工作者提供科学的学情分析工具。

### 主要技术栈：

- **前端**：Vue 3 + TypeScript + Element Plus + Vite + Pinia
- **后端**：Spring Boot 3.2.0 + MySQL 8.0 + JPA
- **机器学习**：Python + FastAPI + scikit-learn + pandas

## 系统截图

系统界面采用响应式设计，能够根据屏幕尺寸自动调整布局，在不同分辨率和设备上都能保持良好的用户体验。

### 1. 首页

![首页](screenshots/1.png)

展示系统整体介绍和功能导航，用户可以快速了解系统功能并进行页面跳转。界面采用卡片式布局，随着窗口缩放自动调整内容排列方式。

### 2. 成绩预测功能

#### 2-1. 单个预测

![单个预测](screenshots/2-1.png)

支持单个学生行为数据的输入与预测。用户可以输入学生的举手次数、资源访问次数、讨论参与度和缺勤情况，系统会实时展示5种算法的预测结果和最终推荐。表单和结果区域会根据屏幕尺寸自动调整布局。

#### 2-2. 批量预测

![批量预测](screenshots/2-2.png)

支持多个学生数据的批量预测。用户可以添加多个学生记录，系统会一次性处理所有数据并展示预测结果。表格采用滚动设计，能够自适应不同屏幕高度，保证在小屏幕设备上也能完整查看数据。

### 3. 模型训练

![模型训练](screenshots/3.png)

提供模型训练功能，支持数据增强、模型训练和准确率统计。界面展示训练进度和各模型的性能指标。随着窗口大小变化，进度条和统计图表会自动调整显示方式。

### 4. 数据分析

![数据分析](screenshots/4.png)

展示自动生成的数据分析图表，包括相关性热力图、成绩分布图等多维度可视化内容。图表区域采用网格布局，能够根据屏幕宽度自动调整每行显示的图表数量，充分利用屏幕空间。

## 系统架构

本系统采用前后端分离的微服务架构：

```
┌─────────────────────────────────────────────────────────────────┐
│                       前端层 (Frontend)                          │
│          Vue 3 + TypeScript + Element Plus + Vite               │
│                      Port: 8081                                 │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│                      业务后端层 (Backend)                        │
│               Spring Boot 3.2.0 + MySQL                         │
│                      Port: 8080                                 │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│                     预测服务层 (ML Service)                      │
│               Python FastAPI + scikit-learn                     │
│                      Port: 8000                                 │
└─────────────────────────────────────────────────────────────────┘
```

## 核心功能

### 1. 成绩预测

- **单个预测**: 输入学生行为数据，实时预测学业表现
- **批量预测**: 支持多个学生数据的批量处理
- **模型投票**: 5种算法预测结果进行多数投票，提高准确率

## 数据来源

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

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

该数据集通过学习管理系统（LMS）追踪学生在课堂上的各种行为表现，用于预测学生的最终学业等级（H-优秀、M-中等、L-需改进）。经过数据增强处理后，训练集扩展至 1920 条记录（4倍）。

### 2. 机器学习模型

系统集成了以下5种经典分类算法：

| 模型     | 算法                | 特点                 |
| -------- | ------------------- | -------------------- |
| 决策树   | Decision Tree       | 可解释性强，训练快速 |
| 随机森林 | Random Forest       | 集成学习，准确率高   |
| 感知机   | Perceptron          | 线性分类器，简单高效 |
| 逻辑回归 | Logistic Regression | 概率预测，稳定可靠   |
| 神经网络 | MLP Classifier      | 复杂模式识别能力强   |

### 3. 特征工程

预测基于以下4个关键学生行为特征：

- **举手次数 (raisedhands)**: 课堂参与度
- **访问资源次数 (visited_resources)**: 学习主动性
- **讨论参与度 (discussions)**: 互动交流情况
- **缺勤天数 (absences)**: 出勤情况（Under-7 / Above-7）

### 4. 数据增强

- 支持4倍数据增强（480条 → 1920条）
- 采用噪声注入、SMOTE插值、类别平衡等策略
- 提高模型泛化能力，减少过拟合

### 5. 数据可视化

- 自动生成10+种数据分析图表
- 支持相关性热力图、多维度成绩分布图等
- 图表实时更新功能

### 6. 模型管理

- 模型训练与保存
- 模型准确率统计
- 支持多种数据源（CSV/API/数据库）

## 技术栈

### 前端

- **框架**: Vue 3.4 + TypeScript 5.5
- **构建工具**: Vite 5.4
- **UI组件库**: Element Plus 2.13
- **状态管理**: Pinia 3.0
- **路由**: Vue Router 4.6
- **HTTP客户端**: Axios 1.13

### 后端 (Java Service)

- **框架**: Spring Boot 3.2.0
- **JDK版本**: Java 21
- **ORM**: Spring Data JPA + Hibernate
- **数据库**: MySQL 8.0
- **模板引擎**: Thymeleaf
- **其他**: Lombok, Gson, Validation

### 预测服务 (Python Service)

- **框架**: FastAPI 0.128.0 + Uvicorn
- **机器学习**: scikit-learn
- **数据处理**: pandas, numpy
- **模型持久化**: joblib
- **数据库**: SQLAlchemy + PyMySQL
- **数据增强**: SMOTE, 自定义算法

## 快速开始

### 环境要求

- **Node.js**: >= 18.0.0
- **Python**: >= 3.9
- **JDK**: 21
- **Maven**: >= 3.6
- **MySQL**: >= 8.0

### 安装步骤

#### 1. 克隆项目

```bash
git clone https://gitee.com/ch1ller/score-prediction-system.git
cd score-prediction-system
```

#### 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;

# 导入数据
SOURCE f:/score-prediction-system/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. 修改配置文件

**Java服务配置** ([`java-service/src/main/resources/application.yml`](java-service/src/main/resources/application.yml)):

```yaml
spring:
  datasource:
    url: jdbc:mysql://localhost:3306/edu_system_v2
    username: root
    password: your_password # 修改为你的密码

python:
  service:
    url: http://localhost:8000
```

**Python数据库配置** ([`python-service/db_loader.py`](python-service/db_loader.py:11)):

```python
DatabaseLoader(
    host="localhost",
    user="root",
    password="123456",  # 修改为你的密码
    database="edu_system_v2"
)
```

#### 4. 安装Python依赖

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

#### 5. 安装前端依赖

```bash
cd score-prediction-frontend
npm install
```

#### 6. 一键启动（Windows）

```bash
START.bat
```

#### 7. 手动启动

**启动Python预测服务**:

```bash
cd python-service
python start.py
# 服务地址: http://localhost:8000
```

**启动Java后端服务**:

```bash
cd java-service
mvn spring-boot:run
# 服务地址: http://localhost:8080
```

**启动Vue前端**:

```bash
cd score-prediction-frontend
npm run dev
# 访问地址: http://localhost:8081
```

### 访问系统

启动完成后，浏览器访问: `http://localhost:8081`

## 项目结构

```
score-prediction-system/
├── python-service/              # Python预测服务
│   ├── main.py                  # FastAPI主程序
│   ├── start.py                 # 服务启动入口
│   ├── schemas.py               # 数据模型定义
│   ├── models/                  # 模型管理模块
│   │   └── model_manager.py     # 模型训练/预测核心逻辑
│   ├── models_saves/            # 已训练模型保存目录
│   ├── db_loader.py             # 数据库加载模块
│   ├── data_augmentation.py     # 数据增强脚本
│   ├── generate_charts.py       # 图表生成脚本
│   ├── Data.csv                 # 原始训练数据
│   ├── augmented_data.csv       # 增强后的训练数据
│   └── requirements.txt         # Python依赖
│
├── java-service/                # Java后端服务
│   ├── src/main/java/com/edu/
│   │   ├── controller/          # REST API控制器
│   │   │   └── PredictionController.java
│   │   ├── service/             # 业务逻辑层
│   │   │   ├── PredictionService.java
│   │   │   └── StudentPerformanceService.java
│   │   ├── entity/              # JPA实体类
│   │   │   └── StudentPerformance.java
│   │   ├── repository/          # 数据访问层
│   │   │   └── StudentPerformanceRepository.java
│   │   ├── dto/                 # 数据传输对象
│   │   ├── config/              # 配置类
│   │   └── EducationalManagementSystemApplication.java
│   ├── src/main/resources/
│   │   ├── application.yml      # 应用配置文件
│   │   └── templates/           # Thymeleaf模板
│   └── pom.xml                  # Maven依赖配置
│
├── score-prediction-frontend/   # Vue前端项目
│   ├── src/
│   │   ├── views/               # 页面视图
│   │   │   ├── HomePage.vue
│   │   │   ├── PredictionView.vue
│   │   │   ├── TrainingView.vue
│   │   │   └── AnalysisView.vue
│   │   ├── components/          # 组件
│   │   │   ├── SinglePredict.vue
│   │   │   ├── BatchPredict.vue
│   │   │   ├── ModelTrain.vue
│   │   │   ├── ChartsDisplay.vue
│   │   │   └── ServiceStatus.vue
│   │   ├── api/                 # API封装
│   │   ├── router/              # 路由配置
│   │   ├── stores/              # Pinia状态管理
│   │   ├── types/               # TypeScript类型定义
│   │   ├── App.vue              # 根组件
│   │   └── main.ts              # 应用入口
│   ├── index.html
│   ├── vite.config.ts
│   └── package.json
│
└── START.bat                    # Windows一键启动脚本
```

## API文档

### Python预测服务 API

基础URL: `http://localhost:8000`

| 方法 | 路径               | 描述             |
| ---- | ------------------ | ---------------- |
| GET  | `/root`            | 获取API概览      |
| GET  | `/health`          | 健康检查         |
| GET  | `/models`          | 获取可用模型列表 |
| POST | `/predict`         | 单个学生预测     |
| POST | `/predict_batch`   | 批量学生预测     |
| POST | `/train`           | 重新训练模型     |
| POST | `/generate-charts` | 生成数据图表     |

### Java后端服务 API

基础URL: `http://localhost:8080/admin/prediction`

| 方法 | 路径                   | 描述               |
| ---- | ---------------------- | ------------------ |
| GET  | `/api/health`          | 检查Python服务状态 |
| GET  | `/api/models`          | 获取模型列表       |
| POST | `/api/predict`         | 单个学生预测       |
| POST | `/api/predict-batch`   | 批量预测           |
| POST | `/api/train`           | 训练模型           |
| GET  | `/api/charts`          | 获取图表列表       |
| POST | `/api/charts/generate` | 重新生成图表       |

## 使用示例

### 单个预测请求

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

{
  "raisedhands": 15,
  "visitedResources": 20,
  "discussions": 10,
  "absences": "Under-7"
}
```

### 预测响应

```json
{
  "predictions": {
    "decision_tree": "H",
    "random_forest": "H",
    "perceptron": "M",
    "logistic_regression": "H",
    "neural_network": "H"
  },
  "recommendation": "H",
  "input_data": {
    "raisedhands": 15,
    "visitedResources": 20,
    "discussions": 10,
    "absences": "Under-7"
  }
}
```

## 数据增强说明

系统支持数据增强以提高模型性能：

- **原始数据**: 480条记录
- **增强后**: 1920条记录（4倍）
- **策略**: 噪声注入 + SMOTE插值 + 类别平衡

详见: [`python-service/DATA_AUGMENTATION_README.md`](python-service/DATA_AUGMENTATION_README.md)

## 开发指南

### 添加新的机器学习模型

编辑 [`python-service/models/model_manager.py`](python-service/models/model_manager.py:23):

```python
# 在 train_models 方法中添加新模型
self.models["new_model"] = NewClassifier()
self.models["new_model"].fit(feats_train, lbls_train)
```

### 扩展预测特征

修改以下文件：

1. [`python-service/models/model_manager.py`](python-service/models/model_manager.py:77) - `preprocess_data` 方法
2. [`python-service/schemas.py`](python-service/schemas.py:12) - `PredictionRequest` 模型
3. 前端表单组件

### 自定义数据源

在 [`python-service/main.py`](python-service/main.py:261) 中修改 `DEFAULT_CSV_PATH`，支持：

- 本地CSV文件路径
- API URL (http://...)
- 数据库 (`db://`)

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