# 4-学生成绩管理系统 - 功能说明

# 项目概述

学生成绩管理系统是一个面向高校教务场景的成绩管理平台，围绕「教学安排 → 选课 → 成绩录入 → 成绩查询」这条主线，提供管理员（基础数据与全量成绩维护）、教师（我的课程、成绩录入）、学生（课程查询、选课退课、我的成绩）三种角色的业务闭环，并附带公告发布、个人中心与后台数据可视化看板。系统采用前后端分离架构：后端基于 Django 3.2 + Django REST Framework 3.14 以「一个功能模块一个 App」的方式组织接口，前端基于 Vue 3.4.29 + Vite 5.3.1 + Element Plus 2.8.4 构建单页应用，通过自定义 JWT Token（请求头 token）完成无状态认证，数据存储使用 MySQL（库名 d_4_grade_system，字符集 utf8mb4）。

# 项目概览

# ✨ 创新点

# 1. 模块化独立 App 架构

一模块一 App：apps/ 下按业务拆分为 admin、teacher、student、department、major、classes、course、teaching、course_selection、grade、notice 共 11 个功能模块，每个模块内含 models.py、XxxSerializer.py、views.py、urls.py 完整四件套。
公共能力独立沉淀：登录、注册、找回密码、当前用户、修改密码、重置密码、文件上传统一收敛到 apps/common/，各业务模块只关注自身 CRUD。
全量接口集中挂载：project/urls.py 以 path("<module>/", include(...)) 的方式统一注册 11 个模块、common/ 公共模块与 file/upload 上传接口。

# 2. 自定义 JWT 认证与中间件统一鉴权

自主签发 Token：utils/jwt_auth.py 使用 PyJWT 以 HS256 算法、项目 SECRET_KEY 作为密钥签发 Token，载荷固定写入 id、username、type 三个字段，有效期默认 60×24×30 分钟（30 天）。
中间件全局拦截：middleware/TokenInterceptorMiddleware.py 对除白名单外的所有请求强制校验请求头 token，校验通过后把 request.token、request.id、request.username、request.type 注入请求上下文；校验失败统一返回 code=401。
白名单放行机制：登录 /common/login、注册 /common/register、找回密码 /common/retrievePassword 精确放行，/uploads/、/static/、/swagger/、/django-admin/ 前缀放行。

# 3. 三角色分表设计与角色路由

角色独立建表：管理员（admin）、教师（teacher）、学生（student）分别独立建模，登录时由前端选择角色，后端 LoginAPIView 按 type 路由到不同表查询、并用对应序列化器返回。
角色贯穿前后端：JWT 中的 type 字段既用于后端数据过滤，也用于前端菜单渲染与登录后跳转（ADMIN → /admin，TEACHER / STUDENT → /）。
按角色隔离数据：成绩、教学安排、选课记录的查询接口按 type 过滤数据集（教师只看自己授课的、学生只看自己的）。

# 4. 冗余快照式成绩数据设计

名称字段随记录一同落库：grade、course_selection、teaching 表在保存 student_id、course_id、teacher_id 的同时冗余保存 student_name、course_name、teacher_name，列表页无需连表即可直接展示中文名称。
无物理外键：全库仅通过 xx_id 做逻辑关联，表间无物理主外键约束，便于单独维护与导入导出。
统一时间戳信号：所有模型通过 pre_save 信号 pre_save_timestamp_handler 在新增时自动写入 create_time，无需业务代码手工赋值。

# 5. 配套 Java 代码生成器与数据可视化看板

一键生成 CRUD：项目内置 CodeGenerator/（Java + Velocity 模板），可从数据库表批量生成 Django 后端代码与 Vue3 管理页面，并自动注册到 settings.py、project/urls.py、前端路由与后台菜单。
四图联动看板：后台首页 /admin/home 使用 ECharts 渲染柱状图、饼图、折线图、雷达图，数据源为四个分页接口返回的 total。

# ✨ 项目亮点

