forked from datawhale/whale-town-end
refactor：完善用户数据模型
- 优化用户实体字段设计和约束 - 完善用户服务的CRUD操作 - 添加详细的字段注释和业务说明 - 优化数据验证和错误处理
This commit is contained in:
moyin
@@ -1,4 +1,20 @@
|
||||
// src/user/dto/create-user.dto.ts
|
||||
/**
|
||||
* 用户数据传输对象模块
|
||||
*
|
||||
* 功能描述：
|
||||
* - 定义用户创建和更新的数据传输对象
|
||||
* - 提供完整的数据验证规则和错误提示
|
||||
* - 支持多种登录方式的数据格式验证
|
||||
*
|
||||
* 依赖模块：
|
||||
* - class-validator: 数据验证装饰器
|
||||
* - class-transformer: 数据转换工具
|
||||
*
|
||||
* @author moyin
|
||||
* @version 1.0.0
|
||||
* @since 2025-12-17
|
||||
*/
|
||||
|
||||
import {
|
||||
IsString,
|
||||
IsEmail,
|
||||
@@ -9,51 +25,194 @@ import {
|
||||
IsOptional,
|
||||
Length,
|
||||
IsNotEmpty
|
||||
} from 'class-validator'
|
||||
} from 'class-validator';
|
||||
|
||||
/**
|
||||
* 创建用户数据传输对象
|
||||
*
|
||||
* 职责：
|
||||
* - 定义用户创建时的数据结构和验证规则
|
||||
* - 确保输入数据的格式正确性和业务规则符合性
|
||||
* - 提供友好的错误提示信息
|
||||
*
|
||||
* 主要字段：
|
||||
* - username: 唯一用户名，用于登录识别
|
||||
* - email: 邮箱地址，用于通知和账户找回
|
||||
* - phone: 手机号码，支持全球格式
|
||||
* - password_hash: 密码哈希值，OAuth登录时可为空
|
||||
* - nickname: 显示昵称，在游戏中展示
|
||||
* - github_id: GitHub第三方登录标识
|
||||
* - avatar_url: 用户头像链接
|
||||
* - role: 用户角色，控制权限级别
|
||||
*
|
||||
* 使用场景：
|
||||
* - 用户注册接口的请求体验证
|
||||
* - 管理员创建用户的数据验证
|
||||
* - 第三方登录用户信息同步
|
||||
*
|
||||
* 验证规则：
|
||||
* - 必填字段：username, nickname
|
||||
* - 唯一性字段：username, email, phone, github_id
|
||||
* - 长度限制：username(1-50), nickname(1-50), github_id(1-100)
|
||||
* - 格式验证：email格式, phone国际格式
|
||||
* - 数值范围：role(1-9)
|
||||
*/
|
||||
export class CreateUserDto {
|
||||
// 用户名：必填、字符串、长度1-50
|
||||
/**
|
||||
* 用户名
|
||||
*
|
||||
* 业务规则：
|
||||
* - 必填字段，用于用户登录和唯一标识
|
||||
* - 长度限制：1-50个字符
|
||||
* - 全局唯一性：不允许重复
|
||||
* - 建议使用字母、数字、下划线组合
|
||||
*
|
||||
* 验证规则：
|
||||
* - 非空验证：确保用户名不为空
|
||||
* - 字符串类型验证
|
||||
* - 长度范围验证：1-50字符
|
||||
*/
|
||||
@IsString()
|
||||
@IsNotEmpty({ message: '用户名不能为空' })
|
||||
@Length(1, 50, { message: '用户名长度需在1-50字符之间' })
|
||||
username: string;
|
||||
|
||||
// 邮箱：可选、合法邮箱格式
|
||||
/**
|
||||
* 邮箱地址
|
||||
*
|
||||
* 业务规则：
|
||||
* - 可选字段，用于账户找回和通知
|
||||
* - 全局唯一性：不允许重复
|
||||
* - 支持标准邮箱格式验证
|
||||
* - OAuth登录时可能为空
|
||||
*
|
||||
* 验证规则：
|
||||
* - 可选字段验证
|
||||
* - 邮箱格式验证：符合RFC标准
|
||||
* - 长度限制：最大100字符（数据库约束）
|
||||
*/
|
||||
@IsOptional()
|
||||
@IsEmail({}, { message: '邮箱格式不正确' })
|
||||
email?: string;
|
||||
|
||||
// 手机号：可选、合法手机号格式（支持全球号码）
|
||||
/**
|
||||
* 手机号码
|
||||
*
|
||||
* 业务规则：
|
||||
* - 可选字段，用于账户找回和通知
|
||||
* - 全局唯一性：不允许重复
|
||||
* - 支持国际手机号格式
|
||||
* - 用于短信验证和双因子认证
|
||||
*
|
||||
* 验证规则：
|
||||
* - 可选字段验证
|
||||
* - 国际手机号格式验证
|
||||
* - 长度限制：最大30字符（数据库约束）
|
||||
*/
|
||||
@IsOptional()
|
||||
@IsPhoneNumber(null, { message: '手机号格式不正确' })
|
||||
phone?: string;
|
||||
|
||||
// 密码哈希：可选（OAuth登录为空）
|
||||
/**
|
||||
* 密码哈希值
|
||||
*
|
||||
* 业务规则：
|
||||
* - 可选字段，OAuth登录时为空
|
||||
* - 存储加密后的密码，不存储明文
|
||||
* - 用于传统用户名密码登录方式
|
||||
* - 应使用bcrypt等安全哈希算法
|
||||
*
|
||||
* 验证规则：
|
||||
* - 可选字段验证
|
||||
* - 字符串类型验证
|
||||
* - 长度限制：最大255字符（数据库约束）
|
||||
*
|
||||
* 安全注意：
|
||||
* - 传输过程中应使用HTTPS
|
||||
* - 日志记录时会自动脱敏处理
|
||||
*/
|
||||
@IsOptional()
|
||||
@IsString({ message: '密码哈希必须是字符串' })
|
||||
password_hash?: string;
|
||||
|
||||
// 昵称：必填、字符串、长度1-50
|
||||
/**
|
||||
* 用户昵称
|
||||
*
|
||||
* 业务规则：
|
||||
* - 必填字段，用于游戏内显示
|
||||
* - 长度限制：1-50个字符
|
||||
* - 支持中文、英文、数字等字符
|
||||
* - 可以与用户名不同，更友好的显示名称
|
||||
*
|
||||
* 验证规则：
|
||||
* - 非空验证：确保昵称不为空
|
||||
* - 字符串类型验证
|
||||
* - 长度范围验证：1-50字符
|
||||
*/
|
||||
@IsString()
|
||||
@IsNotEmpty({ message: '昵称不能为空' })
|
||||
@Length(1, 50, { message: '昵称长度需在1-50字符之间' })
|
||||
nickname: string;
|
||||
|
||||
// GitHub ID：可选、字符串、长度1-100
|
||||
/**
|
||||
* GitHub用户标识
|
||||
*
|
||||
* 业务规则：
|
||||
* - 可选字段，用于GitHub OAuth登录
|
||||
* - 全局唯一性：不允许重复
|
||||
* - 存储GitHub用户的唯一标识符
|
||||
* - 用于关联GitHub账户信息
|
||||
*
|
||||
* 验证规则：
|
||||
* - 可选字段验证
|
||||
* - 字符串类型验证
|
||||
* - 长度范围验证：1-100字符
|
||||
*/
|
||||
@IsOptional()
|
||||
@IsString({ message: 'GitHub ID必须是字符串' })
|
||||
@Length(1, 100, { message: 'GitHub ID长度需在1-100字符之间' })
|
||||
github_id?: string;
|
||||
|
||||
// 头像URL：可选、字符串
|
||||
/**
|
||||
* 用户头像链接
|
||||
*
|
||||
* 业务规则：
|
||||
* - 可选字段，用于显示用户头像
|
||||
* - 支持GitHub头像或自定义头像
|
||||
* - 应为有效的HTTP/HTTPS链接
|
||||
* - 建议使用CDN加速访问
|
||||
*
|
||||
* 验证规则：
|
||||
* - 可选字段验证
|
||||
* - 字符串类型验证
|
||||
* - 长度限制：最大255字符（数据库约束）
|
||||
*/
|
||||
@IsOptional()
|
||||
@IsString({ message: '头像URL必须是字符串' })
|
||||
avatar_url?: string;
|
||||
|
||||
// 角色：可选、数字、1（普通）或9（管理员）
|
||||
/**
|
||||
* 用户角色
|
||||
*
|
||||
* 业务规则：
|
||||
* - 可选字段，默认为普通用户(1)
|
||||
* - 角色级别：1-普通用户，9-管理员
|
||||
* - 控制用户在系统中的权限范围
|
||||
* - 管理员具有系统管理权限
|
||||
*
|
||||
* 验证规则：
|
||||
* - 可选字段验证
|
||||
* - 整数类型验证
|
||||
* - 数值范围验证：1-9之间
|
||||
* - 默认值：1（普通用户）
|
||||
*
|
||||
* 权限说明：
|
||||
* - 1: 普通用户 - 基础游戏功能
|
||||
* - 9: 管理员 - 系统管理权限
|
||||
*/
|
||||
@IsOptional()
|
||||
@IsInt({ message: '角色必须是数字' })
|
||||
@Min(1, { message: '角色值最小为1' })
|
||||
@Max(9, { message: '角色值最大为9' })
|
||||
role?: number = 1; // 默认普通用户
|
||||
role?: number = 1;
|
||||
}
|
||||
@@ -1,15 +1,103 @@
|
||||
/**
|
||||
* 用户数据实体模块
|
||||
*
|
||||
* 功能描述：
|
||||
* - 定义用户数据表的实体映射和字段约束
|
||||
* - 提供用户数据的持久化存储结构
|
||||
* - 支持多种登录方式的用户信息存储
|
||||
*
|
||||
* 依赖模块：
|
||||
* - TypeORM: ORM框架，提供数据库映射功能
|
||||
* - MySQL: 底层数据库存储
|
||||
*
|
||||
* 数据库表：users
|
||||
* 存储引擎：InnoDB
|
||||
* 字符集：utf8mb4
|
||||
*
|
||||
* @author moyin
|
||||
* @version 1.0.0
|
||||
* @since 2025-12-17
|
||||
*/
|
||||
|
||||
import { Entity, Column, PrimaryGeneratedColumn, CreateDateColumn, UpdateDateColumn } from 'typeorm';
|
||||
|
||||
@Entity('users') // 对应数据库表名
|
||||
/**
|
||||
* 用户实体类
|
||||
*
|
||||
* 职责：
|
||||
* - 映射数据库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、主键、非空、唯一、自增
|
||||
/**
|
||||
* 用户主键ID
|
||||
*
|
||||
* 数据库设计：
|
||||
* - 类型：BIGINT，支持大量用户数据
|
||||
* - 约束：主键、非空、自增
|
||||
* - 范围：1 ~ 9,223,372,036,854,775,807
|
||||
*
|
||||
* 业务规则：
|
||||
* - 系统自动生成，不可手动指定
|
||||
* - 全局唯一标识符，用于用户关联
|
||||
* - 作为其他表的外键引用
|
||||
*
|
||||
* 性能考虑：
|
||||
* - 自增主键，插入性能优异
|
||||
* - 聚簇索引，范围查询效率高
|
||||
* - BIGINT类型，避免ID耗尽问题
|
||||
*/
|
||||
@PrimaryGeneratedColumn({
|
||||
type: 'bigint',
|
||||
comment: '主键ID'
|
||||
})
|
||||
id: bigint;
|
||||
|
||||
// username：varchar(50)、非空、唯一
|
||||
/**
|
||||
* 用户名
|
||||
*
|
||||
* 数据库设计：
|
||||
* - 类型：VARCHAR(50)，支持多语言字符
|
||||
* - 约束：非空、唯一索引
|
||||
* - 字符集：utf8mb4，支持emoji等特殊字符
|
||||
*
|
||||
* 业务规则：
|
||||
* - 用户登录的唯一标识符
|
||||
* - 全系统唯一，不允许重复
|
||||
* - 长度限制：1-50个字符
|
||||
* - 建议格式：字母、数字、下划线组合
|
||||
*
|
||||
* 安全考虑：
|
||||
* - 不应包含敏感信息
|
||||
* - 避免使用易猜测的用户名
|
||||
* - 支持用户名修改（需要额外验证）
|
||||
*/
|
||||
@Column({
|
||||
type: 'varchar',
|
||||
length: 50,
|
||||
@@ -19,7 +107,25 @@ export class Users {
|
||||
})
|
||||
username: string;
|
||||
|
||||
// email：varchar(100)、允许空、唯一
|
||||
/**
|
||||
* 邮箱地址
|
||||
*
|
||||
* 数据库设计：
|
||||
* - 类型：VARCHAR(100)，支持长邮箱地址
|
||||
* - 约束：允许空、唯一索引
|
||||
* - 索引：用于快速邮箱查找
|
||||
*
|
||||
* 业务规则：
|
||||
* - 用于账户找回和重要通知
|
||||
* - 全系统唯一，不允许重复
|
||||
* - OAuth登录时可能为空
|
||||
* - 支持邮箱验证和双因子认证
|
||||
*
|
||||
* 隐私保护：
|
||||
* - 敏感信息，日志记录时脱敏
|
||||
* - 仅用于系统通知，不对外展示
|
||||
* - 支持用户自主修改和验证
|
||||
*/
|
||||
@Column({
|
||||
type: 'varchar',
|
||||
length: 100,
|
||||
@@ -29,7 +135,25 @@ export class Users {
|
||||
})
|
||||
email: string;
|
||||
|
||||
// phone：varchar(30)、允许空、唯一
|
||||
/**
|
||||
* 手机号码
|
||||
*
|
||||
* 数据库设计：
|
||||
* - 类型：VARCHAR(30)，支持国际号码格式
|
||||
* - 约束：允许空、唯一索引
|
||||
* - 格式：包含国家代码的完整号码
|
||||
*
|
||||
* 业务规则：
|
||||
* - 用于账户找回和短信通知
|
||||
* - 全系统唯一，不允许重复
|
||||
* - 支持国际手机号格式（+86、+1等）
|
||||
* - 用于短信验证码和双因子认证
|
||||
*
|
||||
* 隐私保护：
|
||||
* - 敏感信息，日志记录时脱敏
|
||||
* - 仅用于安全验证，不对外展示
|
||||
* - 支持用户自主修改和验证
|
||||
*/
|
||||
@Column({
|
||||
type: 'varchar',
|
||||
length: 30,
|
||||
@@ -39,7 +163,27 @@ export class Users {
|
||||
})
|
||||
phone: string;
|
||||
|
||||
// password_hash：varchar(255)、允许空
|
||||
/**
|
||||
* 密码哈希值
|
||||
*
|
||||
* 数据库设计：
|
||||
* - 类型：VARCHAR(255)，支持各种哈希算法
|
||||
* - 约束：允许空（OAuth登录时）
|
||||
* - 存储：加密后的哈希值，不存储明文
|
||||
*
|
||||
* 业务规则：
|
||||
* - 传统用户名密码登录方式使用
|
||||
* - OAuth第三方登录时此字段为空
|
||||
* - 使用bcrypt等安全哈希算法
|
||||
* - 支持密码强度验证和定期更新
|
||||
*
|
||||
* 安全措施：
|
||||
* - 绝不存储明文密码
|
||||
* - 使用盐值防止彩虹表攻击
|
||||
* - 日志系统自动脱敏处理
|
||||
* - 传输过程使用HTTPS加密
|
||||
* - 支持密码重置和修改功能
|
||||
*/
|
||||
@Column({
|
||||
type: 'varchar',
|
||||
length: 255,
|
||||
@@ -48,7 +192,26 @@ export class Users {
|
||||
})
|
||||
password_hash: string;
|
||||
|
||||
// nickname：varchar(50)、非空
|
||||
/**
|
||||
* 用户昵称
|
||||
*
|
||||
* 数据库设计：
|
||||
* - 类型：VARCHAR(50)，支持多语言字符
|
||||
* - 约束：非空，无唯一性要求
|
||||
* - 字符集：utf8mb4，支持emoji表情
|
||||
*
|
||||
* 业务规则：
|
||||
* - 游戏内显示的友好名称
|
||||
* - 允许重复，提高用户体验
|
||||
* - 长度限制：1-50个字符
|
||||
* - 支持中文、英文、数字、表情符号
|
||||
*
|
||||
* 显示规则：
|
||||
* - 游戏内头顶显示名称
|
||||
* - 聊天消息发送者标识
|
||||
* - 排行榜和用户列表显示
|
||||
* - 支持用户随时修改
|
||||
*/
|
||||
@Column({
|
||||
type: 'varchar',
|
||||
length: 50,
|
||||
@@ -57,7 +220,26 @@ export class Users {
|
||||
})
|
||||
nickname: string;
|
||||
|
||||
// github_id：varchar(100)、允许空、唯一
|
||||
/**
|
||||
* GitHub用户标识
|
||||
*
|
||||
* 数据库设计：
|
||||
* - 类型：VARCHAR(100)，存储GitHub用户ID
|
||||
* - 约束：允许空、唯一索引
|
||||
* - 用途：GitHub OAuth登录关联
|
||||
*
|
||||
* 业务规则：
|
||||
* - GitHub第三方登录的唯一标识
|
||||
* - 全系统唯一，不允许重复
|
||||
* - 用于关联GitHub账户信息
|
||||
* - 支持GitHub头像和基础信息同步
|
||||
*
|
||||
* OAuth集成：
|
||||
* - 存储GitHub返回的用户ID
|
||||
* - 用于后续API调用身份验证
|
||||
* - 支持账户绑定和解绑操作
|
||||
* - 可扩展支持其他OAuth提供商
|
||||
*/
|
||||
@Column({
|
||||
type: 'varchar',
|
||||
length: 100,
|
||||
@@ -67,7 +249,26 @@ export class Users {
|
||||
})
|
||||
github_id: string;
|
||||
|
||||
// avatar_url：varchar(255)、允许空
|
||||
/**
|
||||
* 用户头像链接
|
||||
*
|
||||
* 数据库设计：
|
||||
* - 类型：VARCHAR(255)，支持长URL
|
||||
* - 约束：允许空，无唯一性要求
|
||||
* - 存储：完整的HTTP/HTTPS链接
|
||||
*
|
||||
* 业务规则：
|
||||
* - 用户头像图片的访问链接
|
||||
* - 支持GitHub头像或自定义上传
|
||||
* - 建议使用CDN加速访问
|
||||
* - 支持多种图片格式（jpg、png、gif等）
|
||||
*
|
||||
* 性能优化：
|
||||
* - 建议使用图片CDN服务
|
||||
* - 支持多尺寸头像适配
|
||||
* - 缓存策略优化加载速度
|
||||
* - 默认头像兜底机制
|
||||
*/
|
||||
@Column({
|
||||
type: 'varchar',
|
||||
length: 255,
|
||||
@@ -76,7 +277,31 @@ export class Users {
|
||||
})
|
||||
avatar_url: string;
|
||||
|
||||
// role：tinyint、非空、默认1
|
||||
/**
|
||||
* 用户角色
|
||||
*
|
||||
* 数据库设计：
|
||||
* - 类型：TINYINT，节省存储空间
|
||||
* - 约束：非空、默认值1
|
||||
* - 范围：1-9，支持角色扩展
|
||||
*
|
||||
* 业务规则：
|
||||
* - 控制用户在系统中的权限级别
|
||||
* - 1：普通用户，基础游戏功能
|
||||
* - 9：管理员，系统管理权限
|
||||
* - 支持角色升级和降级操作
|
||||
*
|
||||
* 权限设计：
|
||||
* - 基于角色的访问控制（RBAC）
|
||||
* - 支持细粒度权限配置
|
||||
* - 可扩展更多角色类型
|
||||
* - 权限验证中间件集成
|
||||
*
|
||||
* 扩展性：
|
||||
* - 预留2-8角色级别供未来使用
|
||||
* - 支持角色权限动态配置
|
||||
* - 可关联角色权限表进行扩展
|
||||
*/
|
||||
@Column({
|
||||
type: 'tinyint',
|
||||
nullable: false,
|
||||
@@ -85,7 +310,26 @@ export class Users {
|
||||
})
|
||||
role: number;
|
||||
|
||||
// created_at：datetime、非空、默认当前时间
|
||||
/**
|
||||
* 创建时间
|
||||
*
|
||||
* 数据库设计：
|
||||
* - 类型：DATETIME，精确到秒
|
||||
* - 约束：非空、默认当前时间
|
||||
* - 时区：使用系统时区，建议UTC
|
||||
*
|
||||
* 业务规则：
|
||||
* - 记录用户注册的准确时间
|
||||
* - 用于用户数据统计和分析
|
||||
* - 支持按时间范围查询用户
|
||||
* - 不可修改，保证数据完整性
|
||||
*
|
||||
* 应用场景：
|
||||
* - 用户注册趋势分析
|
||||
* - 新用户欢迎流程触发
|
||||
* - 数据审计和合规要求
|
||||
* - 用户生命周期管理
|
||||
*/
|
||||
@CreateDateColumn({
|
||||
type: 'datetime',
|
||||
nullable: false,
|
||||
@@ -94,12 +338,31 @@ export class Users {
|
||||
})
|
||||
created_at: Date;
|
||||
|
||||
// updated_at：datetime、非空、默认当前时间
|
||||
/**
|
||||
* 更新时间
|
||||
*
|
||||
* 数据库设计：
|
||||
* - 类型：DATETIME，精确到秒
|
||||
* - 约束：非空、自动更新
|
||||
* - 触发：任何字段更新时自动刷新
|
||||
*
|
||||
* 业务规则：
|
||||
* - 记录用户信息最后修改时间
|
||||
* - 数据库级别自动维护
|
||||
* - 用于数据同步和缓存失效
|
||||
* - 支持增量数据同步
|
||||
*
|
||||
* 应用场景：
|
||||
* - 数据变更审计
|
||||
* - 缓存更新策略
|
||||
* - 数据同步时间戳
|
||||
* - 用户活跃度分析
|
||||
*/
|
||||
@UpdateDateColumn({
|
||||
type: 'datetime',
|
||||
nullable: false,
|
||||
default: () => 'CURRENT_TIMESTAMP',
|
||||
onUpdate: 'CURRENT_TIMESTAMP', // 数据库更新时自动刷新时间
|
||||
onUpdate: 'CURRENT_TIMESTAMP',
|
||||
comment: '更新时间'
|
||||
})
|
||||
updated_at: Date;
|
||||
|
||||
@@ -8,7 +8,7 @@
|
||||
*
|
||||
* @author moyin
|
||||
* @version 1.0.0
|
||||
* @since 2024-12-17
|
||||
* @since 2025-12-17
|
||||
*/
|
||||
|
||||
import { Injectable, ConflictException, NotFoundException, BadRequestException } from '@nestjs/common';
|
||||
|
||||
Reference in New Issue
Block a user