用户平台 SDK

本 SDK 提供了一套与 NestJS 生态无缝集成的工具，可以帮助其他服务（如 Beacon 平台）轻松地集成用户平台的认证与授权功能。

安装与配置

第 1 步：构建 SDK

在使用前，请确保 SDK 本身已经被编译。

# 进入 sdk 目录
cd user/sdk
# 运行构建命令
pnpm build

第 2 步：在您的项目中添加依赖

方式一：使用 pnpm file link (推荐用于开发环境)

在您的项目 package.json 中添加：

{
  "dependencies": {
    "@vimo/user-sdk": "file:../user/sdk"
  }
}

然后运行：

pnpm install

方式二：使用相对路径导入 (当前使用)

如果file link出现问题，可以直接使用相对路径导入：

import { UserAuthGuard, MUser, MUserId } from '../../../../../user/sdk/dist';

第 3 步：配置环境变量

在您的项目的 .env 文件中，添加用户平台服务器的 URL：

USER_PLATFORM_BASE_URL=http://localhost:3508

🔄 Token 管理说明

Token 有效期

• 当前设置: 30天有效期
• 刷新机制: 支持使用 refreshToken API 刷新现有Token
• 安全性: 验证Token时会检查用户是否存在且未被删除

Token 刷新最佳实践

// 在Token即将过期时刷新
async function refreshTokenIfNeeded(currentToken: string) {
  try {
    const newTokenData = await userPlatformClient.user.refreshToken(currentToken);
    // 更新本地存储的Token
    localStorage.setItem('token', newTokenData.token);
    return newTokenData.token;
  } catch (error) {
    // Token刷新失败，需要重新登录
    console.error('Token refresh failed:', error);
    // 跳转到登录页面
  }
}

主要用法：通过 Guard 和装饰器获取用户信息

这是最推荐、最便捷的使用方式。

1. 导入 UserPlatformSdkModule

在您的主模块（如 app.module.ts）中导入并配置 SDK 模块。

import { Module } from '@nestjs/common';
import { ConfigModule } from '@nestjs/config';
import { UserPlatformSdkModule } from '@vimo/user-sdk';
// 或者使用相对路径导入
// import { UserPlatformSdkModule } from '../../../../../user/sdk/dist';

@Module({
  imports: [
    ConfigModule.forRoot({ isGlobal: true }), // 确保环境变量已加载
    UserPlatformSdkModule.forRootAsync(),
    // ... 其他模块
  ],
})
export class AppModule {}

2. 使用 UserAuthGuard 保护路由

在需要用户登录才能访问的控制器或具体路由上，应用 UserAuthGuard。

import { Controller, Get, UseGuards } from '@nestjs/common';
import { UserAuthGuard } from '@vimo/user-sdk';
// 或者使用相对路径导入
// import { UserAuthGuard } from '../../../../../user/sdk/dist';

@Controller('protected-resource')
@UseGuards(UserAuthGuard) // <--- 在这里应用 Guard
export class MyProtectedController {
  // 此控制器下的所有路由都将被保护
}

3. 使用 @MUser 和 @MUserId 装饰器获取信息

在被 UserAuthGuard 保护的路由中，您可以轻松地注入当前登录用户的信息。

import { Controller, Get, UseGuards } from '@nestjs/common';
import { UserAuthGuard, MUser, MUserId, UserLoginVO } from '@vimo/user-sdk';
// 或者使用相对路径导入
// import { UserAuthGuard, MUser, MUserId } from '../../../../../user/sdk/dist';

@Controller('user')
@UseGuards(UserAuthGuard)
export class UserController {

  @Get('me')
  getCurrentUser(@MUser() user: UserLoginVO) {
    // user 对象包含了完整的用户信息 (id, nickname, email 等)
    return user;
  }

  @Get('profile')
  getUserProfile(@MUser() user: UserLoginVO, @MUserId() userId: number) {
    // 可以同时获取完整用户信息和用户ID
    return { 
      id: userId,
      nickname: user.nickname,
      email: user.email 
    };
  }
  
  @Get('email')
  getUserEmail(@MUser('email') email: string) {
    // @MUser() 装饰器也可以传入字段名，只获取特定信息
    return { email };
  }
}

备用方法：直接使用 API 客户端

