forked from datawhale/whale-town-end
feat：实现管理员系统核心功能
- 添加管理员数据库管理控制器和服务 - 实现管理员操作日志记录系统 - 添加数据库异常处理过滤器 - 完善管理员权限验证和响应格式 - 添加全面的属性测试覆盖
This commit is contained in:
moyin
570
src/business/admin/admin_database.dto.ts
Normal file
570
src/business/admin/admin_database.dto.ts
Normal file
@@ -0,0 +1,570 @@
|
||||
/**
|
||||
* 管理员数据库管理 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;
|
||||
};
|
||||
};
|
||||
}
|
||||
Reference in New Issue
Block a user