diff --git a/stu_jiuye/就业模块文档11.md b/stu_jiuye/就业模块文档11.md new file mode 100644 index 0000000..2054956 --- /dev/null +++ b/stu_jiuye/就业模块文档11.md @@ -0,0 +1,270 @@ +# 学生就业信息管理系统 —— 就业模块项目文档 + +## 一、模块概述 + +本模块是「学生就业信息管理系统」的核心业务模块,负责管理学生就业状态的全生命周期。围绕就业信息(Employments)、公司信息(Company)、地址信息(Address)三张核心表,并与学生表(students)、班级表(classes)建立外键关联,提供增删改查(CRUD)与统计分析接口。 + +**技术栈:** + +| 项 | 选型 | +|---|---| +| Web 框架 | FastAPI | +| ORM | SQLAlchemy 2.x | +| 数据库 | MySQL 8.x(驱动 PyMySQL) | +| 数据校验 | Pydantic v2 | +| 服务启动 | Uvicorn | + +## 二、目录结构 + +``` +student_manage_system/ +├── main.py # 程序入口:注册全模块路由、建表(__main__ 中执行) +├── databases.py # 根数据库配置:engine_all / Base_all / Session / get_db +└── stu_jiuye/ # 就业模块业务包 + ├── main.py # 路由组装(Shtudent_Jiuye);独立自测 app + ├── database.py # 模块级数据库配置(engine / Base / Session / get_db) + ├── model.py # ORM 模型:Employments / Company / Address + ├── request.py # Pydantic 请求体 / 响应体模型 + ├── dao.py # 数据访问层(纯数据库操作) + └── CURD_api.py # 路由层(API 接口定义) +``` + +**分层职责:** + +| 层 | 文件 | 职责 | +|---|---|---| +| 路由层 | CURD_api.py | 接收 HTTP 请求,参数校验,调用 DAO,返回响应 | +| 数据访问层 | dao.py | 封装 SQLAlchemy 查询与事务,向上提供函数 | +| 模型层 | model.py | 定义表结构与外键关系 | +| 校验层 | request.py | 定义请求体 / 响应体的字段与类型 | +| 配置层 | database.py | 数据库 URL、引擎、Session 工厂 | + +## 三、数据表设计 + +### 1. Employments(就业信息表) + +| 字段 | 类型 | 约束 | 说明 | +|---|---|---|---| +| id | Integer | PK, 自增 | 主键 | +| stuid | Integer | FK → students.id | 学生 ID | +| class_id | Integer | FK → classes.id | 班级 ID | +| company_id | Integer | FK → Company.id, 可空 | 就业公司 | +| address_id | Integer | FK → Address.id, NOT NULL | 就业地址 | +| employment_salary | Integer | 可空 | 就业薪资 | +| employment_open_time | DATE | 可空 | 就业开放时间 | +| offer_recived_time | DATE | 可空 | Offer 下发时间 | +| create_time | DateTime | default=now | 创建时间 | +| update_time | DateTime | default=now, onupdate=now | 更新时间 | +| is_deleted | Integer | default=0 | 软删除标记(0 正常 / 1 已删) | + +### 2. Company(公司表) + +| 字段 | 类型 | 约束 | 说明 | +|---|---|---|---| +| id | Integer | PK, 自增 | 主键 | +| employment_company | String(50) | NOT NULL | 公司名称 | +| create_time | DateTime | default=now | 创建时间 | +| update_time | DateTime | default=now, onupdate=now | 更新时间 | +| is_deleted | Integer | default=0 | 软删除标记 | + +### 3. Address(地址表) + +| 字段 | 类型 | 约束 | 说明 | +|---|---|---|---| +| id | Integer | PK, 自增 | 主键 | +| somewhere | String(50) | NOT NULL | 地址区域,如"深圳市南山区" | +| create_time | DateTime | default=now | 创建时间 | +| update_time | DateTime | default=now, onupdate=now | 更新时间 | +| is_deleted | Integer | default=0 | 软删除标记 | + +### 表关系图 + +``` +students (1) ───< (N) Employments (N) >─── (1) Company +classes (1) ───< (N) | (N) >─── (1) Address +``` + +- 一个学生可有多个就业记录,一条就业记录对应一个学生(通过 stuid 关联学生表) +- 一条就业记录对应一个公司(company_id)与一个地址(address_id) +- 通过多表 JOIN 可从就业记录直接获取学生姓名、班级名称、公司名称与地址信息 + +**设计说明:姓名/班级不冗余,走 JOIN 获取** + +与"在就业表冗余学生姓名"的方案不同,本模块选择通过 `stuid`、`class_id` 外键关联学生表与班级表,查询时动态 JOIN 获取姓名与班级名。代价是查询多一次 JOIN;好处是学生姓名/班级变更后无需同步,数据天然一致。 + +## 四、API 功能清单(CRUD) + +接口定义于 `stu_jiuye/CURD_api.py` 的 `CURD` 路由,由根 `main.py` 以 `Shtudent_Jiuye` 挂载。 + +### 📌 新增(Create) + +| 方法 | 路径 | 功能 | 请求体 | +|---|---|---|---| +| POST | /emp/company/address | 新增地址区域 | AddRequest | +| POST | /emp/company | 新增公司 | CompRequest | +| POST | /emp | 新增学生就业信息 | PostRequest | + +> 注意:由于外键依赖,建议按 Address → Company → Employments 的顺序添加。 + +### 📌 查询(Read) + +| 方法 | 路径 | 功能 | 查询参数 | +|---|---|---|---| +| GET | /emp | 多条件查询就业信息 | sname、class_id、employment_company、min_salary、max_salary、somewhere、employment_open_start、employment_open_end、offer_recived_start、offer_recived_end(全部可选,均不传则查询全部) | + +> 就业薪资 Top5、就业时长、平均就业时长等统计接口已迁移至统计分析模块(StatCalc):`/statcalc/top`、`/statcalc/job`、`/statcalc/avgjob`。 + +### 📌 更新(Update) + +| 方法 | 路径 | 功能 | 参数 | +|---|---|---|---| +| PUT | /emp?id=X | 修改就业信息 | Query:id;Body:PostRequest(支持部分字段更新) | + +### 📌 删除(Delete) + +| 方法 | 路径 | 功能 | 参数 | +|---|---|---|---| +| DELETE | /emp/{id} | 软删除就业信息 | Path:id | + +**删除说明**:本模块采用软删除(`is_deleted = 1`),数据不会从物理表中移除,便于审计与恢复。 + +## 五、核心流程示例 + +### 查询流程(GET /emp) + +``` +前端 → CURD_api.get_stuinfo() + ↓ 收集 10 个可选查询条件 + ↓ 调用 get_emp_dao() + ↓ DAO 五表 OUTER JOIN:Employments + Students + ClassInfo + Company + Address + ↓ 动态拼接 filter(姓名/班级/公司/薪资范围/地址/时间范围) + ↓ 统一过滤 is_deleted = 0 + ↓ 返回 list[dict](含学生姓名、班级名称、公司、区域、薪资、时间) + ↓ 结果为空 → 404「名单不存在」 +``` + +### 添加流程(POST /emp) + +``` +前端 → CURD_api.add_stuinfo() + ↓ p.model_dump() 转 dict + ↓ add_employment_dao() + ↓ o.pop('id' / 'create_time' / 'update_time' / 'is_deleted') 去掉自增主键与自动字段 + ↓ Employments(**o) 实例化 + ↓ db.add → db.commit → db.refresh + ↓ 失败 → db.rollback → 返回 500 +``` + +### 更新流程(PUT /emp?id=X) + +``` +前端 → CURD_api.updata_stuinfo() + ↓ 请求体排除未传字段(exclude_unset) + ↓ 为空 → 400「没有需要更新的字段」 + ↓ update_emp_dao() 按 id 执行 update + ↓ 影响 0 行 → 404「未找到对应记录」 +``` + +### 删除流程(DELETE /emp/{id}) + +``` +前端 → CURD_api.delete_stuinfo() + ↓ delete_emp_dao() 按 id 执行 UPDATE is_deleted = 1(软删除) + ↓ 影响 0 行 → 500「没有删除」 +``` + +## 六、项目亮点 + +1. **清晰的分层架构** + 路由(CURD_api.py)、数据访问(dao.py)、模型(model.py)、校验(request.py)各司其职,便于单元测试与维护。 + +2. **全链路软删除** + Employments、Company、Address 三张表均有 `is_deleted` 字段,删除统一走 `UPDATE is_deleted = 1`,数据可追溯、可恢复;查询时统一过滤 `is_deleted == 0`。 + +3. **动态多条件组合查询** + `get_emp_dao` 使用链式 filter 动态拼接查询条件,任一条件为空自动跳过,一个接口覆盖 10 种查询维度(姓名/班级/公司/薪资区间/地址/开放时间区间/Offer 时间区间)。 + +4. **统一时间戳审计** + 所有表均带 `create_time` / `update_time`,`onupdate=datetime.now` 让修改自动记录时间,为审计、报表提供数据基础。 + +5. **请求体与响应体分离** + request.py 为每类资源定义独立请求体(PostRequest / CompRequest / AddRequest)与响应体(EmpResponse / CompResponse / AddResponse),前端契约清晰,Swagger 自动生成接口文档。 + +6. **多表 JOIN 关联查询** + 就业记录与学生、班级、公司、地址四张表通过外键关联,一次查询即可返回完整就业信息,无需前端二次请求。 + +7. **外键约束保证数据完整性** + stuid / class_id / company_id / address_id 全部建立外键,杜绝"就业记录指向不存在学生/公司"的脏数据。 + +## 七、待添加的新功能 与 已知问题 + +### 🎯 短期(可快速落地) + +| 功能 | 说明 | 涉及改动 | +|---|---|---| +| 分页查询 | /emp 支持 page / page_size,返回 total 与 items | dao.py 加 .offset().limit(),request.py 加分页请求体 | +| 薪资区间校验 | 确保 min_salary <= max_salary | request.py 加 @model_validator | +| 数据去重 | 同一学生同一公司只保留一条有效就业记录 | add_employment_dao 前置查询 + 唯一约束 | +| 级联删除 | 删公司/地址时同步软删其下就业记录 | dao.py 加级联更新逻辑 | +| 外键存在性校验 | 新增时校验 stuid / company_id / address_id 真实存在,给出明确错误 | dao.py 前置查询 | + +### 🚀 中期(需要设计) + +| 功能 | 说明 | +|---|---| +| 批量导入 | 支持 Excel/CSV 批量导入就业信息 | +| 数据导出 | 查询结果一键导出为 Excel | +| JWT 鉴权 | 管理员 / 普通用户角色分离,保护写接口 | +| 操作日志 | 记录每一次增删改操作的操作人与时间 | +| Alembic 迁移 | 用 Alembic 管理表结构变更,告别手动 DROP TABLE | + +### 🌟 长期(数据价值) + +| 功能 | 说明 | +|---|---| +| 就业数据看板 | 按班级/公司/薪资维度统计,前端可视化 | +| 薪资分布分析 | 直方图、分位数、同比环比 | +| 就业率追踪 | 结合学生表计算班级/专业就业率 | +| 缓存层 | Redis 缓存 Top5、统计类接口 | +| 异步任务 | Celery 处理导入/导出等耗时任务 | + +### + +| | | | | +|---|---|---|---| +| | | | | +| | | | | +| | | | | +| | | | | +| | | | | +| | | | | +| | | | | + +## 八、运行方式 + +```bash +# 1. 安装依赖 +pip install fastapi uvicorn sqlalchemy pymysql pydantic python-dotenv + +# 2. 配置数据库(项目根目录 .env 中 DB_USER / DB_PASSWORD / DB_HOST / DB_PORT / DB_NAME) + +# 3. 启动服务(根入口,含全模块) +python main.py +# 或 +uvicorn main:app --host 127.0.0.1 --port 59000 --reload + +# 4. 单独调试就业模块 +uvicorn stu_jiuye.main:app --host 127.0.0.1 --port 12395 --reload + +# 5. 访问 Swagger 文档 +http://127.0.0.1:59000/docs +``` + +## 九、注意事项 + +1. **表结构变更需删表重建**:`Base.metadata.create_all(engine)` 只建不改,模型加字段后需 DROP TABLE 或引入 Alembic。 +2. **建表时机**:当前建表逻辑在根 `main.py` 的 `__main__` 块中执行;直接用 `uvicorn main:app` 启动时不会建表,全新环境需先执行一次 `python main.py`(或后续将建表移入 FastAPI lifespan)。 +3. **添加顺序有外键依赖**:先建学生/班级/公司/地址,再添加就业记录;Employments 的 stuid / class_id / company_id / address_id 均受外键约束。 +4. **软删除后查询自动过滤**:`get_emp_dao` 已统一过滤 `is_deleted == 0`,被删除的记录不会再出现在列表里。 +5. **删除接口用 Path 参数**:`DELETE /emp/{id}`,不要写成 `/emp?id=X`。 +6. **echo=True 仅限开发**:生产环境请关掉,避免刷屏与性能损耗。