一、项目简介

本项目是一个面向校园成绩治理与教学分析场景的数据分析平台，主要围绕学生考试成绩数据，完成从 Excel 导入、数据清洗、成绩分析、排名预警、教师分析、资源推荐、AI 助手到报表导出 的完整业务流程。

系统采用前后端分离架构，前端使用 Vue3 + Element Plus + ECharts 构建数据分析页面，后端使用 Spring Boot + MyBatis-Plus + MySQL + Redis 实现接口服务、数据存储和缓存优化。同时，系统还接入了本地 Ollama 大模型服务，用于实现 AI 问答和教学辅助分析。

本项目的核心目标不是单纯展示静态图表，而是构建一个能够完成真实数据导入、真实数据库写入、真实接口分析和真实报表导出的本地化校园成绩分析平台。

---

二、项目背景

在学校日常教学管理中，考试成绩数据通常以 Excel 表格的形式存在。传统处理方式往往存在以下问题：

1. 成绩数据分散，缺乏统一管理平台。

2. Excel 手动统计效率较低，容易出现统计错误。

3. 学生、班级、年级、学科等维度分析不够直观。

4. 成绩异常、排名波动、薄弱学科等问题难以及时发现。

5. 教师教学数据、资源推荐和教学改进建议缺乏系统化支持。

6. 报表导出依赖人工整理，重复工作较多。

因此，本系统希望通过信息化方式，将成绩数据从 Excel 中导入系统，再通过后端接口和可视化页面完成多维度分析，为教学管理和教学决策提供数据支持。

---

三、系统整体目标

本系统围绕“导入 - 分析 - 预警 - 导出”这一主线进行设计，主要实现以下目标：

• 支持 Excel 成绩文件上传、自动表头识别、数据预览和确认导入。

• 支持学生、班级、年级、学科等多个维度的成绩分析。

• 支持排名预警，辅助发现成绩波动较大的学生。

• 支持教师分析和教学资源检索。

• 支持接入本地 Ollama，实现 AI 助手问答。

• 支持 Excel 和 PDF 报表导出。

• 支持 Redis 缓存，提高部分分析接口响应速度。

• 支持本地部署，便于毕业设计演示和测试。

---

四、技术栈选型

1. 前端技术栈

技术	作用
Vue3	构建前端页面和组件
Vite	前端构建工具，提升开发启动速度
TypeScript	增强代码类型约束，提高可维护性
Element Plus	快速构建后台管理类界面
ECharts	实现柱状图、折线图、雷达图、环图等可视化图表
ECharts-GL	实现 3D 图表展示
Axios	封装前后端接口请求

前端整体采用后台管理系统风格，页面以浅色教育风为主，结合蓝紫色和薄荷绿色作为主色调，突出数据分析平台的清晰感和专业感。

---

2. 后端技术栈

技术	作用
Spring Boot	搭建后端 RESTful API 服务
MyBatis-Plus	简化数据库增删改查操作
JWT	实现登录认证和接口鉴权
Redis	缓存驾驶舱、学科分析、导入预览等数据
MySQL 8	存储用户、成绩、导入任务、教师、资源、报表等业务数据
Maven	后端项目构建和依赖管理
Ollama	本地 AI 模型服务
Swagger	接口文档和接口测试

后端采用分层架构设计，将 Controller、Service、Mapper、Util 等模块进行拆分，方便后续维护和扩展。

---

五、系统总体架构设计

系统整体采用前后端分离架构，主要分为以下几层：

表现层：Vue3 页面
接口层：Spring Boot Controller
业务层：Service + Util
数据层：MyBatis-Plus Mapper + MySQL
缓存层：Redis
AI 层：Ollama 本地模型服务

1. 表现层

表现层主要由 Vue3 前端页面组成，位于：

frontend/src/views

主要负责页面展示、用户交互、表单提交、图表渲染和接口调用。

---

2. 接口层

接口层由 Spring Boot Controller 组成，主要负责接收前端请求，并将请求分发给对应的业务服务。

主要接口模块包括：

