Initial WhaleTown V2 backend

src/core/db/users/users.dto.ts

@@ -0,0 +1,275 @@
+/**
+ * 用户数据传输对象模块
+ *
+ * 功能描述：
+ * - 定义用户创建和更新的数据传输对象
+ * - 提供完整的数据验证规则和错误提示
+ * - 支持多种登录方式的数据格式验证
+ * - 确保数据传输的安全性和完整性
+ *
+ * 职责分离：
+ * - 数据验证：使用class-validator进行输入数据验证
+ * - 类型定义：定义清晰的数据结构和类型约束
+ * - 错误处理：提供友好的验证错误提示信息
+ * - 业务规则：实现用户数据的业务验证逻辑
+ *
+ * 依赖模块：
+ * - class-validator: 数据验证装饰器
+ * - class-transformer: 数据转换工具
+ *
+ * 最近修改：
+ * - 2026-01-07: 代码规范优化 - 完善注释规范，添加完整的文件头和字段注释
+ *
+ * @author moyin
+ * @version 1.0.1
+ * @since 2025-12-17
+ * @lastModified 2026-01-07
+ */
+
+import {
+  IsString,
+  IsEmail,
+  IsPhoneNumber,
+  IsInt,
+  Min,
+  Max,
+  IsOptional,
+  Length,
+  IsNotEmpty,
+  IsEnum
+} from 'class-validator';
+import { UserStatus } from './user_status.enum';
+import { USER_ROLES, FIELD_LIMITS } from './users.constants';
+
+/**
+ * 创建用户数据传输对象
+ *
+ * 职责：
+ * - 定义用户创建时的数据结构和验证规则
+ * - 确保输入数据的格式正确性和业务规则符合性
+ * - 提供友好的错误提示信息
+ *
+ * 主要字段：
+ * - 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, FIELD_LIMITS.USERNAME_MAX_LENGTH, { message: `用户名长度需在1-${FIELD_LIMITS.USERNAME_MAX_LENGTH}字符之间` })
+  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, FIELD_LIMITS.NICKNAME_MAX_LENGTH, { message: `昵称长度需在1-${FIELD_LIMITS.NICKNAME_MAX_LENGTH}字符之间` })
+  nickname: string;
+
+  /**
+   * GitHub用户标识
+   *
+   * 业务规则：
+   * - 可选字段，用于GitHub OAuth登录
+   * - 全局唯一性：不允许重复
+   * - 存储GitHub用户的唯一标识符
+   * - 用于关联GitHub账户信息
+   *
+   * 验证规则：
+   * - 可选字段验证
+   * - 字符串类型验证
+   * - 长度范围验证：1-100字符
+   */
+  @IsOptional()
+  @IsString({ message: 'GitHub ID必须是字符串' })
+  @Length(1, FIELD_LIMITS.GITHUB_ID_MAX_LENGTH, { message: `GitHub ID长度需在1-${FIELD_LIMITS.GITHUB_ID_MAX_LENGTH}字符之间` })
+  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(USER_ROLES.NORMAL_USER, { message: `角色值最小为${USER_ROLES.NORMAL_USER}` })
+  @Max(USER_ROLES.ADMIN, { message: `角色值最大为${USER_ROLES.ADMIN}` })
+  role?: number = USER_ROLES.NORMAL_USER;
+
+  /**
+   * 邮箱验证状态
+   *
+   * 业务规则：
+   * - 可选字段，默认为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;
+}