@lark-apaas/nestjs-authzpaas 0.1.0-alpha.0

package/README.md

@@ -0,0 +1,1191 @@
+# nestjs-authzpaas
+
+`nestjs-authzpaas` 是一个基于 NestJS 的权限管理模块，提供了完整的 RBAC（基于角色的访问控制）和 ABAC（基于属性的访问控制）解决方案。它基于 [CASL](https://casl.js.org/) 实现，支持角色检查、权限检查、环境检查等多种鉴权方式。
+
+## 目录
+
+- [核心概念](#核心概念)
+- [快速开始](#快速开始)
+- [装饰器使用](#装饰器使用)
+- [核心组件](#核心组件)
+- [高级用法](#高级用法)
+- [最佳实践](#最佳实践)
+
+## 核心概念
+
+### 权限模型
+
+本模块采用以下权限模型：
+
+- **角色 (Role)**: 用户所属的角色，如 `admin`、`editor`、`viewer`
+- **权限 (Permission)**: 对特定资源的操作权限，由 `actions` + `subject` 组成
+  - `actions`: 操作类型，如 `create`、`read`、`update`、`delete`、`manage`
+  - `subject`: 资源类型，如 `User`、`Task`、`Article`
+
+### 核心组件
+
+| 组件 | 类型 | 说明 |
+|------|------|------|
+| `AuthZPaasGuard` | 全局守卫 | 自动拦截所有请求，执行鉴权检查 |
+| `PermissionService` | 服务 | 提供权限获取、检查、缓存管理等功能 |
+| `RolesMiddleware` | 中间件 | 自动获取并注入用户角色信息到请求上下文 |
+| `CanRole` | 装饰器 | 声明式角色检查 |
+| `CanPermission` | 装饰器 | 声明式权限检查 |
+| `UserId` | 参数装饰器 | 获取当前用户ID |
+
+## 快速开始
+
+### 1. 安装依赖
+
+```bash
+npm install @lark-apaas/nestjs-authzpaas
+# 或
+yarn add @lark-apaas/nestjs-authzpaas
+```
+
+### 2. 配置模块
+
+在 `app.module.ts` 中导入并配置 `AuthZPaasModule`：
+
+```typescript
+import { Module, MiddlewareConsumer, NestModule } from '@nestjs/common';
+import { AuthZPaasModule, RolesMiddleware } from '@lark-apaas/nestjs-authzpaas';
+import { UserContextMiddleware } from '@lark-apaas/fullstack-nestjs-core';
+
+@Module({
+  imports: [
+    // 配置 AuthZPaas 模块
+    AuthZPaasModule.forRoot({
+      permissionApi: {
+        // 权限 API 配置
+        baseUrl: 'http://localhost:3000',
+        endpoint: '/mock-api/users/:userId/permissions',
+        timeout: 5000,
+      },
+      cache: {
+        ttl: 60,        // 缓存时间（秒）
+        max: 100,       // 最大缓存数量
+        enabled: true,  // 启用缓存
+      },
+      // 高级配置选项
+      enableMockRole: false,     // 是否启用角色模拟功能（默认 false）
+      isGlobal: true,            // 全局模块
+    }),
+  ],
+  controllers: [/* ... */],
+  providers: [/* ... */],
+})
+export class AppModule implements NestModule {
+  configure(consumer: MiddlewareConsumer) {
+    // 1. UserContextMiddleware 必须在最前面，用于解析用户信息
+    consumer
+      .apply(UserContextMiddleware)
+      .forRoutes('*');
+    
+    // 2. RolesMiddleware 用于自动获取用户角色
+    //    注意：对于不需要鉴权的接口可以配置排除
+    consumer
+      .apply(RolesMiddleware)
+      .exclude('mock-api/(.*)')  // 排除权限权限 MOCK API
+      .forRoutes('*');
+  }
+}
+```
+
+### 3. 异步配置（可选）
+
+如果需要从 `ConfigService` 获取配置：
+
+```typescript
+import { ConfigModule, ConfigService } from '@nestjs/config';
+
+@Module({
+  imports: [
+    ConfigModule.forRoot(),
+    AuthZPaasModule.forRootAsync({
+      imports: [ConfigModule],
+      inject: [ConfigService],
+      useFactory: async (configService: ConfigService) => ({
+        permissionApi: {
+          baseUrl: configService.get('PERMISSION_API_URL'),
+          endpoint: configService.get('PERMISSION_API_ENDPOINT'),
+          timeout: 5000,
+        },
+        cache: {
+          ttl: configService.get('CACHE_TTL', 300),
+          max: configService.get('CACHE_MAX', 1000),
+          enabled: true,
+        },
+      }),
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+## 配置选项详解
+
+### 核心配置
+
+| 配置项 | 类型 | 默认值 | 说明 |
+|--------|------|--------|------|
+| `permissionApi` | `PermissionApiConfig` | - | 权限 API 配置（必需） |
+| `cache` | `CacheConfig` | `{ ttl: 300, max: 1000, enabled: true }` | 缓存配置 |
+| `isGlobal` | `boolean` | `true` | 是否注册为全局模块 |
+
+### 高级配置
+
+| 配置项 | 类型 | 默认值 | 说明 |
+|--------|------|--------|------|
+| `enableMockRole` | `boolean` | `false` | 是否启用角色模拟功能 |
+
+#### enableMockRole
+
+启用角色模拟功能，允许通过 Cookie 模拟用户角色，主要用于开发和测试环境。
+
+```typescript
+AuthZPaasModule.forRoot({
+  enableMockRole: true,  // 启用角色模拟
+})
+```
+
+**功能特性**
+
+- 通过 Cookie `mockRoles` 设置模拟角色
+- 支持多个角色：`admin,editor,viewer`
+- 仅在开发/测试环境使用，生产环境应关闭
+
+**使用示例**
+
+```typescript
+// 1. 开启角色模拟
+POST /api/permissions/mock/enable
+{
+  "roles": ["admin", "editor"]
+}
+
+// 2. 使用 @MockRoles 装饰器获取模拟角色
+@Get('test')
+testMockRoles(@MockRoles() mockRoles: string[]) {
+  return { mockRoles };
+}
+
+// 3. 关闭角色模拟
+POST /api/permissions/mock/disable
+```
+
+## 装饰器使用
+
+> 💡 **装饰器是最常用的权限控制方式**，推荐优先使用装饰器来进行权限检查，简单、直观、声明式。
+
+### 1. CanRole - 角色检查
+
+使用 `@CanRole()` 装饰器检查用户角色。
+
+#### 示例 1: 单个角色
+
+```typescript
+import { Controller, Get } from '@nestjs/common';
+import { CanRole } from '@lark-apaas/nestjs-authzpaas';
+
+@Controller('demo')
+export class DemoController {
+  // 需要 admin 角色
+  @CanRole(['admin'])
+  @Get('admin-only')
+  adminOnly() {
+    return {
+      message: '✅ 这是管理员专属接口',
+      timestamp: new Date(),
+    };
+  }
+}
+```
+
+#### 示例 2: 多个角色（OR 逻辑，默认）
+
+```typescript
+@Controller('content')
+export class ContentController {
+  // 拥有 admin 或 editor 任一角色即可访问
+  @CanRole(['admin', 'editor'])
+  @Get('manage')
+  manage() {
+    return '管理内容';
+  }
+}
+```
+
+#### 示例 3: 多个角色（AND 逻辑）
+
+```typescript
+@Controller('sensitive')
+export class SensitiveController {
+  // 需要同时拥有 admin 和 superuser 角色
+  @CanRole(['admin', 'superuser'], true)
+  @Get('dangerous')
+  dangerousOperation() {
+    return '危险操作';
+  }
+}
+```
+
+### 2. CanPermission - 权限检查
+
+使用 `@CanPermission()` 装饰器检查用户对特定资源的操作权限。
+
+#### 示例 1: 单个操作检查
+
+```typescript
+import { Controller, Get } from '@nestjs/common';
+import { CanPermission } from '@lark-apaas/nestjs-authzpaas';
+
+@Controller('demo')
+export class DemoController {
+  // 需要对 User 资源有 read 权限
+  @CanPermission([{ actions: ['read'], subject: 'User' }])
+  @Get('read-user')
+  readUser() {
+    return {
+      message: '✅ 用户读取成功（需要 read 权限）',
+    };
+  }
+
+  // 需要对 User 资源有 create 权限
+  @CanPermission([{ actions: ['create'], subject: 'User' }])
+  @Get('create-user')
+  createUser() {
+    return {
+      message: '✅ 用户创建成功（需要 create 权限）',
+    };
+  }
+}
+```
+
+#### 示例 2: 多个操作检查（AND 逻辑，默认）
+
+```typescript
+@Controller('articles')
+export class ArticleController {
+  // 需要同时拥有 read 和 update 权限
+  @CanPermission([{ 
+    actions: ['read', 'update'], 
+    subject: 'Article',
+    requireAll: true  // 默认为 true，可省略
+  }])
+  @Get('publish')
+  publish() {
+    return '发布文章';
+  }
+}
+```
+
+#### 示例 3: 多个操作检查（OR 逻辑）
+
+```typescript
+@Controller('articles')
+export class ArticleController {
+  // 拥有 read 或 preview 任一权限即可
+  @CanPermission([{ 
+    actions: ['read', 'preview'], 
+    subject: 'Article',
+    requireAll: false  // OR 逻辑
+  }])
+  @Get('preview')
+  preview() {
+    return '预览文章';
+  }
+}
+```
+
+#### 示例 4: 多个资源权限检查
+
+```typescript
+@Controller('articles')
+export class ArticleController {
+  // 需要同时满足：能读文章 AND 能创建评论
+  @CanPermission([
+    { actions: ['read'], subject: 'Article' },
+    { actions: ['create'], subject: 'Comment' }
+  ])
+  @Get('comment')
+  addComment() {
+    return '添加评论';
+  }
+
+  // 需要同时满足：能读文章 AND (能更新或删除评论)
+  @CanPermission([
+    { actions: ['read'], subject: 'Article' },
+    { actions: ['update', 'delete'], subject: 'Comment', requireAll: false }
+  ])
+  @Get('manage-comment')
+  manageComment() {
+    return '管理评论';
+  }
+}
+```
+
+### 3. UserId - 获取用户ID
+
+使用 `@UserId()` 参数装饰器获取当前用户ID。
+
+#### 示例 1: 基本用法
+
+```typescript
+import { Controller, Get } from '@nestjs/common';
+import { UserId } from '@lark-apaas/nestjs-authzpaas';
+
+@Controller('demo')
+export class DemoController {
+  @Get('profile')
+  getProfile(@UserId() userId: string) {
+    return {
+      message: '获取用户资料',
+      userId,
+    };
+  }
+}
+```
+
+#### 示例 2: 结合 PermissionService 使用
+
+```typescript
+import { Controller, Get } from '@nestjs/common';
+import { UserId, PermissionService } from '@lark-apaas/nestjs-authzpaas';
+
+@Controller('demo')
+export class DemoController {
+  constructor(private readonly permissionService: PermissionService) {}
+
+  @Get('check-permission')
+  async checkPermission(@UserId() userId: string) {
+    // 手动检查权限
+    const hasPermission = await this.permissionService.checkPermissions(
+      [{ actions: ['read'], subject: 'User' }], 
+      userId
+    );
+    
+    return {
+      message: '权限检查成功',
+      userId,
+      hasPermission,
+    };
+  }
+}
+```
+
+#### 示例 3: 使用 CASL Ability
+
+```typescript
+import { Controller, Get } from '@nestjs/common';
+import { UserId, PermissionService, ROLE_SUBJECT } from '@lark-apaas/nestjs-authzpaas';
+
+@Controller('demo')
+export class DemoController {
+  constructor(private readonly permissionService: PermissionService) {}
+
+  @Get('ability')
+  async getAbility(@UserId() userId: string) {
+    const ability = await this.permissionService.getAbility(userId);
+    
+    // 使用 CASL Ability 检查权限
+    const canReadUser = ability.can('read', 'User');
+    const canWriteTask = ability.can('write', 'Task');
+    const isAdmin = ability.can('admin', ROLE_SUBJECT);
+    
+    return {
+      userId,
+      permissions: {
+        canReadUser,
+        canWriteTask,
+        isAdmin,
+      },
+    };
+  }
+}
+```
+
+### 4. MockRoles - 角色模拟
+
+使用 `@MockRoles()` 参数装饰器获取模拟角色，仅在 `enableMockRole: true` 时有效。
+
+#### 示例 1: 基本用法
+
+```typescript
+import { Controller, Get } from '@nestjs/common';
+import { MockRoles } from '@lark-apaas/nestjs-authzpaas';
+
+@Controller('demo')
+export class DemoController {
+  @Get('mock-roles')
+  getMockRoles(@MockRoles() mockRoles: string[]) {
+    return {
+      message: '获取模拟角色',
+      mockRoles: mockRoles || [],
+      hasMockRoles: !!mockRoles,
+    };
+  }
+}
+```
+
+#### 示例 2: 结合权限检查
+
+```typescript
+@Controller('admin')
+export class AdminController {
+  @Get('test')
+  @CanRole(['admin'])  // 会优先使用模拟角色进行验证
+  testWithMockRoles(@MockRoles() mockRoles: string[]) {
+    return {
+      message: '管理员测试接口',
+      mockRoles,
+    };
+  }
+}
+```
+
+### 5. 装饰器组合使用
+
+可以组合使用多个装饰器实现复杂的鉴权需求。
+
+#### 示例 1: 角色 + 权限
+
+```typescript
+import { Controller, Get } from '@nestjs/common';
+import { CanRole, CanPermission } from '@lark-apaas/nestjs-authzpaas';
+
+@Controller('posts')
+export class PostController {
+  // 需要 editor 角色 + 对 Post 有 delete 权限
+  @CanRole(['editor'])
+  @CanPermission([{ actions: ['delete'], subject: 'Post' }])
+  @Get('delete')
+  delete() {
+    return '删除帖子';
+  }
+}
+```
+
+#### 示例 2: 多层权限检查
+
+```typescript
+@Controller('tasks')
+export class TasksController {
+  // 需要 admin 或 manager 角色 + Task 的 manage 权限
+  @CanRole(['admin', 'manager'])
+  @CanPermission([{ actions: ['manage'], subject: 'Task' }])
+  @Get('manage')
+  manageTasks() {
+    return '管理任务';
+  }
+}
+```
+
+## 核心组件
+
+> 📚 **核心组件是装饰器的底层实现**，了解核心组件有助于深入理解权限系统的工作原理。
+
+### AuthZPaasGuard
+
+`AuthZPaasGuard` 是一个全局守卫，会自动拦截所有请求并执行以下操作：
+
+1. **提取用户ID**: 从 `req.userContext.userId` 中提取用户ID
+2. **角色检查**: 如果使用了 `@CanRole()`，检查用户角色
+3. **权限检查**: 如果使用了 `@CanPermission()`，检查用户权限
+4. **环境检查**: 如果使用了 `@RequireEnvironment()`，检查环境条件
+5. **注入权限数据**: 将权限数据附加到 `req.userPermissions`
+
+**工作流程**:
+
+```yaml
+   请求 
+    ↓
+AuthZPaasGuard
+    ↓
+提取 userId
+    ↓
+检查角色/权限
+    ↓
+注入权限数据
+    ↓
+Controller
+```
+
+**配置**: `AuthZPaasGuard` 会在模块导入时自动注册为全局守卫，无需手动配置。
+
+### PermissionService
+
+`PermissionService` 提供权限管理的核心功能。
+
+#### 主要方法
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import { PermissionService } from '@lark-apaas/nestjs-authzpaas';
+
+@Injectable()
+export class YourService {
+  constructor(private readonly permissionService: PermissionService) {}
+
+  async checkUserPermission(userId: string) {
+    // 1. 获取用户权限数据（带缓存）
+    const permissionData = await this.permissionService.getUserPermissions(userId);
+    console.log('用户角色:', permissionData.roles);
+    console.log('用户权限:', permissionData.permissions);
+
+    // 2. 获取用户的 CASL Ability 实例
+    const ability = await this.permissionService.getAbility(userId);
+    
+    // 使用 Ability 检查权限
+    const canReadUser = ability.can('read', 'User');
+    const canCreateTask = ability.can('create', 'Task');
+    const canManageAll = ability.can('manage', 'all');
+
+    // 3. 检查权限要求
+    const hasPermission = await this.permissionService.checkPermissions(
+      [{ actions: ['read'], subject: 'User' }],
+      userId
+    );
+
+    // 4. 清除用户缓存（权限变更时）
+    this.permissionService.clearUserCache(userId);
+
+    // 5. 清除所有缓存
+    this.permissionService.clearAllCache();
+
+    // 6. 获取缓存统计
+    const stats = this.permissionService.getCacheStats();
+    console.log('缓存统计:', stats);
+  }
+}
+```
+
+#### 权限缓存机制
+
+- **自动缓存**: 权限数据和 Ability 实例会自动缓存
+- **防重复请求**: 同时发起的相同请求会共享同一个 Promise
+- **TTL 控制**: 通过配置的 `ttl` 自动过期
+- **手动清除**: 可以调用 `clearUserCache()` 或 `clearAllCache()`
+
+### RolesMiddleware
+
+`RolesMiddleware` 是一个中间件，用于在请求处理前自动获取用户角色信息。
+
+#### 工作原理
+
+1. 从 `req.userContext.userId` 中提取用户ID
+2. 调用 `PermissionService.getUserPermissions()` 获取权限数据
+3. 将角色列表注入到 `req.userContext.userRoles`
+4. 如果获取失败，记录警告但不阻塞请求（由 Guard 处理）
+
+#### 配置示例
+
+```typescript
+export class AppModule implements NestModule {
+  configure(consumer: MiddlewareConsumer) {
+    consumer
+      .apply(RolesMiddleware)
+      .exclude('mock-api/(.*)')  // 排除特定路由
+      .forRoutes('*');
+  }
+}
+```
+
+#### 类型扩展
+
+`RolesMiddleware` 会扩展 Express Request 类型：
+
+```typescript
+declare global {
+  namespace Express {
+    interface Request {
+      userContext: {
+        userId?: string;
+        tenantId?: number;
+        appId?: string;
+        userRoles?: string[];  // RolesMiddleware 注入
+      }
+    }
+  }
+}
+```
+
+## 高级用法
+
+### 1. 手动权限检查
+
+在某些场景下，你可能需要在业务逻辑中手动检查权限，而不是使用装饰器：
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import { PermissionService } from '@lark-apaas/nestjs-authzpaas';
+
+@Injectable()
+export class TasksService {
+  constructor(private readonly permissionService: PermissionService) {}
+
+  async processTask(userId: string, taskId: string) {
+    // 获取用户权限数据
+    const permissionData = await this.permissionService.getUserPermissions(userId);
+    
+    // 检查权限
+    const canUpdate = await this.permissionService.checkPermissions(
+      [{ actions: ['update'], subject: 'Task' }],
+      userId
+    );
+
+    if (!canUpdate) {
+      throw new Error('没有权限');
+    }
+
+    // 执行业务逻辑
+    return '任务处理成功';
+  }
+}
+```
+
+### 2. 使用 CASL Ability 进行细粒度控制
+
+CASL Ability 提供了更灵活的权限检查方式：
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import { PermissionService, ROLE_SUBJECT } from '@lark-apaas/nestjs-authzpaas';
+
+@Injectable()
+export class ArticleService {
+  constructor(private readonly permissionService: PermissionService) {}
+
+  async canUserEditArticle(userId: string, articleId: string) {
+    const ability = await this.permissionService.getAbility(userId);
+    
+    // 检查是否可以更新文章
+    if (ability.can('update', 'Article')) {
+      return true;
+    }
+    
+    // 或者检查是否有 manage all 权限
+    if (ability.can('manage', 'all')) {
+      return true;
+    }
+    
+    // 检查角色
+    if (ability.can('admin', ROLE_SUBJECT)) {
+      return true;
+    }
+    
+    return false;
+  }
+}
+```
+
+### 3. 权限缓存管理
+
+当用户权限发生变更时，需要清除缓存：
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import { PermissionService } from '@lark-apaas/nestjs-authzpaas';
+
+@Injectable()
+export class UserManagementService {
+  constructor(private readonly permissionService: PermissionService) {}
+
+  async updateUserRole(userId: string, newRole: string) {
+    // 1. 更新用户角色（调用你的业务逻辑）
+    await this.updateRoleInDatabase(userId, newRole);
+    
+    // 2. 清除该用户的权限缓存
+    this.permissionService.clearUserCache(userId);
+    
+    return '角色更新成功';
+  }
+
+  async batchUpdatePermissions() {
+    // 批量更新权限后，清除所有缓存
+    this.permissionService.clearAllCache();
+    
+    return '权限批量更新成功';
+  }
+
+  private async updateRoleInDatabase(userId: string, newRole: string) {
+    // 实现你的数据库更新逻辑
+  }
+}
+```
+
+### 4. 自定义权限 API 响应处理
+
+如果你的权限 API 返回的数据格式不同，可以通过自定义逻辑转换：
+
+```typescript
+// 你的权限 API 应该返回以下格式：
+interface PermissionApiResponse {
+  userId: string;
+  roles: string[];  // 角色列表，如 ['admin', 'editor']
+  permissions: Array<{
+    id: string;
+    name: string;
+    sub: string;      // 资源类型，如 'User', 'Task'
+    actions: string[]; // 操作列表，如 ['create', 'read', 'update']
+  }>;
+  fetchedAt?: Date;
+}
+```
+
+## 权限 API 规范
+
+### 请求格式
+
+权限 API 的 endpoint 配置支持动态参数替换：
+
+```typescript
+AuthZPaasModule.forRoot({
+  permissionApi: {
+    baseUrl: 'http://localhost:3000',
+    endpoint: '/mock-api/users/:userId/permissions',  // :userId 会被替换
+    timeout: 5000,
+  },
+})
+```
+
+### 响应格式
+
+您的权限 API 必须返回以下格式的 JSON 数据：
+
+```json
+{
+  "userId": "user-admin",
+  "roles": ["admin_role", "editor_role"],
+  "permissions": [
+    {
+      "id": "1",
+      "name": "user.create",
+      "sub": "User",
+      "actions": ["create"]
+    },
+    {
+      "id": "2",
+      "name": "user.read",
+      "sub": "User",
+      "actions": ["read"]
+    },
+    {
+      "id": "3",
+      "name": "task.manage",
+      "sub": "Task",
+      "actions": ["manage"]
+    }
+  ],
+  "fetchedAt": "2024-01-01T00:00:00.000Z"
+}
+```
+
+### 字段说明
+
+- `userId`: 用户ID（必需）
+- `roles`: 角色名称列表（必需）
+  - 可以是字符串数组 `['admin', 'editor']`
+  - 或角色对象数组（会自动提取 `name` 字段）
+- `permissions`: 权限列表（必需）
+  - `id`: 权限ID
+  - `name`: 权限名称
+  - `sub`: 资源类型（如 `User`、`Task`、`Article`）
+  - `actions`: 操作列表（如 `['create', 'read', 'update', 'delete']` 或 `['manage']`）
+- `fetchedAt`: 获取时间（可选，SDK 会自动添加）
+
+### Mock 权限 API 示例
+
+参考 `node-demo` 中的实现：
+
+```typescript
+import { Controller, Get, Param } from '@nestjs/common';
+import { Public, Permission, UserRole } from '@lark-apaas/nestjs-authzpaas';
+
+@Controller('mock-api/users')
+@Public()  // 重要：跳过 AuthZPaasGuard，避免循环调用
+export class MockPermissionController {
+  // 模拟用户权限数据库
+  private readonly mockPermissions: Record<string, { 
+    roles: UserRole[], 
+    permissions: Permission[] 
+  }> = {
+    'user-admin': {
+      roles: [
+        { id: '1', name: 'admin', description: '管理员' },
+      ],
+      permissions: [
+        { id: '1', name: 'user.create', sub: 'User', actions: ['create'] },
+        { id: '2', name: 'user.read', sub: 'User', actions: ['read'] },
+        { id: '3', name: 'task.manage', sub: 'Task', actions: ['manage'] },
+      ],
+    },
+    'user-normal': {
+      roles: [
+        { id: '2', name: 'reader', description: '只读用户' },
+      ],
+      permissions: [
+        { id: '4', name: 'user.read', sub: 'User', actions: ['read'] },
+        { id: '5', name: 'task.read', sub: 'Task', actions: ['read'] },
+      ],
+    },
+  };
+
+  @Get(':userId/permissions')
+  getUserPermissions(@Param('userId') userId: string) {
+    const permissions = this.mockPermissions[userId] || this.mockPermissions['user-guest'];
+    
+    return {
+      userId,
+      ...permissions,
+      fetchedAt: new Date(),
+    };
+  }
+}
+```
+
+## 错误处理
+
+### 1. 使用内置异常过滤器
+
+模块提供了 `AuthZPaasExceptionFilter` 用于统一处理权限异常：
+
+```typescript
+import { Module } from '@nestjs/common';
+import { APP_FILTER } from '@nestjs/core';
+import { AuthZPaasExceptionFilter } from '@lark-apaas/nestjs-authzpaas';
+
+@Module({
+  providers: [
+    {
+      provide: APP_FILTER,
+      useClass: AuthZPaasExceptionFilter,
+    },
+  ],
+})
+export class AppModule {}
+```
+
+### 2. 自定义异常处理
+
+```typescript
+import { ExceptionFilter, Catch, ArgumentsHost } from '@nestjs/common';
+import { PermissionDeniedException } from '@lark-apaas/nestjs-authzpaas';
+
+@Catch(PermissionDeniedException)
+export class CustomPermissionExceptionFilter implements ExceptionFilter {
+  catch(exception: PermissionDeniedException, host: ArgumentsHost) {
+    const ctx = host.switchToHttp();
+    const response = ctx.getResponse();
+    
+    response.status(403).json({
+      statusCode: 403,
+      message: exception.message,
+      error: 'Forbidden',
+      timestamp: new Date().toISOString(),
+    });
+  }
+}
+```
+
+### 3. 常见异常类型
+
+| 异常 | 说明 | HTTP 状态码 |
+|------|------|------------|
+| `PermissionDeniedException.unauthenticated()` | 未认证（无 userId） | 403 |
+| `PermissionDeniedException.roleRequired()` | 缺少必需的角色 | 403 |
+| `PermissionDeniedException.permissionDenied()` | 缺少必需的权限 | 403 |
+| `PermissionDeniedException.environmentRestricted()` | 环境限制（如 IP 白名单） | 403 |
+
+## 最佳实践
+
+### 1. 使用有意义的资源和操作名称
+
+```typescript
+// ✅ 好的做法：清晰的资源和操作命名
+@CanPermission([{ actions: ['create'], subject: 'Article' }])
+@CanPermission([{ actions: ['update'], subject: 'User' }])
+@CanPermission([{ actions: ['delete'], subject: 'Task' }])
+
+// ❌ 避免使用：模糊的命名
+@CanPermission([{ actions: ['action1'], subject: 'resource1' }])
+```
+
+### 2. 遵循 CRUD 标准操作
+
+建议使用标准的 CRUD 操作名称：
+
+- `create`: 创建资源
+- `read`: 读取资源
+- `update`: 更新资源
+- `delete`: 删除资源
+- `manage`: 完全管理权限（包含所有操作）
+
+```typescript
+// 推荐的权限设计
+@CanPermission([{ actions: ['read'], subject: 'User' }])
+@CanPermission([{ actions: ['manage'], subject: 'Task' }])  // manage 包含所有操作
+```
+
+### 3. 合理使用 requireAll
+
+- **默认 `requireAll: true`**: 适用于需要同时满足多个权限的场景（AND 逻辑）
+- **`requireAll: false`**: 适用于满足任一权限即可的场景（OR 逻辑）
+
+```typescript
+// AND 逻辑：需要同时拥有 read 和 update 权限
+@CanPermission([{ 
+  actions: ['read', 'update'], 
+  subject: 'Article',
+  requireAll: true  // 默认值，可省略
+}])
+
+// OR 逻辑：拥有 read 或 preview 任一权限即可
+@CanPermission([{ 
+  actions: ['read', 'preview'], 
+  subject: 'Article',
+  requireAll: false
+}])
+```
+
+### 4. 权限粒度设计
+
+细粒度权限优于粗粒度权限：
+
+```typescript
+// ✅ 推荐：细粒度权限，更精确的控制
+@CanPermission([{ actions: ['publish'], subject: 'Article' }])
+@CanPermission([{ actions: ['archive'], subject: 'Article' }])
+
+// ⚠️ 谨慎使用：粗粒度权限，权限范围过大
+@CanPermission([{ actions: ['manage'], subject: 'Article' }])
+```
+
+### 5. 缓存策略
+
+根据业务需求调整缓存配置：
+
+```typescript
+AuthZPaasModule.forRoot({
+  cache: {
+    ttl: 60,         // 开发环境：较短的缓存时间，便于测试
+    // ttl: 300,     // 生产环境：较长的缓存时间，提升性能
+    max: 1000,       // 根据用户量调整
+    enabled: true,   // 生产环境建议开启
+  },
+})
+```
+
+**重要**：权限变更后务必清除缓存
+
+```typescript
+// 单用户权限变更
+this.permissionService.clearUserCache(userId);
+
+// 批量权限变更
+this.permissionService.clearAllCache();
+```
+
+### 6. 中间件配置顺序
+
+确保中间件按正确的顺序配置：
+
+```typescript
+export class AppModule implements NestModule {
+  configure(consumer: MiddlewareConsumer) {
+    // 1️⃣ 第一步：UserContextMiddleware 提取用户信息
+    consumer.apply(UserContextMiddleware).forRoutes('*');
+    
+    // 2️⃣ 第二步：RolesMiddleware 获取用户角色
+    //    注意：必须排除权限 API 路由
+    consumer
+      .apply(RolesMiddleware)
+      .exclude('mock-api/(.*)')
+      .forRoutes('*');
+  }
+}
+```
+
+### 7. 公开接口使用 @Public()
+
+对于不需要鉴权的接口，务必使用 `@Public()` 装饰器：
+
+```typescript
+// ✅ 好的做法
+@Controller('health')
+export class HealthController {
+  @Get()
+  @Public()
+  check() {
+    return { status: 'ok' };
+  }
+}
+
+// ❌ 避免：未标记 @Public()，会触发鉴权检查
+@Controller('health')
+export class HealthController {
+  @Get()
+  check() {
+    return { status: 'ok' };
+  }
+}
+```
+
+### 8. 组合使用装饰器
+
+对于复杂的权限需求，可以组合使用多个装饰器：
+
+```typescript
+@Controller('admin')
+export class AdminController {
+  // 角色检查 + 权限检查
+  @CanRole(['admin'])
+  @CanPermission([{ actions: ['manage'], subject: 'System' }])
+  @Get('system')
+  manageSystem() {
+    return '系统管理';
+  }
+}
+```
+
+### 9. 使用 TypeScript 类型提示
+
+充分利用 TypeScript 的类型系统：
+
+```typescript
+import { 
+  CanPermission, 
+  CanRole,
+  PermissionService,
+  ROLE_SUBJECT 
+} from '@lark-apaas/nestjs-authzpaas';
+
+// TypeScript 会自动提供代码提示和类型检查
+```
+
+### 10. 高级配置使用建议
+
+#### enableMockRole 使用场景
+
+```typescript
+// ✅ 开发环境：启用角色模拟
+AuthZPaasModule.forRoot({
+  enableMockRole: process.env.NODE_ENV === 'development',
+})
+
+// ✅ 测试环境：便于自动化测试
+AuthZPaasModule.forRoot({
+  enableMockRole: process.env.NODE_ENV === 'test',
+})
+
+// ❌ 生产环境：必须关闭
+AuthZPaasModule.forRoot({
+  enableMockRole: false,  // 生产环境安全考虑
+})
+```
+
+**使用建议**：
+- 开发环境：便于测试不同角色权限
+- 测试环境：自动化测试时模拟不同用户
+- 生产环境：必须关闭，避免安全风险
+
+### 11. 测试建议
+
+编写单元测试时，可以 mock `PermissionService`：
+
+```typescript
+describe('TasksController', () => {
+  let controller: TasksController;
+  let permissionService: PermissionService;
+
+  beforeEach(async () => {
+    const module = await Test.createTestingModule({
+      controllers: [TasksController],
+      providers: [
+        {
+          provide: PermissionService,
+          useValue: {
+            getUserPermissions: jest.fn(),
+            getAbility: jest.fn(),
+            checkPermissions: jest.fn(),
+          },
+        },
+      ],
+    }).compile();
+
+    controller = module.get<TasksController>(TasksController);
+    permissionService = module.get<PermissionService>(PermissionService);
+  });
+
+  it('should check permissions', async () => {
+    jest.spyOn(permissionService, 'checkPermissions').mockResolvedValue(true);
+    
+    // 测试逻辑...
+  });
+});
+```
+
+## 完整示例
+
+查看 `examples/node-demo` 目录获取完整的工作示例，包括：
+
+- ✅ 模块配置和中间件设置
+- ✅ Mock 权限 API 实现
+- ✅ 角色和权限装饰器使用
+- ✅ 手动权限检查
+- ✅ CASL Ability 使用
+- ✅ 测试脚本
+
+运行示例：
+
+```bash
+cd examples/node-demo
+yarn install
+yarn start
+
+# 测试不同用户的权限
+curl -H "x-user-id: user-admin" http://localhost:3000/demo/admin-only
+curl -H "x-user-id: user-normal" http://localhost:3000/demo/reader-only
+```
+
+## 常见问题
+
+### Q: 如何自定义提取 userId 的逻辑？
+
+A: 可以自定义 `UserContextMiddleware` 或扩展 `AuthZPaasGuard`。通常在 `UserContextMiddleware` 中从 JWT、Session 或 Header 中提取用户信息并设置到 `req.userContext.userId`。
+
+### Q: manage 权限和其他权限的关系？
+
+A: `manage` 是特殊的操作类型，在 CASL 中表示"所有权限"。如果用户有某个资源的 `manage` 权限，则自动拥有该资源的所有操作权限（`create`、`read`、`update`、`delete` 等）。
+
+### Q: 如何实现数据级权限控制（如只能访问自己创建的数据）？
+
+A: 可以结合 CASL 的 conditions 功能和业务逻辑实现。在 `PermissionService` 中手动检查时，可以传入资源实例进行细粒度验证。
+
+### Q: 性能优化建议？
+
+A:
+
+- 启用缓存（默认启用）
+- 根据业务调整 TTL（生产环境可设置 5-15 分钟）
+- 权限变更时及时清除缓存
+- 对于高频接口，考虑将权限检查前置到网关层
+
+### Q: enableMockRole 的安全风险？
+
+A:
+
+- 角色模拟功能仅在开发/测试环境使用
+- 生产环境必须设置 `enableMockRole: false`
+- 模拟角色通过 Cookie 传递，存在被恶意利用的风险
+- 建议在环境变量中控制：`enableMockRole: process.env.NODE_ENV !== 'production'`
+
+## License
+
+MIT
+
+## 相关链接
+
+- [CASL 文档](https://casl.js.org/)
+- [NestJS 文档](https://docs.nestjs.com/)
+- [示例项目](../../examples/node-demo)