@lark-apaas/nestjs-authzpaas 0.1.0-alpha.10 → 0.1.0-alpha.12

package/README.md

@@ -18,20 +18,14 @@
 本模块采用以下权限模型：
 
 - **角色 (Role)**: 用户所属的角色，如 `admin`、`editor`、`viewer`
-- **权限 (Permission)**: 对特定资源的操作权限，由 `actions` + `subject` 组成
-  - `actions`: 操作类型，如 `create`、`read`、`update`、`delete`、`manage`
-  - `subject`: 资源类型，如 `User`、`Task`、`Article`
 
 ### 核心组件
 
 | 组件 | 类型 | 说明 |
 |------|------|------|
 | `AuthZPaasGuard` | 全局守卫 | 自动拦截所有请求，执行鉴权检查 |
-| `PermissionService` | 服务 | 提供权限获取、检查、缓存管理等功能 |
 | `RolesMiddleware` | 中间件 | 自动获取并注入用户角色信息到请求上下文 |
 | `CanRole` | 装饰器 | 声明式角色检查 |
-| `CanPermission` | 装饰器 | 声明式权限检查 |
-| `UserId` | 参数装饰器 | 获取当前用户ID |
 
 ## 快速开始
 
@@ -57,39 +51,13 @@ import { UserContextMiddleware } from '@lark-apaas/fullstack-nestjs-core';
     // 配置 AuthZPaas 模块
     AuthZPaasModule.forRoot({
       permissionApi: {
-        // 权限 API 配置
-        baseUrl: 'http://localhost:3000',
-        endpoint: '/mock-api/users/:userId/permissions',
-        timeout: 5000,
+        timeout: 5000, // 权限 API 超时时间（毫秒）, 默认 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. 异步配置（可选）
@@ -107,15 +75,8 @@ import { ConfigModule, ConfigService } from '@nestjs/config';
       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,
-        },
       }),
     }),
   ],
@@ -129,50 +90,7 @@ 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
-```
+| `permissionApi` | `PermissionApiConfig` | - | 权限 API 配置 |
 
 ## 装饰器使用
 
@@ -202,7 +120,7 @@ export class DemoController {
 }
 ```
 
-#### 示例 2: 多个角色（OR 逻辑，默认）
+#### 示例 2: 多个角色（OR 逻辑）
 
 ```typescript
 @Controller('content')
@@ -216,20 +134,6 @@ export class ContentController {
 }
 ```
 
-#### 示例 3: 多个角色（AND 逻辑）
-
-```typescript
-@Controller('sensitive')
-export class SensitiveController {
-  // 需要同时拥有 admin 和 superuser 角色
-  @CanRole(['admin', 'superuser'], true)
-  @Get('dangerous')
-  dangerousOperation() {
-    return '危险操作';
-  }
-}
-```
-
 ## 核心组件
 
 > 📚 **核心组件是装饰器的底层实现**，了解核心组件有助于深入理解权限系统的工作原理。
@@ -307,17 +211,6 @@ export class YourService {
 }
 ```
 
-#### 权限缓存机制
-
-- **自动缓存**: 权限数据和 Ability 实例会自动缓存
-- **防重复请求**: 同时发起的相同请求会共享同一个 Promise
-- **TTL 控制**: 通过配置的 `ttl` 自动过期
-- **手动清除**: 可以调用 `clearUserCache()` 或 `clearAllCache()`
-
-### RolesMiddleware
-
-`RolesMiddleware` 是一个中间件，用于在请求处理前自动获取用户角色信息。
-
 #### 工作原理
 
 1. 从 `req.userContext.userId` 中提取用户ID
@@ -325,38 +218,6 @@ export class YourService {
 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. 手动权限检查
@@ -426,60 +287,6 @@ export class ArticleService {
 }
 ```
 
-### 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 规范
 
 ### 请求格式
@@ -489,8 +296,6 @@ interface PermissionApiResponse {
 ```typescript
 AuthZPaasModule.forRoot({
   permissionApi: {
-    baseUrl: 'http://localhost:3000',
-    endpoint: '/mock-api/users/:userId/permissions',  // :userId 会被替换
     timeout: 5000,
   },
 })
@@ -502,28 +307,7 @@ AuthZPaasModule.forRoot({
 
 ```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"]
-    }
-  ],
+  "roles": ["role_admin", "role_editor"],
   "fetchedAt": "2024-01-01T00:00:00.000Z"
 }
 ```
@@ -532,110 +316,12 @@ AuthZPaasModule.forRoot({
 
 - `userId`: 用户ID（必需）
 - `roles`: 角色名称列表（必需）
-  - 可以是字符串数组 `['admin', 'editor']`
-  - 或角色对象数组（会自动提取 `name` 字段）
-- `permissions`: 权限列表（必需）
-  - `id`: 权限ID
-  - `name`: 权限名称
-  - `sub`: 资源类型（如 `User`、`Task`、`Article`）
-  - `actions`: 操作列表（如 `['create', 'read', 'update', 'delete']` 或 `['manage']`）
+  - 字符串数组 `['role_admin', 'role_editor']`
 - `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. 常见异常类型
+### 1. 常见异常类型
 
 | 异常 | 说明 | HTTP 状态码 |
 |------|------|------------|
@@ -646,156 +332,7 @@ export class CustomPermissionExceptionFilter implements ExceptionFilter {
 
 ## 最佳实践
 
-### 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 类型提示
+### 1. 使用 TypeScript 类型提示
 
 充分利用 TypeScript 的类型系统：
 
@@ -810,33 +347,7 @@ import {
 // 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. 测试建议
+### 2. 测试建议
 
 编写单元测试时，可以 mock `PermissionService`：
 
@@ -895,38 +406,6 @@ 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