ctms/IMPLEMENTATION_SUMMARY.md

权限系统重构实现总结

实现状态

✅ 已完成的阶段

第1阶段：数据库设计

• ApiEndpointPermission 模型 (/backend/app/models/api_endpoint_permission.py)

  • 存储接口级权限配置
  • 支持按项目、角色、接口端点的权限管理

• ApiEndpointRegistry 模型 (/backend/app/models/api_endpoint_registry.py)

  • 存储系统中所有已注册的API端点
  • 包含端点元数据（方法、路径、模块、操作、默认角色）

• 数据库迁移 (/backend/alembic/versions/20250513_01_add_api_endpoint_permissions.py)

  • 创建两个新表
  • 包含幂等性检查

第2阶段：权限配置系统

• API_ENDPOINT_PERMISSIONS (/backend/app/core/api_permissions.py)

  • 定义了所有关键业务模块的接口级权限
  • 包含 subjects, risk_issues, fees, finance_contracts, project_members, sites 等模块

• MODULE_TO_ENDPOINTS 映射

  • 支持向后兼容，允许回退到模块级权限

第3阶段：权限检查依赖注入

• require_api_permission() (/backend/app/core/deps.py)

  • FastAPI 依赖注入函数
  • 支持接口级权限检查

• role_has_api_permission() (/backend/app/core/project_permissions.py)

  • 核心权限检查逻辑
  • 支持接口级权限优先，模块级权限回退

• get_api_endpoint_permissions() 和 replace_api_endpoint_permissions()

  • 权限矩阵查询和更新函数

第4阶段：API端点迁移

已迁移的模块：

1. subjects.py - 参与者管理

   • POST /subjects → POST:/subjects
   • GET /subjects → GET:/subjects
   • GET /subjects/{id} → GET:/subjects/{id}
   • PATCH /subjects/{id} → PATCH:/subjects/{id}
   • DELETE /subjects/{id} → DELETE:/subjects/{id}

2. aes.py - 不良事件管理

   • POST /aes → POST:/risk-issues
   • GET /aes → GET:/risk-issues
   • GET /aes/{id} → GET:/risk-issues/{id}
   • PATCH /aes/{id} → PATCH:/risk-issues/{id}
   • DELETE /aes/{id} → DELETE:/risk-issues/{id}

3. fees_contracts.py - 费用合同管理

   • GET /fees/contracts → GET:/fees/contracts
   • GET /fees/contracts/{id} → GET:/fees/contracts/{id}
   • POST /fees/contracts → POST:/fees/contracts
   • PATCH /fees/contracts/{id} → PATCH:/fees/contracts/{id}
   • DELETE /fees/contracts/{id} → DELETE:/fees/contracts/{id}
   • POST /fees/contracts/{id}/payments → POST:/fees/contracts/{id}/payments
   • PATCH /fees/payments/{id} → PATCH:/fees/payments/{id}
   • DELETE /fees/payments/{id} → DELETE:/fees/payments/{id}

4. finance_contracts.py - 财务合同管理

   • POST /finance/contracts → POST:/finance/contracts
   • GET /finance/contracts → GET:/finance/contracts
   • GET /finance/contracts/{id} → GET:/finance/contracts/{id}
   • PATCH /finance/contracts/{id} → PATCH:/finance/contracts/{id}
   • DELETE /finance/contracts/{id} → DELETE:/finance/contracts/{id}

第5阶段：权限管理API

• api_permissions.py (/backend/app/api/v1/api_permissions.py)
  • GET /api-permissions/endpoints - 获取所有已注册的API端点
  • GET /studies/{study_id}/api-permissions - 获取项目的权限矩阵
  • PUT /studies/{study_id}/api-permissions - 更新项目的权限矩阵

📋 待完成的工作（第6阶段）

单元测试

• 权限检查函数测试

  • 接口级权限检查
  • 向后兼容（模块级权限回退）
  • 权限优先级验证

• 权限配置测试

  • 权限配置的创建、读取、更新
  • 权限配置的验证

集成测试

• 跨模块数据访问测试

  • 验证 risk_issues 模块可以读取 subjects 数据
  • 验证权限检查正确

• 权限管理API测试

  • 权限查询、更新、删除

• 向后兼容测试

  • 验证旧的模块级权限仍然有效
  • 验证迁移期间两套权限系统并行运行

端到端测试

• 权限变更流程

  • 管理员修改权限
  • 用户权限立即生效
  • 审计日志记录

• 跨模块场景

  • PV 查看参与者信息
  • PV 创建不良事件（需要参与者信息）
  • 权限检查正确

文档更新

• API文档更新

  • 新增权限管理API文档
  • 更新已迁移模块的权限说明

• 开发指南

  • 如何添加新的接口级权限
  • 如何迁移现有模块到接口级权限

• 权限矩阵文档

  • 各角色的默认权限
  • 权限配置示例

关键特性

1. 细粒度权限控制

• 从模块级（subjects.read/write）升级到接口级（POST:/subjects, GET:/subjects/{id}）
• 支持跨模块数据访问权限管理

2. 向后兼容

• 接口级权限优先级高于模块级权限
• 如果接口级权限未配置，自动回退到模块级权限
• 现有代码无需立即迁移

3. 灵活的权限配置

• 权限配置存储在数据库中
• 支持动态调整，无需重启应用
• 提供REST API进行权限管理

4. 权限检查流程

请求到达
  ↓
FastAPI依赖注入 → require_api_permission("POST:/subjects")
  ↓
role_has_api_permission(db, study_id, role, "POST:/subjects")
  ↓
  ├─ 查询 ApiEndpointPermission 表
  │  ├─ 找到 → 返回 allowed 值
  │  └─ 未找到 → 继续
  │
  └─ 回退到模块级权限
     └─ role_has_project_permission(db, study_id, role, "subjects", "write")
        ├─ 查询 StudyRolePermission 表
        └─ 返回权限结果
  ↓
权限检查通过 → 执行业务逻辑
权限检查失败 → 返回 403 Forbidden

文件清单

新增文件

• /backend/app/models/api_endpoint_permission.py - 接口级权限模型
• /backend/app/models/api_endpoint_registry.py - 接口注册表模型
• /backend/app/core/decorators.py - 装饰器辅助函数
• /backend/app/api/v1/api_permissions.py - 权限管理API
• /backend/alembic/versions/20250513_01_add_api_endpoint_permissions.py - 数据库迁移

修改文件

• /backend/app/core/api_permissions.py - 接口权限配置
• /backend/app/core/project_permissions.py - 权限检查函数
• /backend/app/core/deps.py - 依赖注入函数
• /backend/app/main.py - 应用启动初始化
• /backend/app/api/v1/router.py - 路由注册
• /backend/app/api/v1/subjects.py - 参与者管理API
• /backend/app/api/v1/aes.py - 不良事件API
• /backend/app/api/v1/fees_contracts.py - 费用合同API
• /backend/app/api/v1/finance_contracts.py - 财务合同API

下一步

1. 运行数据库迁移

   alembic upgrade head
   

2. 启动应用并验证

   uvicorn app.main:app --reload
   

3. 编写和运行测试

   • 单元测试
   • 集成测试
   • 端到端测试

4. 迁移第二批模块

   • members (project_members)
   • sites

5. 更新文档

   • API文档
   • 开发指南
   • 权限矩阵文档

验证清单

• 代码语法检查通过
• 数据库模型可以导入
• 权限配置系统完整
• 关键业务模块已迁移
• 单元测试编写
• 集成测试编写
• 端到端测试编写
• 文档更新
• 性能测试
• 安全审计