权限系统：完成接口级权限系统第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>

backend/app/api/v1/fees_contracts.py

@@ -6,8 +6,8 @@ from fastapi import APIRouter, Depends, HTTPException, Query, status
 from sqlalchemy.ext.asyncio import AsyncSession
 from sqlalchemy import select
 
-from app.core.deps import get_cra_site_scope, get_current_user, get_db_session, require_study_not_locked
-from app.core.project_permissions import role_has_project_permission
+from app.core.deps import get_cra_site_scope, get_current_user, get_db_session, require_study_not_locked, require_api_permission
+from app.core.project_permissions import role_has_api_permission
 from app.crud import audit as audit_crud
 from app.crud import contract_fee as contract_fee_crud
 from app.crud import contract_fee_payment as payment_crud
@@ -29,7 +29,7 @@ from app.models.attachment import Attachment
 router = APIRouter()
 
 
-async def _ensure_project_access(db: AsyncSession, project_id: uuid.UUID, current_user, write: bool = False):
+async def _ensure_project_access(db: AsyncSession, project_id: uuid.UUID, current_user, endpoint_key: str):
     study = await study_crud.get(db, project_id)
     if not study:
         raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="项目不存在")
@@ -39,10 +39,9 @@ async def _ensure_project_access(db: AsyncSession, project_id: uuid.UUID, curren
     membership = await member_crud.get_member(db, project_id, current_user.id)
     if not membership or not membership.is_active:
         raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="不是项目成员")
-    action = "write" if write else "read"
-    allowed = await role_has_project_permission(db, project_id, membership.role_in_study, "fees", action)
+    allowed = await role_has_api_permission(db, project_id, membership.role_in_study, endpoint_key)
     if not allowed:
-        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="项目权限不足")
+        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="接口权限不足")
     return membership
 
 
@@ -86,7 +85,7 @@ async def list_contract_fees(
     db: AsyncSession = Depends(get_db_session),
     current_user=Depends(get_current_user),
 ) -> FeeApiResponse[list[ContractFeeListItem]]:
-    await _ensure_project_access(db, project_id, current_user, write=False)
+    await _ensure_project_access(db, project_id, current_user, "GET:/fees/contracts")
     cra_scope = await get_cra_site_scope(db, project_id, current_user)
     center_ids = cra_scope[0] if cra_scope else None
     if center_id and center_ids is not None and center_id not in center_ids:
@@ -142,7 +141,7 @@ async def get_contract_fee(
     contract = await contract_fee_crud.get_contract_fee(db, contract_id)
     if not contract:
         raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="合同费用不存在")
-    await _ensure_project_access(db, contract.project_id, current_user, write=False)
+    await _ensure_project_access(db, contract.project_id, current_user, "GET:/fees/contracts/{id}")
     cra_scope = await get_cra_site_scope(db, contract.project_id, current_user)
     if cra_scope and contract.center_id not in cra_scope[0]:
         raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="权限不足")
@@ -217,7 +216,7 @@ async def create_contract_fee(
     db: AsyncSession = Depends(get_db_session),
     current_user=Depends(get_current_user),
 ) -> FeeApiResponse[ContractFeeRead]:
-    await _ensure_project_access(db, contract_in.project_id, current_user, write=True)
+    await _ensure_project_access(db, contract_in.project_id, current_user, "POST:/fees/contracts")
     existing = await contract_fee_crud.get_contract_fee_by_project_center(
         db, contract_in.project_id, contract_in.center_id
     )
@@ -256,7 +255,7 @@ async def update_contract_fee(
     contract = await contract_fee_crud.get_contract_fee(db, contract_id)
     if not contract:
         raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="合同费用不存在")
-    await _ensure_project_access(db, contract.project_id, current_user, write=True)
+    await _ensure_project_access(db, contract.project_id, current_user, "PATCH:/fees/contracts/{id}")
     await _ensure_center_active(db, contract.project_id, contract.center_id)
     contract = await contract_fee_crud.update_contract_fee(db, contract, contract_in)
     await audit_crud.log_action(
@@ -285,7 +284,7 @@ async def delete_contract_fee(
     contract = await contract_fee_crud.get_contract_fee(db, contract_id)
     if not contract:
         raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="合同费用不存在")
-    await _ensure_project_access(db, contract.project_id, current_user, write=True)
+    await _ensure_project_access(db, contract.project_id, current_user, "DELETE:/fees/contracts/{id}")
     await _ensure_center_active(db, contract.project_id, contract.center_id)
     await contract_fee_crud.delete_contract_fee(db, contract)
     await audit_crud.log_action(
@@ -315,7 +314,7 @@ async def create_contract_payment(
     contract = await contract_fee_crud.get_contract_fee(db, contract_id)
     if not contract:
         raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="合同费用不存在")
-    await _ensure_project_access(db, contract.project_id, current_user, write=True)
+    await _ensure_project_access(db, contract.project_id, current_user, "POST:/fees/contracts/{id}/payments")
     _validate_payment_rules(payment_in)
     payment = await payment_crud.create_payment(db, contract_id, payment_in)
     await audit_crud.log_action(
@@ -348,7 +347,7 @@ async def update_contract_payment(
     contract = await contract_fee_crud.get_contract_fee(db, payment.contract_fee_id)
     if not contract:
         raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="合同费用不存在")
-    await _ensure_project_access(db, contract.project_id, current_user, write=True)
+    await _ensure_project_access(db, contract.project_id, current_user, "PATCH:/fees/payments/{id}")
     merged_payment = ContractFeePaymentCreate(
         amount=payment_in.amount if payment_in.amount is not None else payment.amount,
         paid_date=payment_in.paid_date if payment_in.paid_date is not None else payment.paid_date,
@@ -388,7 +387,7 @@ async def delete_contract_payment(
     contract = await contract_fee_crud.get_contract_fee(db, payment.contract_fee_id)
     if not contract:
         raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="合同费用不存在")
-    await _ensure_project_access(db, contract.project_id, current_user, write=True)
+    await _ensure_project_access(db, contract.project_id, current_user, "DELETE:/fees/payments/{id}")
     await payment_crud.delete_payment(db, payment)
     await payment_crud.resequence_payments(db, contract.id)
     await audit_crud.log_action(