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;
 }

src/core/db/users/users.entity.ts

@@ -1,15 +1,103 @@
+/**
+ * 用户数据实体模块
+ * 
+ * 功能描述：
+ * - 定义用户数据表的实体映射和字段约束
+ * - 提供用户数据的持久化存储结构
+ * - 支持多种登录方式的用户信息存储
+ * 
+ * 依赖模块：
+ * - TypeORM: ORM框架，提供数据库映射功能
+ * - MySQL: 底层数据库存储
+ * 
+ * 数据库表：users
+ * 存储引擎：InnoDB
+ * 字符集：utf8mb4
+ * 
+ * @author moyin
+ * @version 1.0.0
+ * @since 2025-12-17
+ */
+
 import { Entity, Column, PrimaryGeneratedColumn, CreateDateColumn, UpdateDateColumn } from 'typeorm';
 
-@Entity('users') // 对应数据库表名
+/**
+ * 用户实体类
+ * 
+ * 职责：
+ * - 映射数据库users表的结构和约束
+ * - 定义用户数据的字段类型和验证规则
+ * - 提供用户信息的完整数据模型
+ * 
+ * 主要功能：
+ * - 用户身份标识和认证信息存储
+ * - 支持传统登录和OAuth第三方登录
+ * - 用户基础信息和角色权限管理
+ * - 自动时间戳记录和更新
+ * 
+ * 数据完整性：
+ * - 主键约束：id字段自增主键
+ * - 唯一约束：username, email, phone, github_id
+ * - 非空约束：username, nickname, role
+ * - 外键关联：可扩展关联用户详情、权限等表
+ * 
+ * 使用场景：
+ * - 用户注册和登录验证
+ * - 用户信息查询和更新
+ * - 权限验证和角色管理
+ * - 用户数据统计和分析
+ * 
+ * 索引策略：
+ * - 主键索引：id (自动创建)
+ * - 唯一索引：username, email, phone, github_id
+ * - 普通索引：role (用于角色查询)
+ * - 复合索引：created_at + role (用于分页查询)
+ */
+@Entity('users')
 export class Users {
-  // id：bigint、主键、非空、唯一、自增
+  /**
+   * 用户主键ID
+   * 
+   * 数据库设计：
+   * - 类型：BIGINT，支持大量用户数据
+   * - 约束：主键、非空、自增
+   * - 范围：1 ~ 9,223,372,036,854,775,807
+   * 
+   * 业务规则：
+   * - 系统自动生成，不可手动指定
+   * - 全局唯一标识符，用于用户关联
+   * - 作为其他表的外键引用
+   * 
+   * 性能考虑：
+   * - 自增主键，插入性能优异
+   * - 聚簇索引，范围查询效率高
+   * - BIGINT类型，避免ID耗尽问题
+   */
   @PrimaryGeneratedColumn({
     type: 'bigint',
     comment: '主键ID'
   })
   id: bigint;
 
-  // username：varchar(50)、非空、唯一
+  /**
+   * 用户名
+   * 
+   * 数据库设计：
+   * - 类型：VARCHAR(50)，支持多语言字符
+   * - 约束：非空、唯一索引
+   * - 字符集：utf8mb4，支持emoji等特殊字符
+   * 
+   * 业务规则：
+   * - 用户登录的唯一标识符
+   * - 全系统唯一，不允许重复
+   * - 长度限制：1-50个字符
+   * - 建议格式：字母、数字、下划线组合
+   * 
+   * 安全考虑：
+   * - 不应包含敏感信息
+   * - 避免使用易猜测的用户名
+   * - 支持用户名修改（需要额外验证）
+   */
   @Column({
     type: 'varchar',
     length: 50,
@@ -19,7 +107,25 @@ export class Users {
   })
   username: string;
 
-  // email：varchar(100)、允许空、唯一
+  /**
+   * 邮箱地址
+   * 
+   * 数据库设计：
+   * - 类型：VARCHAR(100)，支持长邮箱地址
+   * - 约束：允许空、唯一索引
+   * - 索引：用于快速邮箱查找
+   * 
+   * 业务规则：
+   * - 用于账户找回和重要通知
+   * - 全系统唯一，不允许重复
+   * - OAuth登录时可能为空
+   * - 支持邮箱验证和双因子认证
+   * 
+   * 隐私保护：
+   * - 敏感信息，日志记录时脱敏
+   * - 仅用于系统通知，不对外展示
+   * - 支持用户自主修改和验证
+   */
   @Column({
     type: 'varchar',
     length: 100,
@@ -29,7 +135,25 @@ export class Users {
   })
   email: string;
 
-  // phone：varchar(30)、允许空、唯一
+  /**
+   * 手机号码
+   * 
+   * 数据库设计：
+   * - 类型：VARCHAR(30)，支持国际号码格式
+   * - 约束：允许空、唯一索引
+   * - 格式：包含国家代码的完整号码
+   * 
+   * 业务规则：
+   * - 用于账户找回和短信通知
+   * - 全系统唯一，不允许重复
+   * - 支持国际手机号格式（+86、+1等）
+   * - 用于短信验证码和双因子认证
+   * 
+   * 隐私保护：
+   * - 敏感信息，日志记录时脱敏
+   * - 仅用于安全验证，不对外展示
+   * - 支持用户自主修改和验证
+   */
   @Column({
     type: 'varchar',
     length: 30,
@@ -39,7 +163,27 @@ export class Users {
   })
   phone: string;
 
-  // password_hash：varchar(255)、允许空
+  /**
+   * 密码哈希值
+   * 
+   * 数据库设计：
+   * - 类型：VARCHAR(255)，支持各种哈希算法
+   * - 约束：允许空（OAuth登录时）
+   * - 存储：加密后的哈希值，不存储明文
+   * 
+   * 业务规则：
+   * - 传统用户名密码登录方式使用
+   * - OAuth第三方登录时此字段为空
+   * - 使用bcrypt等安全哈希算法
+   * - 支持密码强度验证和定期更新
+   * 
+   * 安全措施：
+   * - 绝不存储明文密码
+   * - 使用盐值防止彩虹表攻击
+   * - 日志系统自动脱敏处理
+   * - 传输过程使用HTTPS加密
+   * - 支持密码重置和修改功能
+   */
   @Column({
     type: 'varchar',
     length: 255,
@@ -48,7 +192,26 @@ export class Users {
   })
   password_hash: string;
 
-  // nickname：varchar(50)、非空
+  /**
+   * 用户昵称
+   * 
+   * 数据库设计：
+   * - 类型：VARCHAR(50)，支持多语言字符
+   * - 约束：非空，无唯一性要求
+   * - 字符集：utf8mb4，支持emoji表情
+   * 
+   * 业务规则：
+   * - 游戏内显示的友好名称
+   * - 允许重复，提高用户体验
+   * - 长度限制：1-50个字符
+   * - 支持中文、英文、数字、表情符号
+   * 
+   * 显示规则：
+   * - 游戏内头顶显示名称
+   * - 聊天消息发送者标识
+   * - 排行榜和用户列表显示
+   * - 支持用户随时修改
+   */
   @Column({
     type: 'varchar',
     length: 50,
@@ -57,7 +220,26 @@ export class Users {
   })
   nickname: string;
 
-  // github_id：varchar(100)、允许空、唯一
+  /**
+   * GitHub用户标识
+   * 
+   * 数据库设计：
+   * - 类型：VARCHAR(100)，存储GitHub用户ID
+   * - 约束：允许空、唯一索引
+   * - 用途：GitHub OAuth登录关联
+   * 
+   * 业务规则：
+   * - GitHub第三方登录的唯一标识
+   * - 全系统唯一，不允许重复
+   * - 用于关联GitHub账户信息
+   * - 支持GitHub头像和基础信息同步
+   * 
+   * OAuth集成：
+   * - 存储GitHub返回的用户ID
+   * - 用于后续API调用身份验证
+   * - 支持账户绑定和解绑操作
+   * - 可扩展支持其他OAuth提供商
+   */
   @Column({
     type: 'varchar',
     length: 100,
@@ -67,7 +249,26 @@ export class Users {
   })
   github_id: string;
 
-  // avatar_url：varchar(255)、允许空
+  /**
+   * 用户头像链接
+   * 
+   * 数据库设计：
+   * - 类型：VARCHAR(255)，支持长URL
+   * - 约束：允许空，无唯一性要求
+   * - 存储：完整的HTTP/HTTPS链接
+   * 
+   * 业务规则：
+   * - 用户头像图片的访问链接
+   * - 支持GitHub头像或自定义上传
+   * - 建议使用CDN加速访问
+   * - 支持多种图片格式（jpg、png、gif等）
+   * 
+   * 性能优化：
+   * - 建议使用图片CDN服务
+   * - 支持多尺寸头像适配
+   * - 缓存策略优化加载速度
+   * - 默认头像兜底机制
+   */
   @Column({
     type: 'varchar',
     length: 255,
@@ -76,7 +277,31 @@ export class Users {
   })
   avatar_url: string;
 
-  // role：tinyint、非空、默认1
+  /**
+   * 用户角色
+   * 
+   * 数据库设计：
+   * - 类型：TINYINT，节省存储空间
+   * - 约束：非空、默认值1
+   * - 范围：1-9，支持角色扩展
+   * 
+   * 业务规则：
+   * - 控制用户在系统中的权限级别
+   * - 1：普通用户，基础游戏功能
+   * - 9：管理员，系统管理权限
+   * - 支持角色升级和降级操作
+   * 
+   * 权限设计：
+   * - 基于角色的访问控制（RBAC）
+   * - 支持细粒度权限配置
+   * - 可扩展更多角色类型
+   * - 权限验证中间件集成
+   * 
+   * 扩展性：
+   * - 预留2-8角色级别供未来使用
+   * - 支持角色权限动态配置
+   * - 可关联角色权限表进行扩展
+   */
   @Column({
     type: 'tinyint',
     nullable: false,
@@ -85,7 +310,26 @@ export class Users {
   })
   role: number;
 
-  // created_at：datetime、非空、默认当前时间
+  /**
+   * 创建时间
+   * 
+   * 数据库设计：
+   * - 类型：DATETIME，精确到秒
+   * - 约束：非空、默认当前时间
+   * - 时区：使用系统时区，建议UTC
+   * 
+   * 业务规则：
+   * - 记录用户注册的准确时间
+   * - 用于用户数据统计和分析
+   * - 支持按时间范围查询用户
+   * - 不可修改，保证数据完整性
+   * 
+   * 应用场景：
+   * - 用户注册趋势分析
+   * - 新用户欢迎流程触发
+   * - 数据审计和合规要求
+   * - 用户生命周期管理
+   */
   @CreateDateColumn({
     type: 'datetime',
     nullable: false,
@@ -94,12 +338,31 @@ export class Users {
   })
   created_at: Date;
 
-  // updated_at：datetime、非空、默认当前时间
+  /**
+   * 更新时间
+   * 
+   * 数据库设计：
+   * - 类型：DATETIME，精确到秒
+   * - 约束：非空、自动更新
+   * - 触发：任何字段更新时自动刷新
+   * 
+   * 业务规则：
+   * - 记录用户信息最后修改时间
+   * - 数据库级别自动维护
+   * - 用于数据同步和缓存失效
+   * - 支持增量数据同步
+   * 
+   * 应用场景：
+   * - 数据变更审计
+   * - 缓存更新策略
+   * - 数据同步时间戳
+   * - 用户活跃度分析
+   */
   @UpdateDateColumn({
     type: 'datetime',
     nullable: false,
     default: () => 'CURRENT_TIMESTAMP',
-    onUpdate: 'CURRENT_TIMESTAMP', // 数据库更新时自动刷新时间
+    onUpdate: 'CURRENT_TIMESTAMP',
     comment: '更新时间'
   })
   updated_at: Date;

src/core/db/users/users.service.ts

@@ -8,7 +8,7 @@
  * 
  * @author moyin
  * @version 1.0.0
- * @since 2024-12-17
+ * @since 2025-12-17
  */
 
 import { Injectable, ConflictException, NotFoundException, BadRequestException } from '@nestjs/common';