@svton/cli 1.2.2 → 1.2.4

package/templates/examples/authz/README.md

@@ -1,273 +0,0 @@
-# 权限控制示例
-
-本示例展示如何使用 `@svton/nestjs-authz` 模块实现 RBAC 权限管理。
-
-## 文件说明
-
-- `user.controller.ts` - 用户控制器，展示权限控制
-- `roles.guard.ts` - 角色守卫，验证用户权限
-
-## 核心装饰器
-
-### @Roles - 角色权限
-
-限制只有特定角色才能访问：
-
-```typescript
-@Roles('admin')
-@Get('admin')
-async adminOnly() {
-  return { message: 'Admin only' };
-}
-```
-
-支持多个角色（满足其一即可）：
-
-```typescript
-@Roles('admin', 'manager')
-@Get('list')
-async list() {
-  return { message: 'Admin or Manager' };
-}
-```
-
-### @Permissions - 细粒度权限
-
-基于权限点的访问控制：
-
-```typescript
-@Permissions('user:delete')
-@Delete(':id')
-async delete(@Param('id') id: string) {
-  return { message: 'User deleted' };
-}
-```
-
-支持多个权限（需要全部满足）：
-
-```typescript
-@Permissions('user:update', 'user:sensitive')
-@Put(':id/sensitive')
-async updateSensitive() {
-  return { message: 'Updated' };
-}
-```
-
-### 组合使用
-
-同时检查角色和权限：
-
-```typescript
-@Roles('admin')
-@Permissions('user:delete')
-@Delete(':id')
-async delete() {
-  // 需要 admin 角色且有 user:delete 权限
-}
-```
-
-## 权限模型
-
-### 角色（Roles）
-
-- `admin` - 管理员，拥有所有权限
-- `manager` - 管理者，拥有部分管理权限
-- `user` - 普通用户，基础权限
-- `guest` - 访客，只读权限
-
-### 权限点（Permissions）
-
-- `user:create` - 创建用户
-- `user:read` - 查看用户
-- `user:update` - 更新用户
-- `user:delete` - 删除用户
-- `user:batch-delete` - 批量删除用户
-- `user:reset-password` - 重置密码
-
-## 测试接口
-
-### 查看用户列表（需要 admin 或 manager）
-
-```bash
-curl http://localhost:3000/examples/users
-```
-
-### 查看用户详情（所有用户）
-
-```bash
-curl http://localhost:3000/examples/users/1
-```
-
-### 创建用户（需要 admin）
-
-```bash
-curl -X POST http://localhost:3000/examples/users \
-  -H "Content-Type: application/json" \
-  -d '{"name":"New User","email":"user@example.com"}'
-```
-
-### 更新用户（需要 user:update 权限）
-
-```bash
-curl -X PUT http://localhost:3000/examples/users/1 \
-  -H "Content-Type: application/json" \
-  -d '{"name":"Updated Name"}'
-```
-
-### 删除用户（需要 admin 角色和 user:delete 权限）
-
-```bash
-curl -X DELETE http://localhost:3000/examples/users/1
-```
-
-## 权限配置
-
-在 `src/config/authz.config.ts` 中配置：
-
-```typescript
-export const useAuthzConfig = (configService: ConfigService) => ({
-  roles: ['admin', 'manager', 'user', 'guest'],
-  defaultRole: 'guest',
-  rolePermissions: {
-    admin: ['*'], // 所有权限
-    manager: [
-      'user:read',
-      'user:update',
-      'user:reset-password',
-    ],
-    user: [
-      'user:read',
-    ],
-    guest: [],
-  },
-});
-```
-
-## 实现原理
-
-### 1. 定义守卫
-
-```typescript
-@Injectable()
-export class RolesGuard implements CanActivate {
-  canActivate(context: ExecutionContext): boolean {
-    const requiredRoles = this.reflector.get('roles', context.getHandler());
-    const user = context.switchToHttp().getRequest().user;
-    
-    return requiredRoles.some(role => user.role === role);
-  }
-}
-```
-
-### 2. 应用守卫
-
-```typescript
-@Controller('users')
-@UseGuards(RolesGuard)
-export class UserController {
-  // 所有接口都会应用权限检查
-}
-```
-
-### 3. 使用装饰器
-
-```typescript
-@Roles('admin')
-@Get('admin')
-async adminOnly() { }
-```
-
-## 最佳实践
-
-1. **最小权限原则**：只授予必要的权限
-2. **角色分层**：设计合理的角色层级
-3. **权限粒度**：根据业务需求设计权限点
-4. **动态权限**：支持运行时动态调整权限
-5. **权限缓存**：缓存用户权限，提高性能
-
-## 常见场景
-
-### 用户管理
-
-```typescript
-@Roles('admin')
-@Get('users')
-async getUsers() { }  // 只有管理员可以查看用户列表
-
-@Permissions('user:update')
-@Put('users/:id')
-async updateUser() { }  // 需要更新权限
-```
-
-### 内容管理
-
-```typescript
-@Roles('admin', 'editor')
-@Post('articles')
-async createArticle() { }  // 管理员和编辑可以创建文章
-
-@Permissions('article:publish')
-@Post('articles/:id/publish')
-async publishArticle() { }  // 需要发布权限
-```
-
-### 数据导出
-
-```typescript
-@Roles('admin', 'manager')
-@Get('export')
-async export() { }  // 管理员和管理者可以导出数据
-```
-
-## 高级用法
-
-### 动态权限检查
-
-```typescript
-@Get(':id')
-async findOne(@Param('id') id: string, @Req() req) {
-  const user = req.user;
-  
-  // 用户只能查看自己的数据，管理员可以查看所有
-  if (user.role !== 'admin' && user.id !== parseInt(id)) {
-    throw new ForbiddenException('Access denied');
-  }
-  
-  return this.userService.findOne(id);
-}
-```
-
-### 资源级权限
-
-```typescript
-@Put(':id')
-async update(@Param('id') id: string, @Req() req) {
-  const resource = await this.userService.findOne(id);
-  
-  // 检查用户是否有权限修改这个资源
-  if (!this.authzService.canModify(req.user, resource)) {
-    throw new ForbiddenException('Access denied');
-  }
-  
-  return this.userService.update(id, data);
-}
-```
-
-### 条件权限
-
-```typescript
-@Post('approve')
-@Permissions('order:approve')
-async approve(@Body() data, @Req() req) {
-  // 只能审批金额小于 10000 的订单
-  if (data.amount > 10000 && !req.user.permissions.includes('order:approve-large')) {
-    throw new ForbiddenException('Cannot approve large orders');
-  }
-  
-  return this.orderService.approve(data.id);
-}
-```
-
-## 更多信息
-
-查看官方文档：https://751848178.github.io/svton/packages/nestjs-authz

