/**
 * 用户档案数据实体模块
 * 
 * 功能描述：
 * - 定义用户档案表的实体映射和字段约束
 * - 提供用户档案数据的持久化存储结构
 * - 支持用户位置信息和档案数据存储
 * - 实现完整的用户档案数据模型和关系映射
 * 
 * 职责分离：
 * - 数据映射：TypeORM实体与数据库表的映射关系
 * - 约束定义：字段类型、长度、唯一性等约束规则
 * - 关系管理：与其他实体的关联关系定义
 * - 索引优化：数据库查询性能优化策略
 * 
 * 依赖模块：
 * - TypeORM: ORM框架，提供数据库映射功能
 * - MySQL: 底层数据库存储
 * 
 * 数据库表：user_profiles
 * 存储引擎：InnoDB
 * 字符集：utf8mb4
 * 
 * 最近修改：
 * - 2026-01-08: 功能新增 - 创建用户档案实体，支持位置广播系统 (修改者: moyin)
 * 
 * @author moyin
 * @version 1.0.0
 * @since 2026-01-08
 * @lastModified 2026-01-08
 */

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

/**
 * 用户档案实体类
 * 
 * 职责：
 * - 映射数据库user_profiles表的结构和约束
 * - 定义用户档案数据的字段类型和验证规则
 * - 提供用户位置信息和档案数据的完整数据模型
 * 
 * 主要功能：
 * - 用户基础档案信息存储
 * - 用户位置信息管理（current_map, pos_x, pos_y）
 * - 用户状态和活跃度跟踪
 * - 自动时间戳记录和更新
 * 
 * 数据完整性：
 * - 主键约束：id字段自增主键
 * - 外键约束：user_id关联users表
 * - 非空约束：user_id, current_map, pos_x, pos_y
 * - 默认值：current_map='plaza', pos_x=0, pos_y=0
 * 
 * 使用场景：
 * - 用户档案信息查询和更新
 * - 位置广播系统的位置数据存储
 * - 用户活跃度统计和分析
 * - 游戏内用户状态管理
 * 
 * 索引策略：
 * - 主键索引：id (自动创建)
 * - 唯一索引：user_id (用户唯一档案)
 * - 普通索引：current_map (用于地图查询)
 * - 复合索引：current_map + status (用于活跃用户查询)
 */
@Entity('user_profiles')
export class UserProfiles {
  /**
   * 档案主键ID
   * 
   * 数据库设计：
   * - 类型：BIGINT，支持大量档案数据
   * - 约束：主键、非空、自增
   * - 范围：1 ~ 9,223,372,036,854,775,807
   * 
   * 业务规则：
   * - 系统自动生成，不可手动指定
   * - 全局唯一标识符，用于档案关联
   * - 作为其他表的外键引用
   */
  @PrimaryGeneratedColumn({
    type: 'bigint',
    comment: '主键ID'
  })
  id: bigint;

  /**
   * 关联用户ID
   * 
   * 数据库设计：
   * - 类型：BIGINT，与users表id字段对应
   * - 约束：非空、唯一索引
   * - 外键：关联users表的主键
   * 
   * 业务规则：
   * - 每个用户只能有一个档案记录
   * - 用于关联用户基础信息和档案信息
   * - 删除用户时需要同步处理档案数据
   * 
   * 性能考虑：
   * - 建立唯一索引，确保一对一关系
   * - 用于JOIN查询用户完整信息
   */
  @Column({
    type: 'bigint',
    nullable: false,
    unique: true,
    comment: '关联users.id'
  })
  user_id: bigint;

  /**
   * 用户简介
   * 
   * 数据库设计：
   * - 类型：VARCHAR(500)，支持较长的自我介绍
   * - 约束：允许空，无唯一性要求
   * - 字符集：utf8mb4，支持emoji表情
   * 
   * 业务规则：
   * - 用户自定义的个人简介信息
   * - 支持多语言和特殊字符
   * - 长度限制：最多500个字符
   * - 可用于用户搜索和推荐
   */
  @Column({
    type: 'varchar',
    length: 500,
    nullable: true,
    comment: '自我介绍'
  })
  bio?: string;