# 一、业务功能亮点

三角色业务闭环：管理员维护院系、专业、班级、课程、教学安排、选课记录与学生/教师账号，教师录入成绩，学生查询课程与个人成绩，三种角色各司其职。
选课到成绩的全链路贯通：教学安排（teaching）作为选课与成绩录入的共同入口，选课记录带 teaching_id，教师按教学安排调出选课学生名单直接录入成绩。
多维度成绩检索：后台成绩管理支持按学生姓名、课程名称模糊检索；选课记录管理支持按学生姓名、课程名称检索；教学安排管理支持按教师姓名、课程名称检索。
公告与个人中心：管理员发布公告，前台以时间线形式展示；所有角色都可查看个人信息、修改个人信息与登录密码。
数据看板统计：后台首页汇总学生总数、教师总数、课程总数、成绩记录数四项指标并以图表呈现。

# 二、技术实现亮点

现代化前端技术栈：采用 Vue 3.4.29 + Vite 5.3.1 + Element Plus 2.8.4 + Vue Router 4.4.3 + Pinia 2.2.2 + Axios 1.7.5 + ECharts 5.5.1。
稳定可靠的后端架构：基于 Django 3.2 + Django REST Framework 3.14.0，配合 PyJWT 2.7.0 自定义认证、drf-yasg 1.21.7 生成 Swagger 接口文档、django-cors-headers 4.2.0 处理跨域、PyMySQL 1.1.0 / mysqlclient 2.1.1 连接 MySQL。
完善的数据库设计：11 张核心表，全部使用 bigint 自增主键，表间以 xx_id 逻辑关联、不建物理外键，create_time 由信号统一自动写入，列表分页统一读取 settings.PAGE_SIZE（默认 10 条/页）。
丰富的第三方集成：ECharts（图表）、WangEditor 5.1.14 与 @kangc/v-md-editor 2.3.18（编辑器依赖）、highlight.js 11.8.0（代码高亮）、dayjs、lodash、crypto-js、sm-crypto、swiper、@element-plus/icons-vue 图标库。
安全性设计：令牌以 HS256 签名并带过期时间；所有非白名单接口经中间件统一鉴权；修改个人信息与修改密码接口校验操作者必须是本人（user_id != request.id 直接拒绝）；重置密码接口校验当前用户必须为 ADMIN；角色数据在查询层隔离。按项目约定，密码在表中以明文存储并直接比对（data['password'] 与数据库值相等即通过），仅适用于教学/毕业设计场景。

# 三、用户体验亮点

双界面设计：后台管理界面（AdminLayout.vue）采用左侧深色菜单 + 顶部用户下拉，承载 12 个管理入口；前台用户界面（FrontLayout.vue）采用顶部横向菜单，按角色用 v-if 动态渲染菜单项。
响应式布局：基于 Element Plus 栅格系统（el-row / el-col 配合 :xs / :sm / :md）自适应屏幕；前台布局含 @media (max-width: 768px) 断点，窄屏下隐藏用户名与菜单文字；管理页表格列使用 min-width 而非固定 width，长文本列开启 show-overflow-tooltip，操作栏预留 min-width="200" 保证按钮同行显示。
交互优化：
- 友好的加载提示和错误提示：src/utils/http.js 响应拦截器按 code 统一处理 200 / 401 / 409 / 500，并用 ElMessage 弹出对应文案；401 时自动清理本地令牌并跳转登录页。
- 重要操作的确认弹窗：删除与批量删除前使用 ElMessageBox.confirm 二次确认，取消则提示"已取消删除"。
- 及时的全局消息提示：新增、编辑、删除、选课、退课、登录、注册、改密成功后均有 ElMessage 成功提示。
- 严谨的前后端表单验证：前端 el-form 的 :rules 做必填与触发校验，后端 DRF 序列化器二次校验，失败返回统一失败响应。
文件上传体验：封装 components/MyUpload.vue 组件，支持图片卡片/图片/视频/音频/附件多种类型切换；头像场景限制 1 张，超出时自动替换旧文件；上传请求头自动携带 token；支持点击预览（图片/视频/音频弹窗预览，附件直接下载）。

