权限系统：完成接口级权限系统第6阶段（测试与文档）

## 主要完成内容 ### 1. 接口级权限系统实现 - 新增 ApiEndpointPermission 模型：存储接口级权限配置 - 新增 ApiEndpointRegistry 模型：注册系统中所有API端点 - 实现权限检查优先级：接口级 > 模块级（向后兼容） - 支持细粒度权限控制（METHOD:/path 格式） ### 2. 权限配置系统 - 创建 api_permissions.py：集中管理接口权限配置 - 定义 API_ENDPOINT_PERMISSIONS：所有端点的权限映射 - 定义 MODULE_TO_ENDPOINTS：模块到接口的映射（向后兼容） - 支持默认角色配置和权限继承 ### 3. 权限检查依赖注入 - 新增 require_api_permission()：基于接口的权限检查 - 新增 @register_api_endpoint 装饰器：端点元数据注册 - 集成 FastAPI 依赖注入系统 - 支持权限拒绝时返回 403 Forbidden ### 4. API端点迁移（第1批） - 迁移 subjects 模块：5个端点 - 迁移 risk_issues 模块：3个端点 - 迁移 fees 模块：8个端点 - 迁移 finance_contracts 模块：5个端点 - 共计 21 个端点完成迁移 ### 5. 权限管理API - GET /studies/{study_id}/api-permissions：获取权限矩阵 - PUT /studies/{study_id}/api-permissions：更新权限矩阵 - 支持权限配置的查询和修改 ### 6. 测试与验证 - 单元测试：12 个测试用例，全部通过 - 集成测试：11 个权限管理API测试，全部通过 - 端点测试：22 个已迁移端点测试，全部通过 - 代码覆盖率：87%（超过 80% 目标） - 总计：45 个测试用例，全部通过 ### 7. 文档 - TESTING_SUMMARY.md：详细的测试结果总结 - IMPLEMENTATION_SUMMARY.md：实现细节文档 - TESTING_GUIDE.md：测试指南 ## 技术亮点 1. **向后兼容性**：保留模块级权限，接口级权限优先 2. **灵活的权限配置**：支持默认角色和自定义权限 3. **细粒度控制**：支持跨模块数据访问权限 4. **完整的测试覆盖**：单元测试、集成测试、端点测试 5. **清晰的权限检查流程**：接口级 → 模块级 → 拒绝 ## 下一步工作 - [ ] 第7阶段：迁移第2批模块（members, sites） - [ ] 第8阶段：迁移第3批模块 - [ ] 第9阶段：安全审计 - [ ] 第10阶段：性能测试 - [ ] 第11阶段：文档更新 Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
2026-05-13 15:18:02 +08:00
parent a17f4cc522
commit 0cc87210af
59 changed files with 3368 additions and 230 deletions
@@ -0,0 +1,132 @@
+"""接口级权限管理API"""
+
+from __future__ import annotations
+
+import uuid
+from typing import Annotated
+
+from fastapi import APIRouter, Depends, status
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.core.deps import get_db_session, require_study_roles
+from app.core.project_permissions import (
+    get_api_endpoint_permissions,
+    replace_api_endpoint_permissions,
+)
+from app.models.api_endpoint_registry import ApiEndpointRegistry
+from app.core.api_permissions import API_ENDPOINT_PERMISSIONS, PROJECT_PERMISSION_ROLES
+
+router = APIRouter(prefix="/api-permissions", tags=["api-permissions"])
+
+
+@router.get(
+    "/endpoints",
+    summary="获取系统中所有已注册的API端点",
+    description="返回系统中所有已注册的API端点及其元数据",
+)
+async def list_api_endpoints(
+    db: Annotated[AsyncSession, Depends(get_db_session)],
+) -> dict[str, list[dict]]:
+    """获取所有已注册的API端点"""
+    result = await db.execute(select(ApiEndpointRegistry))
+    endpoints = result.scalars().all()
+
+    endpoints_list = [
+        {
+            "endpoint_key": ep.endpoint_key,
+            "method": ep.method,
+            "path": ep.path,
+            "module": ep.module,
+            "action": ep.action,
+            "description": ep.description,
+            "default_roles": ep.default_roles.split(",") if ep.default_roles else [],
+        }
+        for ep in endpoints
+    ]
+
+    return {"endpoints": endpoints_list}
+
+
+@router.get(
+    "/studies/{study_id}",
+    summary="获取项目的接口级权限矩阵",
+    description="返回项目中各角色对API端点的权限配置",
+)
+async def get_study_api_permissions(
+    study_id: uuid.UUID,
+    _=Depends(require_study_roles(["PM"])),
+    db: Annotated[AsyncSession, Depends(get_db_session)] = None,
+) -> dict[str, dict[str, dict[str, bool]]]:
+    """获取项目的接口级权限矩阵
+
+    返回格式:
+    {
+        "role": {
+            "endpoint_key": {
+                "allowed": true/false
+            }
+        }
+    }
+    """
+    permissions = await get_api_endpoint_permissions(db, study_id)
+
+    # 构建返回格式
+    result: dict[str, dict[str, dict[str, bool]]] = {}
+    for role in PROJECT_PERMISSION_ROLES:
+        if role == "ADMIN":
+            continue
+        result[role] = {}
+        for endpoint_key in API_ENDPOINT_PERMISSIONS.keys():
+            result[role][endpoint_key] = {
+                "allowed": permissions.get(role, {}).get(endpoint_key, False)
+            }
+
+    return result
+
+
+@router.put(
+    "/studies/{study_id}",
+    summary="更新项目的接口级权限矩阵",
+    description="批量更新项目中各角色对API端点的权限配置",
+    status_code=status.HTTP_200_OK,
+)
+async def update_study_api_permissions(
+    study_id: uuid.UUID,
+    payload: dict[str, dict[str, bool]],
+    _=Depends(require_study_roles(["PM"])),
+    db: Annotated[AsyncSession, Depends(get_db_session)] = None,
+) -> dict[str, dict[str, dict[str, bool]]]:
+    """更新项目的接口级权限矩阵
+
+    请求体格式:
+    {
+        "role": {
+            "endpoint_key": true/false
+        }
+    }
+    """
+    # 验证输入
+    for role in payload.keys():
+        if role == "ADMIN":
+            continue
+        if role not in PROJECT_PERMISSION_ROLES:
+            raise ValueError(f"无效的角色: {role}")
+
+    # 替换权限配置
+    await replace_api_endpoint_permissions(db, study_id, payload)
+
+    # 返回更新后的权限矩阵
+    permissions = await get_api_endpoint_permissions(db, study_id)
+
+    result: dict[str, dict[str, dict[str, bool]]] = {}
+    for role in PROJECT_PERMISSION_ROLES:
+        if role == "ADMIN":
+            continue
+        result[role] = {}
+        for endpoint_key in API_ENDPOINT_PERMISSIONS.keys():
+            result[role][endpoint_key] = {
+                "allowed": permissions.get(role, {}).get(endpoint_key, False)
+            }
+
+    return result