ANGJustinl/whale-town-end-v2
1
0
Fork 0
forked from xiangwang25/whale-town-end-v2
Code Pull Requests Activity

Initial WhaleTown V2 backend

Browse Source
This commit is contained in:
xiangwang
2026-07-20 02:00:52 +08:00
commit c995891c1f
265 changed files with 75689 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

497
src/core/db/users/users.entity.ts Normal file
View File

@@ -0,0 +1,497 @@
/**
* 用户数据实体模块
*
* 功能描述：
* - 定义用户数据表的实体映射和字段约束
* - 提供用户数据的持久化存储结构
* - 支持多种登录方式的用户信息存储
* - 实现完整的用户数据模型和关系映射
*
* 职责分离：
* - 数据映射：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;
}