@linyjs/plugin-docs 0.0.13

package/docs/guides/permissions.md

@@ -0,0 +1,440 @@
+# 权限管理
+
+本指南介绍如何在 linyjs 插件中实现基于角色的访问控制(RBAC)。
+
+## 概述
+
+linyjs 提供完整的权限管理系统,支持:
+
+- 🔐 基于角色的访问控制(RBAC)
+- 🎯 细粒度的权限定义
+- 🛡️ 服务端和客户端双重验证
+- 🔗 路由级别的权限保护
+
+## 声明权限需求
+
+在插件的 `manifest.json` 中声明需要的权限:
+
+```json
+{
+  "name": "blog-plugin",
+  "version": "1.0.0",
+  "permissions": [
+    "article:read",
+    "article:write",
+    "article:delete",
+    "admin:access"
+  ]
+}
+```
+
+### 权限命名规范
+
+使用 `资源:操作` 格式:
+
+```
+article:read      # 读取文章
+article:write     # 创建/更新文章
+article:delete    # 删除文章
+user:manage       # 管理用户
+admin:access      # 访问管理后台
+```
+
+## 服务端权限检查
+
+### 在控制器中检查权限
+
+```typescript
+class ArticleController {
+  getRoutes() {
+    return [
+      {
+        method: 'POST',
+        path: '/api/articles',
+        middlewares: ['auth'],
+        responseType: 'json',
+        handler: async (params: any, ctx: any) => {
+          const user = ctx.user;
+          
+          // 检查权限
+          if (!user.roles?.includes('admin')) {
+            return {
+              status: 403,
+              data: { error: 'Admin access required' }
+            };
+          }
+          
+          // 业务逻辑...
+          const article = await createArticle(params.body);
+          return { success: true, data: article };
+        }
+      }
+    ];
+  }
+}
+```
+
+### 创建权限中间件
+
+```typescript
+import type { IMiddlewareService } from '@linyjs/server-module-interface';
+
+class PermissionMiddleware implements IMiddlewareService {
+  getMiddlewares() {
+    return [{
+      middlewareId: 'checkPermission',
+      handler: async (params: any, ctx: any, next: any) => {
+        const user = ctx.user;
+        const requiredPermission = params.route?.meta?.requiredPermission;
+        
+        if (requiredPermission && !hasPermission(user, requiredPermission)) {
+          throw new Error('Insufficient permissions');
+        }
+        
+        await next();
+      }
+    }];
+  }
+}
+
+function hasPermission(user: any, permission: string): boolean {
+  // 检查用户角色是否拥有该权限
+  const rolePermissions = {
+    admin: ['article:read', 'article:write', 'article:delete'],
+    editor: ['article:read', 'article:write'],
+    viewer: ['article:read']
+  };
+  
+  return user.roles?.some((role: string) => 
+    rolePermissions[role]?.includes(permission)
+  );
+}
+
+export const permissionMiddlewareDef = {
+  serviceTag: 'permissionMiddleware',
+  serviceImpl: PermissionMiddleware,
+  meta: { usageType: 'middleware' }
+};
+```
+
+### 使用权限中间件
+
+```typescript
+{
+  method: 'DELETE',
+  path: '/api/articles/:id',
+  middlewares: ['auth', 'checkPermission'],
+  meta: {
+    requiredPermission: 'article:delete'
+  },
+  handler: async (params, ctx) => {
+    // 只有拥有 article:delete 权限的用户才能到达这里
+    await deleteArticle(params.id);
+    return { success: true };
+  }
+}
+```
+
+## 客户端权限检查
+
+### 使用 usePermission Hook
+
+```typescript
+import { usePermission } from '@linyjs/permission';
+
+function ArticleEditor() {
+  const { hasPermission } = usePermission();
+  const canEdit = hasPermission('article:write');
+  const canDelete = hasPermission('article:delete');
+  
+  return (
+    <div>
+      <h1>Edit Article</h1>
+      
+      {canEdit && (
+        <button onClick={handleSave}>Save</button>
+      )}
+      
+      {canDelete && (
+        <button onClick={handleDelete} style={{ color: 'red' }}>
+          Delete
+        </button>
+      )}
+      
+      {!canEdit && (
+        <p>You don't have permission to edit this article.</p>
+      )}
+    </div>
+  );
+}
+```
+
+### 条件渲染组件
+
+```typescript
+import { usePermission } from '@linyjs/permission';
+
+function ProtectedComponent({ children }: { children: React.ReactNode }) {
+  const { hasPermission } = usePermission();
+  
+  if (!hasPermission('admin:access')) {
+    return null;  // 不渲染
+  }
+  
+  return <>{children}</>;
+}
+
+// 使用
+function AdminPanel() {
+  return (
+    <ProtectedComponent>
+      <div>Admin Content</div>
+    </ProtectedComponent>
+  );
+}
+```
+
+## 路由权限保护
+
+### 在路由元数据中声明权限
+
+```typescript
+class BlogRouteService {
+  basePath = '/blog';
+  
+  getRoutes() {
+    return [
+      {
+        path: '/admin',
+        component: ArticleManagement,
+        key: 'article-management',
+        meta: {
+          requiresAuth: true,
+          requiredPermissions: ['admin:access', 'article:write']
+        }
+      },
+      {
+        path: '/edit/:id',
+        component: ArticleEditor,
+        key: 'article-edit',
+        meta: {
+          requiresAuth: true,
+          requiredPermissions: ['article:write']
+        }
+      }
+    ];
+  }
+}
+```
+
+### 路由守卫
+
+```typescript
+{
+  path: '/admin',
+  component: AdminPanel,
+  key: 'admin',
+  guard: {
+    canEnter: async ({ location }) => {
+      const { hasPermission } = usePermission();
+      
+      if (!hasPermission('admin:access')) {
+        return '/forbidden';  // 重定向
+      }
+      
+      return true;  // 允许访问
+    }
+  }
+}
+```
+
+## 自定义权限逻辑
+
+### 基于资源的权限
+
+```typescript
+function canEditArticle(user: any, article: any): boolean {
+  // 管理员可以编辑所有文章
+  if (user.roles?.includes('admin')) {
+    return true;
+  }
+  
+  // 作者可以编辑自己的文章
+  if (article.authorId === user.id) {
+    return true;
+  }
+  
+  // 编辑可以编辑任何文章
+  if (user.roles?.includes('editor')) {
+    return true;
+  }
+  
+  return false;
+}
+
+// 在组件中使用
+function ArticlePage({ articleId }: { articleId: number }) {
+  const { user } = useAuth();
+  const [article, setArticle] = useState(null);
+  const [canEdit, setCanEdit] = useState(false);
+  
+  useEffect(() => {
+    fetch(`/api/articles/${articleId}`)
+      .then(res => res.json())
+      .then(data => {
+        setArticle(data);
+        setCanEdit(canEditArticle(user, data));
+      });
+  }, [articleId, user]);
+  
+  return (
+    <div>
+      <h1>{article?.title}</h1>
+      {canEdit && <EditButton />}
+    </div>
+  );
+}
+```
+
+### 动态权限检查
+
+```typescript
+function useArticlePermission(articleId: number) {
+  const { user } = useAuth();
+  const [permissions, setPermissions] = useState({
+    canRead: false,
+    canWrite: false,
+    canDelete: false
+  });
+  
+  useEffect(() => {
+    fetch(`/api/articles/${articleId}/permissions`)
+      .then(res => res.json())
+      .then(setPermissions);
+  }, [articleId]);
+  
+  return permissions;
+}
+
+// 使用
+function ArticleActions({ articleId }: { articleId: number }) {
+  const { canWrite, canDelete } = useArticlePermission(articleId);
+  
+  return (
+    <div>
+      {canWrite && <EditButton />}
+      {canDelete && <DeleteButton />}
+    </div>
+  );
+}
+```
+
+## 权限层级
+
+### 定义权限层级
+
+```typescript
+const permissionHierarchy = {
+  'article:delete': ['article:write', 'article:read'],
+  'article:write': ['article:read'],
+  'admin:access': ['article:read', 'article:write', 'article:delete']
+};
+
+function hasPermissionWithHierarchy(
+  user: any, 
+  requiredPermission: string
+): boolean {
+  // 直接检查
+  if (user.permissions?.includes(requiredPermission)) {
+    return true;
+  }
+  
+  // 检查父权限
+  const parentPermissions = Object.entries(permissionHierarchy)
+    .filter(([_, children]) => children.includes(requiredPermission))
+    .map(([parent]) => parent);
+  
+  return parentPermissions.some(parent => 
+    user.permissions?.includes(parent)
+  );
+}
+```
+
+## 最佳实践
+
+### 1. 最小权限原则
+
+只授予必要的权限:
+
+```typescript
+// ✅ 好的做法 - 精确权限
+permissions: ['article:read']
+
+// ❌ 避免 - 过度授权
+permissions: ['admin:access']
+```
+
+### 2. 服务端验证
+
+永远不要仅依赖客户端权限检查:
+
+```typescript
+// 服务端必须再次验证
+handler: async (params, ctx) => {
+  // 即使客户端已检查,服务端仍需验证
+  if (!hasPermission(ctx.user, 'article:delete')) {
+    return { status: 403, data: { error: 'Forbidden' } };
+  }
+  
+  // 执行删除
+}
+```
+
+### 3. 清晰的错误消息
+
+```typescript
+if (!hasPermission(user, 'article:write')) {
+  return {
+    status: 403,
+    data: { 
+      error: 'You do not have permission to edit articles',
+      requiredPermission: 'article:write'
+    }
+  };
+}
+```
+
+### 4. 权限缓存
+
+```typescript
+import { useMemo } from 'react';
+
+function useUserPermissions() {
+  const { user } = useAuth();
+  
+  const permissions = useMemo(() => {
+    return new Set(user?.permissions || []);
+  }, [user]);
+  
+  const hasPermission = useCallback((permission: string) => {
+    return permissions.has(permission);
+  }, [permissions]);
+  
+  return { hasPermission };
+}
+```
+
+## 完整示例
+
+查看博客插件中的权限实现:
+
+- 📁 [Blog Plugin 示例](../../examples/blog-plugin/)
+
+## 相关文档
+
+- 🎨 [UI 扩展插槽](./ui-slots.md)
+- 💾 [数据持久化](./data-persistence.md)
+
+---
+
+**上一篇**: [UI 扩展插槽](./ui-slots.md) | **下一篇**: [数据持久化](./data-persistence.md)