# 学生管理系统

**Repository Path**: AMIKG/student-management-system

## Basic Information

- **Project Name**: 学生管理系统
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-07-06
- **Last Updated**: 2026-07-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 御学中枢

基于 Django 5.1 的学校学生成绩管理与 AI 学情分析系统。

## 核心功能

- **Excel 批量导入**：支持通过上传 Excel 文件（`.xls` / `.xlsx`）批量导入学生信息和考试成绩，自动创建系统登录账号。
- **双角色权限体系**：老师通过 Django Admin 管理后台管理学生与成绩；学生通过前台页面登录并查看个人成绩。
- **AI 学情分析**：集成 DeepSeek 大模型，自动生成学生学情分析报告（总体评估、优势分析、薄弱环节、成绩趋势、个性化建议），支持多轮 AI 对话辅导。
- **自动账号生成**：添加学生或老师时，系统自动同步创建 `auth_user` 账号，初始密码集中可配置。
- **成绩查阅**：学生登录后首页展示成绩统计卡片和所有考试成绩列表，点击可查看单条成绩详情。
- **密码修改**：学生可在前台自主修改登录密码。
- **数据去重保护**：Excel 导入和手动添加均包含学号/科目重复检测，自动跳过重复数据并提示过滤数量。

## 技术栈

| 组件 | 技术 |
|------|------|
| 后端框架 | Django 5.1 |
| 数据库 | MySQL 5.7+ / 8.0+（通过 mysqlclient 驱动） |
| Excel 解析 | openpyxl 3.1+ |
| AI 大模型 | DeepSeek API（OpenAI 兼容 SDK） |
| 前端样式 | Bootstrap 3 + 自定义 CSS（student-theme / custom-admin） |
| 前端脚本 | jQuery + 原生 JavaScript |
| 模板引擎 | Django Templates |
| 图标库 | Font Awesome 6 |
| 语言 | Python 3.10+ |

## 快速开始

### 环境要求

| 依赖 | 版本 |
|------|------|
| Python | 3.10+ |
| MySQL | 5.7+ / 8.0+ |
| Django | >= 5.1 |
| mysqlclient | — |
| openpyxl | 3.1+ |
| openai | >= 1.0.0 |

### 安装步骤

**Windows（PowerShell）：**

```powershell
# 1. 克隆仓库
git clone https://gitee.com/AMIKG/student-management-system.git
cd student-management-system

# 2. 创建并激活虚拟环境
python -m venv venv
.\venv\Scripts\activate

# 3. 安装依赖
pip install -r stu_project/requirements.txt

# 4. 创建 MySQL 数据库（在 MySQL 客户端中执行）
# CREATE DATABASE student_system DEFAULT CHARACTER SET utf8mb4;

# 5. 修改数据库连接配置
# 编辑 stu_project/config/settings.py 中 DATABASES 的 USER、PASSWORD 等字段

# 6. （可选）配置 DeepSeek API Key
# 在 settings.py 中设置 DEEPSEEK_API_KEY，或通过环境变量传入

# 7. 进入项目目录，执行数据库迁移
cd stu_project
python manage.py migrate

# 8. 创建超级管理员
python manage.py createsuperuser

# 9. 启动开发服务器
python manage.py runserver
```

**macOS / Linux：**

```bash
# 1. 克隆仓库
git clone https://gitee.com/AMIKG/student-management-system.git
cd student-management-system

# 2. 创建并激活虚拟环境
python3 -m venv venv
source venv/bin/activate

# 3. 安装依赖
pip install -r stu_project/requirements.txt

# 4. 创建 MySQL 数据库
# mysql -u root -p -e "CREATE DATABASE student_system DEFAULT CHARACTER SET utf8mb4;"

# 5. 修改 stu_project/config/settings.py 中数据库配置

# 6. （可选）配置 DeepSeek API Key

# 7. 迁移并创建管理员
cd stu_project
python manage.py migrate
python manage.py createsuperuser

# 8. 启动服务
python manage.py runserver
```

