forked from datawhale/whale-town-end
496 lines
13 KiB
TypeScript
496 lines
13 KiB
TypeScript
/**
|
||
* 用户数据实体模块
|
||
*
|
||
* 功能描述：
|
||
* - 定义用户数据表的实体映射和字段约束
|
||
* - 提供用户数据的持久化存储结构
|
||
* - 支持多种登录方式的用户信息存储
|
||
* - 实现完整的用户数据模型和关系映射
|
||
*
|
||
* 职责分离：
|
||
* - 数据映射：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';
|
||
|
||
/**
|
||
* 用户实体类
|
||
*
|
||
* 职责：
|
||
* - 映射数据库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;
|
||
|
||
/**
|
||
* 邮箱验证状态
|
||
*
|
||
* 数据库设计：
|
||
* - 类型：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: 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;
|
||
|
||
/**
|
||
* 用户状态
|
||
*
|
||
* 数据库设计：
|
||
* - 类型：VARCHAR(20)，存储状态枚举值
|
||
* - 约束：非空、默认值'active'
|
||
* - 索引：用于状态查询和统计
|
||
*
|
||
* 业务规则：
|
||
* - 控制用户账户的可用性和权限
|
||
* - active：正常状态，可以正常使用
|
||
* - inactive：未激活，需要邮箱验证
|
||
* - locked：已锁定，临时禁用
|
||
* - banned：已禁用，管理员操作
|
||
* - deleted：已删除，软删除状态
|
||
* - pending：待审核，需要管理员审核
|
||
*
|
||
* 安全控制：
|
||
* - 登录时检查状态权限
|
||
* - API访问时验证状态
|
||
* - 状态变更记录审计日志
|
||
* - 支持批量状态管理
|
||
*
|
||
* 应用场景：
|
||
* - 账户安全管理
|
||
* - 用户生命周期控制
|
||
* - 违规用户处理
|
||
* - 系统维护和升级
|
||
*/
|
||
@Column({
|
||
type: 'varchar',
|
||
length: 20,
|
||
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;
|
||
} |