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

backend/app/api/v1/faqs.py

@@ -8,7 +8,9 @@ from app.crud import audit as audit_crud
 from app.crud import faq_category as category_crud
 from app.crud import faq_item as faq_crud
 from app.crud import member as member_crud
+from app.schemas.common import PaginatedResponse
 from app.schemas.faq import FaqCreate, FaqRead, FaqUpdate
+from app.utils.pagination import paginate
 
 router = APIRouter()
 
@@ -26,6 +28,8 @@ def _check_write_permission(study_id: uuid.UUID | None, current_user, member_rol
     "/",
     response_model=FaqRead,
     status_code=status.HTTP_201_CREATED,
+    summary="创建 FAQ",
+    description="创建全局或项目内 FAQ，项目 FAQ 需项目 PM/ADMIN 权限。",
 )
 async def create_faq(
     payload: FaqCreate,
@@ -61,7 +65,9 @@ async def create_faq(
 
 @router.get(
     "/",
-    response_model=list[FaqRead],
+    response_model=PaginatedResponse[FaqRead],
+    summary="FAQ 列表",
+    description="返回全局与项目 FAQ，可按关键词、分类过滤。",
 )
 async def list_faqs(
     study_id: uuid.UUID | None = None,
@@ -115,12 +121,14 @@ async def list_faqs(
             if role != "PM":
                 continue
         visible.append(FaqRead.model_validate(it))
-    return visible
+    return paginate(visible, total=len(visible))
 
 
 @router.get(
     "/{item_id}",
     response_model=FaqRead,
+    summary="FAQ 详情",
+    description="获取单条 FAQ，非 PM 不能查看停用 FAQ。",
 )
 async def get_faq(
     item_id: uuid.UUID,
@@ -147,6 +155,8 @@ async def get_faq(
 @router.patch(
     "/{item_id}",
     response_model=FaqRead,
+    summary="更新 FAQ",
+    description="更新 FAQ 内容或启停状态，项目内需 PM/ADMIN 权限。",
 )
 async def update_faq(
     item_id: uuid.UUID,