学生管理模块&就业模块

api/region_api.py

@@ -0,0 +1,106 @@
+# 导入类型提示 List，用于指定响应模型为列表
+from typing import List
+
+# 导入 FastAPI 的 APIRouter（路由）、Depends（依赖注入）、HTTPException（HTTP 异常）
+from fastapi import APIRouter, Depends, HTTPException
+
+# 从 dao.region_sql 导入数据库操作函数，并为添加、修改、删除起了别名，避免与路由函数重名
+from dao.region_sql import (
+    get_region_part,
+    add_region as dao_add_resp,
+    update_region as dao_update_resp,
+    delete_region as dao_delete_resp,
+)
+
+# 导入数据库会话依赖，用于每个请求获取独立的 Session
+from database import get_db
+
+# 导入 Pydantic 模型：地区响应体、地区添加请求体、通用操作响应体、地区修改请求体
+from schema.stu_info_region_schema import (
+    region_resp,
+    region_req,
+    region_add_resp,
+    region_update_req,
+)
+
+# 创建地区模块的路由实例
+region_api = APIRouter()
+
+
+# -------------------- 查询地区（支持按省份过滤） --------------------
+@region_api.get('/region', response_model=List[region_resp], summary='查询')
+def get_regions_part(province: str = None, gs=Depends(get_db)):
+    """
+    根据省份查询地区信息。
+    - province 为可选参数，不传则返回全部地区。
+    - 返回列表，每个元素符合 region_resp 模型。
+    """
+    try:
+        # 调用 dao 层查询函数，传入数据库会话和省份过滤条件
+        data = get_region_part(gs, province)
+        return data
+    except Exception as e:
+        # 捕获异常，返回 500 错误，详情为字符串化的异常信息
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+# -------------------- 添加地区 --------------------
+@region_api.post('/region', response_model=region_add_resp, summary='添加')
+def add_region(rreq: region_req, gs=Depends(get_db)):
+    """
+    新增一条地区记录。
+    - 请求体必须符合 region_req 模型。
+    - 返回统一的 region_add_resp（code + message）。
+    """
+    try:
+        # 将 Pydantic 模型转为字典，便于传给 dao 层
+        data = rreq.model_dump()
+        # 调用 dao 层添加函数（别名为 dao_add_resp）
+        dao_add_resp(gs, data)
+        return region_add_resp(code=200, message='数据已添加')
+    except Exception as e:
+        # 注意：此处状态码写成了 200，通常异常应返回 500。
+        # 建议改为 status_code=500。
+        raise HTTPException(status_code=200, detail=str(e))
+
+
+# -------------------- 修改地区 --------------------
+@region_api.put('/region', response_model=region_add_resp, summary='修改')
+def update_region(code: str, rreq: region_update_req, gs=Depends(get_db)):
+    """
+    根据地区编码更新地区信息。
+    - code 为查询参数，指定要修改的地区编码。
+    - 请求体为 region_update_req，字段均为可选，只更新传入的字段。
+    - 返回统一的 region_add_resp。
+    """
+    try:
+        # exclude_unset=True：只获取客户端显式传入的字段，未传的字段不参与更新
+        data = rreq.model_dump(exclude_unset=True)
+        # 调用 dao 层更新函数（别名为 dao_update_resp），传入编码和待更新数据
+        res = dao_update_resp(gs, code, data)
+        if not res:
+            # 没有更新任何行，说明编码不存在或数据未变化
+            raise HTTPException(status_code=500, detail='没有更新！')
+        # res 可能是 dao 返回的消息字符串，直接作为 message 返回
+        return region_add_resp(code=200, message=res)
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+# -------------------- 删除地区 --------------------
+@region_api.delete('/region', response_model=region_add_resp, summary='删除')
+def delete_region(code: str, gs=Depends(get_db)):
+    """
+    根据地区编码删除地区记录。
+    - code 为查询参数，指定要删除的地区编码。
+    - 返回统一的 region_add_resp。
+    """
+    try:
+        # 调用 dao 层删除函数（别名为 dao_delete_resp），传入编码
+        res = dao_delete_resp(gs, code)
+        if not res:
+            # 没有删除任何行，可能编码不存在
+            raise HTTPException(status_code=500, detail='没有删除')
+        return region_add_resp(code=200, message='删除成功')
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))