/**
 * 用户数据实体模块
 * 
 * 功能描述：
 * - 定义用户数据表的实体映射和字段约束
 * - 提供用户数据的持久化存储结构
 * - 支持多种登录方式的用户信息存储
 * 
 * 依赖模块：
 * - TypeORM: ORM框架，提供数据库映射功能
 * - MySQL: 底层数据库存储
 * 
 * 数据库表：users
 * 存储引擎：InnoDB
 * 字符集：utf8mb4
 * 
 * @author moyin
 * @version 1.0.0
 * @since 2025-12-17
 */

import { Entity, Column, PrimaryGeneratedColumn, CreateDateColumn, UpdateDateColumn } from 'typeorm';

/**
 * 用户实体类
 * 
 * 职责：
 * - 映射数据库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，支持大量用户数据
   * - 约束：主键、非空、自增
   * - 范围：1 ~ 9,223,372,036,854,775,807
   * 
   * 业务规则：
   * - 系统自动生成，不可手动指定
   * - 全局唯一标识符，用于用户关联
   * - 作为其他表的外键引用
   * 
   * 性能考虑：
   * - 自增主键，插入性能优异
   * - 聚簇索引，范围查询效率高
   * - BIGINT类型，避免ID耗尽问题
   */
  @PrimaryGeneratedColumn({
    type: 'bigint',
    comment: '主键ID'
  })
  id: bigint;

  /**
   * 用户名
   * 
   * 数据库设计：
   * - 类型：VARCHAR(50)，支持多语言字符
   * - 约束：非空、唯一索引
   * - 字符集：utf8mb4，支持emoji等特殊字符
   * 
   * 业务规则：
   * - 用户登录的唯一标识符
   * - 全系统唯一，不允许重复
   * - 长度限制：1-50个字符
   * - 建议格式：字母、数字、下划线组合
   * 
   * 安全考虑：
   * - 不应包含敏感信息
   * - 避免使用易猜测的用户名
   * - 支持用户名修改（需要额外验证）
   */
  @Column({
    type: 'varchar',
    length: 50,
    nullable: false,
    unique: true,
    comment: '唯一用户名/登录名'
  })
  username: string;

  /**
   * 邮箱地址
   * 
   * 数据库设计：
   * - 类型：VARCHAR(100)，支持长邮箱地址
   * - 约束：允许空、唯一索引
   * - 索引：用于快速邮箱查找
   * 
   * 业务规则：
   * - 用于账户找回和重要通知
   * - 全系统唯一，不允许重复
   * - OAuth登录时可能为空
   * - 支持邮箱验证和双因子认证
   * 
   * 隐私保护：
   * - 敏感信息，日志记录时脱敏
   * - 仅用于系统通知，不对外展示
   * - 支持用户自主修改和验证
   */
  @Column({
    type: 'varchar',
    length: 100,
    nullable: true,
    unique: true,
    comment: '邮箱（用于找回/通知）'
  })
  email: string;

  /**
   * 手机号码
   * 
   * 数据库设计：
   * - 类型：VARCHAR(30)，支持国际号码格式
   * - 约束：允许空、唯一索引
   * - 格式：包含国家代码的完整号码
   * 
   * 业务规则：
   * - 用于账户找回和短信通知
   * - 全系统唯一，不允许重复
   * - 支持国际手机号格式（+86、+1等）
   * - 用于短信验证码和双因子认证
   * 
   * 隐私保护：
   * - 敏感信息，日志记录时脱敏
   * - 仅用于安全验证，不对外展示
   * - 支持用户自主修改和验证
   */
  @Column({
    type: 'varchar',
    length: 30,
    nullable: true,
    unique: true,
    comment: '全球电话号码（用于找回/通知）'
  })
  phone: string;

  /**
   * 密码哈希值
   * 
   * 数据库设计：
   * - 类型：VARCHAR(255)，支持各种哈希算法
   * - 约束：允许空（OAuth登录时）
   * - 存储：加密后的哈希值，不存储明文
   * 
   * 业务规则：
   * - 传统用户名密码登录方式使用
   * - OAuth第三方登录时此字段为空
   * - 使用bcrypt等安全哈希算法
   * - 支持密码强度验证和定期更新
   * 
   * 安全措施：
   * - 绝不存储明文密码
   * - 使用盐值防止彩虹表攻击
   * - 日志系统自动脱敏处理
   * - 传输过程使用HTTPS加密
   * - 支持密码重置和修改功能
   */
  @Column({
    type: 'varchar',
    length: 255,
    nullable: true,
    comment: '密码哈希（OAuth登录为空）'
  })
  password_hash: string;

  /**
   * 用户昵称
   * 
   * 数据库设计：
   * - 类型：VARCHAR(50)，支持多语言字符
   * - 约束：非空，无唯一性要求
   * - 字符集：utf8mb4，支持emoji表情
   * 
   * 业务规则：
   * - 游戏内显示的友好名称
   * - 允许重复，提高用户体验
   * - 长度限制：1-50个字符
   * - 支持中文、英文、数字、表情符号
   * 
   * 显示规则：
   * - 游戏内头顶显示名称
   * - 聊天消息发送者标识
   * - 排行榜和用户列表显示
   * - 支持用户随时修改
   */
  @Column({
    type: 'varchar',
    length: 50,
    nullable: false,
    comment: '显示昵称（头顶显示）'
  })
  nickname: string;

  /**
   * GitHub用户标识
   * 
   * 数据库设计：
   * - 类型：VARCHAR(100)，存储GitHub用户ID
   * - 约束：允许空、唯一索引
   * - 用途：GitHub OAuth登录关联
   * 
   * 业务规则：
   * - GitHub第三方登录的唯一标识
   * - 全系统唯一，不允许重复
   * - 用于关联GitHub账户信息
   * - 支持GitHub头像和基础信息同步
   * 
   * OAuth集成：
   * - 存储GitHub返回的用户ID
   * - 用于后续API调用身份验证
   * - 支持账户绑定和解绑操作
   * - 可扩展支持其他OAuth提供商
   */
  @Column({
    type: 'varchar',
    length: 100,
    nullable: true,
    unique: true,
    comment: 'GitHub OpenID（第三方登录用）'
  })
  github_id: string;

  /**
   * 用户头像链接
   * 
   * 数据库设计：
   * - 类型：VARCHAR(255)，支持长URL
   * - 约束：允许空，无唯一性要求
   * - 存储：完整的HTTP/HTTPS链接
   * 
   * 业务规则：
   * - 用户头像图片的访问链接
   * - 支持GitHub头像或自定义上传
   * - 建议使用CDN加速访问
   * - 支持多种图片格式（jpg、png、gif等）
   * 
   * 性能优化：
   * - 建议使用图片CDN服务
   * - 支持多尺寸头像适配
   * - 缓存策略优化加载速度
   * - 默认头像兜底机制
   */
  @Column({
    type: 'varchar',
    length: 255,
    nullable: true,
    comment: 'GitHub头像或自定义头像URL'
  })
  avatar_url: string;

  /**
   * 用户角色
   * 
   * 数据库设计：
   * - 类型：TINYINT，节省存储空间
   * - 约束：非空、默认值1
   * - 范围：1-9，支持角色扩展
   * 
   * 业务规则：
   * - 控制用户在系统中的权限级别
   * - 1：普通用户，基础游戏功能
   * - 9：管理员，系统管理权限
   * - 支持角色升级和降级操作
   * 
   * 权限设计：
   * - 基于角色的访问控制（RBAC）
   * - 支持细粒度权限配置
   * - 可扩展更多角色类型
   * - 权限验证中间件集成
   * 
   * 扩展性：
   * - 预留2-8角色级别供未来使用
   * - 支持角色权限动态配置
   * - 可关联角色权限表进行扩展
   */
  @Column({
    type: 'tinyint',
    nullable: false,
    default: 1,
    comment: '角色：1-普通，9-管理员'
  })
  role: number;

  /**
   * 创建时间
   * 
   * 数据库设计：
   * - 类型：DATETIME，精确到秒
   * - 约束：非空、默认当前时间
   * - 时区：使用系统时区，建议UTC
   * 
   * 业务规则：
   * - 记录用户注册的准确时间
   * - 用于用户数据统计和分析
   * - 支持按时间范围查询用户
   * - 不可修改，保证数据完整性
   * 
   * 应用场景：
   * - 用户注册趋势分析
   * - 新用户欢迎流程触发
   * - 数据审计和合规要求
   * - 用户生命周期管理
   */
  @CreateDateColumn({
    type: 'datetime',
    nullable: false,
    default: () => 'CURRENT_TIMESTAMP',
    comment: '注册时间'
  })
  created_at: Date;

  /**
   * 更新时间
   * 
   * 数据库设计：
   * - 类型：DATETIME，精确到秒
   * - 约束：非空、自动更新
   * - 触发：任何字段更新时自动刷新
   * 
   * 业务规则：
   * - 记录用户信息最后修改时间
   * - 数据库级别自动维护
   * - 用于数据同步和缓存失效
   * - 支持增量数据同步
   * 
   * 应用场景：
   * - 数据变更审计
   * - 缓存更新策略
   * - 数据同步时间戳
   * - 用户活跃度分析
   */
  @UpdateDateColumn({
    type: 'datetime',
    nullable: false,
    default: () => 'CURRENT_TIMESTAMP',
    onUpdate: 'CURRENT_TIMESTAMP',
    comment: '更新时间'
  })
  updated_at: Date;
}