all in
This commit is contained in:
@@ -0,0 +1,526 @@
|
||||
# 权限粒度设计方案对比
|
||||
|
||||
## 📋 问题描述
|
||||
|
||||
**场景**：
|
||||
- 用户访问 `/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
|
||||
Reference in New Issue
Block a user