# 管理员

# 系统管理

管理员管理：管理管理员账号，支持新增、编辑、删除、批量删除，可按用户名、联系方式检索，并可一键重置密码。

教师管理：管理教师账号，支持新增、编辑、删除、批量删除，可按职称检索，支持上传教师头像。

学生管理：管理学生账号，支持新增、编辑、删除、批量删除，可维护学号、班级、专业、所属院系、入学年份、头像等信息。

# 教学资源管理

院系管理：维护院系名称与院系简介，支持新增、编辑、删除、批量删除。

专业管理：维护专业名称、所属院系（含 department_id 与院系名称）、专业简介，支持新增、编辑、删除、批量删除。

班级管理：维护班级名称、所属专业、所属院系、年级、学生人数，支持新增、编辑、删除、批量删除。

课程管理：维护课程编号、课程名称、学分、课程类型、开课院系、课程描述，支持新增、编辑、删除、批量删除。

教学安排管理：按「教师 + 课程」安排学期、学年、上课时间与教室，支持新增、编辑、删除、批量删除，可按教师姓名、课程名称检索。

选课记录管理：查看与管理全部选课记录（学生、学号、教学安排、课程、教师、学期、学年），支持新增、编辑、删除、批量删除，可按学生姓名、课程名称检索。

# 成绩与公告管理

成绩管理：维护全部成绩记录（学生、学号、课程、教师、成绩、学期、学年、备注），支持新增、编辑、删除、批量删除，可按学生姓名、课程名称检索。

公告管理：发布与维护系统公告（标题、内容），支持新增、编辑、删除、批量删除，可按标题检索。

# 个人设置

个人信息：修改本人邮箱、联系方式与头像。

修改密码：校验原密码后修改本人登录密码，修改成功后需重新登录。

# 教师

# 教学

我的课程：查看本人的教学安排列表（课程名称、学年、学期、上课时间、教室）。

成绩录入：先选择自己的教学安排，系统自动调出该教学安排下的选课学生名单，逐行录入 0~100 的成绩与备注并保存。

# 公共

公告通知：以时间线形式浏览全部系统公告。

个人中心 / 个人信息：查看本人用户名、昵称、邮箱、联系方式与角色，可跳转编辑个人信息与修改密码。

修改密码：校验原密码后修改本人登录密码，修改成功后需重新登录。

# 学生

# 选课与成绩

课程查询：浏览课程教学安排（课程、授课教师、学年、学期、上课时间、教室），页面提供课程名称筛选输入框，点击"选课"即按当前教学安排生成选课记录。

我的选课：查看本人已选课程（课程、授课教师、学年、学期、上课时间、教室），可对单条选课记录执行"退课"（带二次确认）。

我的成绩：查看本人的成绩记录（课程、授课教师、成绩、学年、学期、备注），成绩按分数段以不同颜色的标签展示。

# 公共

公告通知：以时间线形式浏览全部系统公告。

个人中心 / 个人信息：查看本人用户名、昵称、邮箱、联系方式与角色，可跳转编辑个人信息与修改密码。

修改密码：校验原密码后修改本人登录密码，修改成功后需重新登录。

# 功能权限对照表

功能模块	管理员	教师	学生
后台首页（数据看板）	✓	-	-
前台首页	-	✓	✓
管理员管理	✓	-	-
教师管理	✓	-	-
学生管理	✓	-	-
院系管理	✓	-	-
专业管理	✓	-	-
班级管理	✓	-	-
课程管理	✓	-	-
教学安排管理	✓	-	-
选课记录管理	✓	-	-
成绩管理	✓	-	-
公告管理（发布维护）	✓	-	-
我的课程（教学安排）	-	✓（仅自己的）	-
成绩录入	-	✓	-
课程查询	-	-	✓
我的选课 / 退课	-	-	✓（仅自己的）
我的成绩	-	-	✓（仅自己的）
公告通知（浏览）	-	✓	✓
个人信息管理	✓	✓	✓
修改密码	✓	✓	✓
重置密码	✓	-	-

