whale-town-end/src/core/db/users/users.dto.ts

/**
 * 用户数据传输对象模块
 * 
 * 功能描述：
 * - 定义用户创建和更新的数据传输对象
 * - 提供完整的数据验证规则和错误提示
 * - 支持多种登录方式的数据格式验证
 * 
 * 依赖模块：
 * - class-validator: 数据验证装饰器
 * - class-transformer: 数据转换工具
 * 
 * @author moyin
 * @version 1.0.0
 * @since 2025-12-17
 */

import { 
  IsString, 
  IsEmail, 
  IsPhoneNumber, 
  IsInt, 
  Min, 
  Max, 
  IsOptional, 
  Length, 
  IsNotEmpty,
  IsEnum
} from 'class-validator';
import { UserStatus } from '../../../business/user-mgmt/enums/user-status.enum';

/**
 * 创建用户数据传输对象
 * 
 * 职责：
 * - 定义用户创建时的数据结构和验证规则
 * - 确保输入数据的格式正确性和业务规则符合性
 * - 提供友好的错误提示信息
 * 
 * 主要字段：
 * - username: 唯一用户名，用于登录识别
 * - email: 邮箱地址，用于通知和账户找回
 * - phone: 手机号码，支持全球格式
 * - password_hash: 密码哈希值，OAuth登录时可为空
 * - nickname: 显示昵称，在游戏中展示
 * - github_id: GitHub第三方登录标识
 * - avatar_url: 用户头像链接
 * - role: 用户角色，控制权限级别
 * 
 * 使用场景：
 * - 用户注册接口的请求体验证
 * - 管理员创建用户的数据验证
 * - 第三方登录用户信息同步
 * 
 * 验证规则：
 * - 必填字段：username, nickname
 * - 唯一性字段：username, email, phone, github_id
 * - 长度限制：username(1-50), nickname(1-50), github_id(1-100)
 * - 格式验证：email格式, phone国际格式
 * - 数值范围：role(1-9)
 */
export class CreateUserDto {
  /**
   * 用户名
   * 
   * 业务规则：
   * - 必填字段，用于用户登录和唯一标识
   * - 长度限制：1-50个字符
   * - 全局唯一性：不允许重复
   * - 建议使用字母、数字、下划线组合
   * 
   * 验证规则：
   * - 非空验证：确保用户名不为空
   * - 字符串类型验证
   * - 长度范围验证：1-50字符
   */
  @IsString()
  @IsNotEmpty({ message: '用户名不能为空' })
  @Length(1, 50, { message: '用户名长度需在1-50字符之间' })
  username: string;

  /**
   * 邮箱地址
   * 
   * 业务规则：
   * - 可选字段，用于账户找回和通知
   * - 全局唯一性：不允许重复
   * - 支持标准邮箱格式验证
   * - OAuth登录时可能为空
   * 
   * 验证规则：
   * - 可选字段验证
   * - 邮箱格式验证：符合RFC标准
   * - 长度限制：最大100字符（数据库约束）
   */
  @IsOptional()
  @IsEmail({}, { message: '邮箱格式不正确' })
  email?: string;

  /**
   * 手机号码
   * 
   * 业务规则：
   * - 可选字段，用于账户找回和通知
   * - 全局唯一性：不允许重复
   * - 支持国际手机号格式
   * - 用于短信验证和双因子认证
   * 
   * 验证规则：
   * - 可选字段验证
   * - 国际手机号格式验证
   * - 长度限制：最大30字符（数据库约束）
   */
  @IsOptional()
  @IsPhoneNumber(null, { message: '手机号格式不正确' })
  phone?: string;

  /**
   * 密码哈希值
   * 
   * 业务规则：
   * - 可选字段，OAuth登录时为空
   * - 存储加密后的密码，不存储明文
   * - 用于传统用户名密码登录方式
   * - 应使用bcrypt等安全哈希算法
   * 
   * 验证规则：
   * - 可选字段验证
   * - 字符串类型验证
   * - 长度限制：最大255字符（数据库约束）
   * 
   * 安全注意：
   * - 传输过程中应使用HTTPS
   * - 日志记录时会自动脱敏处理
   */
  @IsOptional()
  @IsString({ message: '密码哈希必须是字符串' })
  password_hash?: string;

