1/api/wl_advisor_api.py

# 顾问模块：独立接口，沿用原学生接口的依赖注入与返回方式。
# FastAPI路由层，定义顾问管理相关接口，接收前端请求，参数校验，调用DAO层完成数据库操作
from fastapi import APIRouter, Depends, HTTPException, Query
from sqlalchemy.orm import Session
# 数据库会话依赖函数
from database import get_db
# 导入Pydantic模型：新增、更新、返回响应模型
from scheme.wl_advisor_scheme import AdvisorCreate, AdvisorUpdate, AdvisorOut
# 导入DAO层，封装数据库增删改查逻辑
from dao import wl_advisor_dao

# 创建路由对象，统一前缀 /advisor，接口文档分组标签【顾问管理】
router = APIRouter(prefix="/advisor", tags=["顾问管理"])


def check_advisor_data(data):
    # 只取出前端实际传入的字段
    values = data.model_dump(exclude_unset=True)

    # 如果传入了顾问姓名，则校验姓名
    if "adv_name" in values:
        # 姓名为空或者全空格，抛出异常
        if data.adv_name is None or not data.adv_name.strip():
            raise HTTPException(422, "顾问姓名不能为空")
        # 去除姓名前后空格
        data.adv_name = data.adv_name.strip()
        # 限制姓名最大长度50字符
        if len(data.adv_name) > 50:
            raise HTTPException(422, "顾问姓名不能超过50个字符")

    # 性别不为空时，校验性别长度
    if data.adv_gender is not None and len(data.adv_gender) > 8:
        raise HTTPException(422, "性别不能超过8个字符")
    # 手机号不为空时，校验手机号长度
    if data.adv_phone is not None and len(data.adv_phone) > 20:
        raise HTTPException(422, "手机号不能超过20个字符")
    # 邮箱不为空时，校验邮箱长度
    if data.adv_email is not None and len(data.adv_email) > 64:
        raise HTTPException(422, "邮箱不能超过64个字符")
    # 地区不为空时，校验地区长度
    if data.adv_region is not None and len(data.adv_region) > 64:
        raise HTTPException(422, "区域不能超过64个字符")


@router.get("/list", response_model=list[AdvisorOut])
def list_advisors(
    adv_name: str = Query(None),       # 查询参数：顾问姓名，模糊搜索，非必传
    adv_phone: str = Query(None),      # 查询参数：顾问电话，模糊搜索，非必传
    adv_region: str = Query(None),      # 查询参数：所属地区，模糊搜索，非必传
    adv_gender: str = Query(None),     # 查询参数：性别，精确搜索，非必传
    page: int = Query(1),               # 查询参数：当前页码，默认第1页
    size: int = Query(10),             # 查询参数：每页条数，默认10条
    db: Session = Depends(get_db),      # 依赖注入，自动获取数据库会话
):
    # 校验分页参数合法性
    if page < 1 or size < 1 or size > 100:
        raise HTTPException(422, "页码从1开始，每页条数为1到100")
    # 调用DAO层查询顾问列表，返回ORM对象列表
    return wl_advisor_dao.search_advisors(
        db, adv_name=adv_name, adv_phone=adv_phone,
        adv_region=adv_region, adv_gender=adv_gender, page=page, size=size,
    )


@router.post("/add", response_model=AdvisorOut)
def create_advisor(data: AdvisorCreate, db: Session = Depends(get_db)):

    # 执行字段校验
    check_advisor_data(data)
    # 调用DAO层新增顾问
    return wl_advisor_dao.create_advisor(db, data)


@router.get("/{adv_id}", response_model=AdvisorOut)
def get_advisor(adv_id: int, db: Session = Depends(get_db)):

    # 校验ID必须大于0
    if adv_id <= 0:
        raise HTTPException(422, "顾问编号必须大于0")
    # DAO查询顾问
    advisor = wl_advisor_dao.get_advisor_by_id(db, adv_id)
    # 查不到抛出404
    if not advisor:
        raise HTTPException(404, "顾问不存在")
    return advisor


@router.put("/{adv_id}", response_model=AdvisorOut)
def update_advisor(adv_id: int, data: AdvisorUpdate, db: Session = Depends(get_db)):

    # 校验ID合法性
    if adv_id <= 0:
        raise HTTPException(422, "顾问编号必须大于0")
    # 校验提交的数据
    check_advisor_data(data)
    # 调用DAO层执行更新
    advisor = wl_advisor_dao.update_advisor(db, adv_id, data)
    # 找不到顾问返回404
    if not advisor:
        raise HTTPException(404, "顾问不存在")
    return advisor


@router.delete("/{adv_id}")
def delete_advisor(adv_id: int, db: Session = Depends(get_db)):

    # 校验ID合法性
    if adv_id <= 0:
        raise HTTPException(422, "顾问编号必须大于0")
    # 调用DAO逻辑删除，返回布尔值
    deleted = wl_advisor_dao.delete_advisor(db, adv_id)
    # 顾问不存在则抛出404
    if not deleted:
        raise HTTPException(404, "顾问不存在")
    # 返回成功信息
    return {"msg": "删除成功"}