# 成绩等级说明

# 成绩取值与展示

成绩取值范围：成绩录入使用数字输入框并限制最小值 0、最大值 100、保留 2 位小数；数据库中 grade.score 为 decimal(5,2)。
成绩标签配色规则（front/student/MyGrades.vue）：
- 成绩 ≥ 90：绿色标签（success）。
- 80 ≤ 成绩 < 90：默认色标签。
- 60 ≤ 成绩 < 80：橙色警示标签（warning）。
- 成绩 < 60：红色危险标签（danger）。

# 备注（等级）取值

优秀：初始化数据中 90 分及以上的成绩备注为"优秀"（如 92.00、90.00、95.00）。
良好：初始化数据中 80~89 分的成绩备注为"良好"（如 88.50、85.50、82.00）。
及格：初始化数据中 76.00 分的成绩备注为"及格"。
说明：grade.remark 为普通文本字段（varchar(255)，中文备注），由录入人手工填写；代码中未定义成绩等级的枚举常量或自动换算规则。

# 学期与学年取值

学期：初始化数据取值为"第一学期""第二学期"。
学年：初始化数据取值为"2024-2025"。

# 默认账号

# 管理员

用户名: admin
密码: 123456
类型: ADMIN（角色：系统管理员）

1
2
3

# 教师

用户名: teacher1
密码: 123456
类型: TEACHER（张教授，教授，计算机学院）

用户名: teacher2
密码: 123456
类型: TEACHER（李副教授，副教授，计算机学院）

用户名: teacher3
密码: 123456
类型: TEACHER（王讲师，讲师，数学学院）

1
2
3
4
5
6
7
8
9
10
11

# 学生

用户名: student1
密码: 123456
类型: STUDENT（张三，学号 2021001，计科2021-1班）

用户名: student2
密码: 123456
类型: STUDENT（李四，学号 2021002，计科2021-1班）

用户名: student3
密码: 123456
类型: STUDENT（王五，学号 2021003，软工2021-1班）

用户名: student4
密码: 123456
类型: STUDENT（赵六，学号 2021004，软工2021-1班）

用户名: student5
密码: 123456
类型: STUDENT（孙七，学号 2021005，数学2021-1班）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

以上账号来自 project/sql/sql.sql、project/sql/d_4_grade_system.sql 的初始化 INSERT 语句，密码在表中以明文存储。

# 核心业务流程

# 登录认证流程

1. 用户在登录页选择用户类型（管理员 / 教师 / 学生），输入用户名与密码
2. 前端 POST /common/login 提交 username、password、type
3. 后端校验 type 必须为 ADMIN / TEACHER / STUDENT，按类型到 admin、teacher 或 student 表查询用户
4. 比对密码与数据库中存储的密码，不一致返回"用户名或者是密码错误"
5. 校验通过后签发 JWT（载荷含 id、username、type，有效期 30 天）
6. 前端把 token 与用户信息写入 localStorage，后续请求由 Axios 拦截器自动在请求头 token 中携带
7. 按角色跳转：ADMIN 进入 /admin 后台，TEACHER / STUDENT 进入前台首页

1
2
3
4
5
6
7

# 学生选课流程

1. 学生进入"课程查询"，前端 GET /teaching/page 拉取教学安排列表并分页展示（页面提供课程名称筛选输入框）
2. 点击"选课"，前端 POST /course_selection/add，提交 studentId、studentName、studentNo、teachingId、
   courseId、courseName、teacherId、teacherName、semester、academicYear
3. 后端写入 course_selection 表（记录由选课动作快照生成，含课程与教师名称）
4. 学生进入"我的选课"，前端 GET /course_selection/page 查询（后端对 STUDENT 角色过滤 student_id）
5. 需要退课时点击"退课"，经 ElMessageBox 二次确认后 DELETE /course_selection/delete，提交待删 id 数组
6. 后端逐条删除选课记录并返回操作成功