package/templates/examples/authz/roles.guard.ts

@@ -1,37 +0,0 @@
-import { Injectable, CanActivate, ExecutionContext } from '@nestjs/common';
-import { Reflector } from '@nestjs/core';
-
-@Injectable()
-export class RolesGuard implements CanActivate {
-  constructor(private reflector: Reflector) {}
-
-  canActivate(context: ExecutionContext): boolean {
-    // 获取装饰器设置的角色
-    const requiredRoles = this.reflector.getAllAndOverride<string[]>('roles', [
-      context.getHandler(),
-      context.getClass(),
-    ]);
-
-    if (!requiredRoles) {
-      return true;
-    }
-
-    const request = context.switchToHttp().getRequest();
-    const user = request.user;
-
-    // TODO: 实际项目中从 JWT 或 Session 获取用户信息
-    // 这里模拟用户信息
-    if (!user) {
-      // 模拟用户（实际应从认证中间件获取）
-      request.user = {
-        id: 1,
-        name: 'Test User',
-        role: 'admin', // 可以改为 'user', 'manager', 'guest' 测试不同角色
-        permissions: ['user:update', 'user:delete', 'user:batch-delete', 'user:reset-password'],
-      };
-    }
-
-    // 检查用户角色
-    return requiredRoles.some((role) => user.role === role);
-  }
-}

package/templates/examples/authz/user.controller.ts

