forked from datawhale/whale-town-end
5f662ef091
- 更新管理员控制器和数据库管理功能 - 完善管理员操作日志系统 - 添加全面的属性测试覆盖 - 优化用户管理和用户档案服务 - 更新代码检查规范文档 功能改进: - 增强管理员权限验证 - 完善操作日志记录 - 优化数据库管理接口 - 提升系统安全性和可维护性
404 lines
16 KiB
TypeScript
404 lines
16 KiB
TypeScript
/**
|
||
* 管理员数据库管理控制器
|
||
*
|
||
* 功能描述：
|
||
* - 提供管理员专用的数据库管理HTTP接口
|
||
* - 集成用户、用户档案、Zulip账号关联的CRUD操作
|
||
* - 实现统一的权限控制和参数验证
|
||
* - 支持分页查询和搜索功能
|
||
*
|
||
* 职责分离：
|
||
* - HTTP请求处理：接收和验证HTTP请求参数
|
||
* - 权限控制：通过AdminGuard确保只有管理员可以访问
|
||
* - 业务委托：将业务逻辑委托给DatabaseManagementService处理
|
||
* - 响应格式化：返回统一格式的HTTP响应
|
||
*
|
||
* API端点分组：
|
||
* - /admin/database/users/* 用户管理相关接口
|
||
* - /admin/database/user-profiles/* 用户档案管理相关接口
|
||
* - /admin/database/zulip-accounts/* Zulip账号关联管理相关接口
|
||
*
|
||
* 最近修改：
|
||
* - 2026-01-08: 注释规范优化 - 修正@author字段，更新版本号和修改记录 (修改者: moyin)
|
||
* - 2026-01-08: 代码质量优化 - 清理未使用的导入 (修改者: moyin)
|
||
* - 2026-01-08: 文件夹扁平化 - 从controllers/子文件夹移动到上级目录 (修改者: moyin)
|
||
* - 2026-01-08: 功能新增 - 创建管理员数据库管理控制器 (修改者: assistant)
|
||
*
|
||
* @author moyin
|
||
* @version 1.1.0
|
||
* @since 2026-01-08
|
||
* @lastModified 2026-01-08
|
||
*/
|
||
|
||
import {
|
||
Controller,
|
||
Get,
|
||
Post,
|
||
Put,
|
||
Delete,
|
||
Param,
|
||
Query,
|
||
Body,
|
||
UseGuards,
|
||
UseFilters,
|
||
UseInterceptors,
|
||
ParseIntPipe,
|
||
DefaultValuePipe
|
||
} from '@nestjs/common';
|
||
import {
|
||
ApiTags,
|
||
ApiBearerAuth,
|
||
ApiOperation,
|
||
ApiParam,
|
||
ApiQuery,
|
||
ApiResponse,
|
||
ApiBody
|
||
} from '@nestjs/swagger';
|
||
import { AdminGuard } from './admin.guard';
|
||
import { AdminDatabaseExceptionFilter } from './admin_database_exception.filter';
|
||
import { AdminOperationLogInterceptor } from './admin_operation_log.interceptor';
|
||
import { LogAdminOperation } from './log_admin_operation.decorator';
|
||
import { DatabaseManagementService, AdminApiResponse, AdminListResponse } from './database_management.service';
|
||
import {
|
||
AdminCreateUserDto,
|
||
AdminUpdateUserDto,
|
||
AdminBatchUpdateStatusDto,
|
||
AdminDatabaseResponseDto,
|
||
AdminHealthCheckResponseDto,
|
||
AdminCreateUserProfileDto,
|
||
AdminUpdateUserProfileDto,
|
||
AdminCreateZulipAccountDto,
|
||
AdminUpdateZulipAccountDto
|
||
} from './admin_database.dto';
|
||
import { PAGINATION_LIMITS, REQUEST_ID_PREFIXES } from './admin_constants';
|
||
import { safeLimitValue, createSuccessResponse, getCurrentTimestamp } from './admin_utils';
|
||
|
||
@ApiTags('admin-database')
|
||
@Controller('admin/database')
|
||
@UseGuards(AdminGuard)
|
||
@UseFilters(AdminDatabaseExceptionFilter)
|
||
@UseInterceptors(AdminOperationLogInterceptor)
|
||
@ApiBearerAuth('JWT-auth')
|
||
export class AdminDatabaseController {
|
||
constructor(
|
||
private readonly databaseManagementService: DatabaseManagementService
|
||
) {}
|
||
|
||
// ==================== 用户管理接口 ====================
|
||
|
||
@ApiOperation({
|
||
summary: '获取用户列表',
|
||
description: '分页获取用户列表，支持管理员查看所有用户信息'
|
||
})
|
||
@ApiQuery({ name: 'limit', required: false, description: '返回数量（默认20，最大100）', example: 20 })
|
||
@ApiQuery({ name: 'offset', required: false, description: '偏移量（默认0）', example: 0 })
|
||
@ApiResponse({ status: 200, description: '获取成功' })
|
||
@ApiResponse({ status: 401, description: '未授权访问' })
|
||
@ApiResponse({ status: 403, description: '权限不足' })
|
||
@LogAdminOperation({
|
||
operationType: 'QUERY',
|
||
targetType: 'users',
|
||
description: '获取用户列表',
|
||
isSensitive: false
|
||
})
|
||
@Get('users')
|
||
async getUserList(
|
||
@Query('limit', new DefaultValuePipe(PAGINATION_LIMITS.DEFAULT_LIMIT), ParseIntPipe) limit: number,
|
||
@Query('offset', new DefaultValuePipe(PAGINATION_LIMITS.DEFAULT_OFFSET), ParseIntPipe) offset: number
|
||
): Promise<AdminListResponse> {
|
||
const safeLimit = safeLimitValue(limit, PAGINATION_LIMITS.USER_LIST_MAX_LIMIT);
|
||
return await this.databaseManagementService.getUserList(safeLimit, offset);
|
||
}
|
||
|
||
@ApiOperation({
|
||
summary: '获取用户详情',
|
||
description: '根据用户ID获取详细的用户信息'
|
||
})
|
||
@ApiParam({ name: 'id', description: '用户ID', example: '1' })
|
||
@ApiResponse({ status: 200, description: '获取成功' })
|
||
@ApiResponse({ status: 404, description: '用户不存在' })
|
||
@Get('users/:id')
|
||
async getUserById(@Param('id') id: string): Promise<AdminApiResponse> {
|
||
return await this.databaseManagementService.getUserById(BigInt(id));
|
||
}
|
||
|
||
@ApiOperation({
|
||
summary: '搜索用户',
|
||
description: '根据关键词搜索用户，支持用户名、邮箱、昵称模糊匹配'
|
||
})
|
||
@ApiQuery({ name: 'keyword', description: '搜索关键词', example: 'admin' })
|
||
@ApiQuery({ name: 'limit', required: false, description: '返回数量（默认20，最大50）', example: 20 })
|
||
@ApiResponse({ status: 200, description: '搜索成功' })
|
||
@Get('users/search')
|
||
async searchUsers(
|
||
@Query('keyword') keyword: string,
|
||
@Query('limit', new DefaultValuePipe(PAGINATION_LIMITS.DEFAULT_LIMIT), ParseIntPipe) limit: number
|
||
): Promise<AdminListResponse> {
|
||
const safeLimit = safeLimitValue(limit, PAGINATION_LIMITS.SEARCH_MAX_LIMIT);
|
||
return await this.databaseManagementService.searchUsers(keyword, safeLimit);
|
||
}
|
||
|
||
@ApiOperation({
|
||
summary: '创建用户',
|
||
description: '创建新用户，需要提供用户名和昵称等基本信息'
|
||
})
|
||
@ApiBody({ type: AdminCreateUserDto, description: '用户创建数据' })
|
||
@ApiResponse({ status: 201, description: '创建成功', type: AdminDatabaseResponseDto })
|
||
@ApiResponse({ status: 400, description: '请求参数错误' })
|
||
@ApiResponse({ status: 409, description: '用户名或邮箱已存在' })
|
||
@LogAdminOperation({
|
||
operationType: 'CREATE',
|
||
targetType: 'users',
|
||
description: '创建用户',
|
||
isSensitive: true
|
||
})
|
||
@Post('users')
|
||
async createUser(@Body() createUserDto: AdminCreateUserDto): Promise<AdminApiResponse> {
|
||
return await this.databaseManagementService.createUser(createUserDto);
|
||
}
|
||
|
||
@ApiOperation({
|
||
summary: '更新用户',
|
||
description: '根据用户ID更新用户信息'
|
||
})
|
||
@ApiParam({ name: 'id', description: '用户ID', example: '1' })
|
||
@ApiBody({ type: AdminUpdateUserDto, description: '用户更新数据' })
|
||
@ApiResponse({ status: 200, description: '更新成功', type: AdminDatabaseResponseDto })
|
||
@ApiResponse({ status: 404, description: '用户不存在' })
|
||
@Put('users/:id')
|
||
async updateUser(
|
||
@Param('id') id: string,
|
||
@Body() updateUserDto: AdminUpdateUserDto
|
||
): Promise<AdminApiResponse> {
|
||
return await this.databaseManagementService.updateUser(BigInt(id), updateUserDto);
|
||
}
|
||
|
||
@ApiOperation({
|
||
summary: '删除用户',
|
||
description: '根据用户ID删除用户（软删除）'
|
||
})
|
||
@ApiParam({ name: 'id', description: '用户ID', example: '1' })
|
||
@ApiResponse({ status: 200, description: '删除成功' })
|
||
@ApiResponse({ status: 404, description: '用户不存在' })
|
||
@LogAdminOperation({
|
||
operationType: 'DELETE',
|
||
targetType: 'users',
|
||
description: '删除用户',
|
||
isSensitive: true
|
||
})
|
||
@Delete('users/:id')
|
||
async deleteUser(@Param('id') id: string): Promise<AdminApiResponse> {
|
||
return await this.databaseManagementService.deleteUser(BigInt(id));
|
||
}
|
||
|
||
// ==================== 用户档案管理接口 ====================
|
||
|
||
@ApiOperation({
|
||
summary: '获取用户档案列表',
|
||
description: '分页获取用户档案列表，包含位置信息和档案数据'
|
||
})
|
||
@ApiQuery({ name: 'limit', required: false, description: '返回数量（默认20，最大100）', example: 20 })
|
||
@ApiQuery({ name: 'offset', required: false, description: '偏移量（默认0）', example: 0 })
|
||
@ApiResponse({ status: 200, description: '获取成功' })
|
||
@Get('user-profiles')
|
||
async getUserProfileList(
|
||
@Query('limit', new DefaultValuePipe(PAGINATION_LIMITS.DEFAULT_LIMIT), ParseIntPipe) limit: number,
|
||
@Query('offset', new DefaultValuePipe(PAGINATION_LIMITS.DEFAULT_OFFSET), ParseIntPipe) offset: number
|
||
): Promise<AdminListResponse> {
|
||
const safeLimit = safeLimitValue(limit, PAGINATION_LIMITS.USER_LIST_MAX_LIMIT);
|
||
return await this.databaseManagementService.getUserProfileList(safeLimit, offset);
|
||
}
|
||
|
||
@ApiOperation({
|
||
summary: '获取用户档案详情',
|
||
description: '根据档案ID获取详细的用户档案信息'
|
||
})
|
||
@ApiParam({ name: 'id', description: '档案ID', example: '1' })
|
||
@ApiResponse({ status: 200, description: '获取成功' })
|
||
@ApiResponse({ status: 404, description: '档案不存在' })
|
||
@Get('user-profiles/:id')
|
||
async getUserProfileById(@Param('id') id: string): Promise<AdminApiResponse> {
|
||
return await this.databaseManagementService.getUserProfileById(BigInt(id));
|
||
}
|
||
|
||
@ApiOperation({
|
||
summary: '根据地图获取用户档案',
|
||
description: '获取指定地图中的所有用户档案信息'
|
||
})
|
||
@ApiParam({ name: 'mapId', description: '地图ID', example: 'plaza' })
|
||
@ApiQuery({ name: 'limit', required: false, description: '返回数量（默认20，最大100）', example: 20 })
|
||
@ApiQuery({ name: 'offset', required: false, description: '偏移量（默认0）', example: 0 })
|
||
@ApiResponse({ status: 200, description: '获取成功' })
|
||
@Get('user-profiles/by-map/:mapId')
|
||
async getUserProfilesByMap(
|
||
@Param('mapId') mapId: string,
|
||
@Query('limit', new DefaultValuePipe(PAGINATION_LIMITS.DEFAULT_LIMIT), ParseIntPipe) limit: number,
|
||
@Query('offset', new DefaultValuePipe(PAGINATION_LIMITS.DEFAULT_OFFSET), ParseIntPipe) offset: number
|
||
): Promise<AdminListResponse> {
|
||
const safeLimit = safeLimitValue(limit, PAGINATION_LIMITS.USER_LIST_MAX_LIMIT);
|
||
return await this.databaseManagementService.getUserProfilesByMap(mapId, safeLimit, offset);
|
||
}
|
||
|
||
@ApiOperation({
|
||
summary: '创建用户档案',
|
||
description: '为指定用户创建档案信息'
|
||
})
|
||
@ApiBody({ type: AdminCreateUserProfileDto, description: '用户档案创建数据' })
|
||
@ApiResponse({ status: 201, description: '创建成功' })
|
||
@ApiResponse({ status: 400, description: '请求参数错误' })
|
||
@ApiResponse({ status: 409, description: '用户档案已存在' })
|
||
@Post('user-profiles')
|
||
async createUserProfile(@Body() createProfileDto: AdminCreateUserProfileDto): Promise<AdminApiResponse> {
|
||
return await this.databaseManagementService.createUserProfile(createProfileDto);
|
||
}
|
||
|
||
@ApiOperation({
|
||
summary: '更新用户档案',
|
||
description: '根据档案ID更新用户档案信息'
|
||
})
|
||
@ApiParam({ name: 'id', description: '档案ID', example: '1' })
|
||
@ApiBody({ type: AdminUpdateUserProfileDto, description: '用户档案更新数据' })
|
||
@ApiResponse({ status: 200, description: '更新成功' })
|
||
@ApiResponse({ status: 404, description: '档案不存在' })
|
||
@Put('user-profiles/:id')
|
||
async updateUserProfile(
|
||
@Param('id') id: string,
|
||
@Body() updateProfileDto: AdminUpdateUserProfileDto
|
||
): Promise<AdminApiResponse> {
|
||
return await this.databaseManagementService.updateUserProfile(BigInt(id), updateProfileDto);
|
||
}
|
||
|
||
@ApiOperation({
|
||
summary: '删除用户档案',
|
||
description: '根据档案ID删除用户档案'
|
||
})
|
||
@ApiParam({ name: 'id', description: '档案ID', example: '1' })
|
||
@ApiResponse({ status: 200, description: '删除成功' })
|
||
@ApiResponse({ status: 404, description: '档案不存在' })
|
||
@Delete('user-profiles/:id')
|
||
async deleteUserProfile(@Param('id') id: string): Promise<AdminApiResponse> {
|
||
return await this.databaseManagementService.deleteUserProfile(BigInt(id));
|
||
}
|
||
|
||
// ==================== Zulip账号关联管理接口 ====================
|
||
|
||
@ApiOperation({
|
||
summary: '获取Zulip账号关联列表',
|
||
description: '分页获取Zulip账号关联列表，包含关联状态和错误信息'
|
||
})
|
||
@ApiQuery({ name: 'limit', required: false, description: '返回数量（默认20，最大100）', example: 20 })
|
||
@ApiQuery({ name: 'offset', required: false, description: '偏移量（默认0）', example: 0 })
|
||
@ApiResponse({ status: 200, description: '获取成功' })
|
||
@Get('zulip-accounts')
|
||
async getZulipAccountList(
|
||
@Query('limit', new DefaultValuePipe(PAGINATION_LIMITS.DEFAULT_LIMIT), ParseIntPipe) limit: number,
|
||
@Query('offset', new DefaultValuePipe(PAGINATION_LIMITS.DEFAULT_OFFSET), ParseIntPipe) offset: number
|
||
): Promise<AdminListResponse> {
|
||
const safeLimit = safeLimitValue(limit, PAGINATION_LIMITS.USER_LIST_MAX_LIMIT);
|
||
return await this.databaseManagementService.getZulipAccountList(safeLimit, offset);
|
||
}
|
||
|
||
@ApiOperation({
|
||
summary: '获取Zulip账号关联详情',
|
||
description: '根据关联ID获取详细的Zulip账号关联信息'
|
||
})
|
||
@ApiParam({ name: 'id', description: '关联ID', example: '1' })
|
||
@ApiResponse({ status: 200, description: '获取成功' })
|
||
@ApiResponse({ status: 404, description: '关联不存在' })
|
||
@Get('zulip-accounts/:id')
|
||
async getZulipAccountById(@Param('id') id: string): Promise<AdminApiResponse> {
|
||
return await this.databaseManagementService.getZulipAccountById(id);
|
||
}
|
||
|
||
@ApiOperation({
|
||
summary: '获取Zulip账号关联统计',
|
||
description: '获取各种状态的Zulip账号关联数量统计信息'
|
||
})
|
||
@ApiResponse({ status: 200, description: '获取成功' })
|
||
@Get('zulip-accounts/statistics')
|
||
async getZulipAccountStatistics(): Promise<AdminApiResponse> {
|
||
return await this.databaseManagementService.getZulipAccountStatistics();
|
||
}
|
||
|
||
@ApiOperation({
|
||
summary: '创建Zulip账号关联',
|
||
description: '创建游戏用户与Zulip账号的关联'
|
||
})
|
||
@ApiBody({ type: AdminCreateZulipAccountDto, description: 'Zulip账号关联创建数据' })
|
||
@ApiResponse({ status: 201, description: '创建成功' })
|
||
@ApiResponse({ status: 400, description: '请求参数错误' })
|
||
@ApiResponse({ status: 409, description: '关联已存在' })
|
||
@Post('zulip-accounts')
|
||
async createZulipAccount(@Body() createAccountDto: AdminCreateZulipAccountDto): Promise<AdminApiResponse> {
|
||
return await this.databaseManagementService.createZulipAccount(createAccountDto);
|
||
}
|
||
|
||
@ApiOperation({
|
||
summary: '更新Zulip账号关联',
|
||
description: '根据关联ID更新Zulip账号关联信息'
|
||
})
|
||
@ApiParam({ name: 'id', description: '关联ID', example: '1' })
|
||
@ApiBody({ type: AdminUpdateZulipAccountDto, description: 'Zulip账号关联更新数据' })
|
||
@ApiResponse({ status: 200, description: '更新成功' })
|
||
@ApiResponse({ status: 404, description: '关联不存在' })
|
||
@Put('zulip-accounts/:id')
|
||
async updateZulipAccount(
|
||
@Param('id') id: string,
|
||
@Body() updateAccountDto: AdminUpdateZulipAccountDto
|
||
): Promise<AdminApiResponse> {
|
||
return await this.databaseManagementService.updateZulipAccount(id, updateAccountDto);
|
||
}
|
||
|
||
@ApiOperation({
|
||
summary: '删除Zulip账号关联',
|
||
description: '根据关联ID删除Zulip账号关联'
|
||
})
|
||
@ApiParam({ name: 'id', description: '关联ID', example: '1' })
|
||
@ApiResponse({ status: 200, description: '删除成功' })
|
||
@ApiResponse({ status: 404, description: '关联不存在' })
|
||
@Delete('zulip-accounts/:id')
|
||
async deleteZulipAccount(@Param('id') id: string): Promise<AdminApiResponse> {
|
||
return await this.databaseManagementService.deleteZulipAccount(id);
|
||
}
|
||
|
||
@ApiOperation({
|
||
summary: '批量更新Zulip账号状态',
|
||
description: '批量更新多个Zulip账号关联的状态'
|
||
})
|
||
@ApiBody({ type: AdminBatchUpdateStatusDto, description: '批量更新数据' })
|
||
@ApiResponse({ status: 200, description: '批量更新完成', type: AdminDatabaseResponseDto })
|
||
@LogAdminOperation({
|
||
operationType: 'BATCH',
|
||
targetType: 'zulip_accounts',
|
||
description: '批量更新Zulip账号状态',
|
||
isSensitive: true
|
||
})
|
||
@Post('zulip-accounts/batch-update-status')
|
||
async batchUpdateZulipAccountStatus(@Body() batchUpdateDto: AdminBatchUpdateStatusDto): Promise<AdminApiResponse> {
|
||
return await this.databaseManagementService.batchUpdateZulipAccountStatus(
|
||
batchUpdateDto.ids,
|
||
batchUpdateDto.status,
|
||
batchUpdateDto.reason
|
||
);
|
||
}
|
||
|
||
// ==================== 系统健康检查接口 ====================
|
||
|
||
@ApiOperation({
|
||
summary: '数据库管理系统健康检查',
|
||
description: '检查数据库管理系统的运行状态和连接情况'
|
||
})
|
||
@ApiResponse({ status: 200, description: '系统正常', type: AdminHealthCheckResponseDto })
|
||
@Get('health')
|
||
async healthCheck(): Promise<AdminApiResponse> {
|
||
return createSuccessResponse({
|
||
status: 'healthy',
|
||
timestamp: getCurrentTimestamp(),
|
||
services: {
|
||
users: 'connected',
|
||
user_profiles: 'connected',
|
||
zulip_accounts: 'connected'
|
||
}
|
||
}, '数据库管理系统运行正常', REQUEST_ID_PREFIXES.HEALTH_CHECK);
|
||
}
|
||
} |