在某些非 HTTP 请求的场景（如定时任务、队列消费者）或需要在服务层主动调用接口时，您可以直接注入并使用 UserPlatformClient。

1. 注入客户端

import { Injectable, Inject } from '@nestjs/common';
import { UserPlatformClient, USER_PLATFORM_CLIENT } from '@vimo/user-sdk';

@Injectable()
export class MyService {
  constructor(
    @Inject(USER_PLATFORM_CLIENT)
    private readonly userPlatformClient: UserPlatformClient,
  ) {}

  async someMethod() {
    // 主动调用登录接口
    const user = await this.userPlatformClient.user.login({ account: 'test', password: '123' });
  }
}

2. 客户端 API 详解

userPlatformClient 实例上有一个 user 属性，包含了所有与用户相关的 API 方法。

user.registerByAccount(body: AccountRegisterVO): Promise<any>

使用账号和密码注册一个新用户。

• 参数: body - 包含 account 和 password 的对象。
• 返回: Promise<any> - 服务端的原始响应。

user.registerWithKey(body: RegisterWithKeyVO): Promise<UserLoginVO>

使用注册Key进行平台特定用户注册。

• 参数: body - 包含 account、password(MD5加密) 和 registerKey 的对象。
• 返回: Promise<UserLoginVO> - 包含用户完整信息和 token 的对象。
• 说明: 用于特定平台的受控注册，需要有效的注册Key才能成功。

user.login(params: AccountRegisterVO): Promise<UserLoginVO>

使用账号和密码进行登录。

• 参数: params - 包含 account 和 password 的对象。
• 返回: Promise<UserLoginVO> - 包含用户完整信息和 token 的对象。

user.me(token: string): Promise<UserLoginVO>

验证一个 Token 并返回对应的用户信息。UserAuthGuard 内部就是调用此方法。

• 参数: token - 用户的 JWT 字符串（不含 "Bearer " 前缀）。
• 返回: Promise<UserLoginVO> - 如果 Token 有效，返回用户信息。

user.refreshToken(token: string): Promise<{ token: string }>

[新增] 刷新用户的访问Token，延长登录状态。

• 参数: token - 当前有效的 JWT Token
• 返回: Promise<{ token: string }> - 包含新Token的对象

// 刷新Token示例
const newTokenData = await userPlatformClient.user.refreshToken(currentToken);
const newToken = newTokenData.token;

user.loginWithWechat(params: WechatLoginParams): Promise<UserLoginVO>

[新增] 使用微信授权码进行登录或静默注册。

• 参数: params - 包含 code, platform, userInfo? 的对象
• 返回: Promise<UserLoginVO> - 用户信息和Token

user.getWechatOpenId(params: { code: string, platform: string }): Promise<{ openId: string }>

[新增] 获取微信用户的OpenID，用于用户识别。

user.loginWithOpenId(params: { openId: string, platform: string }): Promise<UserLoginVO>

[新增] 使用微信OpenID进行登录。

user.loginWithApple(params: AppleLoginParams): Promise<UserLoginVO>

[新增] 使用Apple Sign In进行登录或静默注册。

• 参数: params - 包含 identityToken, platform 等的对象
• 返回: Promise<UserLoginVO> - 用户信息和Token

user.searchUsers(query: string): Promise<UserLoginVO[]>

[新增] 根据昵称模糊搜索用户。

• 参数: query - 搜索关键字
• 返回: Promise<UserLoginVO[]> - 匹配的用户列表

user.batchGetUsers(userIds: number[]): Promise<UserLoginVO[]>

[新增] 批量获取用户信息。

• 参数: userIds - 用户ID数组
• 返回: Promise<UserLoginVO[]> - 用户信息列表

user.deregisterApple(token: string): Promise<void>

[新增] 注销Apple登录方式。

• 参数: token - 用户的有效Token
• 返回: Promise<void> - 注销成功无返回值

3. 匿名用户API

SDK还支持匿名用户功能，适用于无需注册即可使用的场景：

user.createAnonymousUser(body: AnonymousUserCreateVO): Promise<UserLoginVO>

创建匿名用户。

user.authenticateAnonymousUser(body: AnonymousUserAuthVO): Promise<UserLoginVO>

验证匿名用户身份。

user.upgradeAnonymousUser(token: string, upgradeData: any): Promise<UserLoginVO>

将匿名用户升级为正式用户。