  /**
   * 简历内容
   * 
   * 数据库设计：
   * - 类型：TEXT，支持大量文本内容
   * - 约束：允许空，无长度限制
   * - 存储：适合存储结构化的简历信息
   * 
   * 业务规则：
   * - 用户的详细简历或经历信息
   * - 支持富文本或结构化数据
   * - 可用于职业匹配和推荐
   * - 隐私敏感，需要权限控制
   */
  @Column({
    type: 'text',
    nullable: true,
    comment: '个人详细简历'
  })
  resume_content?: string;

  /**
   * 标签信息
   * 
   * 数据库设计：
   * - 类型：JSON，支持结构化标签数据
   * - 约束：允许空，灵活的数据结构
   * - 存储：JSON格式，便于查询和过滤
   * 
   * 业务规则：
   * - 用户的兴趣标签、技能标签等
   * - 支持多维度标签分类
   * - 用于用户匹配和内容推荐
   * - 支持动态添加和删除标签
   * 
   * 数据格式示例：
   * ```json
   * {
   *   "interests": ["游戏", "编程", "音乐"],
   *   "skills": ["JavaScript", "Python", "React"],
   *   "personality": ["外向", "创新", "团队合作"]
   * }
   * ```
   */
  @Column({
    type: 'json',
    nullable: true,
    comment: '身份标签信息'
  })
  tags?: Record<string, any>;

  /**
   * 社交链接
   * 
   * 数据库设计：
   * - 类型：JSON，支持多个社交平台链接
   * - 约束：允许空，灵活的数据结构
   * - 存储：JSON格式，便于扩展新平台
   * 
   * 业务规则：
   * - 用户的各种社交媒体链接
   * - 支持GitHub、Twitter、LinkedIn等平台
   * - 用于用户社交网络建立
   * - 需要验证链接的有效性
   * 
   * 数据格式示例：
   * ```json
   * {
   *   "github": "https://github.com/username",
   *   "twitter": "https://twitter.com/username",
   *   "linkedin": "https://linkedin.com/in/username",
   *   "website": "https://personal-website.com"
   * }
   * ```
   */
  @Column({
    type: 'json',
    nullable: true,
    comment: '社交链接信息'
  })
  social_links?: Record<string, string>;

  /**
   * 皮肤ID
   * 
   * 数据库设计：
   * - 类型：INT，整数类型
   * - 约束：允许空，默认值null
   * - 范围：支持大量皮肤选择
   * 
   * 业务规则：
   * - 用户选择的游戏皮肤或主题
   * - 关联皮肤资源库的ID
   * - 影响游戏内角色外观
   * - 支持皮肤商城和个性化定制
   */
  @Column({
    type: 'int',
    nullable: true,
    comment: '角色外观皮肤'
  })
  skin_id?: number;

  /**
   * 当前地图
   * 
   * 数据库设计：
   * - 类型：VARCHAR(50)，支持地图名称
   * - 约束：非空、默认值'plaza'
   * - 索引：用于地图用户查询
   * 
   * 业务规则：
   * - 用户当前所在的游戏地图
   * - 用于位置广播系统的地图过滤
   * - 影响用户可见性和交互范围
   * - 默认为广场(plaza)，新用户的起始位置
   * 
   * 位置广播系统：
   * - 核心字段，用于确定用户所在区域
   * - 同一地图的用户可以相互看到位置
   * - 切换地图时需要更新此字段
   */
  @Column({
    type: 'varchar',
    length: 50,
    nullable: false,
    default: 'plaza',
    comment: '当前所在地图'
  })
  current_map: string;

