@svton/cli 1.2.1 → 1.2.2

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

@@ -0,0 +1,116 @@
+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

@@ -0,0 +1,82 @@
+# 缓存功能示例
+
+本示例展示如何使用 `@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

@@ -0,0 +1,42 @@
+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

@@ -0,0 +1,78 @@
+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`,
+    }));
+  }
+}

package/templates/examples/oauth/README.md

@@ -0,0 +1,192 @@
+# OAuth 登录示例
+
+本示例展示如何使用 `@svton/nestjs-oauth` 模块实现微信登录。
+
+## 文件说明
+
+- `auth.service.ts` - 认证服务，处理 OAuth 流程
+- `auth.controller.ts` - 认证控制器，提供登录接口
+
+## 支持的登录方式
+
+### 1. 微信开放平台（PC 扫码登录）
+
+适用于网站应用，用户扫码登录。
+
+### 2. 微信公众号（网页授权）
+
+适用于公众号内网页，静默授权或用户授权。
+
+### 3. 微信小程序
+
+适用于小程序，使用 wx.login() 获取 code。
+
+## 使用方式
+
+### PC 扫码登录
+
+```typescript
+// 1. 获取授权 URL
+const url = this.authService.getWechatOpenAuthUrl('/dashboard');
+
+// 2. 重定向到微信授权页面
+// 用户扫码授权后，微信会回调到 callback 接口
+
+// 3. 处理回调
+const userInfo = await this.authService.handleWechatOpenCallback(code);
+```
+
+### 公众号网页授权
+
+```typescript
+// 1. 获取授权 URL
+const url = this.authService.getWechatMpAuthUrl('/profile');
+
+// 2. 重定向到微信授权页面
+// 用户授权后，微信会回调到 callback 接口
+
+// 3. 处理回调
+const userInfo = await this.authService.handleWechatMpCallback(code);
+```
+
+### 小程序登录
+
+```typescript
+// 小程序端
+wx.login({
+  success: (res) => {
+    // 将 code 发送到后端
+    wx.request({
+      url: 'https://api.example.com/examples/auth/wechat/miniprogram/login',
+      method: 'POST',
+      data: { code: res.code },
+    });
+  },
+});
+
+// 后端处理
+const result = await this.authService.miniprogramLogin(code);
+```
+
+### 小程序获取手机号
+
+```typescript
+// 小程序端
+<button open-type="getPhoneNumber" @getphonenumber="getPhoneNumber">
+  获取手机号
+</button>
+
+// 获取到 code 后发送到后端
+const result = await this.authService.getMiniprogramPhoneNumber(code);
+```
+
+## 测试接口
+
+### PC 扫码登录
+
+```bash
+# 1. 访问登录页面（会重定向到微信）
+curl http://localhost:3000/examples/auth/wechat/open/login
+
+# 2. 扫码授权后，微信会回调到：
+# http://localhost:3000/examples/auth/wechat/open/callback?code=xxx&state=/
+```
+
+### 小程序登录
+
+```bash
+curl -X POST http://localhost:3000/examples/auth/wechat/miniprogram/login \
+  -H "Content-Type: application/json" \
+  -d '{"code":"081234567890abcdef"}'
+```
+
+### 小程序获取手机号
+
+```bash
+curl -X POST http://localhost:3000/examples/auth/wechat/miniprogram/phone \
+  -H "Content-Type: application/json" \
+  -d '{"code":"081234567890abcdef"}'
+```
+
+## 环境变量配置
+
+在 `.env` 文件中配置：
+
+```env
+# 微信开放平台
+WECHAT_OPEN_APP_ID=wx1234567890abcdef
+WECHAT_OPEN_APP_SECRET=1234567890abcdef1234567890abcdef
+WECHAT_OPEN_CALLBACK_URL=https://yourdomain.com/examples/auth/wechat/open/callback
+
+# 微信公众号
+WECHAT_MP_APP_ID=wx1234567890abcdef
+WECHAT_MP_APP_SECRET=1234567890abcdef1234567890abcdef
+
+# 微信小程序
+WECHAT_MINI_APP_ID=wx1234567890abcdef
+WECHAT_MINI_APP_SECRET=1234567890abcdef1234567890abcdef
+```
+
+## 配置回调地址
+
+需要在微信后台配置回调地址：
+
+### 开放平台
+1. 登录微信开放平台
+2. 进入网站应用详情
+3. 配置授权回调域：`yourdomain.com`
+
+### 公众号
+1. 登录微信公众平台
+2. 设置与开发 -> 接口权限 -> 网页授权
+3. 配置授权回调域：`yourdomain.com`
+
+### 小程序
+1. 登录微信小程序后台
+2. 开发 -> 开发管理 -> 开发设置
+3. 配置服务器域名：`https://yourdomain.com`
+
+## 最佳实践
+
+1. **UnionID 机制**：使用 unionid 关联同一用户在不同应用的身份
+2. **Token 管理**：使用 JWT 生成 token，设置合理的过期时间
+3. **刷新机制**：实现 refresh_token 机制，避免频繁授权
+4. **错误处理**：妥善处理授权失败、token 过期等异常情况
+5. **安全性**：验证 state 参数，防止 CSRF 攻击
+
+## 常见场景
+
+### 网站登录
+
+```typescript
+// 1. 用户点击"微信登录"
+// 2. 重定向到微信授权页面
+// 3. 用户扫码授权
+// 4. 微信回调到后端
+// 5. 后端获取用户信息，生成 token
+// 6. 重定向到前端，携带 token
+```
+
+### 小程序登录
+
+```typescript
+// 1. 小程序调用 wx.login() 获取 code
+// 2. 将 code 发送到后端
+// 3. 后端调用 code2Session 获取 openid
+// 4. 查询或创建用户
+// 5. 返回 token 给小程序
+```
+
+### 绑定手机号
+
+```typescript
+// 1. 用户点击"获取手机号"按钮
+// 2. 小程序获取到 code
+// 3. 将 code 发送到后端
+// 4. 后端调用接口获取手机号
+// 5. 绑定手机号到用户账号
+```
+
+## 更多信息
+
+查看官方文档：https://751848178.github.io/svton/packages/nestjs-oauth

