📝 docs(rules): add CRUD permissions configuration specification

- document the structure of permission configuration
- define permission identifier naming convention
- describe permission configuration levels and best practices
- explain permission verification mechanism and data permission control
- provide complete configuration examples and common patterns

.roo/rules/16-crud-permissions.md

@@ -0,0 +1,282 @@
+# 通用CRUD权限配置规范
+
+## 概述
+
+本规范定义了如何在通用CRUD模块中配置权限控制，支持基于角色的权限管理和数据权限控制。
+
+## 权限配置结构
+
+在`createCrudRoutes`中通过`permissions`参数配置权限：
+
+```typescript
+const routes = createCrudRoutes({
+  entity: UserEntity,
+  createSchema: CreateUserDto,
+  updateSchema: UpdateUserDto,
+  getSchema: UserSchema,
+  listSchema: UserSchema,
+  permissions: {
+    create: ['system:user:create'],     // 创建权限
+    read: ['system:user:view:all'],     // 读取权限
+    update: ['system:user:update'],     // 更新权限
+    delete: ['system:user:delete']      // 删除权限
+  }
+});
+```
+
+## 权限配置详细规范
+
+### 1. permissions 配置项结构
+
+```typescript
+permissions: {
+  create?: string[];      // 创建操作的权限标识数组
+  read?: string[];        // 读取操作的权限标识数组
+  update?: string[];      // 更新操作的权限标识数组
+  delete?: string[];      // 删除操作的权限标识数组
+}
+```
+
+### 2. 权限标识命名规范
+
+权限标识应采用以下格式：
+
+```
+[系统]:[模块]:[操作]:[范围]
+```
+
+示例：
+- `system:user:create` - 系统用户创建权限
+- `system:user:view:all` - 系统用户查看所有数据权限
+- `system:user:update` - 系统用户更新权限
+- `system:user:delete` - 系统用户删除权限
+
+### 3. 权限配置层级
+
+#### 3.1 基础权限配置
+为所有CRUD操作配置统一的权限：
+
+```typescript
+permissions: {
+  create: ['user:manage'],
+  read: ['user:manage'],
+  update: ['user:manage'],
+  delete: ['user:manage']
+}
+```
+
+#### 3.2 细粒度权限配置
+为不同操作配置不同的权限：
+
+```typescript
+permissions: {
+  create: ['user:create'],
+  read: ['user:view', 'user:view:all'],
+  update: ['user:update', 'user:edit'],
+  delete: ['user:delete', 'user:remove']
+}
+```
+
+### 4. 权限验证机制
+
+#### 4.1 权限检查流程
+1. 用户发起请求
+2. `enhancedPermissionWithLog`中间件检查用户权限
+3. 检查用户是否拥有配置的任一权限标识
+4. 记录操作日志
+5. 无权限时返回403错误
+
+#### 4.2 权限检查规则
+- **OR关系**：用户只需拥有权限数组中的任意一个权限标识即可
+- **权限继承**：支持角色权限继承
+- **动态权限**：支持运行时权限计算
+
+### 5. 数据权限控制
+
+除了操作权限外，还支持数据权限控制：
+
+```typescript
+const routes = createCrudRoutes({
+  entity: ClientEntity,
+  createSchema: CreateClientDto,
+  updateSchema: UpdateClientDto,
+  getSchema: ClientSchema,
+  listSchema: ClientSchema,
+  permissions: {
+    create: ['client:create'],
+    read: ['client:view'],
+    update: ['client:update'],
+    delete: ['client:delete']
+  },
+  dataPermission: {
+    entity: 'client',
+    userIdField: 'createdBy',
+    departmentIdField: 'departmentId',
+    responsibleUserIdField: 'responsibleUserId'
+  }
+});
+```
+
+### 6. 完整配置示例
+
+#### 6.1 基础权限配置
+
+```typescript
+import { createCrudRoutes } from '@/server/utils/generic-crud.routes';
+import { UserEntity } from '@/server/modules/users/user.entity';
+import { UserSchema, CreateUserDto, UpdateUserDto } from '@/server/modules/users/user.dto';
+import { authMiddleware } from '@/server/middleware/auth.middleware';
+
+const userRoutes = createCrudRoutes({
+  entity: UserEntity,
+  createSchema: CreateUserDto,
+  updateSchema: UpdateUserDto,
+  getSchema: UserSchema,
+  listSchema: UserSchema,
+  searchFields: ['username', 'email', 'phone'],
+  middleware: [authMiddleware],
+  permissions: {
+    create: ['system:user:create'],
+    read: ['system:user:view'],
+    update: ['system:user:update'],
+    delete: ['system:user:delete']
+  },
+  userTracking: {
+    createdByField: 'createdBy',
+    updatedByField: 'updatedBy'
+  }
+});
+```
+
+#### 6.2 复杂权限配置
+
+```typescript
+const clientRoutes = createCrudRoutes({
+  entity: ClientEntity,
+  createSchema: CreateClientDto,
+  updateSchema: UpdateClientDto,
+  getSchema: ClientSchema,
+  listSchema: ClientSchema,
+  searchFields: ['name', 'contact', 'phone'],
+  middleware: [authMiddleware],
+  relations: ['department', 'responsibleUser'],
+  permissions: {
+    create: ['crm:client:create', 'client:manage'],
+    read: ['crm:client:view', 'crm:client:view:all', 'client:manage'],
+    update: ['crm:client:update', 'client:manage', 'client:edit:self'],
+    delete: ['crm:client:delete', 'client:manage']
+  },
+  dataPermission: {
+    entity: 'client',
+    userIdField: 'created_by',
+    departmentIdField: 'department_id',
+    responsibleUserIdField: 'responsible_user_id'
+  }
+});
+```
+
+### 7. 权限配置最佳实践
+
+#### 7.1 权限粒度设计
+- **最小权限原则**：只授予用户必要的最小权限
+- **权限分层**：系统级、模块级、操作级、数据级
+- **权限组合**：支持权限组合使用
+
+#### 7.2 权限命名规范
+```
+格式：[系统/业务域]:[模块]:[操作]:[范围]
+示例：
+- system:user:create (系统用户创建)
+- crm:client:view:all (CRM客户查看所有)
+- finance:invoice:approve (财务发票审批)
+```
+
+#### 7.3 权限配置模板
+
+```typescript
+// 管理员权限
+permissions: {
+  create: ['system:admin'],
+  read: ['system:admin'],
+  update: ['system:admin'],
+  delete: ['system:admin']
+}
+
+// 普通用户权限
+permissions: {
+  create: ['module:create'],
+  read: ['module:view:self', 'module:view:department'],
+  update: ['module:update:self'],
+  delete: ['module:delete:self']
+}
+
+// 只读权限
+permissions: {
+  read: ['module:view']
+}
+```
+
+### 8. 权限验证响应
+
+当用户无权限时，系统返回：
+
+```json
+{
+  "code": 403,
+  "message": "没有权限执行此操作"
+}
+```
+
+### 9. 调试和测试
+
+#### 9.1 权限调试
+- 使用日志查看权限检查过程
+- 检查用户权限列表
+- 验证权限标识匹配
+
+#### 9.2 测试用例
+```typescript
+// 测试权限配置
+describe('User Permissions', () => {
+  it('should allow admin to create users', async () => {
+    // 测试管理员创建用户权限
+  });
+  
+  it('should deny normal user to delete users', async () => {
+    // 测试普通用户无删除权限
+  });
+});
+```
+
+### 10. 常见配置模式
+
+#### 10.1 完全开放
+```typescript
+// 不配置permissions或使用空对象
+permissions: {}
+```
+
+#### 10.2 只读模式
+```typescript
+permissions: {
+  read: ['public']
+}
+```
+
+#### 10.3 完全控制
+```typescript
+permissions: {
+  create: ['admin'],
+  read: ['admin'],
+  update: ['admin'],
+  delete: ['admin']
+}
+```
+
+### 11. 权限配置注意事项
+
+1. **必须配合authMiddleware使用**：权限检查需要用户认证信息
+2. **权限标识区分大小写**：确保权限标识一致
+3. **权限数组支持多个值**：用户拥有任一权限即可
+4. **默认无权限**：未配置权限的操作默认拒绝访问
+5. **权限缓存**：权限信息会被缓存，更新后需要重新登录生效