  /**
   * X坐标位置
   * 
   * 数据库设计：
   * - 类型：FLOAT，支持小数坐标
   * - 约束：非空、默认值0
   * - 精度：单精度浮点数，满足游戏精度需求
   * 
   * 业务规则：
   * - 用户在当前地图的X轴坐标
   * - 用于位置广播系统的精确定位
   * - 坐标范围由具体地图决定
   * - 默认值0表示地图中心或起始点
   * 
   * 位置广播系统：
   * - 核心字段，用于计算用户间距离
   * - 实时更新，频繁读写操作
   * - 需要与Redis缓存保持同步
   */
  @Column({
    type: 'float',
    nullable: false,
    default: 0,
    comment: 'X坐标（横轴）'
  })
  pos_x: number;

  /**
   * Y坐标位置
   * 
   * 数据库设计：
   * - 类型：FLOAT，支持小数坐标
   * - 约束：非空、默认值0
   * - 精度：单精度浮点数，满足游戏精度需求
   * 
   * 业务规则：
   * - 用户在当前地图的Y轴坐标
   * - 用于位置广播系统的精确定位
   * - 坐标范围由具体地图决定
   * - 默认值0表示地图中心或起始点
   * 
   * 位置广播系统：
   * - 核心字段，用于计算用户间距离
   * - 实时更新，频繁读写操作
   * - 需要与Redis缓存保持同步
   */
  @Column({
    type: 'float',
    nullable: false,
    default: 0,
    comment: 'Y坐标（纵轴）'
  })
  pos_y: number;

  /**
   * 用户状态
   * 
   * 数据库设计：
   * - 类型：TINYINT，节省存储空间
   * - 约束：非空、默认值0
   * - 范围：0-255，支持多种状态
   * 
   * 业务规则：
   * - 用户当前的活动状态
   * - 0: 离线，1: 在线，2: 忙碌，3: 隐身等
   * - 影响位置广播的可见性
   * - 用于用户活跃度统计
   * 
   * 位置广播系统：
   * - 影响位置信息的广播范围
   * - 隐身用户不参与位置广播
   * - 离线用户需要清理位置缓存
   */
  @Column({
    type: 'tinyint',
    nullable: false,
    default: 0,
    comment: '状态：0-离线，1-在线，2-忙碌，3-隐身'
  })
  status: number;

  /**
   * 最后登录时间
   * 
   * 数据库设计：
   * - 类型：DATETIME，精确到秒
   * - 约束：允许空，新用户可能为空
   * - 时区：使用系统时区，建议UTC
   * 
   * 业务规则：
   * - 记录用户最后一次登录的时间
   * - 用于用户活跃度分析
   * - 支持长时间未登录用户的清理
   * - 影响位置数据的有效性判断
   * 
   * 位置广播系统：
   * - 用于判断位置数据的时效性
   * - 长时间未登录的用户位置数据可能过期
   * - 支持基于登录时间的数据清理策略
   */
  @Column({
    type: 'datetime',
    nullable: true,
    comment: '最后登录时间'
  })
  last_login_at?: Date;

  /**
   * 最后位置更新时间
   * 
   * 数据库设计：
   * - 类型：DATETIME，精确到秒
   * - 约束：允许空，默认值null
   * - 时区：使用系统时区，建议UTC
   * 
   * 业务规则：
   * - 记录用户位置最后更新的时间
   * - 用于位置数据的缓存失效判断
   * - 支持位置更新频率的统计分析
   * - 用于清理过期的位置缓存数据
   * 
   * 位置广播系统：
   * - 核心字段，用于缓存同步策略
   * - 判断Redis中位置数据是否需要更新
   * - 支持增量同步和数据一致性保证
   * - 用于性能监控和优化
   * 
   * 注意：此字段需要通过ALTER TABLE添加到现有表中
   */
  @Column({
    type: 'datetime',
    nullable: true,
    default: null,
    comment: '最后位置更新时间，用于位置广播系统'
  })
  last_position_update?: Date;
}