优化“知识库模块“--基本完善

backend/app/api/v1/faq_categories.py

@@ -6,6 +6,7 @@ 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 item_crud
 from app.crud import member as member_crud
 from app.schemas.common import PaginatedResponse
 from app.schemas.faq import CategoryCreate, CategoryRead, CategoryUpdate
@@ -35,6 +36,9 @@ async def create_category(
     db: AsyncSession = Depends(get_db_session),
     current_user=Depends(get_current_user),
 ) -> CategoryRead:
+    existing = await category_crud.get_category_by_name(db, payload.study_id, payload.name)
+    if existing:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="分类名称已存在")
     member_role = None
     if payload.study_id:
         member = await member_crud.get_member(db, payload.study_id, current_user.id)
@@ -93,15 +97,24 @@ async def update_category(
     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)
+    update_data = payload.model_dump(exclude_unset=True)
+    target_study_id = update_data.get("study_id", category.study_id)
+    target_name = update_data.get("name", category.name)
+    if "study_id" in update_data and update_data["study_id"] != category.study_id and current_user.role != "ADMIN":
+        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="Only admin can change category scope")
+    existing = await category_crud.get_category_by_name(db, target_study_id, target_name)
+    if existing and existing.id != category.id:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="分类名称已存在")
+    if target_study_id:
+        member = await member_crud.get_member(db, target_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)
+        if not member and current_user.role != "ADMIN":
+            raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="Not a study member")
+    _check_permission_for_scope(target_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,
+        study_id=updated.study_id,
         entity_type="faq_category",
         entity_id=category_id,
         action="UPDATE_FAQ_CATEGORY",
@@ -110,3 +123,36 @@ async def update_category(
         operator_role=current_user.role,
     )
     return CategoryRead.model_validate(updated)
+
+
+@router.delete(
+    "/{category_id}",
+    status_code=status.HTTP_204_NO_CONTENT,
+    summary="删除 FAQ 分类",
+    description="仅 ADMIN 可删除分类，分类下存在 FAQ 时不可删除。",
+)
+async def delete_category(
+    category_id: uuid.UUID,
+    db: AsyncSession = Depends(get_db_session),
+    current_user=Depends(get_current_user),
+) -> None:
+    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")
+    if current_user.role != "ADMIN":
+        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="Only admin can delete FAQ category")
+    item_count = await item_crud.count_items_by_category(db, category_id)
+    if item_count > 0:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="分类下存在 FAQ，无法删除")
+    await db.delete(category)
+    await db.commit()
+    await audit_crud.log_action(
+        db,
+        study_id=category.study_id,
+        entity_type="faq_category",
+        entity_id=category_id,
+        action="DELETE_FAQ_CATEGORY",
+        detail=f"FAQ category {category_id} deleted",
+        operator_id=current_user.id,
+        operator_role=current_user.role,
+    )

backend/app/api/v1/faqs.py

@@ -7,9 +7,19 @@ 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 faq_reply as reply_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.schemas.faq import (
+    FaqBestReplyUpdate,
+    FaqCreate,
+    FaqRead,
+    FaqReplyCreate,
+    FaqReplyQuote,
+    FaqReplyRead,
+    FaqStatusUpdate,
+    FaqUpdate,
+)
 from app.utils.pagination import paginate
 
 router = APIRouter()
@@ -24,6 +34,15 @@ def _check_write_permission(study_id: uuid.UUID | None, current_user, member_rol
             raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="Insufficient permissions")
 
 
+def _check_create_permission(study_id: uuid.UUID | None, current_user, is_member: bool):
+    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 not is_member:
+            raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="Not a study member")
+
+
 @router.post(
     "/",
     response_model=FaqRead,
@@ -42,14 +61,25 @@ async def create_faq(
     if cat.study_id != payload.study_id:
         raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="Category scope mismatch")
     member_role = None
+    is_member = False
     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)
+        is_member = member is not None
+    _check_create_permission(payload.study_id, current_user, is_member)
     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