@@ -1,116 +0,0 @@
-import {
-  Controller,
-  Get,
-  Post,
-  Put,
-  Delete,
-  Body,
-  Param,
-  UseGuards,
-} from '@nestjs/common';
-import { Roles, Permissions, RolesGuard } from '@svton/nestjs-authz';
-
-@Controller('examples/users')
-@UseGuards(RolesGuard)
-export class UserController {
-  /**
-   * 查看用户列表 - 需要 admin 或 manager 角色
-   */
-  @Get()
-  @Roles('admin', 'manager')
-  findAll() {
-    return {
-      message: 'User list',
-      users: [
-        { id: 1, name: 'User 1', role: 'admin' },
-        { id: 2, name: 'User 2', role: 'user' },
-      ],
-    };
-  }
-
-  /**
-   * 查看用户详情 - 所有登录用户都可以
-   */
-  @Get(':id')
-  findOne(@Param('id') id: string) {
-    return {
-      message: 'User detail',
-      user: { id, name: `User ${id}`, role: 'user' },
-    };
-  }
-
-  /**
-   * 创建用户 - 需要 admin 角色
-   */
-  @Post()
-  @Roles('admin')
-  create(@Body() data: any) {
-    return {
-      message: 'User created',
-      user: { id: 3, ...data },
-    };
-  }
-
-  /**
-   * 更新用户 - 需要 user:update 权限
-   */
-  @Put(':id')
-  @Permissions('user:update')
-  update(@Param('id') id: string, @Body() data: any) {
-    return {
-      message: 'User updated',
-      user: { id, ...data },
-    };
-  }
-
-  /**
-   * 删除用户 - 需要 admin 角色和 user:delete 权限
-   */
-  @Delete(':id')
-  @Roles('admin')
-  @Permissions('user:delete')
-  delete(@Param('id') id: string) {
-    return {
-      message: 'User deleted',
-      userId: id,
-    };
-  }
-
-  /**
-   * 批量删除 - 需要 admin 角色和 user:batch-delete 权限
-   */
-  @Delete()
-  @Roles('admin')
-  @Permissions('user:batch-delete')
-  batchDelete(@Body() data: { ids: string[] }) {
-    return {
-      message: 'Users deleted',
-      count: data.ids.length,
-    };
-  }
-
-  /**
-   * 导出用户 - 需要 admin 或 manager 角色
-   */
-  @Get('export')
-  @Roles('admin', 'manager')
-  export() {
-    return {
-      message: 'Export users',
-      url: 'https://example.com/users.xlsx',
-    };
-  }
-
-  /**
-   * 重置密码 - 需要 user:reset-password 权限
-   */
-  @Post(':id/reset-password')
-  @Permissions('user:reset-password')
-  resetPassword(@Param('id') id: string) {
-    return {
-      message: 'Password reset',
-      userId: id,
-      newPassword: 'temp123456',
-    };
-  }
-}

package/templates/examples/cache/README.md

@@ -1,82 +0,0 @@
-# 缓存功能示例
-
-本示例展示如何使用 `@svton/nestjs-cache` 模块进行声明式缓存。
-
-## 文件说明
-
-- `user.service.ts` - 使用缓存装饰器的 Service 层
-- `user.controller.ts` - 对应的 Controller 层
-
-## 核心装饰器
-
-### @Cacheable - 缓存查询结果
-
-```typescript
-@Cacheable({ key: 'user:#id', ttl: 3600 })
-async findOne(id: number) {
-  // 首次调用会执行方法并缓存结果
-  // 后续调用直接返回缓存数据
-}
-```
-
-### @CacheEvict - 清除缓存
-
-```typescript
-@CacheEvict({ key: 'user:#id' })
-async update(id: number, data: any) {
-  // 方法执行后会清除对应的缓存
-}
-```
-
-### @CachePut - 更新缓存
-
-```typescript
-@CachePut({ key: 'user:#id' })
-async updateAndRefresh(id: number, data: any) {
-  // 方法执行后会用返回值更新缓存
-}
-```
-
-## Key 表达式
-
-- `#id` - 从 request.params 获取
-- `#0`, `#1` - 位置参数
-- `#paramName` - 参数名
-- `#body.field` - 从 request.body 获取
-- `user:*` - 通配符模式（需要 pattern: true）
-
-## 测试接口
-
-启动项目后，可以通过以下接口测试：
-
-```bash
-# 查询用户（首次会查询数据库，后续返回缓存）
-curl http://localhost:3000/examples/users/1
-
-# 查询用户列表
-curl http://localhost:3000/examples/users?page=1&pageSize=10
-
-# 更新用户（会清除缓存）
-curl -X PUT http://localhost:3000/examples/users/1 \
-  -H "Content-Type: application/json" \
-  -d '{"name":"New Name"}'
-
-# 更新用户并刷新缓存
-curl -X PUT http://localhost:3000/examples/users/1/refresh \
-  -H "Content-Type: application/json" \
-  -d '{"name":"New Name"}'
-
-# 清除所有用户缓存
-curl -X DELETE http://localhost:3000/examples/users/cache
-```
-
-## 最佳实践
-
-1. **合理设置 TTL**：根据数据更新频率设置过期时间
-2. **及时清除缓存**：更新/删除操作使用 @CacheEvict
-3. **避免缓存穿透**：对空结果也进行缓存
-4. **使用命名空间**：key 前缀区分不同业务
-
-## 更多信息
-
-查看官方文档：https://751848178.github.io/svton/packages/nestjs-cache