### 默认初始密码

| 角色 | 初始密码 | 配置项（settings.py） |
|------|---------|----------------------|
| 老师 | `t123456` | `TEACHRE_INIT_PASSWORD` |
| 学生 | `123456` | `STUDENT_INIT_PASSWORD` |

## 项目结构

```
student-management-system/
├── .gitignore                    # Git 忽略规则
├── README.md
└── stu_project/                  # Django 项目根目录
    ├── manage.py                 # Django 管理入口
    ├── requirements.txt          # Python 依赖清单
    ├── config/                   # 项目配置
    │   ├── __init__.py           # PyMySQL 兼容初始化（保留）
    │   ├── settings.py           # 数据库、静态文件、DeepSeek、密码策略等配置
    │   ├── urls.py               # URL 路由分发
    │   ├── asgi.py
    │   └── wsgi.py
    ├── teacher/                  # 教师模块
    │   ├── models.py             # Teacher 模型
    │   └── admin.py              # 后台教师管理（自动创建 User）
    ├── student/                  # 学生模块
    │   ├── models.py             # Student 模型
    │   ├── views.py              # 全部前台视图（登录、首页、成绩详情、改密、学情分析、AI 对话等）
    │   ├── forms.py              # 表单验证（StudentLoginForm、ChangepwdForm）
    │   └── admin.py              # 后台学生管理（自动创建 User）
    ├── score/                    # 成绩模块
    │   ├── models.py             # Score 模型
    │   └── admin.py              # 后台成绩管理
    ├── uploadfile/               # 文件上传模块
    │   ├── models.py             # FileUpload 模型
    │   └── admin.py              # Excel 解析与入库逻辑
    ├── utils/
    │   ├── base_models.py        # 抽象基类（status + created_at + updated_at）
    │   └── deepseek_service.py   # DeepSeek API 服务层（报告生成、多轮对话、历史管理）
    ├── templates/                # 前端模板
    │   ├── base.html             # 基础布局（导航栏、页脚）
    │   ├── index.html            # 学生首页（成绩统计卡片 + 成绩列表）
    │   ├── login.html            # 学生登录页（含角色切换选择器）
    │   ├── score.html            # 成绩详情页
    │   ├── changepwd.html        # 修改密码页
    │   ├── analysis.html         # AI 学情分析页（报告 + 对话）
    │   ├── about.html            # 关于我们
    │   ├── contact.html          # 联系我们
    │   ├── 404.html              # 404 错误页
    │   └── admin/                # 后台管理模板覆盖
    │       ├── base_site.html    # 侧边栏 emoji 注入、品牌标识
    │       ├── login.html        # 自定义登录页（渐变背景、角色切换）
    │       ├── index.html        # 自定义仪表盘（欢迎横幅、快捷操作、统计面板）
    │       ├── change_form.html  # 编辑表单覆盖
    │       └── change_list.html  # 列表页覆盖
    ├── static/                   # 静态资源
    │   ├── css/
    │   │   ├── student-theme.css # 学生前台主题样式
    │   │   ├── style.css         # 旧版网站主题样式
    │   │   └── bootstrap.css     # Bootstrap 3
    │   ├── admin/css/
    │   │   └── custom-admin.css  # 管理后台自定义主题（Academic Blue/Slate）
    │   ├── js/                   # jQuery、Bootstrap JS
    │   ├── fonts/                # 图标字体
    │   └── images/               # Logo、404 插图等
    └── uploads/                  # 上传文件存储目录
```

## URL 路由