+    if payload.answer:
+        await reply_crud.create_reply(
+            db,
+            faq_id=item.id,
+            study_id=item.study_id,
+            created_by=current_user.id,
+            reply_in=FaqReplyCreate(content=payload.answer),
+        )
+        await faq_crud.set_status(db, item.id, "PROCESSING")
     await audit_crud.log_action(
         db,
         study_id=payload.study_id,
@@ -73,7 +103,7 @@ 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,
+    is_active: bool | None = None,
     study_scope: str | None = "project",
     db: AsyncSession = Depends(get_db_session),
     current_user=Depends(get_current_user),
@@ -167,11 +197,12 @@ async def update_faq(
     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)
+    if item.created_by != current_user.id:
+        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"
@@ -190,3 +221,265 @@ async def update_faq(
         operator_role=current_user.role,
     )
     return FaqRead.model_validate(updated)
+
+
+@router.patch(
+    "/{item_id}/status",
+    response_model=FaqRead,
+    summary="更新 FAQ 状态",
+    description="提问者或项目 PM/ADMIN 可确认已解决。",
+)
+async def update_faq_status(
+    item_id: uuid.UUID,
+    payload: FaqStatusUpdate,
+    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 payload.status != "RESOLVED":
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="Only RESOLVED is allowed")
+    if item.created_by != current_user.id and current_user.role != "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="Insufficient permissions")
+    await faq_crud.set_status(db, item.id, "RESOLVED", resolved_by_confirm=True)
+    updated = await faq_crud.get_item(db, item_id)
+    return FaqRead.model_validate(updated)
+
+
+@router.patch(
+    "/{item_id}/best-reply",
+    response_model=FaqRead,
+    summary="设置最佳回复",
+    description="项目成员可设置最佳回复，全局仅 ADMIN。",
+)
+async def set_best_reply(
+    item_id: uuid.UUID,
+    payload: FaqBestReplyUpdate,
+    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")
+    is_member = False
+    if item.study_id:
+        member = await member_crud.get_member(db, item.study_id, current_user.id)
+        is_member = member is not None
+    _check_create_permission(item.study_id, current_user, is_member)
+    if payload.best_reply_id:
+        reply = await reply_crud.get_reply(db, payload.best_reply_id)
+        if not reply or reply.faq_id != item.id:
+            raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="Invalid reply")
+        if reply.is_deleted:
+            raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="Reply deleted")
+        await faq_crud.set_best_reply(db, item.id, reply.id)
+        await faq_crud.set_status(db, item.id, "RESOLVED", resolved_by_confirm=item.resolved_by_confirm)
+    else:
+        await faq_crud.set_best_reply(db, item.id, None)
+        if not item.resolved_by_confirm:
+            remaining = await reply_crud.count_active_replies(db, item.id)
+            await faq_crud.set_status(
+                db,
+                item.id,
+                "PROCESSING" if remaining > 0 else "PENDING",
+                resolved_by_confirm=False,
+            )
+    updated = await faq_crud.get_item(db, item_id)
+    return FaqRead.model_validate(updated)
+
+
+@router.get(
+    "/{item_id}/replies",
+    response_model=PaginatedResponse[FaqReplyRead],
+    summary="FAQ 回复列表",
+    description="获取 FAQ 的回复列表。",
+)
+async def list_replies(
+    item_id: uuid.UUID,
+    db: AsyncSession = Depends(get_db_session),
+    current_user=Depends(get_current_user),
+) -> list[FaqReplyRead]:
+    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")
+    replies = await reply_crud.list_replies(db, item_id)
+    reply_map = {r.id: r for r in replies}
+    result: list[FaqReplyRead] = []
+    for r in replies:
+        data = FaqReplyRead.model_validate(r)
+        if r.quote_reply_id and r.quote_reply_id in reply_map:
+            quote = reply_map[r.quote_reply_id]
+            if quote.is_deleted:
+                data.quote = FaqReplyQuote(
+                    id=quote.id,
+                    content="回复已删除",
+                    created_by=quote.created_by,
+                    created_at=quote.created_at,
+                )
+            else:
+                data.quote = FaqReplyQuote.model_validate(quote)
+        result.append(data)
+    return paginate(result, total=len(result))
+
+
+@router.post(
+    "/{item_id}/replies",
+    response_model=FaqReplyRead,
+    status_code=status.HTTP_201_CREATED,
+    summary="创建 FAQ 回复",
+    description="回复 FAQ，项目内成员可回复，全局仅 ADMIN。",
+)
+async def create_reply(
+    item_id: uuid.UUID,
+    payload: FaqReplyCreate,
+    db: AsyncSession = Depends(get_db_session),
+    current_user=Depends(get_current_user),
+) -> FaqReplyRead:
+    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 not payload.content.strip():
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="Reply content is required")
+    is_member = False
+    if item.study_id:
+        member = await member_crud.get_member(db, item.study_id, current_user.id)
+        is_member = member is not None
+    _check_create_permission(item.study_id, current_user, is_member)
+    quote = None
+    if payload.quote_reply_id:
+        quote = await reply_crud.get_reply(db, payload.quote_reply_id)
+        if not quote or quote.faq_id != item.id:
+            raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="Invalid quote reply")
+    reply = await reply_crud.create_reply(
+        db,
+        faq_id=item.id,
+        study_id=item.study_id,
+        created_by=current_user.id,
+        reply_in=payload,
+    )
+    if item.status != "RESOLVED":
+        await faq_crud.set_status(db, item.id, "PROCESSING")
+    await faq_crud.touch_item(db, item.id)
+    await audit_crud.log_action(
+        db,
+        study_id=item.study_id,
+        entity_type="faq_reply",
+        entity_id=reply.id,
+        action="CREATE_FAQ_REPLY",
+        detail="FAQ replied",
+        operator_id=current_user.id,
+        operator_role=current_user.role,
+    )
+    data = FaqReplyRead.model_validate(reply)
+    if quote:
+        if quote.is_deleted:
+            data.quote = FaqReplyQuote(
+                id=quote.id,
+                content="回复已删除",
+                created_by=quote.created_by,
+                created_at=quote.created_at,
+            )
+        else:
+            data.quote = FaqReplyQuote.model_validate(quote)
+    return data
+
+
+@router.delete(
+    "/{item_id}",
+    status_code=status.HTTP_204_NO_CONTENT,
+    summary="删除 FAQ",
+    description="删除 FAQ，项目内需 PM/ADMIN 权限，全局仅 ADMIN。",
+)
+async def delete_faq(
+    item_id: uuid.UUID,
+    db: AsyncSession = Depends(get_db_session),
+    current_user=Depends(get_current_user),
+) -> None:
+    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.created_by != current_user.id:
+        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)
+    await reply_crud.delete_replies_by_faq_id(db, item.id)
+    await db.delete(item)
+    await db.commit()
+    await audit_crud.log_action(
+        db,
+        study_id=item.study_id,
+        entity_type="faq_item",
+        entity_id=item_id,
+        action="DELETE_FAQ_ITEM",
+        detail="FAQ deleted",
+        operator_id=current_user.id,
+        operator_role=current_user.role,
+    )
+
+
+@router.delete(
+    "/{item_id}/replies/{reply_id}",
+    status_code=status.HTTP_204_NO_CONTENT,
+    summary="删除 FAQ 回复",
+    description="删除 FAQ 回复，管理员、项目 PM 或回复者可删除。",
+)
+async def delete_reply(
+    item_id: uuid.UUID,
+    reply_id: uuid.UUID,
+    db: AsyncSession = Depends(get_db_session),
+    current_user=Depends(get_current_user),
+) -> None:
+    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")
+    reply = await reply_crud.get_reply(db, reply_id)
+    if not reply or reply.faq_id != item.id:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Reply not found")
+    if reply.created_by != current_user.id and current_user.role != "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="Insufficient permissions")
+    if item.best_reply_id == reply.id:
+        await faq_crud.set_best_reply(db, item.id, None)
+    ref_count = await reply_crud.count_quote_references(db, reply.id)
+    if ref_count > 0:
+        await reply_crud.soft_delete_reply(db, reply)
+    else:
+        await reply_crud.delete_reply(db, reply)
+    if not item.resolved_by_confirm:
+        if item.best_reply_id and item.best_reply_id != reply.id:
+            await faq_crud.set_status(db, item.id, "RESOLVED", resolved_by_confirm=False)
+        else:
+            remaining = await reply_crud.count_active_replies(db, item.id)
+            await faq_crud.set_status(
+                db,
+                item.id,
+                "PROCESSING" if remaining > 0 else "PENDING",
+                resolved_by_confirm=False,
+            )
+    await faq_crud.touch_item(db, item.id)
+    await audit_crud.log_action(
+        db,
+        study_id=item.study_id,
+        entity_type="faq_reply",
+        entity_id=reply_id,
+        action="DELETE_FAQ_REPLY",
+        detail="FAQ reply deleted",
+        operator_id=current_user.id,
+        operator_role=current_user.role,
+    )