package/templates/examples/cache/user.controller.ts

@@ -1,42 +0,0 @@
-import { Controller, Get, Put, Delete, Param, Body, Query } from '@nestjs/common';
-import { UserService, User } from './user.service';
-
-@Controller('examples/users')
-export class UserController {
-  constructor(private readonly userService: UserService) {}
-
-  @Get(':id')
-  async findOne(@Param('id') id: string): Promise<User> {
-    return this.userService.findOne(Number(id));
-  }
-
-  @Get()
-  async findAll(
-    @Query('page') page: string = '1',
-    @Query('pageSize') pageSize: string = '10',
-  ): Promise<User[]> {
-    return this.userService.findAll(Number(page), Number(pageSize));
-  }
-
-  @Put(':id')
-  async update(
-    @Param('id') id: string,
-    @Body() data: Partial<User>,
-  ): Promise<User> {
-    return this.userService.update(Number(id), data);
-  }
-
-  @Put(':id/refresh')
-  async updateAndRefresh(
-    @Param('id') id: string,
-    @Body() data: Partial<User>,
-  ): Promise<User> {
-    return this.userService.updateAndRefresh(Number(id), data);
-  }
-
-  @Delete('cache')
-  async clearCache(): Promise<{ message: string }> {
-    await this.userService.clearAllCache();
-    return { message: 'Cache cleared successfully' };
-  }
-}

package/templates/examples/cache/user.service.ts

@@ -1,78 +0,0 @@
-import { Injectable } from '@nestjs/common';
-import { Cacheable, CacheEvict, CachePut } from '@svton/nestjs-cache';
-
-export interface User {
-  id: number;
-  name: string;
-  email: string;
-}
-
-@Injectable()
-export class UserService {
-  /**
-   * 缓存查询结果
-   * key: user:#id 会自动从参数中获取 id 值
-   * ttl: 缓存过期时间（秒）
-   */
-  @Cacheable({ key: 'user:#id', ttl: 3600 })
-  async findOne(id: number): Promise<User> {
-    console.log(`Fetching user ${id} from database...`);
-    // TODO: 实际项目中从数据库查询
-    return {
-      id,
-      name: `User ${id}`,
-      email: `user${id}@example.com`,
-    };
-  }
-
-  /**
-   * 更新数据时清除缓存
-   */
-  @CacheEvict({ key: 'user:#id' })
-  async update(id: number, data: Partial<User>): Promise<User> {
-    console.log(`Updating user ${id}...`);
-    // TODO: 实际项目中更新数据库
-    return {
-      id,
-      name: data.name || `User ${id}`,
-      email: data.email || `user${id}@example.com`,
-    };
-  }
-
-  /**
-   * 更新数据并刷新缓存
-   */
-  @CachePut({ key: 'user:#id' })
-  async updateAndRefresh(id: number, data: Partial<User>): Promise<User> {
-    console.log(`Updating and refreshing cache for user ${id}...`);
-    // TODO: 实际项目中更新数据库
-    return {
-      id,
-      name: data.name || `User ${id}`,
-      email: data.email || `user${id}@example.com`,
-    };
-  }
-
-  /**
-   * 批量清除缓存（使用通配符）
-   */
-  @CacheEvict({ key: 'user:*', pattern: true })
-  async clearAllCache(): Promise<void> {
-    console.log('Clearing all user cache...');
-  }
-
-  /**
-   * 列表查询缓存
-   * 支持多个参数
-   */
-  @Cacheable({ key: 'users:list:#page:#pageSize', ttl: 300 })
-  async findAll(page: number, pageSize: number): Promise<User[]> {
-    console.log(`Fetching users page ${page}...`);
-    // TODO: 实际项目中从数据库查询
-    return Array.from({ length: pageSize }, (_, i) => ({
-      id: (page - 1) * pageSize + i + 1,
-      name: `User ${(page - 1) * pageSize + i + 1}`,
-      email: `user${(page - 1) * pageSize + i + 1}@example.com`,
-    }));
-  }
-}