权限管理：接入项目级权限矩阵

新增项目级角色权限矩阵，覆盖 PM、CRA、PV、IMP、QA 等项目角色，并通过迁移表持久化各业务模块的读写权限。

后端将参与者、合同费用、物资、启动、里程碑、风险问题、监查稽查、FAQ、共享库、文件版本等接口接入矩阵校验，修复审计日志导出权限和登录 502 的依赖导入问题。

前端新增权限管理页面和项目路由权限映射，按矩阵控制导航显示、直接访问拦截、操作按钮启停，并限制管理后台仅 admin 和授权 PM 可进入。

补充后端权限归一化与接口静态测试、前端路由/权限工具/权限管理页面/工作台等回归测试。

backend/app/api/v1/faqs.py

@@ -4,6 +4,7 @@ from fastapi import APIRouter, Depends, HTTPException, status
 from sqlalchemy.ext.asyncio import AsyncSession
 
 from app.core.deps import get_current_user, get_db_session, require_study_not_locked
+from app.core.project_permissions import role_has_project_permission
 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
@@ -25,14 +26,28 @@ from app.utils.pagination import paginate
 router = APIRouter()
 
 
-def _check_write_permission(study_id: uuid.UUID, current_user, member_role: str | None):
-    if current_user.role != "ADMIN" and member_role != "PM":
-        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="权限不足")
+def _is_system_admin(current_user) -> bool:
+    role = current_user.role.value if hasattr(current_user.role, "value") else current_user.role
+    return role == "ADMIN"
 
 
-def _check_create_permission(current_user, is_member: bool):
-    if current_user.role != "ADMIN" and not is_member:
+async def _require_project_permission(
+    db: AsyncSession,
+    study_id: uuid.UUID | None,
+    current_user,
+    action: str,
+):
+    if not study_id:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="FAQ 不存在")
+    if _is_system_admin(current_user):
+        return None
+    member = await member_crud.get_member(db, study_id, current_user.id)
+    if not member or not member.is_active:
         raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="不是该项目成员")
+    allowed = await role_has_project_permission(db, study_id, member.role_in_study, "faq", action)
+    if not allowed:
+        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="权限不足")
+    return member
 
 
 @router.post(
@@ -40,7 +55,7 @@ def _check_create_permission(current_user, is_member: bool):
     response_model=FaqRead,
     status_code=status.HTTP_201_CREATED,
     summary="创建 FAQ",
-    description="创建全局或项目内 FAQ，项目 FAQ 需项目 PM/ADMIN 权限。",
+    description="创建项目内 FAQ，权限由项目级权限矩阵控制。",
     dependencies=[Depends(require_study_not_locked())],
 )
 async def create_faq(
@@ -55,12 +70,7 @@ async def create_faq(
         raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="分类不存在")
     if cat.study_id != payload.study_id:
         raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="分类范围不匹配")
-    member_role = None
-    is_member = False
-    member = await member_crud.get_member(db, payload.study_id, current_user.id)
-    member_role = member.role_in_study if member else None
-    is_member = member is not None
-    _check_create_permission(current_user, is_member)
+    await _require_project_permission(db, payload.study_id, current_user, "write")
     try:
         item = await faq_crud.create_item(db, payload, created_by=current_user.id)
     except ValueError as exc:
@@ -106,22 +116,14 @@ async def list_faqs(
     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
+        member = await _require_project_permission(db, sid, current_user, "read")
+        role = member.role_in_study if member else "ADMIN"
         membership_cache[sid] = role
         return role
 
     if not study_id:
         raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="必须提供项目 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="不是该项目成员")
-
-    if is_active is False and current_user.role != "ADMIN":
-        role = await _get_member_role(study_id)
-        if role != "PM":
-            raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="权限不足")
+    await _require_project_permission(db, study_id, current_user, "write" if is_active is False else "read")
 
     items = await faq_crud.list_items(
         db,
@@ -134,13 +136,13 @@ async def list_faqs(
 
     visible: list[FaqRead] = []
     for it in items:
-        if current_user.role != "ADMIN":
+        if not _is_system_admin(current_user):
             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 role != "PM":
+        if not it.is_active and not _is_system_admin(current_user):
+            allowed = await role_has_project_permission(db, it.study_id, role, "faq", "write")
+            if not allowed:
                 continue
         visible.append(FaqRead.model_validate(it))
     return paginate(visible, total=len(visible))
@@ -150,7 +152,7 @@ async def list_faqs(
     "/{item_id}",
     response_model=FaqRead,
     summary="FAQ 详情",
-    description="获取单条 FAQ，非 PM 不能查看停用 FAQ。",
+    description="获取单条 FAQ，停用 FAQ 需项目级写权限。",
 )
 async def get_faq(
     item_id: uuid.UUID,
@@ -162,15 +164,7 @@ async def get_faq(
         raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="FAQ 不存在")
     if not item.study_id:
         raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="FAQ 不存在")
-    if 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="不是该项目成员")
-    if not item.is_active and current_user.role not in {"ADMIN"}:
-        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="FAQ 已停用")
+    await _require_project_permission(db, item.study_id, current_user, "write" if not item.is_active else "read")
     return FaqRead.model_validate(item)
 
 
