ctms/docs/guides/frontend-permission-integration.md

前端权限管理集成指南

概述

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

---

功能特性

1. 权限管理页面

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

功能:

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

2. 权限管理UI

模块级权限标签页

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

接口级权限标签页

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

权限监控标签页

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

---

API 客户端使用

导入 API 函数

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

获取权限

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

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

更新权限

// 更新模块级权限
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,
  },
});

获取监控数据

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

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

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

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

重置监控数据

// 重置指标
await resetPermissionMetrics();

// 清除告警
await clearPermissionAlerts();

---

组件使用

ApiPermissions.vue（主页面）

<template>
  <ApiPermissions />
</template>

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

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

事件: 无

ProjectPermissionsModule.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（接口级权限）

<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（监控仪表板）

<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

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

ApiEndpointPermissionsUpdate

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

PermissionMetricsResponse

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

HealthResponse

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

---

最佳实践

1. 权限管理

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

2. 性能优化

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

3. 错误处理

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