Merge remote-tracking branch 'origin/lon_students_merge_code_test' into lon_students_merge_code_test

class_management/readme.md

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

scores/dao/statistic_dao.py

@@ -50,11 +50,9 @@ def get_failing_students_dao(db):
         .order_by(ClassInfo.id, Score.num)
         .all())
 
-    return [{"sid": r.sid,
+    return [{
             "name": r.name,
             "class_name": r.class_name,
-            "num": r.num,
-            "t_subject": r.tsub,
             "score": r.score,}
         for r in results]
 

students/api/students_api.py

@@ -31,7 +31,7 @@ def get_students( stu:StudentsQuery = Depends()
                  f'时间格式：YYYY-MM-DD\n'
                  f'班级ID和顾问ID必须已经存在才可以绑定'
             )
-def add_student( stu:StudentsResponse  = Body(...)
+def add_student( stu:StudentsResponse =Depends()
                 , db=Depends(get_db)
                  ):
     s_dict = stu.model_dump(exclude_unset=True)
@@ -43,7 +43,7 @@ def add_student( stu:StudentsResponse  = Body(...)
     ,description=f'请输入需要更新信息的学生ID，学生手机号不可重复，填写即更新，为空即不更新。\n '
                  f'时间格式：YYYY-MM-DD'
     ,response_model=StudentsUpdate )
-def get_students( stu:StudentsUpdate = Body(...)
+def update_students( stu:StudentsUpdate =Depends()
                  , db=Depends(get_db)
                  ):
     s_dict = stu.model_dump(exclude_unset=True)
@@ -54,10 +54,10 @@ def get_students( stu:StudentsUpdate = Body(...)
 
 @s_api.delete("/students"
     ,summary='删除学生资料'
-    ,description=f'输入需要删除的学生信息，删除条件任选，但不可全为空，工资筛选能删除大于等于输入工资的所有人。\n '
+    ,description=f'输入需要删除的学生信息，删除条件任选，但不可全为空。\n '
                  f'时间格式：YYYY-MM-DD'
     ,response_model=list[StudentsDelete] ) # 逻辑删除/软删除
-def delete_students( stu:StudentsDelete = Body(...)
+def delete_students( stu:StudentsDelete =Depends()
                     , db=Depends(get_db)
                    ):
     s_dict = stu.model_dump(exclude_unset=True)

students/schema/students_request.py

@@ -8,6 +8,12 @@ class SexEnum(str , enum.Enum):
     m = '男'
     f = '女'
 
+class EducationEnum(str , enum.Enum):
+    z = '专科'
+    ben = '本科'
+    s = '硕士'
+    bo = '博士'
+
 # 查询
 class StudentsQuery(BaseModel):
     id:int | None = None
@@ -20,18 +26,14 @@ class StudentsQuery(BaseModel):
     specialty:str | None = None
     enrollment_time:datetime | None = None
     graduate_time:datetime | None = None
-    education:str | None = None
+    education:EducationEnum | None = None
     # 外键字段
     class_id:int | None = None
     advisor_id:int | None = None
     # 额外字段
     phone:str | None = None
 
-class EducationEnum(str , enum.Enum):
+
-    z = '专科'
-    ben = '本科'
-    s = '硕士'
-    bo = '博士'
 
 # 新建
 class StudentsResponse(BaseModel):
@@ -47,7 +49,7 @@ class StudentsResponse(BaseModel):
     education:EducationEnum
     # 外键字段
     class_id:int = Field(..., gt=0, description='班级ID')
-    advisor_id:int | None = None
+    advisor_id:int = Field(..., gt=0, description='班级ID')
     # 额外字段
     phone:str = Field(...,min_length=11,max_length=11,description='学生手机号')
 
@@ -63,7 +65,7 @@ class StudentsUpdate(BaseModel):
     specialty:str | None = None
     enrollment_time:datetime | None = None
     graduate_time:datetime | None = None
-    education:str | None = None
+    education:EducationEnum | None = None
     # 外键字段
     class_id:int | None = None
     advisor_id:int | None = None
@@ -82,7 +84,7 @@ class StudentsDelete(BaseModel):
     specialty:str | None = None
     enrollment_time:datetime | None = None
     graduate_time:datetime | None = None
-    education:str | None = None
+    education:EducationEnum | None = None
     # 外键字段
     class_id:int | None = None
     advisor_id:int | None = None