@@ -178,7 +172,7 @@ async def get_faq(
     "/{item_id}",
     response_model=FaqRead,
     summary="更新 FAQ",
-    description="更新 FAQ 内容或启停状态，项目内需 PM/ADMIN 权限。",
+    description="更新 FAQ 内容或启停状态，权限由项目级权限矩阵控制。",
     dependencies=[Depends(require_study_not_locked())],
 )
 async def update_faq(
@@ -191,11 +185,9 @@ async def update_faq(
     if not item:
         raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="FAQ 不存在")
     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 _require_project_permission(db, item.study_id, current_user, "write")
+    else:
+        await _require_project_permission(db, item.study_id, current_user, "write")
     old_active = item.is_active
     updated = await faq_crud.update_item(db, item, payload)
     action = "UPDATE_FAQ_ITEM"
@@ -220,7 +212,7 @@ async def update_faq(
     "/{item_id}/status",
     response_model=FaqRead,
     summary="更新 FAQ 状态",
-    description="提问者或项目 PM/ADMIN 可确认已解决。",
+    description="提问者或具备项目级写权限的成员可确认已解决。",
     dependencies=[Depends(require_study_not_locked())],
 )
 async def update_faq_status(
@@ -234,13 +226,10 @@ async def update_faq_status(
         raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="FAQ 不存在")
     if payload.status != "RESOLVED":
         raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="仅允许设置为已解决")
-    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="权限不足")
+    if item.created_by != current_user.id:
+        await _require_project_permission(db, item.study_id, current_user, "write")
+    else:
+        await _require_project_permission(db, item.study_id, current_user, "read")
     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)
@@ -264,10 +253,7 @@ async def set_best_reply(
         raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="FAQ 不存在")
     if not item.study_id:
         raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="FAQ 不存在")
-    is_member = False
-    member = await member_crud.get_member(db, item.study_id, current_user.id)
-    is_member = member is not None
-    _check_create_permission(current_user, is_member)
+    await _require_project_permission(db, item.study_id, current_user, "write")
     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:
@@ -304,10 +290,7 @@ async def list_replies(
     item = await faq_crud.get_item(db, item_id)
     if not item:
         raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="FAQ 不存在")
-    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="不是该项目成员")
+    await _require_project_permission(db, item.study_id, current_user, "read")
     replies = await reply_crud.list_replies(db, item_id)
     reply_map = {r.id: r for r in replies}
     result: list[FaqReplyRead] = []
@@ -349,10 +332,7 @@ async def create_reply(
         raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="FAQ 不存在")
     if not payload.content.strip():
         raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="回复内容不能为空")
-    is_member = False
-    member = await member_crud.get_member(db, item.study_id, current_user.id)
-    is_member = member is not None
-    _check_create_permission(current_user, is_member)
+    await _require_project_permission(db, item.study_id, current_user, "write")
     quote = None
     if payload.quote_reply_id:
         quote = await reply_crud.get_reply(db, payload.quote_reply_id)
@@ -396,7 +376,7 @@ async def create_reply(
     "/{item_id}",
     status_code=status.HTTP_204_NO_CONTENT,
     summary="删除 FAQ",
-    description="删除 FAQ，项目内需 PM/ADMIN 权限，全局仅 ADMIN。",
+    description="删除 FAQ，权限由项目级权限矩阵控制。",
     dependencies=[Depends(require_study_not_locked())],
 )
 async def delete_faq(
@@ -408,11 +388,9 @@ async def delete_faq(
     if not item:
         raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="FAQ 不存在")
     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 _require_project_permission(db, item.study_id, current_user, "write")
+    else:
+        await _require_project_permission(db, item.study_id, current_user, "write")
     await reply_crud.delete_replies_by_faq_id(db, item.id)
     await db.delete(item)
     await db.commit()
@@ -432,7 +410,7 @@ async def delete_faq(
     "/{item_id}/replies/{reply_id}",
     status_code=status.HTTP_204_NO_CONTENT,
     summary="删除 FAQ 回复",
-    description="删除 FAQ 回复，管理员、项目 PM 或回复者可删除。",
+    description="删除 FAQ 回复，回复者或具备项目级写权限的成员可删除。",
     dependencies=[Depends(require_study_not_locked())],
 )
 async def delete_reply(
@@ -447,13 +425,10 @@ async def delete_reply(
     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="回复不存在")
-    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="权限不足")
+    if reply.created_by != current_user.id:
+        await _require_project_permission(db, item.study_id, current_user, "write")
+    else:
+        await _require_project_permission(db, item.study_id, current_user, "read")
     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)