Step 11：百问百答（FAQ / Knowledge Base）

2025-12-16 19:50:44 +08:00
parent 96f7e35713
commit a54d7faf19
68 changed files with 553 additions and 1 deletions
@@ -0,0 +1,104 @@
+import uuid
+
+from fastapi import APIRouter, Depends, HTTPException, status
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.core.deps import get_current_user, get_db_session
+from app.crud import audit as audit_crud
+from app.crud import faq_category as category_crud
+from app.crud import member as member_crud
+from app.schemas.faq import CategoryCreate, CategoryRead, CategoryUpdate
+
+router = APIRouter()
+
+
+def _check_permission_for_scope(study_id: uuid.UUID | None, current_user, member_role: str | None):
+    if study_id is None:
+        if current_user.role != "ADMIN":
+            raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="Only admin can manage global FAQ")
+    else:
+        if current_user.role != "ADMIN" and member_role != "PM":
+            raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="Insufficient permissions")
+
+
+@router.post(
+    "/",
+    response_model=CategoryRead,
+    status_code=status.HTTP_201_CREATED,
+)
+async def create_category(
+    payload: CategoryCreate,
+    db: AsyncSession = Depends(get_db_session),
+    current_user=Depends(get_current_user),
+) -> CategoryRead:
+    member_role = None
+    if payload.study_id:
+        member = await member_crud.get_member(db, payload.study_id, current_user.id)
+        if not member:
+            raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="Not a study member")
+        member_role = member.role_in_study
+    _check_permission_for_scope(payload.study_id, current_user, member_role)
+    category = await category_crud.create_category(db, payload)
+    await audit_crud.log_action(
+        db,
+        study_id=payload.study_id,
+        entity_type="faq_category",
+        entity_id=category.id,
+        action="CREATE_FAQ_CATEGORY",
+        detail=f"FAQ category {category.name} created",
+        operator_id=current_user.id,
+        operator_role=current_user.role,
+    )
+    return CategoryRead.model_validate(category)
+
+
+@router.get(
+    "/",
+    response_model=list[CategoryRead],
+)
+async def list_categories(
+    study_id: uuid.UUID | None = None,
+    include_global: bool = True,
+    is_active: bool | None = True,
+    db: AsyncSession = Depends(get_db_session),
+    current_user=Depends(get_current_user),
+) -> list[CategoryRead]:
+    if study_id:
+        member = await member_crud.get_member(db, study_id, current_user.id)
+        if not member and current_user.role != "ADMIN":
+            raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="Not a study member")
+    categories = await category_crud.list_categories(db, study_id, include_global=include_global, is_active=is_active)
+    return [CategoryRead.model_validate(c) for c in categories]
+
+
+@router.patch(
+    "/{category_id}",
+    response_model=CategoryRead,
+)
+async def update_category(
+    category_id: uuid.UUID,
+    payload: CategoryUpdate,
+    db: AsyncSession = Depends(get_db_session),
+    current_user=Depends(get_current_user),
+) -> CategoryRead:
+    category = await category_crud.get_category(db, category_id)
+    if not category:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Category not found")
+    member_role = None
+    if category.study_id:
+        from app.crud import member as member_crud
+        member = await member_crud.get_member(db, category.study_id, current_user.id)
+        member_role = member.role_in_study if member else None
+    _check_permission_for_scope(category.study_id, current_user, member_role)
+    updated = await category_crud.update_category(db, category, payload)
+    await audit_crud.log_action(
+        db,
+        study_id=category.study_id,
+        entity_type="faq_category",
+        entity_id=category_id,
+        action="UPDATE_FAQ_CATEGORY",
+        detail=f"FAQ category {category_id} updated",
+        operator_id=current_user.id,
+        operator_role=current_user.role,
+    )
+    return CategoryRead.model_validate(updated)
@@ -0,0 +1,182 @@
+import uuid
+
+from fastapi import APIRouter, Depends, HTTPException, status
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.core.deps import get_current_user, get_db_session
+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.faq import FaqCreate, FaqRead, FaqUpdate
+
+router = APIRouter()
+
+
+def _check_write_permission(study_id: uuid.UUID | None, current_user, member_role: str | None):
+    if study_id is None:
+        if current_user.role != "ADMIN":
+            raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="Only admin can manage global FAQ")
+    else:
+        if current_user.role != "ADMIN" and member_role != "PM":
+            raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="Insufficient permissions")
+
+
+@router.post(
+    "/",
+    response_model=FaqRead,
+    status_code=status.HTTP_201_CREATED,
+)
+async def create_faq(
+    payload: FaqCreate,
+    db: AsyncSession = Depends(get_db_session),
+    current_user=Depends(get_current_user),
+) -> FaqRead:
+    cat = await category_crud.get_category(db, payload.category_id)
+    if not cat:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Category not found")
+    if cat.study_id != payload.study_id:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="Category scope mismatch")
+    member_role = None
+    if payload.study_id:
+        member = await member_crud.get_member(db, payload.study_id, current_user.id)
+        member_role = member.role_in_study if member else None
+    _check_write_permission(payload.study_id, current_user, member_role)
+    try:
+        item = await faq_crud.create_item(db, payload, created_by=current_user.id)
+    except ValueError as exc:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(exc)) from exc
+    await audit_crud.log_action(
+        db,
+        study_id=payload.study_id,
+        entity_type="faq_item",
+        entity_id=item.id,
+        action="CREATE_FAQ_ITEM",
+        detail="FAQ created",
+        operator_id=current_user.id,
+        operator_role=current_user.role,
+    )
+    return FaqRead.model_validate(item)
+
+
+@router.get(
+    "/",
+    response_model=list[FaqRead],
+)
+async def list_faqs(
+    study_id: uuid.UUID | None = None,
+    category_id: uuid.UUID | None = None,
+    keyword: str | None = None,
+    is_active: bool | None = True,
+    study_scope: str | None = "project",
+    db: AsyncSession = Depends(get_db_session),
+    current_user=Depends(get_current_user),
+) -> list[FaqRead]:
+    membership_cache: dict[uuid.UUID, str | None] = {}
+
+    async def _get_member_role(sid: uuid.UUID) -> str | None:
+        if sid in membership_cache:
+            return membership_cache[sid]
+        member = await member_crud.get_member(db, sid, current_user.id)
+        role = member.role_in_study if member else None
+        membership_cache[sid] = role
+        return role
+
+    if study_id:
+        if current_user.role != "ADMIN":
+            role = await _get_member_role(study_id)
+            if not role:
+                raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="Not a study member")
+
+    if is_active is False and current_user.role != "ADMIN":
+        role = None
+        if study_id:
+            role = await _get_member_role(study_id)
+        if role != "PM":
+            raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="Insufficient permissions")
+
+    items = await faq_crud.list_items(
+        db,
+        study_id=study_id,
+        category_id=category_id,
+        keyword=keyword,
+        is_active=is_active,
+        study_scope=study_scope,
+    )
+
+    visible: list[FaqRead] = []
+    for it in items:
+        if it.study_id and current_user.role != "ADMIN":
+            role = await _get_member_role(it.study_id)
+            if not role:
+                continue
+        if not it.is_active and current_user.role != "ADMIN":
+            role = await _get_member_role(it.study_id) if it.study_id else None
+            if role != "PM":
+                continue
+        visible.append(FaqRead.model_validate(it))
+    return visible
+
+
+@router.get(
+    "/{item_id}",
+    response_model=FaqRead,
+)
+async def get_faq(
+    item_id: uuid.UUID,
+    db: AsyncSession = Depends(get_db_session),
+    current_user=Depends(get_current_user),
+) -> FaqRead:
+    item = await faq_crud.get_item(db, item_id)
+    if not item:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="FAQ not found")
+    if item.study_id and current_user.role != "ADMIN":
+        member = await member_crud.get_member(db, item.study_id, current_user.id)
+        if not member:
+            raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="Not a study member")
+    if not item.is_active and current_user.role not in {"ADMIN"}:
+        member_role = None
+        if item.study_id:
+            member = await member_crud.get_member(db, item.study_id, current_user.id)
+            member_role = member.role_in_study if member else None
+        if member_role != "PM":
+            raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="Inactive FAQ")
+    return FaqRead.model_validate(item)
+
+
+@router.patch(
+    "/{item_id}",
+    response_model=FaqRead,
+)
+async def update_faq(
+    item_id: uuid.UUID,
+    payload: FaqUpdate,
+    db: AsyncSession = Depends(get_db_session),
+    current_user=Depends(get_current_user),
+) -> FaqRead:
+    item = await faq_crud.get_item(db, item_id)
+    if not item:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="FAQ not found")
+    member_role = None
+    if item.study_id:
+        member = await member_crud.get_member(db, item.study_id, current_user.id)
+        member_role = member.role_in_study if member else None
+    _check_write_permission(item.study_id, current_user, member_role)
+    old_active = item.is_active
+    updated = await faq_crud.update_item(db, item, payload)
+    action = "UPDATE_FAQ_ITEM"
+    detail = "FAQ updated"
+    if payload.is_active is not None and payload.is_active != old_active:
+        action = "FAQ_STATUS_CHANGE"
+        detail = "FAQ disabled" if not payload.is_active else "FAQ enabled"
+    await audit_crud.log_action(
+        db,
+        study_id=item.study_id,
+        entity_type="faq_item",
+        entity_id=item_id,
+        action=action,
+        detail=detail,
+        operator_id=current_user.id,
+        operator_role=current_user.role,
+    )
+    return FaqRead.model_validate(updated)
@@ -1,6 +1,6 @@
 from fastapi import APIRouter

