学生信息管理系统

基于 Flask + MongoDB 的学生信息增删改查系统
Jinja2 服务端渲染 · Bootstrap 5 管理界面

一、项目简介

本项目是一个轻量级的学生信息管理系统，实现学生档案的 录入、查询、修改、删除、查看详情 全流程管理。

采用经典的服务端渲染方案：Flask 提供路由与模板渲染，MongoDB 存储学生文档，Jinja2 模板输出 HTML 页面，Bootstrap 5 负责界面样式。所有交互通过表单提交完成，无需前端构建流程。

配套文档：同目录下的 说明文档（含安装部署说明）.docx。

二、功能模块

功能	路由	方法	说明
学生列表	`/`	GET	分页展示（每页 10 条），显示学生总数；支持按姓名/学号搜索
添加学生	`/add`	GET / POST	表单录入，服务端校验通过后写入数据库
编辑学生	`/edit/<student_id>`	GET / POST	按 `_id` 加载并更新学生信息
查看详情	`/view/<student_id>`	GET	展示单个学生的完整档案
删除学生	`/delete/<student_id>`	GET	删除记录，前端二次确认

列表页特性

搜索：关键词对 name 与 student_id 做不区分大小写的正则匹配（$or 组合），搜索状态下不分页，一次性返回全部匹配结果。
分页：非搜索状态下按 student_id 升序排列，每页 10 条（per_page = 10），页面底部提供上一页 / 页码 / 下一页导航。
空状态：无数据时显示友好提示。

三、技术栈

层次	技术
后端框架	Flask（路由 + Jinja2 模板渲染）
数据库	MongoDB，通过 `flask-pymongo`（`PyMongo`）访问
文档主键	`bson.objectid.ObjectId`
前端	Jinja2 模板 + Bootstrap 5.3 + Bootstrap Icons 1.11（CDN 引入）
配置	`python-dotenv`（可选，见 `config.py`）
运行环境	Python 3 + 虚拟环境 `venv`

四、目录结构

学生信息管理系统/
├── app.py                       # 主应用：路由、数据校验、错误处理
├── run.py                       # 启动脚本（导入 app 后运行）
├── config.py                    # 分环境配置类（开发 / 生产）
├── models.py                    # Student 模型（to_dict / from_dict）
├── start.bat                    # Windows 一键启动
├── start.sh                     # Linux / macOS 一键启动
├── templates/
│   ├── base.html                # 基础布局（导航栏 + flash 消息 + 页脚）
│   ├── index.html               # 学生列表（搜索 + 分页）
│   ├── add.html                 # 添加学生表单
│   ├── edit.html                # 编辑学生表单
│   └── view.html                # 学生详情
├── static/
│   └── css/style.css            # 自定义样式
├── venv/                        # Python 虚拟环境
└── 说明文档（含安装部署说明）.docx

五、数据模型

数据库：student_db，集合：students。

字段	类型	说明
`_id`	ObjectId	MongoDB 自动主键
`student_id`	string	学号，新增时校验唯一性
`name`	string	姓名
`gender`	string	性别（`男` / `女`）
`age`	int	年龄
`major`	string	专业
`class_name`	string	班级
`email`	string	邮箱（选填）
`phone`	string	手机号（选填）
`address`	string	地址（选填）
`enrollment_date`	datetime	录入时间，新增时由 `datetime.now()` 自动写入

文档示例：

{
  "_id": ObjectId("..."),
  "student_id": "2021001",
  "name": "张三",
  "gender": "男",
  "age": 19,
  "major": "计算机科学",
  "class_name": "计科2101",
  "email": "zhang@edu.cn",
  "phone": "13800001001",
  "address": "四川省成都市",
  "enrollment_date": "2026-09-20T10:30:00"
}

models.py 中的 Student 类提供了 to_dict() / from_dict() 双向转换方法，可作为对象化操作的封装。

六、数据校验规则

校验集中在 app.py 的 validate_student(data, is_update=False)，所有错误通过 flash 逐条提示并回填表单：

字段	规则
学号	新增时必填；且不得与已有记录重复（编辑时跳过唯一性检查）
姓名	必填，长度 2–20 个字符
性别	必须为 `男` 或 `女`
年龄	必须为数字，且介于 15–100 之间
专业	必填
班级	必填
邮箱	选填；填写时需匹配 `^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$`
手机号	选填；填写时需匹配 `^1[3-9]\d{9}$`

校验通过后，年龄会被转换为 int 再写入数据库。

七、快速开始

7.1 环境要求

依赖	版本建议
Python	3.7+
MongoDB	4.4+（默认 `localhost:27017`）

7.2 依赖安装

项目依赖以下 Python 包：

flask
flask-pymongo
python-dotenv

注意：start.bat 与 start.sh 都会执行 pip install -r requirements.txt，但当前仓库中 未包含该文件，请先在项目根目录手动创建 requirements.txt，内容如上。

7.3 方式一：一键启动

Windows

双击 start.bat，脚本会依次：检查 MongoDB 服务（未运行则尝试 net start MongoDB）→ 创建并激活 venv → 安装依赖（清华镜像源）→ 启动应用。

Linux / macOS

chmod +x start.sh
./start.sh

脚本会尝试通过 systemctl / service / brew services 启动 MongoDB，随后创建虚拟环境、安装依赖并启动应用。

