ctms/FRONTEND_PERMISSION_INTEGRATION.md

# 前端权限管理集成指南

## 概述

本文档说明如何在前端应用中使用新的权限管理功能，包括接口级权限管理和权限系统监控。

---

## 功能特性

### 1. 权限管理页面

**路由**: `/admin/projects/:id/api-permissions`

**功能**:
- 模块级权限管理（向后兼容）
- 接口级权限管理（新增）
- 权限系统监控仪表板

### 2. 权限管理UI

#### 模块级权限标签页

- 显示角色 × 模块 × 读写权限的矩阵
- 支持权限编辑和保存
- 向后兼容现有权限系统

#### 接口级权限标签页

- 显示角色 × 接口端点的权限矩阵
- 支持按模块、HTTP方法、端点名称搜索和筛选
- 支持权限编辑和保存

#### 权限监控标签页

- 系统健康评分和状态
- 权限检查性能指标
- 缓存效率统计
- 告警列表展示

---

## API 客户端使用

### 导入 API 函数

```typescript
import {
  fetchProjectRolePermissions,
  updateProjectRolePermissions,
  fetchApiEndpointPermissions,
  updateApiEndpointPermissions,
  fetchPermissionMetrics,
  fetchCacheStats,
  fetchPermissionAlerts,
  fetchPermissionHealth,
  resetPermissionMetrics,
  clearPermissionAlerts,
} from "@/api/projectPermissions";
```

### 获取权限

```typescript
// 获取模块级权限
const modulePerms = await fetchProjectRolePermissions(studyId);

// 获取接口级权限
const apiPerms = await fetchApiEndpointPermissions(studyId);
```

### 更新权限

```typescript
// 更新模块级权限
await updateProjectRolePermissions(studyId, {
  roles: {
    PM: { subjects: { read: true, write: true } },
    CRA: { subjects: { read: true, write: true } },
  },
});

// 更新接口级权限
await updateApiEndpointPermissions(studyId, {
  PM: {
    "POST:/subjects": true,
    "GET:/subjects": true,
  },
  CRA: {
    "POST:/subjects": true,
    "GET:/subjects": true,
  },
});
```

### 获取监控数据

```typescript
// 获取权限检查指标
const metrics = await fetchPermissionMetrics();

// 获取缓存统计
const cacheStats = await fetchCacheStats();

// 获取告警列表
const alerts = await fetchPermissionAlerts("warning", 20);

// 获取系统健康状态
const health = await fetchPermissionHealth();
```

### 重置监控数据

```typescript
// 重置指标
await resetPermissionMetrics();

// 清除告警
await clearPermissionAlerts();
```

---

## 组件使用

### ApiPermissions.vue（主页面）

```vue
<template>
  <ApiPermissions />
</template>

<script setup lang="ts">
import ApiPermissions from "@/views/admin/ApiPermissions.vue";
</script>
```

**Props**: 无（从路由参数获取项目ID）

**事件**: 无

### ProjectPermissionsModule.vue（模块级权限）

```vue
<template>
  <ProjectPermissionsModule
    :project="project"
    :matrix="moduleMatrix"
    @update="onUpdate"
  />
</template>

<script setup lang="ts">
import ProjectPermissionsModule from "@/components/ProjectPermissionsModule.vue";
import type { ProjectRolePermissionsResponse } from "@/types/api";

const onUpdate = (matrix: ProjectRolePermissionsResponse) => {
  // 处理权限更新
};
</script>
```

**Props**:
- `project`: 项目信息
- `matrix`: 权限矩阵数据

**事件**:
- `update`: 权限矩阵更新时触发

### ApiEndpointPermissions.vue（接口级权限）

```vue
<template>
  <ApiEndpointPermissions
    :project="project"
    :matrix="apiMatrix"
    @update="onUpdate"
  />
</template>

<script setup lang="ts">
import ApiEndpointPermissions from "@/components/ApiEndpointPermissions.vue";
import type { ApiEndpointPermissionsResponse } from "@/types/api";

const onUpdate = (matrix: ApiEndpointPermissionsResponse) => {
  // 处理权限更新
};
</script>
```

**Props**:
- `project`: 项目信息
- `matrix`: 权限矩阵数据

**事件**:
- `update`: 权限矩阵更新时触发

### PermissionMonitoring.vue（监控仪表板）

```vue
<template>
  <PermissionMonitoring
    :metrics="metrics"
    :health="health"
    :alerts="alerts"
    @refresh="onRefresh"
  />
</template>

<script setup lang="ts">
import PermissionMonitoring from "@/components/PermissionMonitoring.vue";
import type {
  PermissionMetricsResponse,
  HealthResponse,
  AlertsResponse,
} from "@/types/api";

const onRefresh = () => {
  // 刷新监控数据
};
</script>
```

**Props**:
- `metrics`: 权限检查指标
- `health`: 系统健康状态
- `alerts`: 告警列表

**事件**:
- `refresh`: 刷新按钮点击时触发

---

## 类型定义

### ApiEndpointPermissionsResponse

```typescript
interface ApiEndpointPermissionsResponse {
  [role: string]: {
    [endpoint_key: string]: boolean;
  };
}
```

### ApiEndpointPermissionsUpdate

```typescript
interface ApiEndpointPermissionsUpdate {
  [role: string]: {
    [endpoint_key: string]: boolean;
  };
}
```

### PermissionMetricsResponse

```typescript
interface PermissionMetricsResponse {
  check_metrics: PermissionCheckMetrics;
  cache_metrics: CacheMetrics;
  uptime_seconds: number;
}
```

### HealthResponse

```typescript
interface HealthResponse {
  status: "healthy" | "degraded" | "unhealthy";
  health_score: number;
  issues: string[];
  metrics: PermissionMetricsResponse;
  cache_stats: CacheStatsResponse;
}
```

---

## 最佳实践

### 1. 权限管理

- 定期检查权限配置的完整性
- 使用权限监控仪表板监控权限系统状态
- 及时处理告警信息

### 2. 性能优化

- 监控缓存命中率，目标 > 80%
- 监控权限检查响应时间，目标 < 10ms
- 定期重置指标以获取准确的统计数据

### 3. 错误处理

```typescript
try {
  await updateApiEndpointPermissions(studyId, permissions);
  ElMessage.success("权限已保存");
} catch (error) {
  ElMessage.error("保存权限失败");
  console.error(error);
}
```

---

## 故障排除

### 问题1: 权限数据加载失败

**症状**: 权限管理页面显示空白或加载失败

**解决方案**:
1. 检查网络连接
2. 验证项目ID是否正确
3. 检查用户权限是否足够
4. 查看浏览器控制台错误日志

### 问题2: 权限保存失败

**症状**: 点击保存按钮后没有反应或显示错误

**解决方案**:
1. 检查权限数据格式是否正确
2. 验证API端点是否可用
3. 检查用户是否有权限修改权限配置
4. 查看服务器日志

### 问题3: 监控数据不更新

**症状**: 监控仪表板显示的数据不更新

**解决方案**:
1. 点击"刷新指标"按钮手动刷新
2. 检查后端监控API是否正常运行
3. 检查网络连接
4. 查看浏览器控制台错误日志

---

## 后续改进

### 短期

- [ ] 权限导入/导出功能
- [ ] 权限模板功能
- [ ] 权限审计日志查看

### 中期

- [ ] 权限预测和建议
- [ ] 权限使用分析
- [ ] 权限风险评估

### 长期

- [ ] 资源级权限控制
- [ ] 权限继承机制
- [ ] 权限工作流审批

---

**文档版本**: 1.0  
**最后更新**: 2026-05-14