student_manage_system/students/README_students.md

students模块解释

项目层：

web框架：FastAPI(自动生成接口) ORM：sqlalchemy 校验：pydantic 数据库：MYSQL(通过 PyMysql 驱动) 运行：uvicorn，端口暂定52000

总结：用 FastAPI 暴露一组 HTTP 接口 ， 对 MySQL 里的一张 students 表做增、删、改、查 ， 其中删除是逻辑删除（软删除） ， 数据不会被真正抹掉。

项目根目录是main.py是程序入口，而students/是一个

main：学生管理系统的主程序文件、测试接口

1. 下面所有配置文件的接口全部导入并建表
2. 创建合并接口APIRouter
3. 创建fastapi接口并本地运行

databases：链接数据库配置文件

1. 链接本地mysql，实例化mysql，创建引擎，创建基类，实例化数据库会话
2. 创建函数，调用数据库会话
3. 因为后期多代码合并，每个人的databases都不同链接也不同，所以导入了.env文件
   1. 这样在每个人有差异的数据可以直接保存在本地，不用反复同步相互覆盖了
   2. 另外一个原因就是model层大家建表要使用同一个基类
      1. 所以接入了.env文件随时入参
      2. 这样更加方便，而且高频同步和拉取也不用重新配置

分层代码书写顺序：

1. model层：
   1. 确认你的业务需要哪些字段
   2. 确认小组的字段名、表名、库名一致
   3. 确认主键、唯一键、字段数据类型、外键等关键字内容
2. 请求体
   1. 搞清楚业务需求，需要用到哪些字段
   2. 增删改查的具体逻辑
3. api
   1. 写好接收变量
   2. 装饰器设定
   3. 输出规则
   4. 一次写好基本上就不会再改了
4. dao
   1. 工作量最大的层，所有的业务逻辑都写在这里面
   2. 所有的业务逻辑都在这个层里

api.students_api：接口文件

学生表students的功能接口:

1. 学生信息的查询
   1. 仅保存入参标量，代码都在逻辑层，建好了基本不用修改，方便维护
2. 学生信息的新增
   1. 仅保存入参标量，代码都在逻辑层，建好了基本不用修改，方便维护
3. 学生信息的更新
   1. 仅保存入参标量，代码都在逻辑层，建好了基本不用修改，方便维护
4. 学生信息的逻辑删除
   1. 仅保存入参标量，代码都在逻辑层，建好了基本不用修改，方便维护

dao.students_dao：数据筛选文件

数据库的逻辑筛选文件:

1. 查询：get_student_dao
   1. 筛选所有非空内容，过滤逻辑删除数据，输出学生完整字段
2. 新增：add_student_dao
   1. 关键字段限制
   2. 过滤各种报错，反馈报错问题
   3. 无报错即可全部插入
   4. 注意逻辑删除的数据，其实也会占用唯一键，所以有唯一键重复时，直接拉出旧数据进行清空翻新。
3. 更新：update_student_dao
   1. 主要过滤掉没有输入的字段，除非输入才可以被覆盖，不能每次更新清空全部内容
   2. 唯一字段过滤，比如电话号码，在业务逻辑上电话号码不能重复
4. 逻辑删除：delete_student_dao
   1. 逻辑删除可以用所有字段进行精确或者范围删除
   2. 但是不可以全为空删除我的整个库

model.students_model：数据库建表文件

1. 数据表建表代码
2. 字段信息： id:PK num：UNI name age sex:ENUM home_Place college specialty enrollment_time graduate_time education:ENUM 外键字段 class_id:FK advisor_id:FK 额外字段 phone:UNI 通用字段 create_date update_date is_deleted deleted_date

schema.students_request：请求体、数据过滤

请求体根据业务要求有不同调整，方便后续维护和更改需求

1. 查询：StudentsQuery
   1. 所有字段都可以进行查询
   2. 随便填哪个都可以进行精确查询或者范围查询
   3. 全为空即查询全部
2. 新增：StudentsResponse
   1. 新增有必填项、不可重复项等，保证数据干净
3. 更新：StudentsUpdate
   1. 以ID作为查询字段，更新其他内容
   2. 会过滤掉重复值
4. 逻辑删除：StudentsDelete
   1. 所有字段都可以进行删除
   2. 随便填哪个都可以进行精确删除或者范围删除
   3. 不可全字段为空

StatCalc：统计分析模块

• 除了没有model以外没有什么太大的区别
• 因为接口都有具体需求，所以直接一键呼出，不用填写筛选内容

1. 请求体
   1. 搞清楚业务需求，需要用到哪些字段
   2. 增删改查的具体逻辑
2. api
   1. 写好接收变量
   2. 装饰器设定
   3. 输出规则
   4. 一次写好基本上就不会再改了
3. dao
   1. 工作量最大的层，所有的业务逻辑都写在这里面
   2. 所有的业务逻辑都在这个层里

学生管理系统修改报错记录

1. 合并修改记录：

