Step 12：后端轻量优化（API 稳定性 & 前端友好）

backend/app/api/v1/users.py

@@ -4,21 +4,24 @@ from fastapi import APIRouter, Depends, HTTPException, status
 from sqlalchemy.ext.asyncio import AsyncSession
 
 from app.core.deps import get_db_session, require_roles
+from app.schemas.common import PaginatedResponse
 from app.crud import user as user_crud
+from app.utils.pagination import paginate
 from app.schemas.user import UserCreate, UserRead, UserUpdate
 
 router = APIRouter()
 
 
-@router.get("/", response_model=list[UserRead])
+@router.get("/", response_model=PaginatedResponse[UserRead], summary="用户列表", description="仅 ADMIN 可用，支持 skip/limit。")
 async def list_users(
     skip: int = 0,
     limit: int = 100,
     db: AsyncSession = Depends(get_db_session),
     current_user=Depends(require_roles(["ADMIN"])),
-) -> list[UserRead]:
+) -> PaginatedResponse[UserRead]:
     users = await user_crud.list_users(db, skip=skip, limit=limit)
-    return list(users)
+    total_users = await user_crud.list_users(db, skip=0, limit=10_000_000)
+    return paginate(list(users), total=len(total_users))
 
 
 @router.post("/", response_model=UserRead, status_code=status.HTTP_201_CREATED)