7.4 方式二：手动启动

# 1. 启动 MongoDB
net start MongoDB                    # Windows
# sudo systemctl start mongod        # Linux

# 2. 创建并激活虚拟环境
python -m venv venv
venv\Scripts\activate                # Windows
# source venv/bin/activate           # Linux / macOS

# 3. 安装依赖
pip install flask flask-pymongo python-dotenv

# 4. 启动
python app.py
# 或
python run.py

启动成功后控制台输出：

✅ MongoDB连接成功！数据库: student_db
==================================================
学生信息管理系统启动成功！
访问地址: http://localhost:5000
==================================================

访问 http://localhost:5000

服务监听 0.0.0.0:5000，局域网内其他设备也可通过本机 IP 访问。

八、配置说明

配置分为两处：

1. app.py 中的运行时配置（实际生效）

app.config['SECRET_KEY'] = 'your-secret-key-here-change-in-production'
app.config['MONGO_URI'] = 'mongodb://localhost:27017/student_db'

2. config.py 中的分环境配置类（可选项，见第十二节）

类	说明
`Config`	基础配置，从环境变量读取 `SECRET_KEY`、`MONGO_URI`，默认 `mongodb://localhost:27017/student_db`
`DevelopmentConfig`	继承 `Config`，`DEBUG = True`
`ProductionConfig`	继承 `Config`，`DEBUG = False`

config.py 使用 python-dotenv 的 load_dotenv()，因此可以在项目根目录创建 .env 文件覆盖默认值：

SECRET_KEY=你的密钥
MONGO_URI=mongodb://localhost:27017/student_db

九、使用说明

查看列表：首页展示学生总数与分页列表，点「查看 / 编辑 / 删除」图标执行对应操作，删除会弹出确认框。
搜索：在右上角输入姓名或学号关键词后点「搜索」，点「重置」返回完整列表。
新增：点「添加学生」填写表单，提交后若有校验错误会逐条提示并保留已填内容。
编辑：从列表进入编辑页，学号字段不参与编辑（保持唯一性校验只在新增时生效）。
错误处理：注册了 404 / 500 错误处理器（见第十二节说明）。

十、常见问题

1. 启动提示「MongoDB连接失败」 确认 MongoDB 服务已运行（Windows：net start MongoDB），且 27017 端口可访问。

2. start.bat / start.sh 报找不到 requirements.txt 该文件当前未随仓库提供，请按 7.2 节手动创建。

3. 中文乱码 start.bat 已执行 chcp 65001。页面均为 UTF-8 编码，MongoDB 驱动默认以 UTF-8 存储，一般无需额外设置。

4. 添加学生提示「学号已存在」 student_id 在新增时会做唯一性检查，请更换学号。注意该唯一性并未由数据库索引强制约束，而是应用层校验。

5. 搜索状态下的分页消失 搜索模式下会一次性返回全部匹配结果（total_pages = 1），模板中分页条件为 total_pages > 1 and not keyword，因此不显示分页控件——这是设计行为，非缺陷。

6. 访问不存在的地址报模板错误 见下方第十二节第 2 条。

十一、界面说明

Flash 消息：统一在 base.html 中渲染，按 success / danger 分类为绿色或红色告警条，可手动关闭。
列表页：卡片 + 表格布局，性别以蓝/黄徽章区分，联系方式为空时显示”未填写”，操作列为图标按钮组。
样式：Bootstrap 5.3 与 Bootstrap Icons 1.11 通过 jsDelivr CDN 引入，自定义样式位于 static/css/style.css。

十二、已知问题与注意事项

为避免使用踩坑，以下为本仓库当前的实际状态：

缺失 requirements.txt start.bat、start.sh 均依赖该文件，但仓库中不存在，一键脚本会在此步失败。请按 7.2 节创建。
缺失 404.html / 500.html app.py 中注册了错误处理器：
```
@app.errorhandler(404)
def not_found(error):
    return render_template('404.html'), 404
```
但 templates/ 目录下并无这两个模板文件，一旦触发 404 或 500，会因 TemplateNotFound 导致错误处理本身再报错。如需启用，请补齐 templates/404.html 与 templates/500.html。
config.py 与 models.py 未被引用 app.py 未 import config 或 from models import Student，而是直接硬编码了 SECRET_KEY 与 MONGO_URI，并在路由中直接操作字典。因此 config.py 的分环境配置与 .env 加载、models.py 的 Student 模型目前属于预留代码，修改它们不会影响运行行为——若要生效，需在 app.py 中接入。
SECRET_KEY 为占位值 app.py 中的 'your-secret-key-here-change-in-production' 仅用于开发，部署前必须替换（可直接改用 config.py 的 SECRET_KEY 环境变量方案）。
删除操作为 GET 请求 /delete/<student_id> 使用 GET，且未做 CSRF 防护，存在被预取或诱导触发的风险；生产环境建议改为 POST 并加入 CSRF token。
debug=True 默认开启 app.py 与 run.py 都以调试模式启动，仅适用于开发环境。

十三、说明

本项目为课程实践项目，未实现用户认证与权限管理，所有访问者均可执行全部操作。
学号唯一性、字段格式等约束均在应用层校验，数据库层面未建立唯一索引。