feat: 完善后端 API OpenAPI 文档与统一错误响应 schema

server/src/app/api/v1/endpoints/employees.py

@@ -6,6 +6,7 @@ from fastapi import APIRouter, Depends, HTTPException, Query, status
 from sqlalchemy.orm import Session
 
 from app.api.deps import get_db
+from app.schemas.common import ErrorResponse
 from app.schemas.employee import EmployeeCreate, EmployeeMetaRead, EmployeeRead, EmployeeUpdate
 from app.services.employee import EmployeeService
 
@@ -13,21 +14,49 @@ router = APIRouter()
 DbSession = Annotated[Session, Depends(get_db)]
 
 
-@router.get("/meta", response_model=EmployeeMetaRead)
+@router.get(
+    "/meta",
+    response_model=EmployeeMetaRead,
+    summary="读取员工目录元数据",
+    description="返回员工总数、状态汇总和可选角色列表，供员工管理页面初始化使用。",
+)
 def get_employee_meta(db: DbSession) -> EmployeeMetaRead:
     return EmployeeService(db).get_employee_meta()
 
 
-@router.get("", response_model=list[EmployeeRead])
+@router.get(
+    "",
+    response_model=list[EmployeeRead],
+    summary="查询员工列表",
+    description="按状态和关键字筛选员工目录。",
+)
 def list_employees(
     db: DbSession,
-    status_filter: Annotated[str | None, Query(alias="status")] = None,
-    keyword: str | None = None,
+    status_filter: Annotated[
+        str | None,
+        Query(alias="status", description="员工状态筛选值。"),
+    ] = None,
+    keyword: Annotated[
+        str | None,
+        Query(description="姓名、工号、邮箱等关键字模糊查询。"),
+    ] = None,
 ) -> list[EmployeeRead]:
     return EmployeeService(db).list_employees(status=status_filter, keyword=keyword)
 
 
-@router.post("", response_model=EmployeeRead, status_code=status.HTTP_201_CREATED)
+@router.post(
+    "",
+    response_model=EmployeeRead,
+    status_code=status.HTTP_201_CREATED,
+    summary="创建员工",
+    description="创建新的员工目录记录，并初始化基础角色与组织归属。",
+    responses={
+        status.HTTP_400_BAD_REQUEST: {
+            "model": ErrorResponse,
+            "description": "员工数据校验失败。",
+        }
+    },
+)
 def create_employee(payload: EmployeeCreate, db: DbSession) -> EmployeeRead:
     try:
         return EmployeeService(db).create_employee(payload)
@@ -35,7 +64,18 @@ def create_employee(payload: EmployeeCreate, db: DbSession) -> EmployeeRead:
         raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(exc)) from exc
 
 
-@router.get("/{employee_id}", response_model=EmployeeRead)
+@router.get(
+    "/{employee_id}",
+    response_model=EmployeeRead,
+    summary="读取员工详情",
+    description="根据员工主键读取员工完整档案信息。",
+    responses={
+        status.HTTP_404_NOT_FOUND: {
+            "model": ErrorResponse,
+            "description": "员工不存在。",
+        }
+    },
+)
 def get_employee(employee_id: str, db: DbSession) -> EmployeeRead:
     employee = EmployeeService(db).get_employee(employee_id)
     if employee is None:
@@ -43,7 +83,22 @@ def get_employee(employee_id: str, db: DbSession) -> EmployeeRead:
     return employee
 
 
-@router.patch("/{employee_id}", response_model=EmployeeRead)
+@router.patch(
+    "/{employee_id}",
+    response_model=EmployeeRead,
+    summary="更新员工",
+    description="更新员工基础信息、角色、密码等可维护字段。",
+    responses={
+        status.HTTP_400_BAD_REQUEST: {
+            "model": ErrorResponse,
+            "description": "请求字段不合法。",
+        },
+        status.HTTP_404_NOT_FOUND: {
+            "model": ErrorResponse,
+            "description": "员工不存在。",
+        },
+    },
+)
 def update_employee(employee_id: str, payload: EmployeeUpdate, db: DbSession) -> EmployeeRead:
     try:
         return EmployeeService(db).update_employee(employee_id, payload)
@@ -53,7 +108,18 @@ def update_employee(employee_id: str, payload: EmployeeUpdate, db: DbSession) ->
         raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(exc)) from exc
 
 
-@router.post("/{employee_id}/disable", response_model=EmployeeRead)
+@router.post(
+    "/{employee_id}/disable",
+    response_model=EmployeeRead,
+    summary="停用员工",
+    description="将员工状态切换为停用，阻止其继续登录系统。",
+    responses={
+        status.HTTP_404_NOT_FOUND: {
+            "model": ErrorResponse,
+            "description": "员工不存在。",
+        }
+    },
+)
 def disable_employee(employee_id: str, db: DbSession) -> EmployeeRead:
     try:
         return EmployeeService(db).disable_employee(employee_id)