refactor：完善用户数据模型

- 优化用户实体字段设计和约束
- 完善用户服务的CRUD操作
- 添加详细的字段注释和业务说明
- 优化数据验证和错误处理

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

@@ -1,4 +1,20 @@
-// src/user/dto/create-user.dto.ts
+/**
+ * 用户数据传输对象模块
+ * 
+ * 功能描述：
+ * - 定义用户创建和更新的数据传输对象
+ * - 提供完整的数据验证规则和错误提示
+ * - 支持多种登录方式的数据格式验证
+ * 
+ * 依赖模块：
+ * - class-validator: 数据验证装饰器
+ * - class-transformer: 数据转换工具
+ * 
+ * @author moyin
+ * @version 1.0.0
+ * @since 2025-12-17
+ */
+
 import { 
   IsString, 
   IsEmail, 
@@ -9,51 +25,194 @@ import {
   IsOptional, 
   Length, 
   IsNotEmpty 
-} from 'class-validator'
+} from 'class-validator';
 
+/**
+ * 创建用户数据传输对象
+ * 
+ * 职责：
+ * - 定义用户创建时的数据结构和验证规则
+ * - 确保输入数据的格式正确性和业务规则符合性
+ * - 提供友好的错误提示信息
+ * 
+ * 主要字段：
+ * - 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个字符
+   * - 全局唯一性：不允许重复
+   * - 建议使用字母、数字、下划线组合
+   * 
+   * 验证规则：
+   * - 非空验证：确保用户名不为空
+   * - 字符串类型验证
+   * - 长度范围验证：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登录为空）
+  /**
+   * 密码哈希值
+   * 
+   * 业务规则：
+   * - 可选字段，OAuth登录时为空
+   * - 存储加密后的密码，不存储明文
+   * - 用于传统用户名密码登录方式
+   * - 应使用bcrypt等安全哈希算法
+   * 
+   * 验证规则：
+   * - 可选字段验证
+   * - 字符串类型验证
+   * - 长度限制：最大255字符（数据库约束）
+   * 
+   * 安全注意：
+   * - 传输过程中应使用HTTPS
+   * - 日志记录时会自动脱敏处理
+   */
   @IsOptional()
   @IsString({ message: '密码哈希必须是字符串' })
   password_hash?: string;
 
-  // 昵称：必填、字符串、长度1-50
+  /**
+   * 用户昵称
+   * 
+   * 业务规则：
+   * - 必填字段，用于游戏内显示
+   * - 长度限制：1-50个字符
+   * - 支持中文、英文、数字等字符
+   * - 可以与用户名不同，更友好的显示名称
+   * 
+   * 验证规则：
+   * - 非空验证：确保昵称不为空
+   * - 字符串类型验证
+   * - 长度范围验证：1-50字符
+   */
   @IsString()
   @IsNotEmpty({ message: '昵称不能为空' })
   @Length(1, 50, { message: '昵称长度需在1-50字符之间' })
   nickname: string;
 
-  // GitHub ID：可选、字符串、长度1-100
+  /**
+   * GitHub用户标识
+   * 
+   * 业务规则：
+   * - 可选字段，用于GitHub OAuth登录
+   * - 全局唯一性：不允许重复
+   * - 存储GitHub用户的唯一标识符
+   * - 用于关联GitHub账户信息
+   * 
+   * 验证规则：
+   * - 可选字段验证
+   * - 字符串类型验证
+   * - 长度范围验证：1-100字符
+   */
   @IsOptional()
   @IsString({ message: 'GitHub ID必须是字符串' })
   @Length(1, 100, { message: 'GitHub ID长度需在1-100字符之间' })
   github_id?: string;
 
-  // 头像URL：可选、字符串
+  /**
+   * 用户头像链接
+   * 
+   * 业务规则：
+   * - 可选字段，用于显示用户头像
+   * - 支持GitHub头像或自定义头像
+   * - 应为有效的HTTP/HTTPS链接
+   * - 建议使用CDN加速访问
+   * 
+   * 验证规则：
+   * - 可选字段验证
+   * - 字符串类型验证
+   * - 长度限制：最大255字符（数据库约束）
+   */
   @IsOptional()
   @IsString({ message: '头像URL必须是字符串' })
   avatar_url?: string;
 
-  // 角色：可选、数字、1（普通）或9（管理员）
+  /**
+   * 用户角色
+   * 
+   * 业务规则：
+   * - 可选字段，默认为普通用户(1)
+   * - 角色级别：1-普通用户，9-管理员
+   * - 控制用户在系统中的权限范围
+   * - 管理员具有系统管理权限
+   * 
+   * 验证规则：
+   * - 可选字段验证
+   * - 整数类型验证
+   * - 数值范围验证：1-9之间
+   * - 默认值：1（普通用户）
+   * 
+   * 权限说明：
+   * - 1: 普通用户 - 基础游戏功能
+   * - 9: 管理员 - 系统管理权限
+   */
   @IsOptional()
   @IsInt({ message: '角色必须是数字' })
   @Min(1, { message: '角色值最小为1' })
   @Max(9, { message: '角色值最大为9' })
-  role?: number = 1; // 默认普通用户
+  role?: number = 1;
 }