90 lines
3.8 KiB
Markdown
90 lines
3.8 KiB
Markdown
# 码力全开：学生管理系统（FastAPI 分层示例）
|
||
|
||
基于 FastAPI + SQLAlchemy + MySQL 的学生管理系统后端，采用前后端分离的 RESTful API 设计。
|
||
|
||
## 模块一览
|
||
|
||
| 模块 | 路由前缀 | 说明 |
|
||
| --- | --- | --- |
|
||
| 学生信息管理 | `/api/student` | 学生基本信息的增删改查 |
|
||
| 学生成绩管理 | `/api/score` | 成绩增删改查，等级自动判定 |
|
||
| 班级管理 | `/api/classes` | 班级增删改查 |
|
||
| 学生就业管理 | `/api/employ` | 就业记录增删改查（与学生一对一） |
|
||
| 教师信息管理 | `/api/teacher` | 教师增删改查 |
|
||
| 顾问信息管理 | `/api/advisor` | 顾问增删改查 |
|
||
| 统计分析 | `/api/stats` | 总览、分布、成绩/就业综合统计 |
|
||
|
||
## 项目结构（分层）
|
||
|
||
```
|
||
claude_sms_test/
|
||
├── main.py # 应用入口：注册路由、中间件、DAO 异常处理器
|
||
├── database.py # 数据库引擎 / 会话工厂 / 依赖注入
|
||
├── init_db.py # 建表脚本
|
||
├── model/ # 模型层：ORM 表映射
|
||
├── schemas/ # 模式层：Pydantic 请求/响应校验
|
||
├── dao/ # 数据访问层：查库、业务校验、事务
|
||
├── api/ # 路由层：接口出入参
|
||
└── static/ # 前端页面：原生 HTML/CSS/JS 单页应用（挂载在 /ui）
|
||
```
|
||
|
||
### 各层职责
|
||
|
||
| 层 | 干什么 | 不干什么 |
|
||
| --- | --- | --- |
|
||
| `api/` | 接收 HTTP 参数、调用 DAO、组装响应 | 不写 SQL、不 `import HTTPException` |
|
||
| `dao/` | 所有 SQLAlchemy 查询、唯一性/外键校验、软删除、事务提交 | 不感知 HTTP |
|
||
| `schemas/` | 请求体校验与响应序列化 | 不碰数据库 |
|
||
| `model/` | ORM 表结构映射 | 不含业务逻辑 |
|
||
|
||
**异常流转**：DAO 层只抛 `NotFoundError`(404) / `ConflictError`(409)，
|
||
在 `main.py` 注册的全局处理器统一转成 `{"detail": "..."}` 响应。
|
||
因此接口层不需要写任何 `try/except`。
|
||
|
||
```python
|
||
# dao → 抛业务异常
|
||
raise NotFoundError("所属班级不存在")
|
||
|
||
# main.py → 统一映射为状态码
|
||
@app.exception_handler(DaoError)
|
||
async def dao_error_handler(request: Request, exc: DaoError):
|
||
return JSONResponse(status_code=exc.status_code, content={"detail": exc.detail})
|
||
|
||
# api → 干净的一行调用
|
||
return stu_dao.create_student(db, payload.model_dump())
|
||
```
|
||
|
||
## 快速开始
|
||
|
||
1. 安装依赖：
|
||
```bash
|
||
pip install -r requirements.txt
|
||
```
|
||
2. 在 MySQL 中创建数据库（默认库名 `claude_sms_test`），并确认 `database.py` 中的连接信息正确。
|
||
3. 建表：
|
||
```bash
|
||
python init_db.py
|
||
```
|
||
4. 启动服务：
|
||
```bash
|
||
python main.py
|
||
```
|
||
5. 打开接口文档：http://localhost:8002/docs
|
||
6. 打开可视化管理界面（含查询小助手）：http://localhost:8002/ui
|
||
|
||
## 前端界面
|
||
|
||
`static/` 下是配套的管理界面，原生 HTML/CSS/JS，**无构建、无第三方依赖**，由 `main.py` 挂载在 `/ui`。
|
||
|
||
- 九个视图：数据总览 / 统计分析 / 学生 / 班级 / 教师 / 顾问 / 成绩 / 就业 / 查询小助手
|
||
- 表格支持分页与多条件筛选；新增、编辑、软删除均直连后端接口，删除为软删除并二次确认
|
||
- 统计图表为纯 DOM 绘制，不依赖任何 CDN，离线可用
|
||
- 右侧「查询小助手」直接用中文提问：
|
||
- 编号直达详情：`S0001` / `C001` / `T001` / `A001`
|
||
- 条件筛选：性别、学历、生源地、专业、班级、顾问、成绩等级、就业状态、就业公司
|
||
- 统计问答：就业率、平均分、最高/最低分、及格率、薪资、生源地 Top、各类分布
|
||
|
||
## 说明
|
||
|
||
- 所有删除操作均为**软删除**（`is_deleted` 标记），数据不会真正从数据库中移除。
|
||
- 成绩等级未显式指定时，按分数自动判定：`>=90 优秀`、`80-89 良好`、`60-79 普通`、`<60 不及格`。 |