package/templates/examples/oauth/auth.controller.ts

@@ -0,0 +1,99 @@
+import { Controller, Get, Query, Redirect, Post, Body } from '@nestjs/common';
+import { AuthService } from './auth.service';
+
+@Controller('examples/auth')
+export class AuthController {
+  constructor(private readonly authService: AuthService) {}
+
+  /**
+   * 微信开放平台登录 - 获取授权 URL
+   */
+  @Get('wechat/open/login')
+  @Redirect()
+  wechatOpenLogin(@Query('redirect') redirect?: string) {
+    const state = redirect || '/';
+    const url = this.authService.getWechatOpenAuthUrl(state);
+
+    return { url };
+  }
+
+  /**
+   * 微信开放平台登录 - 回调处理
+   */
+  @Get('wechat/open/callback')
+  async wechatOpenCallback(
+    @Query('code') code: string,
+    @Query('state') state: string,
+  ) {
+    const userInfo = await this.authService.handleWechatOpenCallback(code);
+
+    // TODO: 生成 JWT token
+    // const token = await this.jwtService.sign({ userId: user.id });
+
+    return {
+      message: 'Login successful',
+      userInfo,
+      redirectUrl: state,
+      // token,
+    };
+  }
+
+  /**
+   * 微信公众号登录 - 获取授权 URL
+   */
+  @Get('wechat/mp/login')
+  @Redirect()
+  wechatMpLogin(@Query('redirect') redirect?: string) {
+    const state = redirect || '/';
+    const url = this.authService.getWechatMpAuthUrl(state);
+
+    return { url };
+  }
+
+  /**
+   * 微信公众号登录 - 回调处理
+   */
+  @Get('wechat/mp/callback')
+  async wechatMpCallback(
+    @Query('code') code: string,
+    @Query('state') state: string,
+  ) {
+    const userInfo = await this.authService.handleWechatMpCallback(code);
+
+    return {
+      message: 'Login successful',
+      userInfo,
+      redirectUrl: state,
+    };
+  }
+
+  /**
+   * 小程序登录
+   */
+  @Post('wechat/miniprogram/login')
+  async miniprogramLogin(@Body() body: { code: string }) {
+    const result = await this.authService.miniprogramLogin(body.code);
+
+    // TODO: 生成 JWT token
+    // const token = await this.jwtService.sign({ userId: user.id });
+
+    return {
+      message: 'Login successful',
+      ...result,
+      // token,
+    };
+  }
+
+  /**
+   * 小程序获取手机号
+   */
+  @Post('wechat/miniprogram/phone')
+  async getMiniprogramPhone(@Body() body: { code: string }) {
+    const result = await this.authService.getMiniprogramPhoneNumber(body.code);
+
+    return {
+      message: 'Phone number retrieved successfully',
+      ...result,
+    };
+  }
+}