backend/app/crud/faq_category.py

@@ -45,6 +45,20 @@ async def get_category(db: AsyncSession, category_id: uuid.UUID) -> FaqCategory
     return result.scalar_one_or_none()
 
 
+async def get_category_by_name(
+    db: AsyncSession,
+    study_id: uuid.UUID | None,
+    name: str,
+) -> FaqCategory | None:
+    stmt = select(FaqCategory).where(FaqCategory.name == name)
+    if study_id is None:
+        stmt = stmt.where(FaqCategory.study_id.is_(None))
+    else:
+        stmt = stmt.where(FaqCategory.study_id == study_id)
+    result = await db.execute(stmt)
+    return result.scalar_one_or_none()
+
+
 async def update_category(db: AsyncSession, category: FaqCategory, category_in: CategoryUpdate) -> FaqCategory:
     update_data = category_in.model_dump(exclude_unset=True)
     if update_data:

backend/app/crud/faq_item.py

@@ -1,7 +1,7 @@
 import uuid
 from typing import Sequence
 
-from sqlalchemy import or_, select, update as sa_update
+from sqlalchemy import func, or_, select, update as sa_update
 from sqlalchemy.ext.asyncio import AsyncSession
 
 from app.models.faq_category import FaqCategory
@@ -23,8 +23,8 @@ async def create_item(db: AsyncSession, item_in: FaqCreate, *, created_by: uuid.
         study_id=item_in.study_id,
         category_id=item_in.category_id,
         question=item_in.question,
-        answer=item_in.answer,
-        keywords=item_in.keywords,
+        answer=item_in.answer or "",
+        status="PENDING",
         version=1,
         is_active=True,
         created_by=created_by,
@@ -56,7 +56,7 @@ async def list_items(
     elif study_scope == "global":
         stmt = stmt.where(FaqItem.study_id.is_(None))
     else:  # project (default)
-        stmt = stmt.where((FaqItem.study_id == study_id) | (FaqItem.study_id.is_(None)))
+        stmt = stmt.where(FaqItem.study_id == study_id)
 
     if category_id:
         stmt = stmt.where(FaqItem.category_id == category_id)
@@ -88,3 +88,38 @@ async def update_item(db: AsyncSession, item: FaqItem, item_in: FaqUpdate) -> Fa
         await db.commit()
     await db.refresh(item)
     return item
+
+
+async def touch_item(db: AsyncSession, item_id: uuid.UUID) -> None:
+    await db.execute(
+        sa_update(FaqItem)
+        .where(FaqItem.id == item_id)
+        .values(updated_at=func.now())
+    )
+    await db.commit()
+
+
+async def set_best_reply(db: AsyncSession, item_id: uuid.UUID, reply_id: uuid.UUID | None) -> None:
+    await db.execute(
+        sa_update(FaqItem)
+        .where(FaqItem.id == item_id)
+        .values(best_reply_id=reply_id, updated_at=func.now())
+    )
+    await db.commit()
+
+
+async def set_status(db: AsyncSession, item_id: uuid.UUID, status: str, resolved_by_confirm: bool | None = None) -> None:
+    values: dict[str, object] = {"status": status, "updated_at": func.now()}
+    if resolved_by_confirm is not None:
+        values["resolved_by_confirm"] = resolved_by_confirm
+    await db.execute(
+        sa_update(FaqItem)
+        .where(FaqItem.id == item_id)
+        .values(**values)
+    )
+    await db.commit()
+
+
+async def count_items_by_category(db: AsyncSession, category_id: uuid.UUID) -> int:
+    result = await db.execute(select(func.count()).select_from(FaqItem).where(FaqItem.category_id == category_id))
+    return int(result.scalar_one())

backend/app/crud/faq_reply.py

@@ -0,0 +1,78 @@
+import uuid
+from typing import Sequence
+
+from sqlalchemy import delete as sa_delete, func, select, update as sa_update
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.models.faq_reply import FaqReply
+from app.schemas.faq import FaqReplyCreate
+
+
+async def create_reply(
+    db: AsyncSession,
+    *,
+    faq_id: uuid.UUID,
+    study_id: uuid.UUID | None,
+    created_by: uuid.UUID,
+    reply_in: FaqReplyCreate,
+) -> FaqReply:
+    reply = FaqReply(
+        faq_id=faq_id,
+        study_id=study_id,
+        content=reply_in.content,
+        created_by=created_by,
+        quote_reply_id=reply_in.quote_reply_id,
+    )
+    db.add(reply)
+    await db.commit()
+    await db.refresh(reply)
+    return reply
+
+
+async def list_replies(db: AsyncSession, faq_id: uuid.UUID) -> Sequence[FaqReply]:
+    result = await db.execute(
+        select(FaqReply).where(FaqReply.faq_id == faq_id).order_by(FaqReply.created_at)
+    )
+    return result.scalars().all()
+
+
+async def get_reply(db: AsyncSession, reply_id: uuid.UUID) -> FaqReply | None:
+    result = await db.execute(select(FaqReply).where(FaqReply.id == reply_id))
+    return result.scalar_one_or_none()
+
+
+async def delete_reply(db: AsyncSession, reply: FaqReply) -> None:
+    await db.delete(reply)
+    await db.commit()
+
+
+async def soft_delete_reply(db: AsyncSession, reply: FaqReply) -> None:
+    reply.is_deleted = True
+    reply.content = ""
+    await db.commit()
+
+
+async def count_quote_references(db: AsyncSession, reply_id: uuid.UUID) -> int:
+    result = await db.execute(
+        select(func.count()).select_from(FaqReply).where(FaqReply.quote_reply_id == reply_id)
+    )
+    return int(result.scalar_one())
+
+
+async def count_active_replies(db: AsyncSession, faq_id: uuid.UUID) -> int:
+    result = await db.execute(
+        select(func.count())
+        .select_from(FaqReply)
+        .where(FaqReply.faq_id == faq_id, FaqReply.is_deleted.is_(False))
+    )
+    return int(result.scalar_one())
+
+
+async def delete_replies_by_faq_id(db: AsyncSession, faq_id: uuid.UUID) -> None:
+    await db.execute(
+        sa_update(FaqReply)
+        .where(FaqReply.faq_id == faq_id)
+        .values(quote_reply_id=None)
+    )
+    await db.execute(sa_delete(FaqReply).where(FaqReply.faq_id == faq_id))
+    await db.commit()

backend/app/db/base.py

@@ -22,3 +22,4 @@ from app.models.imp_transaction import ImpTransaction  # noqa: F401
 from app.models.finance import FinanceItem  # noqa: F401
 from app.models.faq_category import FaqCategory  # noqa: F401
 from app.models.faq_item import FaqItem  # noqa: F401
+from app.models.faq_reply import FaqReply  # noqa: F401

backend/app/models/faq_item.py

@@ -14,6 +14,11 @@ class FaqItem(Base):
     id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
     study_id: Mapped[uuid.UUID | None] = mapped_column(UUID(as_uuid=True), ForeignKey("studies.id"), nullable=True, index=True)
     category_id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), ForeignKey("faq_categories.id"), index=True, nullable=False)
