137 lines
6.1 KiB
Markdown
137 lines
6.1 KiB
Markdown
# 沃林学生管理系统
|
||
|
||
基于 **FastAPI + SQLAlchemy（同步）+ MySQL + Pydantic v2** 的学生管理系统，提供学生信息、考核成绩、就业管理、班级/老师管理与统计分析能力，内置 JWT 认证（RBAC 角色权限）与 Vue3 前端管理页面，附 Docker / Nginx 生产部署配置。
|
||
|
||
## 目录结构
|
||
|
||
```
|
||
walin_student_system/
|
||
├── main.py # 项目入口：创建应用、注册路由、建表、挂载前端
|
||
├── config.py # 全局配置（环境变量可覆盖）
|
||
├── database.py # 数据库连接 / 会话 / 依赖注入
|
||
├── core/
|
||
│ ├── security.py # 密码哈希(PBKDF2) + JWT 签发/校验
|
||
│ └── deps.py # 认证依赖 + 角色级 RBAC
|
||
├── model/ # Model 层：SQLAlchemy 表模型
|
||
├── scheme/ # Pydantic 请求/响应模型
|
||
├── dao/ # 数据访问层（含统计动态查询、高级筛选器）
|
||
├── api/ # 路由层：auth/classes/teachers/students/scores/employment/statistics
|
||
├── static/ # Vue3 前端管理页面（index.html + app.js + style.css）
|
||
├── sql/init.sql # 修正版建表语句 + 种子数据（含初始账号）
|
||
├── Dockerfile # gunicorn + uvicorn worker 生产镜像
|
||
├── docker-compose.yml # MySQL + API + Nginx 一键部署
|
||
└── nginx.conf # 反向代理配置
|
||
```
|
||
|
||
## 本地运行
|
||
|
||
1. 准备 MySQL，执行初始化脚本（建库建表 + 种子数据 + 初始账号）：
|
||
|
||
```bash
|
||
mysql -uroot -p < sql/init.sql
|
||
```
|
||
|
||
2. 安装依赖并启动（Python 3.10）：
|
||
|
||
```bash
|
||
pip install -r requirements.txt
|
||
python main.py # 或 uvicorn main:app --reload --port 8000
|
||
```
|
||
|
||
3. 访问：
|
||
- 前端管理页面：<http://localhost:8000/>（自动跳转到 /static/index.html）
|
||
- Swagger 文档：<http://localhost:8000/docs>
|
||
|
||
4. 默认账号（见 `sql/init.sql`）：
|
||
|
||
| 账号 | 密码 | 角色 |
|
||
|---|---|---|
|
||
| admin | admin123 | 管理员（全部权限） |
|
||
| teacher1 | teacher123 | 教师（班级1，可管理本班学生） |
|
||
| s2026010003 | student123 | 学生（只读本人信息） |
|
||
|
||
本地默认数据库连接为 `root:123456@localhost:3306/walin_db`，与 compose 不同；可用环境变量 `DATABASE_URL` 覆盖。
|
||
|
||
## Docker 一键部署
|
||
|
||
```bash
|
||
docker compose up -d --build
|
||
```
|
||
|
||
- Nginx 监听 80 端口反向代理 API 容器；
|
||
- MySQL 数据持久化在 `mysql_data` 卷，首次启动自动执行 `sql/init.sql`；
|
||
- 访问 `http://服务器IP/`。
|
||
|
||
生产环境注意：
|
||
- 修改 `docker-compose.yml` 中的 `MYSQL_ROOT_PASSWORD` 与 `SECRET_KEY`；
|
||
- 建议在 Nginx 层配置 HTTPS（证书挂载后改 `listen 443 ssl`）。
|
||
|
||
## 认证与权限（RBAC）
|
||
|
||
- 登录：`POST /api/auth/login`，返回 JWT；后续请求携带 `Authorization: Bearer <token>`。
|
||
- 角色权限：
|
||
- **admin**：全部接口；
|
||
- **teacher**：查询类接口 + 本班学生的成绩/就业/学生信息管理（资源归属校验：`teacher.class_id == student.class_id`）；
|
||
- **student**：只读本人信息与成绩。
|
||
|
||
## 主要接口一览
|
||
|
||
| 模块 | 路径前缀 | 说明 |
|
||
|---|---|---|
|
||
| 认证 | /api/auth | login / register(仅admin) / me |
|
||
| 班级 | /api/classes | add / total_query / single_query / update / delete |
|
||
| 老师 | /api/teachers | teacher/add、teacher/delete、teacher/update、teacher/total_query、teacher/single_query |
|
||
| 学生 | /api/students | add（学号自动生成）/ total_query（多条件分页）/ single_query / update / delete |
|
||
| 成绩 | /api/scores | add（60分红线预警）/ query / update / delete |
|
||
| 就业 | /api/employment | open（状态联动→进入就业）/ offer（状态联动→已就业）/ students/{id} / class/{id} / total_query / update / delete |
|
||
| 统计 | /api/statistics | 见下 |
|
||
|
||
### 统计分析接口
|
||
|
||
| 接口 | 说明 |
|
||
|---|---|
|
||
| GET /statistics/students/by-age | 动态年龄查询（gt/lt/eq/gte/lte/between） |
|
||
| GET /statistics/class/gender-stats | 每班总人数 + 男女分布 |
|
||
| GET /statistics/score/all-above?line=80 | 每次考试都在分数线以上的学生 |
|
||
| GET /statistics/score/fail?times=2 | 不及格次数 ≥ N 的学生（含明细） |
|
||
| GET /statistics/score/class-avg?order=desc | 每次考试每班平均分（动态排序） |
|
||
| GET /statistics/employment/top-salary?n=10 | 薪资 Top N |
|
||
| GET /statistics/employment/duration | 每个学生就业时长（offer时间-开放时间） |
|
||
| GET /statistics/employment/class-avg-duration | 每班平均就业时长 |
|
||
| GET /statistics/score/volatility?top_n=5 | 成绩波动最大 Top N（最大分差） |
|
||
| GET /statistics/employment/funnel | 班级就业漏斗（总人数→已就业→高薪→就业率） |
|
||
| POST /statistics/filter | 通用高级筛选器（AND/OR 嵌套规则，见下） |
|
||
|
||
### 高级筛选器示例
|
||
|
||
```json
|
||
POST /api/statistics/filter
|
||
{
|
||
"model": "student",
|
||
"rules": [
|
||
{ "field": "age", "operator": ">", "value": 20 },
|
||
{ "logic": "OR", "sub_rules": [
|
||
{ "field": "salary", "operator": ">=", "value": 10000 },
|
||
{ "field": "class_name", "operator": "like", "value": "Java" }
|
||
]}
|
||
]
|
||
}
|
||
```
|
||
|
||
支持字段：`stu_id, stu_name, age, gender, education, major, native_place, status, class_id, class_name, salary, company_name`；操作符：`> < = != >= <= like in`。
|
||
|
||
## 设计说明（对原始建表语句的修正）
|
||
|
||
1. `c_lass` 补充 `class_name`（原表无班级名称，展示/统计都需要）；
|
||
2. `student` 补充 `status`（在读/进入就业/已就业），就业联动依赖该字段；
|
||
3. `score` 补充 `is_deleted`，统一逻辑删除风格；
|
||
4. `employment_base` 补充冗余字段 `stu_name / class_name`（需求 2.3 设计提示），登记时从 student/class 同步写入保证一致性；
|
||
5. 新增 `user` 表支撑 JWT 登录与 RBAC（原建表语句缺失）；
|
||
6. 学号生成规则：`入学年份(4位) + 班级号(2位) + 序号(4位)`，如 2026010001。
|
||
|
||
## 待扩展（需求文档第 5 节）
|
||
|
||
- Excel 批量导入学生（python-multipart 已装，可加 pandas/openpyxl）
|
||
- 部门管理、顾问管理独立模块
|
||
- 强制下线/单点登录管控（需引入 Redis Session）
|