码力全开：学生管理系统（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。

# 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. 安装依赖：

   pip install -r requirements.txt
   

2. 在 MySQL 中创建数据库（默认库名 claude_sms_test），并确认 database.py 中的连接信息正确。
3. 建表：

   python init_db.py
   

4. 启动服务：

   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 不及格。