/api/auth/*
/api/import/*
/api/analysis/*
/api/resource/*
/api/teacher/*
/api/data/overview
/api/export/*
/api/ai/*

系统统一返回结构如下：

{
"code": 200,
"message": "success",
"data": {}
}

这种统一返回格式可以减少前端判断成本，使接口调用更加规范。

---

3. 业务层

业务层主要由 Service 和 Util 组成，负责处理具体业务逻辑。

例如：

• Excel 导入解析

• 表头自动映射

• 成绩数据清洗

• 成绩分析统计

• 排名预警计算

• 教师分析

• 资源检索

• AI 问答上下文拼装

• 报表导出

---

4. 数据层

数据层使用 MyBatis-Plus Mapper 操作 MySQL 数据库，主要负责业务数据的持久化。

核心数据包括：

• 用户数据

• 成绩数据

• 考试批次

• 学校信息

• 导入任务

• 导入明细

• 教师信息

• 教学资源

• 报表记录

---

5. 缓存层

系统使用 Redis 缓存部分高频分析数据，例如：

• 数据驾驶舱分析结果

• 学科分析结果

• 导入预览数据

在 Excel 数据确认导入完成后，系统会清理相关分析缓存，保证分析页面能够刷新到最新数据。

---

6. AI 层

AI 层通过本地 Ollama 服务实现，主要包括：

• 获取模型列表

• 检查 AI 服务健康状态

• 调用本地大模型进行问答

• 结合教学资源检索实现辅助分析

AI 相关接口包括：

/api/ai/chat
/api/ai/models
/api/ai/health

---

六、系统核心业务流程

1. Excel 导入流程

Excel 导入是本系统最核心的功能之一。系统不是简单地上传文件，而是实现了从上传、解析、预览、确认到写库的完整闭环。

整体流程如下：

前端选择 Excel 文件
↓
调用 /api/import/upload 上传文件
↓
后端创建 import_task 导入任务
↓
解析 Excel 首个 Sheet
↓
自动识别表头映射
↓
返回预览数据、错误行、缺失字段
↓
用户确认导入
↓
调用 /api/import/confirm
↓
写入 student_score 成绩表
↓
记录 import_task_detail 行级明细
↓
生成错误报告
↓
清理 Redis 分析缓存

对应代码链路为：

ImportView.vue
-> /api/import/upload
-> ImportServiceImpl.parseTask
-> import_task / import_task_detail

确认导入链路为：

ImportView.vue
-> /api/import/confirm
-> ImportServiceImpl.confirmImport
-> student_score

---

2. Excel 数据清洗与校验

在导入成绩数据时，系统对 Excel 中的数据进行了清洗和校验。

主要清洗规则包括：

类型	说明
去空白	去除单元格前后多余空格
年级标准化	将七年级、八年级、九年级等格式统一
班别提取	从班级字段中提取数字
分数字段解析	将各学科成绩转换为可计算数字

主要必填字段包括：

学校
年级
班别
考生号
姓名

分数校验规则包括：

学科	分数范围
语文	0 - 150
数学	0 - 150
英语	0 - 150
道法	0 - 100
历史	0 - 100
地理	0 - 100
生物	0 - 100

系统还会对部分异常情况给出警告，例如：

• 成绩为空

• 英语总分与听说、笔试分数差异较大

• 缺少字段映射

• 重复数据

---

3. 重复数据处理策略

为了避免同一学生同一批次的成绩被重复导入，系统设置了唯一约束。

成绩去重键为：

exam_batch_id + school_id + grade_name + class_no + student_no

重复数据处理策略包括：

策略	说明
OVERWRITE	重复记录覆盖
UPDATE	重复记录更新
SKIP	重复记录跳过

这样可以适应不同的数据导入场景，例如首次导入、修正导入和补充导入。

---

七、成绩分析模块设计

成绩分析模块主要围绕学生、班级、年级、学科和排名预警展开。

1. 数据驾驶舱

数据驾驶舱用于展示系统整体数据概况，包括：

• 总体成绩情况

• 班级平均分对比

• 学科表现

• 缓存命中状态

• 数据统计概览

前端页面：

DashboardView.vue

后端接口：

/api/analysis/dashboard

该接口使用 Redis 缓存，提高首页统计数据加载速度。

---

2. 学生分析

学生分析主要关注单个学生的成绩表现，包括：

• 各学科成绩

• 学科雷达图

• 成绩趋势

• 学科优势与薄弱项

前端页面：

StudentView.vue

---

3. 班级分析

班级分析主要从班级整体表现出发，展示：

• 班级学科均分

• 成绩分布

• 班级 Top10

• 班级整体水平对比

前端页面：

ClassView.vue

---

4. 年级分析

年级分析主要用于横向比较不同班级的整体表现，包括：

• 年级班级对比

• 学科平均分

• 年级排名

• 各班级成绩差异

前端页面：

GradeView.vue

---

5. 学科分析

学科分析用于观察不同学科的整体表现，支持：

• 学科平均分分析

• 英语听说和笔试联动分析

• 学科雷达图

• 学科及格率

• 3D 学科图表展示

前端页面：

SubjectView.vue

该模块部分数据也使用 Redis 缓存。

---

6. 排名预警

排名预警模块用于发现排名变化较大的学生，帮助教师和管理者及时关注学生学习状态。

前端页面：

RankingWarningView.vue

后端接口：

/api/analysis/ranking-warning

该模块可以辅助发现以下情况：

• 成绩明显下滑

• 排名波动较大

• 需要重点关注的学生

• 潜在进步学生

---

八、教师分析与资源推荐模块

除了学生成绩分析，本系统还设计了教师分析和资源检索模块。

1. 教师分析

教师分析模块主要用于展示教师相关数据，包括：

• 教师排名

• 教师综合评分

• 教学建议

• 教师指标雷达图

前端页面：

TeacherView.vue

后端接口：

/api/teacher/*

---

2. 教学资源检索

资源模块支持本地资源检索和推荐，主要包括：

• 资源搜索

• 资源推荐组合

• 资源管理

• 资源增删改查

相关接口：

/api/resource/*

需要注意的是，资源检索模块主要由 ResourceService 负责，本身不直接调用大模型。

---

九、AI 助手模块设计

系统接入了本地 Ollama，用于实现 AI 助手功能。

AI 助手主要有两种工作模式：

1. 资源检索模式

资源检索模式用于从系统本地资源库中查找相关教学资源。

调用链路如下：

ChatView.vue
-> /api/resource/chat-search
-> ResourceService.chatSearch

该模式主要依赖数据库中的教学资源数据，不直接调用大模型。

---

2. Ollama 问答模式

Ollama 问答模式用于调用本地大模型完成问答。

调用链路如下：

ChatView.vue
-> /api/ai/chat
-> AiServiceImpl
-> OllamaClient
-> Ollama

其中：

模块	作用
AiServiceImpl	负责模型选择、上下文拼装、错误处理
OllamaClient	负责调用 Ollama HTTP API
Ollama	本地大模型服务

Ollama 相关配置示例：

ai:
provider: ollama
ollama:
base-url: http://127.0.0.1:11434
model: qwen2.5:7b
timeout: 60000
stream: false

启动 Ollama 示例：

ollama serve
ollama pull qwen2.5:7b

也可以根据电脑性能替换为：

llama3
deepseek-r1
mistral

---

十、报表导出模块

系统支持将分析结果导出为 Excel 或 PDF 报表，方便保存和提交。

主要导出能力包括：

• Excel 统计报表导出

• 学生 PDF 报表导出

• 班级 PDF 报表导出

• 年级 PDF 报表导出

• 导出历史记录保存

后端接口：

/api/export/*

导出记录表：

report_record

导出文件目录：

exports/reports/

错误报告目录：

exports/error-reports/

---

十一、数据库设计

数据库使用 MySQL 8，核心业务表如下：

表名	说明
sys_user	用户认证表
import_task	导入任务主表
import_task_detail	导入任务行级明细表
student_score	学生成绩表
exam_batch	考试批次表
school	学校信息表
edu_resource	教学资源表
edu_resource_combo	教学资源组合表
teacher_profile	教师信息表
teacher_metric	教师指标表
report_record	报表导出记录表

核心关系包括：

student_score.exam_batch_id -> exam_batch.id
student_score.school_id -> school.id
import_task.exam_batch_id -> exam_batch.id
import_task_detail.task_id -> import_task.id
teacher_metric.teacher_id -> teacher_profile.id

关键唯一约束包括：

student_score:
(exam_batch_id, school_id, grade_name, class_no, student_no)

school:
school_name 唯一

sys_user:
username 唯一

其中，student_score 是整个系统最核心的数据表，大部分分析接口最终都围绕该表进行统计计算。

---

十二、可视化设计

系统前端使用 ECharts 和 ECharts-GL 实现数据可视化展示。

1. 视觉风格

系统整体采用浅色教育风，主色系为：

蓝紫色 + 薄荷绿色

这种配色相比传统深色大屏更加简洁，也更适合教学分析类系统的日常使用场景。

---

2. 图表类型

系统中使用的图表类型包括：

图表类型	使用场景
柱状图	班级对比、学科均分
折线图	成绩趋势分析
面积图	趋势数据展示
环图	占比类数据
雷达图	学生能力、教师能力分析
3D 图表	班级均分、学科均分展示

---

3. 图表组件封装

系统使用统一的 ChartCard.vue 组件封装图表区域，主要封装内容包括：

• 图表标题

• 加载状态

• 刷新操作

• 图表容器

• 响应式尺寸适配

这样可以减少不同页面中的重复代码，也让图表区域的风格更加统一。

---

4. 页面与图表映射

页面	图表内容
DashboardView.vue	总览数据 + 3D 班级对比
StudentView.vue	雷达图 + 学科柱状图 + 趋势图
ClassView.vue	学科均分 + 成绩分布 + Top10
GradeView.vue	班级对比 + 学科均分 + 排名
SubjectView.vue	3D 学科图 + 英语联动 + 雷达图 + 及格率
TeacherView.vue	雷达图 + 综合评分条形图

---

十三、系统功能模块总结

目前系统中已经完成前后端联动的模块包括：

模块	前端页面	后端接口
登录 / 注册	LoginView / RegisterView	/api/auth/*
数据驾驶舱	DashboardView	/api/analysis/dashboard
Excel 导入	ImportView	/api/import/*
学生分析	StudentView	/api/analysis/*
班级分析	ClassView	/api/analysis/*
年级分析	GradeView	/api/analysis/*
学科分析	SubjectView	/api/analysis/*
排名预警	RankingWarningView	/api/analysis/ranking-warning
教师分析	TeacherView	/api/teacher/*
资源检索与推荐	ResourceView	/api/resource/*
智能助手	ChatView	/api/resource/chat-search、/api/ai/*
数据管理	DataManageView	/api/data/overview
报表导出	ReportView	/api/export/*

---

十四、当前版本真实状态说明

为了保证项目说明真实可靠，这里也对当前版本的实际状态进行说明。

1. 已完整落地的功能

目前已经完成真实前后端联动的模块包括：

• 登录 / 注册

• Excel 导入闭环

• 数据驾驶舱

• 学生分析

• 班级分析

• 年级分析

• 学科分析

• 排名预警

• 教师分析

• 资源检索与推荐

• AI 助手

• 数据管理

• 报表导出

---

2. 当前为演示或预留的功能

部分模块目前仍为预留或演示状态：

模块	当前状态
决策支持页	静态演示占位
系统管理页	静态演示占位
Spark 实时任务	接口保留，后端返回演示结果

需要特别说明的是，虽然系统中保留了 Spark 相关接口，但当前实际运行模式主要是基于 MySQL 的 SQL 实时分析，并没有在运行时真正启动 Spark 作业。

---

十五、本地部署说明

1. 环境准备

本地运行项目前，需要准备以下环境：

JDK 17
Maven 3.9+
Node.js 20 LTS
MySQL 8
Redis 7
Ollama

---

2. 初始化数据库

数据库名为：

edu_bigdata

按照顺序执行以下 SQL 文件：

sql/init.sql
sql/mock_data.sql
sql/upgrade.sql
sql/fix_db.sql

其中：

文件	作用
init.sql	初始化基础表结构
mock_data.sql	初始化演示数据
upgrade.sql	扩展表结构
fix_db.sql	旧库修复补丁

---

3. 启动基础服务

确保 MySQL 和 Redis 正常运行：

MySQL：127.0.0.1:3306
Redis：127.0.0.1:6379

---

4. 启动后端

进入后端目录：

cd backend
mvn spring-boot:run

启动成功后访问 Swagger：

http://localhost:8080/swagger-ui/index.html

---

5. 启动前端

进入前端目录：

cd frontend
npm install
npm run dev

前端访问地址：

http://localhost:5173

---

6. 启动 Ollama

ollama serve
ollama pull qwen2.5:7b

---

7. 前端环境配置

前端 .env.development 配置示例：

VITE_API_BASE=/api
VITE_API_ORIGIN=http://localhost:8080

---

8. 默认账号

admin / 123456

---

9. 导入模板与文件目录

模板文件：
templates/2025学年第一学期七年级期末成绩统计表（新）.xlsx

上传目录：
uploads/excel/

错误报告：
exports/error-reports/

报表导出：
exports/reports/

---

十六、测试与验收

系统测试主要围绕导入、分析、资源、教师、报表和 AI 助手几个方面进行。

1. 导入链路测试

测试内容包括：

• 上传合法 Excel 文件

• 返回预览数据和自动映射结果

• 自动确认后写入 student_score

• 错误行生成错误报告

• 导入历史显示任务状态和统计信息

---

2. 分析模块测试

测试内容包括：

• 数据驾驶舱接口返回真实数据

• 学生分析接口返回真实数据

• 班级分析接口返回真实数据

• 年级分析接口返回真实数据

• 学科分析接口返回真实数据

• 排名预警接口返回真实数据

• Excel 导入完成后，分析页数据可以刷新为最新结果

• Redis 缓存命中状态可以正常显示

---

3. 教师与资源模块测试

测试内容包括：

• 资源检索可用

• 资源推荐组合可用

• 资源管理增删改查可用

• 教师排名可用

• 教师建议可用

---

4. 报表导出测试

测试内容包括：

• Excel 统计报表可以导出并打开

• 学生 PDF 可以导出并打开

• 班级 PDF 可以导出并打开

• 年级 PDF 可以导出并打开

• report_record 中可以看到导出历史

---

5. AI 助手测试

测试内容包括：

GET /api/ai/health
GET /api/ai/models
POST /api/ai/chat

主要检查：

• Ollama 是否连通

• 模型列表是否能正常返回

• 模型是否能正常回答

• 模型不存在时是否有错误提示

• Ollama 未启动时是否有错误提示

• 请求超时时前后端是否有明确反馈

---

十七、常见问题与解决方案

1. MySQL 连接失败

可能原因：

• MySQL 没有启动

• 数据库名不正确

• application-dev.yml 中数据源配置错误

• 用户名或密码错误

解决方式：

检查 MySQL 服务是否启动
检查数据库 edu_bigdata 是否存在
检查 application-dev.yml 数据源配置

---

2. Redis 连接失败

可能原因：

• Redis 没有启动

• Redis 端口不是 6379

• 后端配置中的 Redis 地址错误

解决方式：

确认 Redis 已启动
确认 127.0.0.1:6379 可连接
检查后端 Redis 配置

---

3. 端口冲突

如果前端或后端启动失败，可能是端口被占用。

解决方式：

后端可修改 server.port
前端可修改 vite.config.ts 中的端口

---

4. 登录失败

可能原因：

• sys_user 表中没有 admin 用户

• 密码不是 123456

• 初始化 SQL 没有正确执行

解决方式：

检查 sys_user 表
确认 admin / 123456 是否存在
重新执行初始化数据脚本

---

5. 401 / 403 鉴权问题

可能原因：

• token 过期

• localStorage 中缓存了错误用户信息

• 请求未携带 token

解决方式：

清理浏览器 localStorage
重新登录系统
检查请求头是否携带 token

---

6. Excel 上传失败

可能原因：

• 文件格式不是 .xls 或 .xlsx

• 文件超过 50MB

• Excel 表头缺失

• 字段映射不完整

解决方式：

检查文件格式
检查文件大小
检查导入页字段映射
查看 import_task.summary_msg
查看错误报告文件

---

7. Ollama 无法连接

可能原因：

• Ollama 服务未启动

• ai.ollama.base-url 配置错误

• 本地模型未下载

解决方式：

ollama serve
ollama pull qwen2.5:7b

并检查配置：

ai:
ollama:
base-url: http://127.0.0.1:11434

---

8. AI 请求超时

可能原因：

• 本地电脑性能不足

• 模型参数较大

• 超时时间设置过短

解决方式：

提高 ai.ollama.timeout
更换更轻量的模型
关闭其他占用资源的程序

---

十八、项目实现亮点

通过本项目，我认为比较有价值的实现点主要有以下几个。

1. Excel 导入闭环完整

系统实现了从上传、解析、预览、确认、写库、错误报告到导入历史追踪的完整流程，而不是简单地读取 Excel 文件。

---

2. 数据清洗和校验规则明确

导入过程中对年级、班级、分数、必填字段和重复数据进行了处理，使系统对真实 Excel 数据具有更好的兼容性。

---

3. 多维度成绩分析

系统支持学生、班级、年级、学科、排名预警等多个维度分析，能够从不同角度观察教学数据。

---

4. Redis 缓存提升性能

对于驾驶舱和学科分析等高频访问数据，系统使用 Redis 进行缓存，减少重复查询数据库的压力。

---

5. 可视化效果直观

前端使用 ECharts 和 ECharts-GL 实现了柱状图、折线图、雷达图、环图和 3D 图表，使分析结果更加直观。

---

6. 本地 AI 助手接入

系统接入本地 Ollama 模型，实现 AI 问答能力。相比在线大模型接口，本地部署更适合毕业设计演示，也更加独立可控。

---

7. 报表导出能力完整

系统支持 Excel 和 PDF 报表导出，能够满足成绩统计结果保存、归档和提交的需求。