feat：实现管理员系统核心功能
- 添加管理员数据库管理控制器和服务 - 实现管理员操作日志记录系统 - 添加数据库异常处理过滤器 - 完善管理员权限验证和响应格式 - 添加全面的属性测试覆盖
This commit is contained in:
moyin
@@ -20,26 +20,28 @@
|
||||
*
|
||||
* 最近修改：
|
||||
* - 2026-01-07: 代码规范优化 - 修正文件命名规范，更新作者信息和修改记录
|
||||
* - 2026-01-08: 注释规范优化 - 补充方法注释，添加@param、@returns、@throws和@example (修改者: moyin)
|
||||
*
|
||||
* @author moyin
|
||||
* @version 1.0.1
|
||||
* @version 1.0.2
|
||||
* @since 2025-12-19
|
||||
* @lastModified 2026-01-07
|
||||
* @lastModified 2026-01-08
|
||||
*/
|
||||
|
||||
import { Body, Controller, Get, HttpCode, HttpStatus, Param, Post, Query, UseGuards, ValidationPipe, UsePipes, Res, Logger } from '@nestjs/common';
|
||||
import { ApiBearerAuth, ApiBody, ApiOperation, ApiParam, ApiProduces, ApiQuery, ApiResponse, ApiTags } from '@nestjs/swagger';
|
||||
import { AdminGuard } from './guards/admin.guard';
|
||||
import { AdminGuard } from './admin.guard';
|
||||
import { AdminService } from './admin.service';
|
||||
import { AdminLoginDto, AdminResetPasswordDto } from './dto/admin_login.dto';
|
||||
import { AdminLoginDto, AdminResetPasswordDto } from './admin_login.dto';
|
||||
import {
|
||||
AdminLoginResponseDto,
|
||||
AdminUsersResponseDto,
|
||||
AdminCommonResponseDto,
|
||||
AdminUserResponseDto,
|
||||
AdminRuntimeLogsResponseDto
|
||||
} from './dto/admin_response.dto';
|
||||
} from './admin_response.dto';
|
||||
import { Throttle, ThrottlePresets } from '../../core/security_core/throttle.decorator';
|
||||
import { getCurrentTimestamp } from './admin_utils';
|
||||
import type { Response } from 'express';
|
||||
import * as fs from 'fs';
|
||||
import * as path from 'path';
|
||||
@@ -53,6 +55,33 @@ export class AdminController {
|
||||
|
||||
constructor(private readonly adminService: AdminService) {}
|
||||
|
||||
/**
|
||||
* 管理员登录
|
||||
*
|
||||
* 功能描述：
|
||||
* 验证管理员身份并生成JWT Token，仅允许role=9的账户登录后台
|
||||
*
|
||||
* 业务逻辑：
|
||||
* 1. 验证登录标识符和密码
|
||||
* 2. 检查用户角色是否为管理员(role=9)
|
||||
* 3. 生成JWT Token
|
||||
* 4. 返回登录结果和Token
|
||||
*
|
||||
* @param dto 登录请求数据
|
||||
* @returns 登录结果，包含Token和管理员信息
|
||||
*
|
||||
* @throws UnauthorizedException 当登录失败时
|
||||
* @throws ForbiddenException 当权限不足或账户被禁用时
|
||||
* @throws TooManyRequestsException 当登录尝试过于频繁时
|
||||
*
|
||||
* @example
|
||||
* ```typescript
|
||||
* const result = await adminController.login({
|
||||
* identifier: 'admin',
|
||||
* password: 'Admin123456'
|
||||
* });
|
||||
* ```
|
||||
*/
|
||||
@ApiOperation({ summary: '管理员登录', description: '仅允许 role=9 的账户登录后台' })
|
||||
@ApiBody({ type: AdminLoginDto })
|
||||
@ApiResponse({ status: 200, description: '登录成功', type: AdminLoginResponseDto })
|
||||
@@ -67,6 +96,28 @@ export class AdminController {
|
||||
return await this.adminService.login(dto.identifier, dto.password);
|
||||
}
|
||||
|
||||
/**
|
||||
* 获取用户列表
|
||||
*
|
||||
* 功能描述：
|
||||
* 分页获取系统中的用户列表，支持限制数量和偏移量参数
|
||||
*
|
||||
* 业务逻辑：
|
||||
* 1. 解析查询参数（limit和offset）
|
||||
* 2. 调用用户服务获取用户列表
|
||||
* 3. 格式化用户数据
|
||||
* 4. 返回分页结果
|
||||
*
|
||||
* @param limit 返回数量，默认100，可选参数
|
||||
* @param offset 偏移量，默认0，可选参数
|
||||
* @returns 用户列表和分页信息
|
||||
*
|
||||
* @example
|
||||
* ```typescript
|
||||
* // 获取前20个用户
|
||||
* const result = await adminController.listUsers('20', '0');
|
||||
* ```
|
||||
*/
|
||||
@ApiBearerAuth('JWT-auth')
|
||||
@ApiOperation({ summary: '获取用户列表', description: '后台用户管理：分页获取用户列表' })
|
||||
@ApiQuery({ name: 'limit', required: false, description: '返回数量（默认100）' })
|
||||
@@ -83,6 +134,28 @@ export class AdminController {
|
||||
return await this.adminService.listUsers(parsedLimit, parsedOffset);
|
||||
}
|
||||
|
||||
/**
|
||||
* 获取用户详情
|
||||
*
|
||||
* 功能描述：
|
||||
* 根据用户ID获取指定用户的详细信息
|
||||
*
|
||||
* 业务逻辑：
|
||||
* 1. 验证用户ID格式
|
||||
* 2. 查询用户详细信息
|
||||
* 3. 格式化用户数据
|
||||
* 4. 返回用户详情
|
||||
*
|
||||
* @param id 用户ID字符串
|
||||
* @returns 用户详细信息
|
||||
*
|
||||
* @throws NotFoundException 当用户不存在时
|
||||
*
|
||||
* @example
|
||||
* ```typescript
|
||||
* const result = await adminController.getUser('123');
|
||||
* ```
|
||||
*/
|
||||
@ApiBearerAuth('JWT-auth')
|
||||
@ApiOperation({ summary: '获取用户详情' })
|
||||
@ApiParam({ name: 'id', description: '用户ID' })
|
||||
@@ -93,6 +166,34 @@ export class AdminController {
|
||||
return await this.adminService.getUser(BigInt(id));
|
||||
}
|
||||
|
||||
/**
|
||||
* 重置用户密码
|
||||
*
|
||||
* 功能描述：
|
||||
* 管理员直接为指定用户设置新密码，新密码需满足密码强度规则
|
||||
*
|
||||
* 业务逻辑：
|
||||
* 1. 验证用户ID和新密码格式
|
||||
* 2. 检查用户是否存在
|
||||
* 3. 验证密码强度规则
|
||||
* 4. 更新用户密码
|
||||
* 5. 记录操作日志
|
||||
*
|
||||
* @param id 用户ID字符串
|
||||
* @param dto 密码重置请求数据
|
||||
* @returns 重置结果
|
||||
*
|
||||
* @throws NotFoundException 当用户不存在时
|
||||
* @throws BadRequestException 当密码不符合强度规则时
|
||||
* @throws TooManyRequestsException 当操作过于频繁时
|
||||
*
|
||||
* @example
|
||||
* ```typescript
|
||||
* const result = await adminController.resetPassword('123', {
|
||||
* newPassword: 'NewPass1234'
|
||||
* });
|
||||
* ```
|
||||
*/
|
||||
@ApiBearerAuth('JWT-auth')
|
||||
@ApiOperation({ summary: '重置用户密码', description: '管理员直接为用户设置新密码（需满足密码强度规则）' })
|
||||
@ApiParam({ name: 'id', description: '用户ID' })
|
||||
@@ -105,7 +206,7 @@ export class AdminController {
|
||||
@HttpCode(HttpStatus.OK)
|
||||
@UsePipes(new ValidationPipe({ transform: true }))
|
||||
async resetPassword(@Param('id') id: string, @Body() dto: AdminResetPasswordDto) {
|
||||
return await this.adminService.resetPassword(BigInt(id), dto.new_password);
|
||||
return await this.adminService.resetPassword(BigInt(id), dto.newPassword);
|
||||
}
|
||||
|
||||
@ApiBearerAuth('JWT-auth')
|
||||
@@ -128,30 +229,70 @@ export class AdminController {
|
||||
async downloadLogsArchive(@Res() res: Response) {
|
||||
const logDir = this.adminService.getLogDirAbsolutePath();
|
||||
|
||||
// 验证日志目录
|
||||
const dirValidation = this.validateLogDirectory(logDir, res);
|
||||
if (!dirValidation.isValid) {
|
||||
return;
|
||||
}
|
||||
|
||||
// 设置响应头
|
||||
this.setArchiveResponseHeaders(res);
|
||||
|
||||
// 创建并处理tar进程
|
||||
await this.createAndHandleTarProcess(logDir, res);
|
||||
}
|
||||
|
||||
/**
|
||||
* 验证日志目录是否存在且可用
|
||||
*
|
||||
* @param logDir 日志目录路径
|
||||
* @param res 响应对象
|
||||
* @returns 验证结果
|
||||
*/
|
||||
private validateLogDirectory(logDir: string, res: Response): { isValid: boolean } {
|
||||
if (!fs.existsSync(logDir)) {
|
||||
res.status(404).json({ success: false, message: '日志目录不存在' });
|
||||
return;
|
||||
return { isValid: false };
|
||||
}
|
||||
|
||||
const stats = fs.statSync(logDir);
|
||||
if (!stats.isDirectory()) {
|
||||
res.status(404).json({ success: false, message: '日志目录不可用' });
|
||||
return;
|
||||
return { isValid: false };
|
||||
}
|
||||
|
||||
const parentDir = path.dirname(logDir);
|
||||
const baseName = path.basename(logDir);
|
||||
const ts = new Date().toISOString().replace(/[:.]/g, '-');
|
||||
return { isValid: true };
|
||||
}
|
||||
|
||||
/**
|
||||
* 设置文件下载的响应头
|
||||
*
|
||||
* @param res 响应对象
|
||||
*/
|
||||
private setArchiveResponseHeaders(res: Response): void {
|
||||
const ts = getCurrentTimestamp().replace(/[:.]/g, '-');
|
||||
const filename = `logs-${ts}.tar.gz`;
|
||||
|
||||
res.setHeader('Content-Type', 'application/gzip');
|
||||
res.setHeader('Content-Disposition', `attachment; filename="${filename}"`);
|
||||
res.setHeader('Cache-Control', 'no-store');
|
||||
}
|
||||
|
||||
/**
|
||||
* 创建并处理tar进程
|
||||
*
|
||||
* @param logDir 日志目录路径
|
||||
* @param res 响应对象
|
||||
*/
|
||||
private async createAndHandleTarProcess(logDir: string, res: Response): Promise<void> {
|
||||
const parentDir = path.dirname(logDir);
|
||||
const baseName = path.basename(logDir);
|
||||
|
||||
const tar = spawn('tar', ['-czf', '-', '-C', parentDir, baseName], {
|
||||
stdio: ['ignore', 'pipe', 'pipe'],
|
||||
});
|
||||
|
||||
// 处理tar进程的stderr输出
|
||||
tar.stderr.on('data', (chunk: Buffer) => {
|
||||
const msg = chunk.toString('utf8').trim();
|
||||
if (msg) {
|
||||
@@ -159,16 +300,38 @@ export class AdminController {
|
||||
}
|
||||
});
|
||||
|
||||
// 处理tar进程错误
|
||||
tar.on('error', (err: any) => {
|
||||
this.logger.error('打包日志失败（tar 进程启动失败）', err?.stack || String(err));
|
||||
if (!res.headersSent) {
|
||||
const msg = err?.code === 'ENOENT' ? '服务器缺少 tar 命令，无法打包日志' : '日志打包失败';
|
||||
res.status(500).json({ success: false, message: msg });
|
||||
} else {
|
||||
res.end();
|
||||
}
|
||||
this.handleTarProcessError(err, res);
|
||||
});
|
||||
|
||||
// 处理数据流和进程退出
|
||||
await this.handleTarStreams(tar, res);
|
||||
}
|
||||
|
||||
/**
|
||||
* 处理tar进程错误
|
||||
*
|
||||
* @param err 错误对象
|
||||
* @param res 响应对象
|
||||
*/
|
||||
private handleTarProcessError(err: any, res: Response): void {
|
||||
this.logger.error('打包日志失败（tar 进程启动失败）', err?.stack || String(err));
|
||||
if (!res.headersSent) {
|
||||
const msg = err?.code === 'ENOENT' ? '服务器缺少 tar 命令，无法打包日志' : '日志打包失败';
|
||||
res.status(500).json({ success: false, message: msg });
|
||||
} else {
|
||||
res.end();
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* 处理tar进程的数据流和退出
|
||||
*
|
||||
* @param tar tar进程
|
||||
* @param res 响应对象
|
||||
*/
|
||||
private async handleTarStreams(tar: any, res: Response): Promise<void> {
|
||||
const pipelinePromise = new Promise<void>((resolve, reject) => {
|
||||
pipeline(tar.stdout, res, (err) => (err ? reject(err) : resolve()));
|
||||
});
|
||||
|
||||
Reference in New Issue
Block a user