527 lines
14 KiB
Markdown
527 lines
14 KiB
Markdown
# 权限粒度设计方案对比
|
||
|
||
## 📋 问题描述
|
||
|
||
**场景**：
|
||
- 用户访问 `/prompts` 列表页
|
||
- 后端返回该路由权限：`['prompt_template:delete:delete', 'prompt_template:list:read']`
|
||
- 子路由 `/prompts/new` 的权限：`['prompt_template:create:write', 'prompt_template:detail:read', 'prompt_template:update:write']`
|
||
|
||
**问题**：
|
||
- 在 `/prompts` 页面想显示"新增"和"编辑"按钮
|
||
- 但这些按钮需要的权限（`create:write`, `update:write`）只在子路由中
|
||
- 导致父路由无法显示这些按钮
|
||
|
||
---
|
||
|
||
## 🎯 解决方案对比
|
||
|
||
### 方案1：后端聚合权限 ⭐⭐⭐⭐⭐ (推荐)
|
||
|
||
#### 设计思路
|
||
|
||
后端在返回父路由权限时，**自动聚合所有子路由的权限**。
|
||
|
||
#### 后端返回格式
|
||
|
||
```json
|
||
{
|
||
"/prompts": [
|
||
"prompt_template:list:read", // 自身权限
|
||
"prompt_template:delete:delete", // 自身权限
|
||
"prompt_template:detail:read", // ← 从子路由聚合
|
||
"prompt_template:create:write", // ← 从子路由聚合
|
||
"prompt_template:update:write" // ← 从子路由聚合
|
||
],
|
||
"/prompts/new": [
|
||
"prompt_template:create:write",
|
||
"prompt_template:detail:read",
|
||
"prompt_template:update:write"
|
||
]
|
||
}
|
||
```
|
||
|
||
#### 后端实现建议
|
||
|
||
**PostgreSQL 示例**：
|
||
```sql
|
||
-- 递归查询：获取路由及其所有子路由的权限
|
||
WITH RECURSIVE route_permissions AS (
|
||
-- 基础查询：当前路由的权限
|
||
SELECT
|
||
r.id,
|
||
r.route_path,
|
||
rp.permission_id,
|
||
p.permission_key
|
||
FROM routes r
|
||
LEFT JOIN route_permissions rp ON r.id = rp.route_id
|
||
LEFT JOIN permissions p ON rp.permission_id = p.id
|
||
WHERE r.id = $1 -- 当前路由ID
|
||
|
||
UNION
|
||
|
||
-- 递归查询：所有子路由的权限
|
||
SELECT
|
||
r.id,
|
||
r.route_path,
|
||
rp.permission_id,
|
||
p.permission_key
|
||
FROM routes r
|
||
INNER JOIN route_permissions base_rp ON r.parent_id = base_rp.id
|
||
LEFT JOIN route_permissions rp ON r.id = rp.route_id
|
||
LEFT JOIN permissions p ON rp.permission_id = p.id
|
||
)
|
||
SELECT DISTINCT permission_key
|
||
FROM route_permissions
|
||
WHERE permission_key IS NOT NULL
|
||
ORDER BY permission_key;
|
||
```
|
||
|
||
**Node.js 后端逻辑示例**：
|
||
```javascript
|
||
// 递归聚合子路由权限
|
||
function aggregatePermissions(route, allRoutes) {
|
||
const permissions = new Set(route.permissions || []);
|
||
|
||
// 找到所有子路由
|
||
const children = allRoutes.filter(r => r.parent_id === route.id);
|
||
|
||
// 递归聚合子路由权限
|
||
children.forEach(child => {
|
||
const childPermissions = aggregatePermissions(child, allRoutes);
|
||
childPermissions.forEach(p => permissions.add(p));
|
||
});
|
||
|
||
return Array.from(permissions);
|
||
}
|
||
|
||
// 在返回路由数据前处理
|
||
routes.forEach(route => {
|
||
route.permissions = aggregatePermissions(route, routes);
|
||
});
|
||
```
|
||
|
||
#### 优点
|
||
|
||
✅ **前端逻辑简单** - 直接使用当前路由权限，无需额外处理
|
||
✅ **性能最好** - 无需前端计算，权限数据已准备好
|
||
✅ **符合直觉** - 在列表页能看到的操作，用户都有权限执行
|
||
✅ **易于维护** - 权限逻辑集中在后端，前端无需关心聚合规则
|
||
|
||
#### 缺点
|
||
|
||
❌ **需要后端修改** - 需要数据库查询逻辑调整
|
||
|
||
---
|
||
|
||
### 方案2：前端聚合权限 ⭐⭐⭐⭐ (已实现)
|
||
|
||
#### 设计思路
|
||
|
||
前端在构建权限映射表时，**自动将子路由权限聚合到父路由**。
|
||
|
||
#### 前端实现（已完成）
|
||
|
||
```typescript
|
||
// app/api/auth/user-routes.ts
|
||
|
||
export function buildPermissionMap(
|
||
routes: BackendRouteInfo[],
|
||
aggregateChildren: boolean = true // ← 默认开启聚合
|
||
): PermissionMap {
|
||
const permissionMap = new Map<string, string[]>();
|
||
|
||
// 递归收集路由及其所有子路由的权限
|
||
function collectAllPermissions(route: BackendRouteInfo): string[] {
|
||
const allPermissions = new Set<string>();
|
||
|
||
// 添加当前路由的权限
|
||
if (route.permissions && route.permissions.length > 0) {
|
||
route.permissions.forEach(p => allPermissions.add(p));
|
||
}
|
||
|
||
// 递归收集子路由的权限
|
||
if (aggregateChildren && route.children && route.children.length > 0) {
|
||
route.children.forEach(child => {
|
||
const childPermissions = collectAllPermissions(child);
|
||
childPermissions.forEach(p => allPermissions.add(p));
|
||
});
|
||
}
|
||
|
||
return Array.from(allPermissions);
|
||
}
|
||
|
||
function traverse(routeList: BackendRouteInfo[]) {
|
||
for (const route of routeList) {
|
||
const permissions = aggregateChildren
|
||
? collectAllPermissions(route) // ← 聚合子路由权限
|
||
: (route.permissions || []);
|
||
|
||
if (permissions.length > 0) {
|
||
permissionMap.set(route.route_path, permissions);
|
||
}
|
||
|
||
if (route.children && route.children.length > 0) {
|
||
traverse(route.children);
|
||
}
|
||
}
|
||
}
|
||
|
||
traverse(routes);
|
||
return permissionMap;
|
||
}
|
||
```
|
||
|
||
#### 使用方式
|
||
|
||
```typescript
|
||
// 默认开启聚合（推荐）
|
||
const permissionMap = buildPermissionMap(routes);
|
||
|
||
// 关闭聚合（仅使用路由自身权限）
|
||
const permissionMap = buildPermissionMap(routes, false);
|
||
```
|
||
|
||
#### 效果
|
||
|
||
**后端返回**：
|
||
```json
|
||
{
|
||
"/prompts": {
|
||
"permissions": ["prompt_template:list:read", "prompt_template:delete:delete"]
|
||
},
|
||
"/prompts/new": {
|
||
"permissions": ["prompt_template:create:write", "prompt_template:detail:read"]
|
||
}
|
||
}
|
||
```
|
||
|
||
**前端聚合后**：
|
||
```json
|
||
{
|
||
"/prompts": [
|
||
"prompt_template:list:read",
|
||
"prompt_template:delete:delete",
|
||
"prompt_template:create:write", // ← 从 /prompts/new 聚合
|
||
"prompt_template:detail:read" // ← 从 /prompts/new 聚合
|
||
],
|
||
"/prompts/new": [
|
||
"prompt_template:create:write",
|
||
"prompt_template:detail:read"
|
||
]
|
||
}
|
||
```
|
||
|
||
#### 优点
|
||
|
||
✅ **无需后端改动** - 前端自动处理
|
||
✅ **立即可用** - 已实现，默认开启
|
||
✅ **灵活控制** - 可通过参数开关聚合行为
|
||
|
||
#### 缺点
|
||
|
||
❌ **前端计算开销** - 需要递归遍历路由树（但性能影响极小）
|
||
❌ **可能过度授权** - 子路由权限不一定适用于父路由场景
|
||
|
||
---
|
||
|
||
### 方案3：按资源模块返回权限 ⭐⭐⭐⭐⭐ (最佳长期方案)
|
||
|
||
#### 设计思路
|
||
|
||
**核心理念**：权限应该是**按资源模块组织**，而不是按路由组织。
|
||
|
||
#### 后端返回格式（推荐）
|
||
|
||
```json
|
||
{
|
||
"routes": [
|
||
{
|
||
"route_path": "/prompts",
|
||
"route_name": "prompts",
|
||
"module": "prompt_template", // ← 标识资源模块
|
||
"permissions": [
|
||
"prompt_template:list:read",
|
||
"prompt_template:detail:read",
|
||
"prompt_template:create:write",
|
||
"prompt_template:update:write",
|
||
"prompt_template:delete:delete"
|
||
]
|
||
},
|
||
{
|
||
"route_path": "/prompts/new",
|
||
"route_name": "prompts.new",
|
||
"module": "prompt_template", // ← 同一模块
|
||
"permissions": [
|
||
"prompt_template:create:write",
|
||
"prompt_template:detail:read",
|
||
"prompt_template:update:write"
|
||
]
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
#### 设计原则
|
||
|
||
1. **模块级权限** - 同一资源模块的所有路由共享权限池
|
||
2. **父路由包含全集** - 父路由（如 `/prompts`）应该包含该模块的所有用户权限
|
||
3. **子路由可以限制** - 子路由（如 `/prompts/:id/edit`）可以是父路由权限的子集
|
||
|
||
#### 数据库设计建议
|
||
|
||
**当前表结构问题**：
|
||
```sql
|
||
-- 当前：权限和路由是多对多关系
|
||
route_permissions (route_id, permission_id)
|
||
```
|
||
|
||
**推荐表结构**：
|
||
```sql
|
||
-- 推荐：权限和模块是多对多关系
|
||
module_permissions (
|
||
module_name VARCHAR(100), -- 如 'prompt_template'
|
||
permission_id INT,
|
||
grant_type VARCHAR(10) -- 'GRANT' | 'DENY'
|
||
)
|
||
|
||
-- 路由表添加模块字段
|
||
routes (
|
||
id INT,
|
||
route_path VARCHAR(255),
|
||
module_name VARCHAR(100), -- ← 新增：关联到模块
|
||
...
|
||
)
|
||
|
||
-- 用户的模块权限（通过角色）
|
||
user_module_permissions (
|
||
user_id INT,
|
||
module_name VARCHAR(100),
|
||
permission_keys TEXT[] -- 聚合后的权限列表
|
||
)
|
||
```
|
||
|
||
#### 后端查询示例
|
||
|
||
```sql
|
||
-- 获取用户在指定模块的所有权限
|
||
SELECT DISTINCT p.permission_key
|
||
FROM sso_users u
|
||
JOIN user_roles ur ON u.id = ur.user_id
|
||
JOIN role_permissions rp ON ur.role_id = rp.role_id
|
||
JOIN permissions p ON rp.permission_id = p.id
|
||
WHERE u.id = $1
|
||
AND p.module = $2 -- 如 'prompt_template'
|
||
AND rp.grant_type = 'GRANT'
|
||
ORDER BY p.permission_key;
|
||
```
|
||
|
||
#### 前端使用方式
|
||
|
||
```typescript
|
||
// 在任何提示词相关页面，都使用同一套权限
|
||
const { canCreate, canUpdate, canDelete } = usePermission();
|
||
|
||
const canCreateTemplate = canCreate('prompt_template');
|
||
const canEditTemplate = canUpdate('prompt_template');
|
||
const canDeleteTemplate = canDelete('prompt_template');
|
||
|
||
// 无论在 /prompts 还是 /prompts/new，权限检查结果一致
|
||
```
|
||
|
||
#### 优点
|
||
|
||
✅ **语义清晰** - 权限围绕业务模块组织，易于理解
|
||
✅ **避免重复** - 不需要为每个路由单独配置权限
|
||
✅ **易于扩展** - 新增路由自动继承模块权限
|
||
✅ **符合RBAC原则** - 权限基于资源而非路由
|
||
|
||
#### 缺点
|
||
|
||
❌ **需要重构数据库** - 需要调整表结构和查询逻辑
|
||
❌ **实施成本高** - 需要后端和前端配合改造
|
||
|
||
---
|
||
|
||
## 📊 方案对比总结
|
||
|
||
| 特性 | 方案1：后端聚合 | 方案2：前端聚合 | 方案3：模块权限 |
|
||
|------|----------------|----------------|----------------|
|
||
| **实施难度** | 中等 | 简单 | 较高 |
|
||
| **性能** | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ |
|
||
| **维护性** | ⭐⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐⭐⭐ |
|
||
| **扩展性** | ⭐⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐⭐⭐ |
|
||
| **是否需要后端改动** | 是 | 否 | 是（较大） |
|
||
| **当前可用性** | 需要实施 | ✅ 已实现 | 需要重构 |
|
||
|
||
---
|
||
|
||
## 🎯 推荐方案
|
||
|
||
### 短期方案（立即可用）：方案2 - 前端聚合
|
||
|
||
**理由**：
|
||
- ✅ 已经实现，默认开启
|
||
- ✅ 无需后端改动，立即解决问题
|
||
- ✅ 可以通过参数控制聚合行为
|
||
|
||
**使用方式**：
|
||
```typescript
|
||
// 已默认开启，无需任何修改
|
||
// 访问 /prompts 时，会自动包含 /prompts/new 的权限
|
||
```
|
||
|
||
**验证效果**：
|
||
```typescript
|
||
// 在 /prompts 页面
|
||
const { getCurrentPermissions } = usePermission();
|
||
|
||
console.log(getCurrentPermissions());
|
||
// 输出:
|
||
// [
|
||
// "prompt_template:list:read",
|
||
// "prompt_template:delete:delete",
|
||
// "prompt_template:create:write", // ← 从子路由聚合
|
||
// "prompt_template:detail:read", // ← 从子路由聚合
|
||
// "prompt_template:update:write" // ← 从子路由聚合
|
||
// ]
|
||
```
|
||
|
||
---
|
||
|
||
### 长期方案（推荐）：方案3 - 模块权限
|
||
|
||
**实施步骤**：
|
||
|
||
#### 阶段1：数据库改造
|
||
1. 在 `routes` 表添加 `module_name` 字段
|
||
2. 创建 `module_permissions` 视图
|
||
3. 更新权限查询逻辑
|
||
|
||
#### 阶段2：后端API调整
|
||
1. 修改 `/rbac/user/routes` 接口
|
||
2. 按模块聚合权限，而非按路由
|
||
3. 确保父路由包含模块的所有权限
|
||
|
||
#### 阶段3：前端适配（无需改动）
|
||
- 前端已支持权限聚合，自动兼容新格式
|
||
|
||
---
|
||
|
||
## 💡 最佳实践建议
|
||
|
||
### 1. 权限粒度原则
|
||
|
||
**不推荐** ❌：
|
||
```json
|
||
{
|
||
"/prompts": ["prompt_template:list:read"],
|
||
"/prompts/new": ["prompt_template:create:write"],
|
||
"/prompts/:id/edit": ["prompt_template:update:write"]
|
||
}
|
||
```
|
||
*问题*：权限分散，父路由无法显示子路由相关操作
|
||
|
||
**推荐** ✅：
|
||
```json
|
||
{
|
||
"/prompts": [
|
||
"prompt_template:list:read",
|
||
"prompt_template:create:write",
|
||
"prompt_template:update:write",
|
||
"prompt_template:delete:delete"
|
||
],
|
||
"/prompts/new": ["prompt_template:create:write"],
|
||
"/prompts/:id/edit": ["prompt_template:update:write"]
|
||
}
|
||
```
|
||
*优点*：父路由包含全集，子路由根据需要限制
|
||
|
||
### 2. 路由设计原则
|
||
|
||
- **列表页**（如 `/documents`）：包含该模块的所有权限
|
||
- **详情页**（如 `/documents/:id`）：至少包含 `read` 权限
|
||
- **新增页**（如 `/documents/new`）：包含 `create` 权限
|
||
- **编辑页**（如 `/documents/:id/edit`）：包含 `update` 权限
|
||
|
||
### 3. 权限命名规范
|
||
|
||
遵循 `module:resource:action` 格式：
|
||
|
||
```
|
||
prompt_template:list:read ← 查看列表
|
||
prompt_template:detail:read ← 查看详情
|
||
prompt_template:create:write ← 创建
|
||
prompt_template:update:write ← 更新
|
||
prompt_template:delete:delete ← 删除
|
||
prompt_template:export:execute ← 导出（特殊操作）
|
||
```
|
||
|
||
### 4. 权限继承规则
|
||
|
||
```
|
||
父路由权限 ⊇ 子路由权限
|
||
```
|
||
|
||
示例：
|
||
```
|
||
/prompts 权限 = [list:read, detail:read, create:write, update:write, delete:delete]
|
||
├─ /prompts/new 权限 = [create:write, detail:read]
|
||
└─ /prompts/:id/edit 权限 = [update:write, detail:read]
|
||
```
|
||
|
||
---
|
||
|
||
## 🔧 当前系统配置
|
||
|
||
### 已启用：前端自动聚合
|
||
|
||
**文件**：`app/api/auth/user-routes.ts`
|
||
|
||
```typescript
|
||
// 默认开启子路由权限聚合
|
||
const permissionMapObj = permissionMapToObject(
|
||
buildPermissionMap(routes) // aggregateChildren = true (默认)
|
||
);
|
||
```
|
||
|
||
### 如何关闭聚合（不推荐）
|
||
|
||
如果需要关闭自动聚合（仅使用路由自身权限）：
|
||
|
||
```typescript
|
||
// app/api/auth/user-routes.ts
|
||
|
||
const permissionMapObj = permissionMapToObject(
|
||
buildPermissionMap(routes, false) // ← 关闭聚合
|
||
);
|
||
```
|
||
|
||
---
|
||
|
||
## 📝 总结
|
||
|
||
### 当前状态
|
||
|
||
✅ **已实现方案2** - 前端自动聚合子路由权限
|
||
✅ **立即可用** - 无需任何配置
|
||
✅ **解决问题** - `/prompts` 页面现在可以正确显示"新增"和"编辑"按钮
|
||
|
||
### 下一步建议
|
||
|
||
1. **短期**：使用当前的前端聚合方案（已完成）
|
||
2. **中期**：与后端沟通，考虑在后端实现聚合（方案1）
|
||
3. **长期**：规划模块化权限设计（方案3）
|
||
|
||
### 注意事项
|
||
|
||
⚠️ **前端权限检查仅用于UI控制**
|
||
⚠️ **后端必须验证所有操作的权限**
|
||
⚠️ **定期审查权限配置的合理性**
|
||
|
||
---
|
||
|
||
**文档版本**: 1.0.0
|
||
**创建日期**: 2025-11-27
|
||
**作者**: Claude Code
|