1. main.py
   1. 所有子模块中的main新增了APIRouter，用来拉到主main进行运行
   2. stu_jiuye
      1. stu_jiuye\main.py
         1. 新增为加粗倾斜处
         2. from sut_jiuye.文件名 import 调用名
      2. CURD_api.py
         1. 新增为加粗倾斜处
         2. from sut_jiuye.文件名 import 调用名
2. databases.py
   1. 所有人的db_url账号密码IP端口和名称全部存入了.env文件
   2. 导入了load_dotenv进行调用
      1. from dotenv import load_dotenv
      2. load_dotenv( )
      3. DB_USER = os.getenv("DB_USER", "root")
      4. DB_PASSWORD = os.getenv("DB_PASSWORD", "")
      5. DB_HOST = os.getenv("DB_HOST", "localhost")
      6. DB_PORT = os.getenv("DB_PORT", "3306")
      7. DB_NAME = os.getenv("DB_NAME", "student_manage_system")
   3. 修改了部分url名称，自行检查
3. class文件夹下导入修改
   1. 新增为加粗倾斜处
      1. from class_management.文件名 import 调用名
         1. 改动文件：
            1. class_management_api.py
            2. class_management_dao.py
            3. class_management_model.py

2. 合并完成

1. 新增.env文件，设置好账号密码等
   1. 可以一次运行创建好所有表格
   2. 但是注意，没办法创建库，也就是student_manage_system
   3. 如果没有建库的话会报错
2. 表外键写完之后，可以用SQL语句删除所有表
   1. 再重新运行main.py文件
      1. 这个main.py特指最外层的运行主程序main.py

3. 分支测试

1. 阶段完成后
   1. 如果不擅长保存版本，可以在自己的分支下面再建新分支
   2. 方便切换版本和查询bug，理解逻辑，以免修改后bug更多了
   3. 完成后可以将子分支变基到主线
   4. 变基（覆盖）完成后可以继续使用子分支进行修改整合
2. 注意云端仓库，没有修改的文件是不会反复上传的
   1. 所以看距离时间最近的基本都是被修改过的
   2. 可以用来进行版本对比

4. 外键创建

1. 外键必须要来自同一个基类，不然会报错
   1. 新增主程序的databases.py文件，统一基类

5. 外键报错

1. 在新建字段时，依赖主表的外键必须要已经建立，不然在提交时都会报错
2. 所以新增接口的报错逻辑需要特别优化，将各个阶段可能报错的内容都捕获下来

hermes agent协作内容：

1. 测试数据脚本 — init_test_data.py/seed_data.py

直接正常运行主程序文件 main.py 即可插入

直接插入前提：

1. 保证数据库 student_manage_system 存在
2. 数据表字段对应
3. 建议直接删库建库 students\StudentsQuery.sql 里有相应需求的语句

向数据库插入了完整的测试数据，没有修改任何原有项目文件： 数据类型 数量 科目 6 门（Python程序设计、数据结构、数据库原理等） 教师 6 位（张伟、李芳、王强、陈静、刘洋、赵敏） 班级 3 个（CS2401、CS2402、AI2501） 学生 20 名（涵盖3个班级，男女各半） 成绩 120 条（每名学生6门课，含部分不及格记录） 公司 5 家（字节跳动、阿里巴巴、腾讯、华为、百度） 就业信息 8 条（含薪资、offer时间等）

2. 前端页面 - frontend/index.html - 双击运行

单文件完整前端，包含：

首页：问候 Banner + 快捷卡片（查课表/查成绩/校园卡/报修）+ 校园动态信息流 学生管理：表格列表、搜索过滤、新增/编辑/删除（含二次确认弹窗） 成绩查询：学期切换 Tab、成绩卡片展示、Chart.js 柱状图 教师管理：教师列表、搜索、新增 就业管理：就业信息列表、状态标签（已就业/待就业） 个人中心：蓝色背景头像区 + 功能菜单列表

交互特性： ✅ 卡片点击缩放反馈（95% 回弹，150ms） ✅ 页面切换从右侧滑入（300ms） ✅ 删除二次确认弹窗 ✅ Toast 提示（成功/失败/信息） ✅ 鼠标悬停按钮/卡片颜色加深、阴影加深 ✅ 隔行变色表格 + 表头排序

启动后端后直接浏览器打开 frontend/index.html 即可使用。

移植

只动几个文件，都不需要改代码：

移动的文件：

seed_data.py → 新项目的根目录 init_test_data.py → 新项目的根目录 frontend/ → 新项目的根目录（整个文件夹）

要改的唯一参数： frontend/index.html

const API_BASE = 'http://localhost:59000'; 改成新项目实际运行的端口即可。

其他都不用动：

init_test_data.py 完全独立，连接的是 databases.py 里的 .env 配置，新项目只要 DB 信息对就能直接跑 frontend/index.html 纯静态页面，不依赖任何项目代码 如果新项目用了不同的端口（比如 8000），改那一行就行