  /**
   * 用户昵称
   * 
   * 业务规则：
   * - 必填字段，用于游戏内显示
   * - 长度限制：1-50个字符
   * - 支持中文、英文、数字等字符
   * - 可以与用户名不同，更友好的显示名称
   * 
   * 验证规则：
   * - 非空验证：确保昵称不为空
   * - 字符串类型验证
   * - 长度范围验证：1-50字符
   */
  @IsString()
  @IsNotEmpty({ message: '昵称不能为空' })
  @Length(1, 50, { message: '昵称长度需在1-50字符之间' })
  nickname: string;

  /**
   * GitHub用户标识
   * 
   * 业务规则：
   * - 可选字段，用于GitHub OAuth登录
   * - 全局唯一性：不允许重复
   * - 存储GitHub用户的唯一标识符
   * - 用于关联GitHub账户信息
   * 
   * 验证规则：
   * - 可选字段验证
   * - 字符串类型验证
   * - 长度范围验证：1-100字符
   */
  @IsOptional()
  @IsString({ message: 'GitHub ID必须是字符串' })
  @Length(1, 100, { message: 'GitHub ID长度需在1-100字符之间' })
  github_id?: string;

  /**
   * 用户头像链接
   * 
   * 业务规则：
   * - 可选字段，用于显示用户头像
   * - 支持GitHub头像或自定义头像
   * - 应为有效的HTTP/HTTPS链接
   * - 建议使用CDN加速访问
   * 
   * 验证规则：
   * - 可选字段验证
   * - 字符串类型验证
   * - 长度限制：最大255字符（数据库约束）
   */
  @IsOptional()
  @IsString({ message: '头像URL必须是字符串' })
  avatar_url?: string;

  /**
   * 用户角色
   * 
   * 业务规则：
   * - 可选字段，默认为普通用户(1)
   * - 角色级别：1-普通用户，9-管理员
   * - 控制用户在系统中的权限范围
   * - 管理员具有系统管理权限
   * 
   * 验证规则：
   * - 可选字段验证
   * - 整数类型验证
   * - 数值范围验证：1-9之间
   * - 默认值：1（普通用户）
   * 
   * 权限说明：
   * - 1: 普通用户 - 基础游戏功能
   * - 9: 管理员 - 系统管理权限
   */
  @IsOptional()
  @IsInt({ message: '角色必须是数字' })
  @Min(1, { message: '角色值最小为1' })
  @Max(9, { message: '角色值最大为9' })
  role?: number = 1;

  /**
   * 邮箱验证状态
   * 
   * 业务规则：
   * - 可选字段，默认为false（未验证）
   * - 控制邮箱相关功能的可用性
   * - OAuth登录时可直接设为true
   * - 影响密码重置等安全功能
   * 
   * 验证规则：
   * - 可选字段验证
   * - 布尔类型验证
   * - 默认值：false（未验证）
   */
  @IsOptional()
  email_verified?: boolean = false;

  /**
   * 用户状态
   * 
   * 业务规则：
   * - 可选字段，默认为active（正常状态）
   * - 控制用户账户的可用性和权限
   * - 支持多种状态：正常、未激活、锁定、禁用等
   * - 影响用户登录和API访问权限
   * 
   * 验证规则：
   * - 可选字段验证
   * - 枚举类型验证
   * - 默认值：active（正常状态）
   * 
   * 状态说明：
   * - active: 正常状态，可以正常使用
   * - inactive: 未激活，需要邮箱验证
   * - locked: 已锁定，临时禁用
   * - banned: 已禁用，管理员操作
   * - deleted: 已删除，软删除状态
   * - pending: 待审核，需要管理员审核
   */
  @IsOptional()
  @IsEnum(UserStatus, { message: '用户状态必须是有效的枚举值' })
  status?: UserStatus = UserStatus.ACTIVE;
}