From a3c54f3db53fa5e05cf9e64ad0849b9b814f07ad Mon Sep 17 00:00:00 2001
From: cyf <15271199537@163.com>
Date: Wed, 23 Sep 2026 10:38:12 +0800
Subject: [PATCH] read.me

---
 class_management/read1.me.txt | 206 ++++++++++++++++++++++++++++++++++
 1 file changed, 206 insertions(+)
 create mode 100644 class_management/read1.me.txt

diff --git a/class_management/read1.me.txt b/class_management/read1.me.txt
new file mode 100644
index 0000000..116020c
--- /dev/null
+++ b/class_management/read1.me.txt
@@ -0,0 +1,206 @@
+========================================
+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
\ No newline at end of file