/**
 * 用户数据实体模块
 * 
 * 功能描述：
 * - 定义用户数据表的实体映射和字段约束
 * - 提供用户数据的持久化存储结构
 * - 支持多种登录方式的用户信息存储
 * - 实现完整的用户数据模型和关系映射
 * 
 * 职责分离：
 * - 数据映射：TypeORM实体与数据库表的映射关系
 * - 约束定义：字段类型、长度、唯一性等约束规则
 * - 关系管理：与其他实体的关联关系定义
 * - 索引优化：数据库查询性能优化策略
 * 
 * 依赖模块：
 * - TypeORM: ORM框架，提供数据库映射功能
 * - MySQL: 底层数据库存储
 * 
 * 数据库表：users
 * 存储引擎：InnoDB
 * 字符集：utf8mb4
 * 
 * 最近修改：
 * - 2026-01-07: 代码规范优化 - 完善注释规范，添加完整的文件头和字段注释
 * 
 * @author moyin
 * @version 1.0.1
 * @since 2025-12-17
 * @lastModified 2026-01-07
 */

import { Entity, Column, PrimaryGeneratedColumn, CreateDateColumn, UpdateDateColumn, OneToOne } from 'typeorm';
import { UserStatus } from './user_status.enum';
import { ZulipAccounts } from '../zulip_accounts/zulip_accounts.entity';
import { FIELD_LIMITS } from './users.constants';

/**
 * 用户实体类
 * 
 * 职责：
 * - 映射数据库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: FIELD_LIMITS.USERNAME_MAX_LENGTH,
    nullable: false,
    unique: true,
    comment: '唯一用户名/登录名'
  })
  username: string;

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

  /**
   * 邮箱验证状态
   * 
   * 数据库设计：
   * - 类型：BOOLEAN，布尔值
   * - 约束：非空、默认值false
   * - 索引：用于查询已验证用户
   * 
   * 业务规则：
   * - false：邮箱未验证
   * - true：邮箱已验证
   * - 影响密码重置等安全功能
   * - OAuth登录时可直接设为true
   * 
   * 安全考虑：
   * - 未验证邮箱限制部分功能
   * - 验证后才能用于密码重置
   * - 支持重新发送验证邮件
   */
  @Column({
    type: 'boolean',
    nullable: false,
    default: false,
    comment: '邮箱是否已验证'
  })
  email_verified: boolean;

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

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

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

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

  /**
   * 用户状态
   * 
   * 数据库设计：
   * - 类型：VARCHAR(20)，存储状态枚举值
   * - 约束：非空、默认值'active'
   * - 索引：用于状态查询和统计
   * 
   * 业务规则：
   * - 控制用户账户的可用性和权限
   * - active：正常状态，可以正常使用
   * - inactive：未激活，需要邮箱验证
   * - locked：已锁定，临时禁用
   * - banned：已禁用，管理员操作
   * - deleted：已删除，软删除状态
   * - pending：待审核，需要管理员审核
   * 
   * 安全控制：
   * - 登录时检查状态权限
   * - API访问时验证状态
   * - 状态变更记录审计日志
   * - 支持批量状态管理
   * 
   * 应用场景：
   * - 账户安全管理
   * - 用户生命周期控制
   * - 违规用户处理
   * - 系统维护和升级
   */
  @Column({
    type: 'varchar',
    length: FIELD_LIMITS.STATUS_MAX_LENGTH,
    nullable: true,
    default: UserStatus.ACTIVE,
    comment: '用户状态：active-正常，inactive-未激活，locked-锁定，banned-禁用，deleted-删除，pending-待审核'
  })
  status?: UserStatus;

  /**
   * 创建时间
   * 
   * 数据库设计：
   * - 类型：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;

  /**
   * 删除时间
   * 
   * 数据库设计：
   * - 类型：DATETIME，精确到秒
   * - 约束：允许空，软删除时手动设置
   * - 索引：用于过滤已删除记录
   * 
   * 业务规则：
   * - null：正常状态，未删除
   * - 有值：已软删除，记录删除时间
   * - 软删除的记录在查询时需要手动过滤
   * - 支持数据恢复和审计追踪
   * 
   * 应用场景：
   * - 数据安全删除，避免误删
   * - 数据审计和合规要求
   * - 支持数据恢复功能
   * - 删除操作的时间追踪
   */
  // @Column({
  //   type: 'datetime',
  //   nullable: true,
  //   default: null,
  //   comment: '软删除时间，null表示未删除'
  // })
  // deleted_at?: Date;

  /**
   * 关联的Zulip账号
   * 
   * 关系设计：
   * - 类型：一对一关系（OneToOne）
   * - 外键：在ZulipAccounts表中
   * - 级联：不设置级联删除，保证数据安全
   * 
   * 业务规则：
   * - 每个游戏用户最多关联一个Zulip账号
   * - 支持延迟加载，提高查询性能
   * - 可选关联，不是所有用户都有Zulip账号
   * 
   * 使用场景：
   * - 游戏内聊天功能集成
   * - 跨平台消息同步
   * - 用户身份验证和权限管理
   */
  @OneToOne(() => ZulipAccounts, zulipAccount => zulipAccount.gameUser)
  zulipAccount?: ZulipAccounts;
}