-from app.api.v1 import auth, users, studies, sites, members, comments, attachments, audit_logs, milestones, tasks, dashboard, subjects, visits, aes, issues, data_queries, verifications, imp_products, imp_batches, imp_inventory, imp_transactions, finance, finance_dashboard
+from app.api.v1 import auth, users, studies, sites, members, comments, attachments, audit_logs, milestones, tasks, dashboard, subjects, visits, aes, issues, data_queries, verifications, imp_products, imp_batches, imp_inventory, imp_transactions, finance, finance_dashboard, faq_categories, faqs

 api_router = APIRouter()
 api_router.include_router(auth.router, prefix="/auth", tags=["auth"])
@@ -26,3 +26,5 @@ api_router.include_router(imp_inventory.router, prefix="/studies/{study_id}/imp/
 api_router.include_router(imp_transactions.router, prefix="/studies/{study_id}/imp/transactions", tags=["imp-transactions"])
 api_router.include_router(finance.router, prefix="/studies/{study_id}/finance", tags=["finance"])
 api_router.include_router(finance_dashboard.router, prefix="/studies/{study_id}/finance", tags=["finance"])
+api_router.include_router(faq_categories.router, prefix="/faqs/categories", tags=["faq-categories"])
+api_router.include_router(faqs.router, prefix="/faqs/items", tags=["faqs"])