@seed-fe/permission/README.md

Framework-agnostic permission management library with batching, caching, and debouncing

# @seed-fe/permission

一个与框架无关的前端权限管理核心库，提供高性能、可扩展的权限检查能力。

## 特性

- 🚀 **框架无关**：纯 JavaScript/TypeScript 实现，可用于任何前端框架
- ⚡ **高性能优化**：基于 `@seed-fe/batch-request` 的智能批处理和缓存
- 🔒 **类型安全**：完整的 TypeScript 类型定义和支持
- 🔧 **高度可配置**：支持自定义批处理、缓存和服务选项
- 📦 **轻量级**：基于成熟的批处理库，代码更简洁高效
- 🔄 **统一架构**：与 React/Vue 权限库共享相同的底层实现

## 安装

```bash
npm install @seed-fe/permission
# 或
yarn add @seed-fe/permission
# 或 (推荐)
pnpm add @seed-fe/permission
```

## 快速开始

### 1. 注册权限服务

```typescript
import { registerPermissionService } from '@seed-fe/permission';

// 注册权限检查服务
registerPermissionService(async (configs) => {
  const response = await fetch('/api/check-permissions', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(configs)
  });
  return response.json();
});
```

### 2. 检查权限

```typescript
import { checkPermission } from '@seed-fe/permission';

// 单个权限检查
const canEdit = await checkPermission('user.edit');

// 多权限码检查（任一满足）
const canManage = await checkPermission({
  code: ['user.edit', 'user.delete'],
  mode: 'any'
});

// 带业务参数的权限检查
const canAccessResource = await checkPermission({
  code: 'resource.access',
  biz: { resourceId: '123', departmentId: 'dept1' }
});
```

## 使用示例

### 基础权限检查

```typescript
import { checkPermission } from '@seed-fe/permission';

async function handleUserAction() {
  // 单权限检查
  const canEdit = await checkPermission('user.edit');

  if (canEdit) {
    // 执行编辑操作
    editUser();
  } else {
    // 显示无权限提示
    showNoPermissionMessage();
  }
}

// 多权限检查（需要同时满足所有权限）
const canManageUsers = await checkPermission({
  code: ['user.create', 'user.edit', 'user.delete'],
  mode: 'all'  // 默认模式
});

// 多权限检查（只需满足其中一个权限）
const canAccessAdmin = await checkPermission({
  code: ['admin', 'super_admin'],
  mode: 'any'
});
```

### 高级配置

```typescript
import { configurePermission } from '@seed-fe/permission';

// 使用配置函数
configurePermission({
  permissionService: async (configs) => {
    const response = await fetch('/api/permissions/check', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(configs)
    });
    return response.json();
  },
  permissionServiceOptions: {
    batch: { delay: 50, maxSize: 100 },
    cache: { enable: true, ttl: 300000 } // 注意：默认缓存是关闭的，需要显式启用
  }
});
```

### 临时权限服务

```typescript
// 为特定检查使用临时权限服务
const hasSpecialPermission = await checkPermission(
  'special.feature',
  async (configs) => {
    // 特殊的权限检查逻辑
    return specialPermissionCheck(configs);
  }
);
```

### 缓存管理

```typescript
import { clearPermissionCache, getPermissionStats } from '@seed-fe/permission';

// 用户登出时清除权限缓存
function logout() {
  clearPermissionCache();
  // 其他登出逻辑...
}

// 获取统计信息用于调试
const stats = getPermissionStats();
console.log('是否已注册服务:', stats.hasGlobalService);
console.log('是否有批处理函数:', stats.hasBatchFunction);
```

### 自动批处理示例

```typescript
// 这些权限检查会自动合并为一个批处理请求
const [canEdit, canDelete, canView] = await Promise.all([
  checkPermission('user.edit'),
  checkPermission('user.delete'),
  checkPermission('user.view')
]);
```

## API 参考

### 核心函数

| 函数名 | 描述 | 参数 | 返回值 |
|--------|------|------|--------|
| `registerPermissionService` | 注册全局权限服务 | `service, options?` | `void` |
| `checkPermission` | 检查权限 | `permission, customService?` | `Promise<boolean>` |
| `clearPermissionCache` | 清除权限缓存 | - | `void` |
| `getPermissionStats` | 获取统计信息 | - | `PermissionStats` |
| `batchRequest` | 创建批处理函数 | `requestFn, options?` | `BatchRequestFn` |
| `configurePermission` | 配置权限服务 | `config` | `void` |

### 常量

| 常量名 | 描述 | 值 |
|--------|------|------|
| `PERMISSION_BATCH_ENDPOINT` | 权限批处理端点标识符 | `'permission-batch'` |
| `BATCH_CONFIG` | 批处理默认配置 | `{ DELAY: 50, MAX_SIZE: 100 }` |
| `CACHE_CONFIG` | 缓存默认配置 | `{ ENABLE: false, TTL: 300000 }` |
| `PERMISSION_CHECK_MODES` | 权限检查模式 | `{ ALL: 'all', ANY: 'any' }` |

### 类型定义

| 类型名 | 描述 | 属性 |
|--------|------|------|
| `PermissionConfig` | 权限配置接口 | `code: string \| readonly string[]`<br>`mode?: 'all' \| 'any'`<br>`biz?: Record<string, unknown>` |
| `PermissionInput` | 权限输入类型 | `string \| readonly string[] \| PermissionConfig` |
| `PermissionResult` | 权限结果类型 | `boolean \| number` |
| `PermissionServiceFn` | 权限服务函数类型 | `(configs: PermissionConfig[]) => Promise<PermissionResult[]>` |
| `PermissionServiceOptions` | 权限服务配置选项 | `batch?: BatchOptions`<br>`cache?: CacheOptions` |
| `BatchOptions` | 批处理配置 | `delay?: number` (默认: 50)<br>`maxSize?: number` (默认: 100) |
| `CacheOptions` | 缓存配置 | `enable?: boolean` (默认: false)<br>`ttl?: number` (默认: 300000) |

## 框架集成

本库作为基础核心，可与特定框架的权限库配合使用：

- **React**: `@seed-fe/react-permission`
- **Vue**: `@seed-fe/vue-permission`

## 许可证

MIT © [xianghongai](https://github.com/xianghongai)