package/templates/examples/oauth/auth.service.ts

@@ -0,0 +1,97 @@
+import { Injectable } from '@nestjs/common';
+import { OAuthService } from '@svton/nestjs-oauth';
+
+@Injectable()
+export class AuthService {
+  constructor(private readonly oauthService: OAuthService) {}
+
+  /**
+   * 获取微信开放平台授权 URL（PC 扫码登录）
+   */
+  getWechatOpenAuthUrl(state: string): string {
+    return this.oauthService.wechat.getAuthorizationUrl('open', state);
+  }
+
+  /**
+   * 获取微信公众号授权 URL（网页授权）
+   */
+  getWechatMpAuthUrl(state: string): string {
+    return this.oauthService.wechat.getAuthorizationUrl('mp', state);
+  }
+
+  /**
+   * 处理微信开放平台回调
+   */
+  async handleWechatOpenCallback(code: string) {
+    // 获取 access_token
+    const tokenResult = await this.oauthService.wechat.getAccessToken('open', code);
+
+    // 获取用户信息
+    const userInfo = await this.oauthService.wechat.getUserInfo(
+      'open',
+      tokenResult.access_token,
+      tokenResult.openid,
+    );
+
+    // TODO: 根据 openid 查询或创建用户
+    // const user = await this.userService.findOrCreateByWechatOpenId(userInfo.unionid);
+
+    return {
+      openid: userInfo.openid,
+      unionid: userInfo.unionid,
+      nickname: userInfo.nickname,
+      avatar: userInfo.headimgurl,
+    };
+  }
+
+  /**
+   * 处理微信公众号回调
+   */
+  async handleWechatMpCallback(code: string) {
+    const tokenResult = await this.oauthService.wechat.getAccessToken('mp', code);
+
+    const userInfo = await this.oauthService.wechat.getUserInfo(
+      'mp',
+      tokenResult.access_token,
+      tokenResult.openid,
+    );
+
+    // TODO: 根据 openid 查询或创建用户
+    // const user = await this.userService.findOrCreateByWechatMpOpenId(userInfo.openid);
+
+    return {
+      openid: userInfo.openid,
+      nickname: userInfo.nickname,
+      avatar: userInfo.headimgurl,
+    };
+  }
+
+  /**
+   * 小程序登录
+   */
+  async miniprogramLogin(code: string) {
+    const result = await this.oauthService.wechat.code2Session(code);
+
+    // TODO: 根据 openid 查询或创建用户
+    // const user = await this.userService.findOrCreateByWechatMiniOpenId(result.openid);
+
+    return {
+      openid: result.openid,
+      sessionKey: result.session_key,
+      unionid: result.unionid,
+    };
+  }
+
+  /**
+   * 小程序获取手机号
+   */
+  async getMiniprogramPhoneNumber(code: string) {
+    const result = await this.oauthService.wechat.getPhoneNumber(code);
+
+    return {
+      phoneNumber: result.phone_info.phoneNumber,
+      purePhoneNumber: result.phone_info.purePhoneNumber,
+      countryCode: result.phone_info.countryCode,
+    };
+  }
+}