更新注释

2026-09-14 13:32:59 +08:00
parent c1862f5279
commit 53afb2897b
3 changed files with 194 additions and 90 deletions
@@ -1,57 +1,116 @@
+# 顾问模块：独立接口，沿用原学生接口的依赖注入与返回方式。
+# FastAPI路由层，定义顾问管理相关接口，接收前端请求，参数校验，调用DAO层完成数据库操作
 from fastapi import APIRouter, Depends, HTTPException, Query
 from sqlalchemy.orm import Session
-
-from dao import wl_advisor_dao
+# 数据库会话依赖函数
 from database import get_db
-from scheme.wl_advisor_scheme import AdvisorCreate, AdvisorOut, AdvisorUpdate
+# 导入Pydantic模型：新增、更新、返回响应模型
+from scheme.wl_advisor_scheme import AdvisorCreate, AdvisorUpdate, AdvisorOut
+# 导入DAO层，封装数据库增删改查逻辑
+from dao import wl_advisor_dao

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


-# 查询顾问列表（支持姓名/手机号/区域/性别模糊筛选 + 分页）
-# 注意：本路由必须写在 /{adv_id} 前面，否则 "/advisor/" 会被当成 adv_id 去解析
-@router.get("/", response_model=list[AdvisorOut])
-def query_list(
-    adv_name: str = Query(None),
-    adv_phone: str = Query(None),
-    adv_region: str = Query(None),
-    adv_gender: str = Query(None),
-    skip: int = 0,
-    limit: int = 100,
-    db: Session = Depends(get_db),
+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),      # 依赖注入，自动获取数据库会话
 ):
-    return wl_advisor_dao.list_advisors(
-        db, adv_name, adv_phone, adv_region, adv_gender, skip, limit
+    # 校验分页参数合法性
+    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("/", response_model=AdvisorOut, status_code=201)
-def add_advisor(body: AdvisorCreate, db: Session = Depends(get_db)):
-    return wl_advisor_dao.create_advisor(db, body)
+@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 query_one(adv_id: int, db: Session = Depends(get_db)):
+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(status_code=404, detail="顾问不存在")
+        raise HTTPException(404, "顾问不存在")
    return advisor


-# 修改顾问
@router.put("/{adv_id}", response_model=AdvisorOut)
-def edit_advisor(adv_id: int, body: AdvisorUpdate, db: Session = Depends(get_db)):
-    advisor = wl_advisor_dao.update_advisor(db, adv_id, body)
+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(status_code=404, detail="顾问不存在")
+        raise HTTPException(404, "顾问不存在")
    return advisor


-# 逻辑删除顾问
@router.delete("/{adv_id}")
-def remove_advisor(adv_id: int, db: Session = Depends(get_db)):
-    if not wl_advisor_dao.delete_advisor(db, adv_id):
-        raise HTTPException(status_code=404, detail="顾问不存在")
-    return {"code": 200, "msg": "删除成功"}
+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": "删除成功"}