1
2
3
4
5
6
7

# 教师成绩录入流程

1. 教师进入"成绩录入"，前端 GET /teaching/list 获取本人教学安排并渲染课程下拉框
2. 选择某条教学安排后，前端 GET /course_selection/list 取该教学安排下的选课学生名单
3. 教师在表格中逐行填写成绩（0~100，2 位小数）与备注
4. 点击"保存"，前端 POST /grade/add 提交 studentId、studentName、studentNo、courseId、courseName、
   teacherId、teacherName、score、semester、academicYear、remark
5. 后端写入 grade 表（create_time 由 pre_save 信号自动填充），返回成功后清空该行录入值

1
2
3
4
5
6

# 成绩查询与统计流程

1. 管理员在"成绩管理"页 GET /grade/page 分页查询全量成绩，可按学生姓名、课程名称模糊检索
2. 教师查询成绩时后端按 type=TEACHER 过滤 teacher_id，学生查询时按 type=STUDENT 过滤 student_id
3. 学生在"我的成绩"页 GET /grade/page，按分数段以不同颜色标签展示成绩
4. 管理员进入后台首页，前端并发请求 /student/page、/teacher/page、/course/page、/grade/page 获取 total
5. 汇总为学生总数、教师总数、课程总数、成绩记录数四项指标，并渲染柱状图、饼图、折线图、雷达图

1
2
3
4
5

# 技术说明

# 系统架构

前端：Vue 3.4.29 + Element Plus 2.8.4 + Vite 5.3.1
后端：Django 3.2 + Django REST Framework 3.14.0
数据库：MySQL（库名 d_4_grade_system，字符集 utf8mb4 / utf8mb4_unicode_ci，端口 3306）
认证：自定义 JWT Token（PyJWT 2.7.0，HS256；请求头 token，有效期 30 天）

# 访问地址

后端API：http://127.0.0.1:8000（前端 .env.development 的 VITE_APP_API_URL 指向该地址）
前端页面：http://localhost:5173（开发环境）
接口文档：http://127.0.0.1:8000/swagger/
Django 自带后台：http://127.0.0.1:8000/django-admin/

# 数据库

数据库名：d_4_grade_system
字符集：utf8mb4（排序规则 utf8mb4_unicode_ci）
总表数：11 张表（admin、teacher、student、department、major、classes、course、teaching、course_selection、grade、notice）

模型类	数据表（db_table）	说明
Admin	admin	管理员账号
Teacher	teacher	教师账号（含职称、所属院系）
Student	student	学生账号（含学号、班级、专业、院系、入学年份）
Department	department	院系
Major	major	专业（逻辑关联 department_id）
Classes	classes	班级（逻辑关联专业、院系）
Course	course	课程（编号、学分、类型、开课院系）
Teaching	teaching	教学安排（逻辑关联 teacher_id、course_id）
CourseSelection	course_selection	选课记录（逻辑关联 student_id、teaching_id、course_id、teacher_id）
Grade	grade	成绩（逻辑关联 student_id、course_id、teacher_id）
Notice	notice	公告

说明：apps/user/、apps/pet/ 目录中保留了脚手架模板遗留的模型定义（user、pet），二者未注册到 settings.py 的 INSTALLED_APPS，sql/ 建表脚本中也没有对应建表语句，前端 User.vue、Pet.vue、PetCategory.vue 同样未挂载到路由，均不属于本系统实际启用的数据表与功能。

# API接口规范

RESTful风格：
GET    /module/page          # 分页查询（每页条数取 settings.PAGE_SIZE，默认 10）
GET    /module/list          # 获取全部列表（不分页）
GET    /module/detail        # 查询详情
POST   /module/add           # 新增
PUT    /module/update        # 更新
DELETE /module/delete        # 删除
DELETE /module/delBatch      # 批量删除（请求体为 id 数组）