+    best_reply_id: Mapped[uuid.UUID | None] = mapped_column(
+        UUID(as_uuid=True), ForeignKey("faq_replies.id", ondelete="SET NULL"), nullable=True
+    )
+    status: Mapped[str] = mapped_column(String(20), nullable=False, default="PENDING")
+    resolved_by_confirm: Mapped[bool] = mapped_column(Boolean, nullable=False, default=False)
     question: Mapped[str] = mapped_column(Text, nullable=False)
     answer: Mapped[str] = mapped_column(Text, nullable=False)
     keywords: Mapped[str | None] = mapped_column(String(255), nullable=True)

backend/app/models/faq_reply.py

@@ -0,0 +1,23 @@
+import uuid
+from datetime import datetime
+
+from sqlalchemy import Boolean, DateTime, ForeignKey, Text, func
+from sqlalchemy.dialects.postgresql import UUID
+from sqlalchemy.orm import Mapped, mapped_column
+
+from app.db.base_class import Base
+
+
+class FaqReply(Base):
+    __tablename__ = "faq_replies"
+
+    id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    faq_id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), ForeignKey("faq_items.id"), index=True, nullable=False)
+    study_id: Mapped[uuid.UUID | None] = mapped_column(UUID(as_uuid=True), ForeignKey("studies.id"), index=True, nullable=True)
+    content: Mapped[str] = mapped_column(Text, nullable=False)
+    created_by: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), ForeignKey("users.id"), nullable=False)
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False, server_default=func.now())
+    quote_reply_id: Mapped[uuid.UUID | None] = mapped_column(
+        UUID(as_uuid=True), ForeignKey("faq_replies.id"), nullable=True
+    )
+    is_deleted: Mapped[bool] = mapped_column(Boolean, nullable=False, server_default="false")