| URL | 视图 | 说明 | 认证 |
|-----|------|------|------|
| `/` | `student.views.index` | 学生首页，展示成绩统计与列表 | 需登录 |
| `/login/` | `StudentLoginView` | 学生登录 | 公开 |
| `/logout/` | `student.views.logout` | 退出登录 | 任意 |
| `/change_pwd/` | `student.views.changepwd` | 修改密码 | 需登录 |
| `/score/<score_id>` | `student.views.score` | 成绩详情 | 需登录 |
| `/analysis/` | `student.views.analysis` | AI 学情分析页面 | 需登录 |
| `/analysis/chat/` | `student.views.analysis_chat` | AI 对话接口（POST JSON） | 需登录 |
| `/analysis/student/<student_num>/` | `student.views.analysis_student_data` | 教师切换学生数据（GET JSON） | 需登录 |
| `/analysis/clear-chat/` | `student.views.analysis_clear_chat` | 清除对话历史（POST） | 需登录 |
| `/about/` | `student.views.about` | 关于我们 | 公开 |
| `/contact/` | `student.views.contact` | 联系我们 | 公开 |
| `/admin/` | Django Admin | 后台管理 | 需 staff 权限 |

## 数据模型

### 通用抽象基类（CreateUpdateMixin）

所有业务模型继承自 `utils/base_models.py` 中的抽象基类，统一提供：

| 字段 | 类型 | 说明 |
|------|------|------|
| `status` | `BooleanField` | 数据状态标记，带索引 |
| `created_at` | `DateTimeField` | 创建时间，自动写入 |
| `updated_at` | `DateTimeField` | 更新时间，自动更新 |

### Teacher（教师）

| 字段 | 类型 | 说明 |
|------|------|------|
| `tid` | `IntegerField`（主键） | 与 `user_id` 同步 |
| `name` | `CharField(20)` | 姓名 |
| `email` | `CharField(60)`，唯一 | 同时作为登录用户名 |
| `class_name` | `CharField(50)` | 所管班级名称 |
| `gender` | `CharField(32)` | 男 / 女 |
| `phone` | `CharField(11)`，唯一 | 手机号 |
| `user` | `OneToOneField(User)` | 关联 `auth_user`（级联删除） |

### Student（学生）

| 字段 | 类型 | 说明 |
|------|------|------|
| `id` | `BigAutoField`（主键） | 自增 ID |
| `student_num` | `CharField(10)`，唯一 | 学号，同时作为登录用户名 |
| `name` | `CharField(20)` | 姓名 |
| `gender` | `CharField(32)` | 男 / 女 |
| `phone` | `CharField(11)` | 联系电话 |
| `birthday` | `DateField` | 出生日期 |
| `user` | `OneToOneField(User)` | 关联 `auth_user`（级联删除） |
| `teacher` | `ForeignKey(Teacher)` | 所属老师（级联删除） |

### Score（成绩）

| 字段 | 类型 | 说明 |
|------|------|------|
| `id` | `BigAutoField`（主键） | 自增 ID |
| `title` | `CharField(20)` | 考试名称 |
| `score` | `DecimalField(5,2)` | 分数，两位小数 |
| `student` | `ForeignKey(Student)` | 所属学生（级联删除） |

### FileUpload（上传文件）

| 字段 | 类型 | 说明 |
|------|------|------|
| `id` | `BigAutoField`（主键） | 自增 ID |
| `file_name` | `FileField` | 仅允许 `.xls` / `.xlsx` |
| `file_type` | `IntegerField` | 1=学生信息，2=成绩信息 |
| `teacher` | `ForeignKey(Teacher)` | 上传老师 |

## Excel 批量导入

### 学生信息导入（文件类型 = 1）

Excel 格式（第 1 行为表头，数据从第 2 行开始）：

| 列 A | 列 B | 列 C | 列 D | 列 E |
|------|------|------|------|------|
| 学号 | 姓名 | 性别 | 出生日期 | 联系电话 |

导入逻辑：
- 以学号为唯一标识自动去重，重复数据跳过并计数
- 为每个学生自动创建 `auth_user`（用户名=学号，密码=`STUDENT_INIT_PASSWORD`）
- 自动绑定当前操作老师的外键
- 使用 `bulk_create` 批量写入

### 成绩信息导入（文件类型 = 2）

Excel 格式：

