206 lines
5.9 KiB
Markdown
206 lines
5.9 KiB
Markdown
|
========================================
|
|||
|
|
Class Management 班级管理模块
|
|||
|
|
========================================
|
|||
|
|
|
|||
|
|
基于 FastAPI + SQLAlchemy + MySQL 的班级管理模块，
|
|||
|
|
提供班级的增删改查、多字段分页查询、逻辑删除等能力。
|
|||
|
|
|
|||
|
|
----------------------------------------
|
|||
|
|
一、目录结构
|
|||
|
|
----------------------------------------
|
|||
|
|
|
|||
|
|
class_management/
|
|||
|
|
api/
|
|||
|
|
class_management_api.py # 路由层：定义 HTTP 接口
|
|||
|
|
dao/
|
|||
|
|
class_management_dao.py # 数据访问层：封装数据库操作
|
|||
|
|
model/
|
|||
|
|
class_management_model.py # ORM 模型：映射数据库表
|
|||
|
|
schema/
|
|||
|
|
class_management_request.py # Pydantic 模型：请求/响应体
|
|||
|
|
database.py # 数据库连接、Session、Base
|
|||
|
|
|
|||
|
|
分层职责：
|
|||
|
|
api 接收请求、参数校验、返回响应，不直接写 SQL
|
|||
|
|
dao 封装 CRUD、事务控制，不处理 HTTP 状态码
|
|||
|
|
model 定义表结构、字段约束，不写业务逻辑
|
|||
|
|
schema 定义请求/响应格式，不碰数据库
|
|||
|
|
|
|||
|
|
----------------------------------------
|
|||
|
|
二、数据表结构
|
|||
|
|
----------------------------------------
|
|||
|
|
|
|||
|
|
表名：classes
|
|||
|
|
|
|||
|
|
字段 类型 约束 说明
|
|||
|
|
------------------ ----------- ---------------------- ------------------
|
|||
|
|
id Integer PK, Auto Increment 班级主键
|
|||
|
|
num String(50) NOT NULL, UNIQUE 班级编号
|
|||
|
|
name String(50) NOT NULL 班级名称
|
|||
|
|
head_teacher_id Integer FK -> teachers.id 班主任编号
|
|||
|
|
coach_teacher_id Integer FK -> teachers.id 授课老师编号
|
|||
|
|
tutor_teacher_id Integer FK -> teachers.id 助教老师编号
|
|||
|
|
class_start_time Date 可空 开班日期
|
|||
|
|
class_end_time Date 可空 结课日期
|
|||
|
|
is_delete Integer 默认 0 逻辑删除 0未删 1已删
|
|||
|
|
create_time DATETIME 默认 now 创建时间
|
|||
|
|
update_time DATETIME 默认 now, onupdate now 更新时间
|
|||
|
|
|
|||
|
|
注意：head_teacher_id / coach_teacher_id / tutor_teacher_id 是外键，
|
|||
|
|
插入前需保证 teachers 表中存在对应 id。
|
|||
|
|
|
|||
|
|
----------------------------------------
|
|||
|
|
三、API 接口
|
|||
|
|
----------------------------------------
|
|||
|
|
|
|||
|
|
基础前缀：/classes
|
|||
|
|
|
|||
|
|
[1] 新增班级
|
|||
|
|
POST /classes
|
|||
|
|
|
|||
|
|
请求体：
|
|||
|
|
{
|
|||
|
|
"num": "C001",
|
|||
|
|
"name": "Python01班",
|
|||
|
|
"head_teacher_id": 1,
|
|||
|
|
"coach_teacher_id": 2,
|
|||
|
|
"tutor_teacher_id": 3,
|
|||
|
|
"class_start_time": "2025-01-01",
|
|||
|
|
"class_end_time": "2025-06-30"
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
字段说明：
|
|||
|
|
num string 班级编号，唯一
|
|||
|
|
name string 班级名称
|
|||
|
|
head_teacher_id int 班主任 ID
|
|||
|
|
coach_teacher_id int 授课老师 ID
|
|||
|
|
tutor_teacher_id int 助教老师 ID
|
|||
|
|
class_start_time date 格式 YYYY-MM-DD
|
|||
|
|
class_end_time date 格式 YYYY-MM-DD
|
|||
|
|
|
|||
|
|
响应：
|
|||
|
|
{
|
|||
|
|
"code": 200,
|
|||
|
|
"detail": "新增成功",
|
|||
|
|
"totals": 1,
|
|||
|
|
"data": { ... }
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
错误：
|
|||
|
|
400 班级编号已存在
|
|||
|
|
|
|||
|
|
|
|||
|
|
[2] 根据 ID 查询班级
|
|||
|
|
GET /classes/{class_id}
|
|||
|
|
|
|||
|
|
响应：
|
|||
|
|
{
|
|||
|
|
"code": 200,
|
|||
|
|
"detail": "OK",
|
|||
|
|
"totals": 1,
|
|||
|
|
"data": {
|
|||
|
|
"id": 1,
|
|||
|
|
"num": "C001",
|
|||
|
|
"name": "Python01班",
|
|||
|
|
"head_teacher_id": 1,
|
|||
|
|
"coach_teacher_id": 2,
|
|||
|
|
"tutor_teacher_id": 3,
|
|||
|
|
"class_start_time": "2025-01-01",
|
|||
|
|
"class_end_time": "2025-06-30"
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
错误：
|
|||
|
|
404 该班级不存在或已删除
|
|||
|
|
|
|||
|
|
[3] 多字段分页查询
|
|||
|
|
GET /classes
|
|||
|
|
|
|||
|
|
Query 参数：
|
|||
|
|
num string 班级编号（精确匹配）
|
|||
|
|
name string 班级名称（精确匹配）
|
|||
|
|
head_teacher_id int 班主任 ID
|
|||
|
|
coach_teacher_id int 授课老师 ID
|
|||
|
|
tutor_teacher_id int 助教老师 ID
|
|||
|
|
class_start_time date 开班日期
|
|||
|
|
class_end_time date 结课日期
|
|||
|
|
page int 页码，默认 1，>=1
|
|||
|
|
page_size int 每页条数，默认 5，1~20
|
|||
|
|
|
|||
|
|
请求示例：
|
|||
|
|
GET /classes?name=Python01班&page=1&page_size=5
|
|||
|
|
|
|||
|
|
响应：
|
|||
|
|
{
|
|||
|
|
"code": 200,
|
|||
|
|
"detail": "OK",
|
|||
|
|
"totals": 1,
|
|||
|
|
"data": [
|
|||
|
|
{ "id": 1, "num": "C001", "name": "Python01班", ... }
|
|||
|
|
]
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
注意：当前为内存分页，先查出所有匹配记录再切片。
|
|||
|
|
数据量大时建议改成 DB 层 offset/limit。
|
|||
|
|
|
|||
|
|
[4] 修改班级信息
|
|||
|
|
PUT /classes/{class_id}
|
|||
|
|
|
|||
|
|
请求体（只传要改的字段）：
|
|||
|
|
{
|
|||
|
|
"head_teacher_id": 5,
|
|||
|
|
"class_end_time": "2025-12-31"
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
响应：
|
|||
|
|
{
|
|||
|
|
"code": 200,
|
|||
|
|
"detail": "修改成功",
|
|||
|
|
"data": { "id": 1 }
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
错误：
|
|||
|
|
400 没有传入要修改的字段
|
|||
|
|
404 班级不存在，修改失败
|
|||
|
|
|
|||
|
|
[5] 逻辑删除班级
|
|||
|
|
DELETE /classes/{class_id}
|
|||
|
|
|
|||
|
|
响应：
|
|||
|
|
{
|
|||
|
|
"code": 200,
|
|||
|
|
"detail": "删除成功",
|
|||
|
|
"data": { "id": 1 }
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
错误：
|
|||
|
|
404 班级不存在，删除失败
|
|||
|
|
|
|||
|
|
说明：逻辑删除，只把 is_delete 置为 1，不物理删除记录。
|
|||
|
|
|
|||
|
|
----------------------------------------
|
|||
|
|
五、约定与规范
|
|||
|
|
----------------------------------------
|
|||
|
|
|
|||
|
|
返回值约定：
|
|||
|
|
|
|||
|
|
DAO 函数 成功返回 失败返回 API 判断
|
|||
|
|
------------------ ---------- ------------ ------------------
|
|||
|
|
add_class_dao None 错误字符串 if res:
|
|||
|
|
update_class_dao int >= 1 0 if not row_count:
|
|||
|
|
delete_class_dao int >= 1 0 if not del_rows:
|
|||
|
|
get_class_dao list [] if not res:
|
|||
|
|
|
|||
|
|
逻辑删除：
|
|||
|
|
所有查询默认过滤 is_delete = 0，
|
|||
|
|
删除操作用 UPDATE is_delete = 1，不做物理删除。
|
|||
|
|
|
|||
|
|
分页：
|
|||
|
|
page 从 1 开始
|
|||
|
|
page_size 范围 1~20
|
|||
|
|
返回 totals 为总条数，data 为当前页数据
|
|||
|
|
|
|||
|
|
|
|||
|
|
|
|||
|
|
模块负责人：cyf
|
|||
|
|
最后更新：2026-09-22
|