student_manage_system/class_management/readme.md

======================================== 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