响应格式：
{
    "code": 200,
    "data": {...},
    "msg": "操作成功"
}

失败响应：
{
    "code": 500,
    "data": null,
    "msg": "操作失败"
}

未授权（由 TokenInterceptorMiddleware 返回）：
{
    "code": 401,
    "data": null,
    "msg": "访问接口未授权，请重新登录"
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

# 系统特色

# 数据可视化

组件：ECharts 5.5.1
图表：柱状图（系统数据统计）、饼图（数据分布）、折线图（数据趋势）、雷达图（系统指标）
位置：管理后台首页 /admin/home
数据来源：/student/page、/teacher/page、/course/page、/grade/page 四个接口返回的 total 字段，汇总为学生总数、教师总数、课程总数、成绩记录数

# 文件上传

上传接口：POST /file/upload（字段名 file），需在请求头携带 token
存储方式：由 settings.UPLOAD_PATH = "uploads\\" 指定相对目录，文件以 UUID 重命名（<uuid><扩展名>）后保存，目录不存在时自动创建
访问格式：http://127.0.0.1:8000/uploads/{uuid}.{扩展名}（由 settings.HTTP_PICTURE 拼接返回，开发环境下 MEDIA_URL = /uploads/ 由 Django 提供静态访问）
前端组件：components/MyUpload.vue 按类型切换上传控件（图片卡片 imageCard、图片 image、视频、音频、附件），头像等单文件场景 limit=1 时超出自动替换，支持预览弹窗与附件下载

# 工具类与公共封装

统一响应封装：apps/common/ResponseMessage.py 提供 success、failed、other、jump 四个静态方法，统一 code / data / msg 响应结构。
JWT 工具：utils/jwt_auth.py 提供 create_token（签发）与 get_payload（解码，返回 status / data / error），并附带 JwtQueryParamAuthentication、JwtHeaderAuthentication 认证类。
自定义异常体系：utils/custom_exception.py 定义 CustomException 基类及 NotFoundException、PermissionDeniedException、UnauthorizedException、ValidationException、BusinessException；utils/exception_handler.py 提供统一异常处理器 custom_exception_handler。
线程级用户上下文：utils/current_user.py 基于 threading.local() 提供 set_current_user / get_current_user / get_current_user_id / get_current_username，配套 middleware/CurrentUserMiddleware.py 在请求开始与结束设置、清理用户。
日期与前端工具：utils/DateUtil.py 提供 get_last_seven_days()、get_date()（返回最近七天日期字符串列表）；前端 src/utils/tools.js 提供 isLogin()、getCurrentUser()、getToken()、formatDateToYYYYMMDD()。

# 4-学生成绩管理系统 - 功能说明

# 项目概述

# 项目概览

# ✨ 创新点

# 1. 模块化独立 App 架构

# 2. 自定义 JWT 认证与中间件统一鉴权

# 3. 三角色分表设计与角色路由

# 4. 冗余快照式成绩数据设计

# 5. 配套 Java 代码生成器与数据可视化看板

# ✨ 项目亮点

# 一、 业务功能亮点

# 二、 技术实现亮点

# 三、 用户体验亮点

# 管理员

# 系统管理

# 教学资源管理

# 成绩与公告管理

# 个人设置

# 教师

# 教学

# 公共

# 学生

# 选课与成绩

# 公共

# 功能权限对照表

# 成绩等级说明

# 成绩取值与展示

# 备注（等级）取值

# 学期与学年取值

# 默认账号

# 管理员

# 教师

# 学生

# 核心业务流程

# 登录认证流程

# 学生选课流程

# 教师成绩录入流程

# 成绩查询与统计流程

# 技术说明

# 系统架构

# 访问地址

# 数据库

# API接口规范

# 系统特色

# 数据可视化

# 文件上传

# 工具类与公共封装

# 一、业务功能亮点

# 二、技术实现亮点

# 三、用户体验亮点