570 lines
16 KiB
TypeScript
570 lines
16 KiB
TypeScript
/**
|
||
* 管理员数据库管理 DTO
|
||
*
|
||
* 功能描述：
|
||
* - 定义管理员数据库管理相关的请求和响应数据结构
|
||
* - 提供完整的数据验证规则
|
||
* - 支持Swagger文档自动生成
|
||
*
|
||
* 职责分离：
|
||
* - 请求数据结构定义和验证
|
||
* - 响应数据结构定义
|
||
* - API文档生成支持
|
||
* - 类型安全保障
|
||
*
|
||
* DTO分类：
|
||
* - Query DTOs: 查询参数验证
|
||
* - Create DTOs: 创建操作数据验证
|
||
* - Update DTOs: 更新操作数据验证
|
||
* - Response DTOs: 响应数据结构定义
|
||
*
|
||
* 最近修改：
|
||
* - 2026-01-08: 注释规范优化 - 修正@author字段，更新版本号和修改记录 (修改者: moyin)
|
||
* - 2026-01-08: 注释规范优化 - 为所有DTO类添加类注释，完善文档说明 (修改者: moyin)
|
||
* - 2026-01-08: 文件夹扁平化 - 从dto/子文件夹移动到上级目录 (修改者: moyin)
|
||
* - 2026-01-08: 功能新增 - 创建管理员数据库管理DTO (修改者: assistant)
|
||
*
|
||
* @author moyin
|
||
* @version 1.0.3
|
||
* @since 2026-01-08
|
||
* @lastModified 2026-01-08
|
||
*/
|
||
|
||
import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
|
||
import { IsOptional, IsString, IsInt, Min, Max, IsEnum, IsEmail, IsArray, IsBoolean, IsNumber } from 'class-validator';
|
||
import { Transform } from 'class-transformer';
|
||
import { UserStatus } from '../../core/db/users/user_status.enum';
|
||
|
||
// ==================== 通用查询 DTOs ====================
|
||
|
||
/**
|
||
* 管理员分页查询DTO
|
||
*
|
||
* 功能描述：
|
||
* 定义分页查询的通用参数结构
|
||
*
|
||
* 使用场景：
|
||
* - 作为其他查询DTO的基类
|
||
* - 提供统一的分页参数验证
|
||
*/
|
||
export class AdminPaginationDto {
|
||
@ApiPropertyOptional({ description: '返回数量（默认20，最大100）', example: 20, minimum: 1, maximum: 100 })
|
||
@IsOptional()
|
||
@IsInt()
|
||
@Min(1)
|
||
@Max(100)
|
||
@Transform(({ value }) => parseInt(value))
|
||
limit?: number = 20;
|
||
|
||
@ApiPropertyOptional({ description: '偏移量（默认0）', example: 0, minimum: 0 })
|
||
@IsOptional()
|
||
@IsInt()
|
||
@Min(0)
|
||
@Transform(({ value }) => parseInt(value))
|
||
offset?: number = 0;
|
||
}
|
||
|
||
// ==================== 用户管理 DTOs ====================
|
||
|
||
/**
|
||
* 管理员查询用户DTO
|
||
*
|
||
* 功能描述：
|
||
* 定义用户查询接口的请求参数结构
|
||
*
|
||
* 使用场景：
|
||
* - GET /admin/database/users 接口的查询参数
|
||
* - 支持关键词搜索和分页查询
|
||
*/
|
||
export class AdminQueryUsersDto extends AdminPaginationDto {
|
||
@ApiPropertyOptional({ description: '搜索关键词（用户名、邮箱、昵称）', example: 'admin' })
|
||
@IsOptional()
|
||
@IsString()
|
||
search?: string;
|
||
|
||
@ApiPropertyOptional({ description: '用户状态过滤', enum: UserStatus, example: UserStatus.ACTIVE })
|
||
@IsOptional()
|
||
@IsEnum(UserStatus)
|
||
status?: UserStatus;
|
||
|
||
@ApiPropertyOptional({ description: '角色过滤', example: 1 })
|
||
@IsOptional()
|
||
@IsInt()
|
||
@Min(0)
|
||
@Max(9)
|
||
role?: number;
|
||
}
|
||
|
||
/**
|
||
* 管理员创建用户DTO
|
||
*
|
||
* 功能描述：
|
||
* 定义创建用户接口的请求数据结构和验证规则
|
||
*
|
||
* 使用场景：
|
||
* - POST /admin/database/users 接口的请求体
|
||
* - 包含用户创建所需的所有必要信息
|
||
*/
|
||
export class AdminCreateUserDto {
|
||
@ApiProperty({ description: '用户名', example: 'newuser' })
|
||
@IsString()
|
||
username: string;
|
||
|
||
@ApiPropertyOptional({ description: '邮箱', example: 'user@example.com' })
|
||
@IsOptional()
|
||
@IsEmail()
|
||
email?: string;
|
||
|
||
@ApiPropertyOptional({ description: '手机号', example: '13800138000' })
|
||
@IsOptional()
|
||
@IsString()
|
||
phone?: string;
|
||
|
||
@ApiProperty({ description: '昵称', example: '新用户' })
|
||
@IsString()
|
||
nickname: string;
|
||
|
||
@ApiPropertyOptional({ description: '密码哈希', example: 'hashed_password' })
|
||
@IsOptional()
|
||
@IsString()
|
||
password_hash?: string;
|
||
|
||
@ApiPropertyOptional({ description: 'GitHub ID', example: 'github123' })
|
||
@IsOptional()
|
||
@IsString()
|
||
github_id?: string;
|
||
|
||
@ApiPropertyOptional({ description: '头像URL', example: 'https://example.com/avatar.jpg' })
|
||
@IsOptional()
|
||
@IsString()
|
||
avatar_url?: string;
|
||
|
||
@ApiPropertyOptional({ description: '角色', example: 1, minimum: 0, maximum: 9 })
|
||
@IsOptional()
|
||
@IsInt()
|
||
@Min(0)
|
||
@Max(9)
|
||
role?: number;
|
||
|
||
@ApiPropertyOptional({ description: '邮箱是否已验证', example: false })
|
||
@IsOptional()
|
||
@IsBoolean()
|
||
email_verified?: boolean;
|
||
|
||
@ApiPropertyOptional({ description: '用户状态', enum: UserStatus, example: UserStatus.ACTIVE })
|
||
@IsOptional()
|
||
@IsEnum(UserStatus)
|
||
status?: UserStatus;
|
||
}
|
||
|
||
/**
|
||
* 管理员更新用户DTO
|
||
*
|
||
* 功能描述：
|
||
* 定义更新用户接口的请求数据结构和验证规则
|
||
*
|
||
* 使用场景：
|
||
* - PUT /admin/database/users/:id 接口的请求体
|
||
* - 支持部分字段更新，所有字段都是可选的
|
||
*/
|
||
export class AdminUpdateUserDto {
|
||
@ApiPropertyOptional({ description: '用户名', example: 'updateduser' })
|
||
@IsOptional()
|
||
@IsString()
|
||
username?: string;
|
||
|
||
@ApiPropertyOptional({ description: '邮箱', example: 'updated@example.com' })
|
||
@IsOptional()
|
||
@IsEmail()
|
||
email?: string;
|
||
|
||
@ApiPropertyOptional({ description: '手机号', example: '13900139000' })
|
||
@IsOptional()
|
||
@IsString()
|
||
phone?: string;
|
||
|
||
@ApiPropertyOptional({ description: '昵称', example: '更新用户' })
|
||
@IsOptional()
|
||
@IsString()
|
||
nickname?: string;
|
||
|
||
@ApiPropertyOptional({ description: '头像URL', example: 'https://example.com/new-avatar.jpg' })
|
||
@IsOptional()
|
||
@IsString()
|
||
avatar_url?: string;
|
||
|
||
@ApiPropertyOptional({ description: '角色', example: 2, minimum: 0, maximum: 9 })
|
||
@IsOptional()
|
||
@IsInt()
|
||
@Min(0)
|
||
@Max(9)
|
||
role?: number;
|
||
|
||
@ApiPropertyOptional({ description: '邮箱是否已验证', example: true })
|
||
@IsOptional()
|
||
@IsBoolean()
|
||
email_verified?: boolean;
|
||
|
||
@ApiPropertyOptional({ description: '用户状态', enum: UserStatus, example: UserStatus.INACTIVE })
|
||
@IsOptional()
|
||
@IsEnum(UserStatus)
|
||
status?: UserStatus;
|
||
}
|
||
|
||
// ==================== 用户档案管理 DTOs ====================
|
||
|
||
/**
|
||
* 管理员查询用户档案DTO
|
||
*
|
||
* 功能描述：
|
||
* 定义用户档案查询接口的请求参数结构
|
||
*
|
||
* 使用场景：
|
||
* - GET /admin/database/user-profiles 接口的查询参数
|
||
* - 支持地图过滤和分页查询
|
||
*/
|
||
export class AdminQueryUserProfileDto extends AdminPaginationDto {
|
||
@ApiPropertyOptional({ description: '当前地图过滤', example: 'plaza' })
|
||
@IsOptional()
|
||
@IsString()
|
||
current_map?: string;
|
||
|
||
@ApiPropertyOptional({ description: '状态过滤', example: 1 })
|
||
@IsOptional()
|
||
@IsInt()
|
||
status?: number;
|
||
|
||
@ApiPropertyOptional({ description: '用户ID过滤', example: '1' })
|
||
@IsOptional()
|
||
@IsString()
|
||
user_id?: string;
|
||
}
|
||
|
||
/**
|
||
* 管理员创建用户档案DTO
|
||
*
|
||
* 功能描述：
|
||
* 定义创建用户档案接口的请求数据结构和验证规则
|
||
*
|
||
* 使用场景：
|
||
* - POST /admin/database/user-profiles 接口的请求体
|
||
* - 包含用户档案创建所需的所有信息
|
||
*/
|
||
export class AdminCreateUserProfileDto {
|
||
@ApiProperty({ description: '用户ID', example: '1' })
|
||
@IsString()
|
||
user_id: string;
|
||
|
||
@ApiPropertyOptional({ description: '个人简介', example: '这是我的个人简介' })
|
||
@IsOptional()
|
||
@IsString()
|
||
bio?: string;
|
||
|
||
@ApiPropertyOptional({ description: '简历内容', example: '工作经历和技能' })
|
||
@IsOptional()
|
||
@IsString()
|
||
resume_content?: string;
|
||
|
||
@ApiPropertyOptional({ description: '标签', example: '["开发者", "游戏爱好者"]' })
|
||
@IsOptional()
|
||
@IsString()
|
||
tags?: string;
|
||
|
||
@ApiPropertyOptional({ description: '社交链接', example: '{"github": "https://github.com/user"}' })
|
||
@IsOptional()
|
||
@IsString()
|
||
social_links?: string;
|
||
|
||
@ApiPropertyOptional({ description: '皮肤ID', example: 'skin_001' })
|
||
@IsOptional()
|
||
@IsString()
|
||
skin_id?: string;
|
||
|
||
@ApiPropertyOptional({ description: '当前地图', example: 'plaza' })
|
||
@IsOptional()
|
||
@IsString()
|
||
current_map?: string;
|
||
|
||
@ApiPropertyOptional({ description: 'X坐标', example: 100.5 })
|
||
@IsOptional()
|
||
@IsNumber()
|
||
pos_x?: number;
|
||
|
||
@ApiPropertyOptional({ description: 'Y坐标', example: 200.3 })
|
||
@IsOptional()
|
||
@IsNumber()
|
||
pos_y?: number;
|
||
|
||
@ApiPropertyOptional({ description: '状态', example: 1 })
|
||
@IsOptional()
|
||
@IsInt()
|
||
status?: number;
|
||
}
|
||
|
||
/**
|
||
* 管理员更新用户档案DTO
|
||
*
|
||
* 功能描述：
|
||
* 定义更新用户档案接口的请求数据结构和验证规则
|
||
*
|
||
* 使用场景：
|
||
* - PUT /admin/database/user-profiles/:id 接口的请求体
|
||
* - 支持部分字段更新，所有字段都是可选的
|
||
*/
|
||
export class AdminUpdateUserProfileDto {
|
||
@ApiPropertyOptional({ description: '个人简介', example: '更新后的个人简介' })
|
||
@IsOptional()
|
||
@IsString()
|
||
bio?: string;
|
||
|
||
@ApiPropertyOptional({ description: '简历内容', example: '更新后的简历内容' })
|
||
@IsOptional()
|
||
@IsString()
|
||
resume_content?: string;
|
||
|
||
@ApiPropertyOptional({ description: '标签', example: '["高级开发者", "技术专家"]' })
|
||
@IsOptional()
|
||
@IsString()
|
||
tags?: string;
|
||
|
||
@ApiPropertyOptional({ description: '社交链接', example: '{"linkedin": "https://linkedin.com/in/user"}' })
|
||
@IsOptional()
|
||
@IsString()
|
||
social_links?: string;
|
||
|
||
@ApiPropertyOptional({ description: '皮肤ID', example: 'skin_002' })
|
||
@IsOptional()
|
||
@IsString()
|
||
skin_id?: string;
|
||
|
||
@ApiPropertyOptional({ description: '当前地图', example: 'forest' })
|
||
@IsOptional()
|
||
@IsString()
|
||
current_map?: string;
|
||
|
||
@ApiPropertyOptional({ description: 'X坐标', example: 150.7 })
|
||
@IsOptional()
|
||
@IsNumber()
|
||
pos_x?: number;
|
||
|
||
@ApiPropertyOptional({ description: 'Y坐标', example: 250.9 })
|
||
@IsOptional()
|
||
@IsNumber()
|
||
pos_y?: number;
|
||
|
||
@ApiPropertyOptional({ description: '状态', example: 0 })
|
||
@IsOptional()
|
||
@IsInt()
|
||
status?: number;
|
||
}
|
||
|
||
// ==================== Zulip账号关联管理 DTOs ====================
|
||
|
||
/**
|
||
* 管理员查询Zulip账号DTO
|
||
*
|
||
* 功能描述：
|
||
* 定义Zulip账号关联查询接口的请求参数结构
|
||
*
|
||
* 使用场景：
|
||
* - GET /admin/database/zulip-accounts 接口的查询参数
|
||
* - 支持用户ID过滤和分页查询
|
||
*/
|
||
export class AdminQueryZulipAccountDto extends AdminPaginationDto {
|
||
@ApiPropertyOptional({ description: '游戏用户ID过滤', example: '1' })
|
||
@IsOptional()
|
||
@IsString()
|
||
gameUserId?: string;
|
||
|
||
@ApiPropertyOptional({ description: 'Zulip用户ID过滤', example: 12345 })
|
||
@IsOptional()
|
||
@IsInt()
|
||
zulipUserId?: number;
|
||
|
||
@ApiPropertyOptional({ description: 'Zulip邮箱过滤', example: 'user@zulip.com' })
|
||
@IsOptional()
|
||
@IsEmail()
|
||
zulipEmail?: string;
|
||
|
||
@ApiPropertyOptional({ description: '状态过滤', example: 'active', enum: ['active', 'inactive', 'suspended', 'error'] })
|
||
@IsOptional()
|
||
@IsEnum(['active', 'inactive', 'suspended', 'error'])
|
||
status?: 'active' | 'inactive' | 'suspended' | 'error';
|
||
}
|
||
|
||
/**
|
||
* 管理员创建Zulip账号DTO
|
||
*
|
||
* 功能描述：
|
||
* 定义创建Zulip账号关联接口的请求数据结构和验证规则
|
||
*
|
||
* 使用场景：
|
||
* - POST /admin/database/zulip-accounts 接口的请求体
|
||
* - 包含Zulip账号关联创建所需的所有信息
|
||
*/
|
||
export class AdminCreateZulipAccountDto {
|
||
@ApiProperty({ description: '游戏用户ID', example: '1' })
|
||
@IsString()
|
||
gameUserId: string;
|
||
|
||
@ApiProperty({ description: 'Zulip用户ID', example: 12345 })
|
||
@IsInt()
|
||
zulipUserId: number;
|
||
|
||
@ApiProperty({ description: 'Zulip邮箱', example: 'user@zulip.com' })
|
||
@IsEmail()
|
||
zulipEmail: string;
|
||
|
||
@ApiProperty({ description: 'Zulip全名', example: '张三' })
|
||
@IsString()
|
||
zulipFullName: string;
|
||
|
||
@ApiProperty({ description: 'Zulip API密钥（加密）', example: 'encrypted_api_key' })
|
||
@IsString()
|
||
zulipApiKeyEncrypted: string;
|
||
|
||
@ApiPropertyOptional({ description: '状态', example: 'active', enum: ['active', 'inactive', 'suspended', 'error'] })
|
||
@IsOptional()
|
||
@IsEnum(['active', 'inactive', 'suspended', 'error'])
|
||
status?: 'active' | 'inactive' | 'suspended' | 'error';
|
||
}
|
||
|
||
/**
|
||
* 管理员更新Zulip账号DTO
|
||
*
|
||
* 功能描述：
|
||
* 定义更新Zulip账号关联接口的请求数据结构和验证规则
|
||
*
|
||
* 使用场景：
|
||
* - PUT /admin/database/zulip-accounts/:id 接口的请求体
|
||
* - 支持部分字段更新，所有字段都是可选的
|
||
*/
|
||
export class AdminUpdateZulipAccountDto {
|
||
@ApiPropertyOptional({ description: 'Zulip全名', example: '李四' })
|
||
@IsOptional()
|
||
@IsString()
|
||
zulipFullName?: string;
|
||
|
||
@ApiPropertyOptional({ description: 'Zulip API密钥（加密）', example: 'new_encrypted_api_key' })
|
||
@IsOptional()
|
||
@IsString()
|
||
zulipApiKeyEncrypted?: string;
|
||
|
||
@ApiPropertyOptional({ description: '状态', example: 'suspended', enum: ['active', 'inactive', 'suspended', 'error'] })
|
||
@IsOptional()
|
||
@IsEnum(['active', 'inactive', 'suspended', 'error'])
|
||
status?: 'active' | 'inactive' | 'suspended' | 'error';
|
||
|
||
@ApiPropertyOptional({ description: '错误信息', example: '连接超时' })
|
||
@IsOptional()
|
||
@IsString()
|
||
errorMessage?: string;
|
||
|
||
@ApiPropertyOptional({ description: '重试次数', example: 3 })
|
||
@IsOptional()
|
||
@IsInt()
|
||
@Min(0)
|
||
retryCount?: number;
|
||
}
|
||
|
||
/**
|
||
* 管理员批量更新状态DTO
|
||
*
|
||
* 功能描述：
|
||
* 定义批量更新状态接口的请求数据结构和验证规则
|
||
*
|
||
* 使用场景：
|
||
* - POST /admin/database/zulip-accounts/batch-update-status 接口的请求体
|
||
* - 支持批量更新多个记录的状态
|
||
*/
|
||
export class AdminBatchUpdateStatusDto {
|
||
@ApiProperty({ description: 'ID列表', example: ['1', '2', '3'] })
|
||
@IsArray()
|
||
@IsString({ each: true })
|
||
ids: string[];
|
||
|
||
@ApiProperty({ description: '目标状态', example: 'active', enum: ['active', 'inactive', 'suspended', 'error'] })
|
||
@IsEnum(['active', 'inactive', 'suspended', 'error'])
|
||
status: 'active' | 'inactive' | 'suspended' | 'error';
|
||
|
||
@ApiPropertyOptional({ description: '操作原因', example: '批量激活账号' })
|
||
@IsOptional()
|
||
@IsString()
|
||
reason?: string;
|
||
}
|
||
|
||
// ==================== 响应 DTOs ====================
|
||
|
||
/**
|
||
* 管理员数据库响应DTO
|
||
*
|
||
* 功能描述：
|
||
* 定义管理员数据库操作的通用响应数据结构
|
||
*
|
||
* 使用场景：
|
||
* - 各种数据库管理接口的响应体基类
|
||
* - 包含操作状态、数据和消息信息
|
||
*/
|
||
export class AdminDatabaseResponseDto {
|
||
@ApiProperty({ description: '是否成功', example: true })
|
||
success: boolean;
|
||
|
||
@ApiProperty({ description: '消息', example: '操作成功' })
|
||
message: string;
|
||
|
||
@ApiPropertyOptional({ description: '数据' })
|
||
data?: any;
|
||
|
||
@ApiPropertyOptional({ description: '错误码', example: 'RESOURCE_NOT_FOUND' })
|
||
error_code?: string;
|
||
|
||
@ApiProperty({ description: '时间戳', example: '2026-01-08T10:30:00.000Z' })
|
||
timestamp: string;
|
||
|
||
@ApiProperty({ description: '请求ID', example: 'req_1641636600000_abc123' })
|
||
request_id: string;
|
||
}
|
||
|
||
/**
|
||
* 管理员数据库列表响应DTO
|
||
*
|
||
* 功能描述：
|
||
* 定义管理员数据库列表查询的响应数据结构
|
||
*
|
||
* 使用场景：
|
||
* - 各种列表查询接口的响应体
|
||
* - 包含列表数据和分页信息
|
||
*/
|
||
export class AdminDatabaseListResponseDto extends AdminDatabaseResponseDto {
|
||
@ApiProperty({ description: '列表数据' })
|
||
data: {
|
||
items: any[];
|
||
total: number;
|
||
limit: number;
|
||
offset: number;
|
||
has_more: boolean;
|
||
};
|
||
}
|
||
|
||
/**
|
||
* 管理员健康检查响应DTO
|
||
*
|
||
* 功能描述：
|
||
* 定义系统健康检查接口的响应数据结构
|
||
*
|
||
* 使用场景：
|
||
* - GET /admin/database/health 接口的响应体
|
||
* - 包含系统健康状态信息
|
||
*/
|
||
export class AdminHealthCheckResponseDto extends AdminDatabaseResponseDto {
|
||
@ApiProperty({ description: '健康检查数据' })
|
||
data: {
|
||
status: string;
|
||
timestamp: string;
|
||
services: {
|
||
users: string;
|
||
user_profiles: string;
|
||
zulip_accounts: string;
|
||
};
|
||
};
|
||
} |