backend/app/schemas/faq.py

@@ -1,6 +1,6 @@
 import uuid
 from datetime import datetime
-from typing import Optional
+from typing import Literal, Optional
 
 from pydantic import BaseModel, ConfigDict
 
@@ -14,6 +14,7 @@ class CategoryCreate(BaseModel):
 
 
 class CategoryUpdate(BaseModel):
+    study_id: Optional[uuid.UUID] = None
     name: Optional[str] = None
     description: Optional[str] = None
     sort_order: Optional[int] = None
@@ -37,21 +38,58 @@ class FaqCreate(BaseModel):
     study_id: Optional[uuid.UUID] = None
     category_id: uuid.UUID
     question: str
-    answer: str
-    keywords: Optional[str] = None
+    answer: Optional[str] = None
 
 
 class FaqUpdate(BaseModel):
     question: Optional[str] = None
     answer: Optional[str] = None
-    keywords: Optional[str] = None
     is_active: Optional[bool] = None
 
 
+class FaqStatusUpdate(BaseModel):
+    status: Literal["PENDING", "PROCESSING", "RESOLVED"]
+
+
+class FaqBestReplyUpdate(BaseModel):
+    best_reply_id: Optional[uuid.UUID] = None
+
+
+class FaqReplyCreate(BaseModel):
+    content: str
+    quote_reply_id: Optional[uuid.UUID] = None
+
+
+class FaqReplyQuote(BaseModel):
+    id: uuid.UUID
+    content: str
+    created_by: uuid.UUID
+    created_at: datetime
+
+    model_config = ConfigDict(from_attributes=True)
+
+
+class FaqReplyRead(BaseModel):
+    id: uuid.UUID
+    faq_id: uuid.UUID
+    study_id: Optional[uuid.UUID]
+    content: str
+    created_by: uuid.UUID
+    created_at: datetime
+    quote_reply_id: Optional[uuid.UUID] = None
+    quote: Optional[FaqReplyQuote] = None
+    is_deleted: bool = False
+
+    model_config = ConfigDict(from_attributes=True)
+
+
 class FaqRead(BaseModel):
     id: uuid.UUID
     study_id: Optional[uuid.UUID]
     category_id: uuid.UUID
+    best_reply_id: Optional[uuid.UUID] = None
+    status: Literal["PENDING", "PROCESSING", "RESOLVED"] = "PENDING"
+    resolved_by_confirm: bool = False
     question: str
     answer: str
     keywords: Optional[str]