| 列 A | 列 B | ... | 最后一列 |
|------|------|-----|---------|
| 考试名称 | 学号 | ... | 分数 |

导入逻辑：
- 通过学号查找学生，学号不存在则跳过该行
- 同一学生同一考试名称自动去重
- 使用 `bulk_create` 批量写入

## AI 学情分析

系统集成 DeepSeek 大模型，提供智能学情分析与学习辅导功能。

### 分析报告

根据学生历次考试成绩自动生成五段式报告：

1. **总体评估** — 整体学业水平概览，平均分、考试次数等关键指标
2. **优势分析** — 成绩最好的科目及优势原因解读
3. **薄弱环节** — 成绩较低或波动较大的科目分析
4. **成绩趋势** — 成绩走势判断（上升/下降/波动/稳定）
5. **个性化学习建议** — 针对薄弱学科的 3-5 条具体改进措施

### AI 学习助手「星智」

- 通过学情分析页面右侧的聊天卡片与 AI 对话
- 支持多轮对话，服务端通过 Django cache 维护上下文（2 小时有效期，最多 10 轮）
- 对话范围限定在学习辅导领域（学科答疑、学习方法、考试策略、心理调节）
- 教师可切换查看任意学生的报告并与 AI 讨论该学生的情况

### 配置

| 配置项 | 说明 | 默认值 |
|--------|------|--------|
| `DEEPSEEK_API_KEY` | DeepSeek API 密钥（必填） | 可通过环境变量设置 |
| `DEEPSEEK_MODEL` | 模型版本 | `deepseek-chat` |
| `DEEPSEEK_BASE_URL` | API 端点地址 | `https://api.deepseek.com` |

未配置 API Key 时，学情分析页面会显示配置提示，不影响其他功能正常使用。

## 账号体系

系统基于 Django 内置 `auth_user` 表，通过 `OneToOneField` 建立教师/学生与登录账号的强绑定：

- **教师**：`tid` 与 `user_id` 同步，用邮箱作为登录用户名，`is_staff=1` 允许登录后台。添加/删除教师时自动同步 `auth_user`。
- **学生**：用学号作为登录用户名。手动添加或 Excel 导入时自动创建 `auth_user`。添加/删除学生时自动同步 `auth_user`。

## 配置说明

| 配置项 | 位置 | 说明 |
|--------|------|------|
| `DATABASES` | `settings.py` | MySQL 连接信息（数据库名 `student_system`） |
| `TEACHRE_INIT_PASSWORD` | `settings.py` | 老师初始密码，默认 `t123456` |
| `STUDENT_INIT_PASSWORD` | `settings.py` | 学生初始密码，默认 `123456` |
| `DEEPSEEK_API_KEY` | `settings.py` | DeepSeek API 密钥 |
| `DEEPSEEK_MODEL` | `settings.py` | 模型版本，默认 `deepseek-chat` |
| `DEEPSEEK_BASE_URL` | `settings.py` | API 端点，默认官方地址 |
| `LOGIN_URL` | `settings.py` | 未登录跳转地址，默认 `/login/` |
| `LANGUAGE_CODE` | `settings.py` | `zh-Hans`（简体中文） |
| `TIME_ZONE` | `settings.py` | `Asia/Shanghai` |
| `MEDIA_ROOT` | `settings.py` | 文件上传目录，`stu_project/uploads/` |

## 使用流程

1. 启动服务后访问 `http://127.0.0.1:8000/admin/`，用超级管理员账号登录
2. 在后台添加**教师**（系统自动创建教师登录账号，默认密码 `t123456`）
3. 教师登录后台，手动添加学生或通过「上传文件」批量导入学生 Excel
4. 学生访问 `http://127.0.0.1:8000/login/`，使用学号 + 默认密码 `123456` 登录
5. 登录后首页自动展示该学生的成绩统计和所有成绩记录
6. 点击导航栏「学情分析」进入 AI 分析页面，查看学习报告并与 AI 助手对话

## 许可证

本项目仅供学习与课程实践使用。