Initial WhaleTown V2 backend

2026-07-20 02:00:52 +08:00
commit c995891c1f
265 changed files with 75689 additions and 0 deletions
--- a/src/business/user_mgmt/index.ts
+++ b/src/business/user_mgmt/index.ts
@@ -0,0 +1,38 @@
+/**
+ * 用户管理业务模块导出
+ *
+ * 功能描述：
+ * - 用户状态管理（激活、锁定、禁用等）
+ * - 批量用户操作
+ * - 用户状态统计和分析
+ * - 状态变更审计和历史记录
+ *
+ * 职责分离：
+ * - 统一导出用户管理模块的所有公共组件
+ * - 提供模块化的访问接口
+ * - 简化外部模块的依赖管理
+ *
+ * 最近修改：
+ * - 2026-01-07: 代码规范优化 - 修正文件命名规范，完善注释规范，更新作者信息 (修改者: moyin)
+ *
+ * @author moyin
+ * @version 1.0.1
+ * @since 2025-12-24
+ * @lastModified 2026-01-07
+ */
+
+// 模块
+export * from './user_mgmt.module';
+
+// 控制器
+export * from './user_status.controller';
+
+// 服务
+export * from './user_management.service';
+
+// DTO
+export * from './user_status.dto';
+export * from './user_status_response.dto';
+
+// 常量
+export * from './user_mgmt.constants';
--- a/src/business/user_mgmt/user_management.service.ts
+++ b/src/business/user_mgmt/user_management.service.ts
@@ -0,0 +1,260 @@
+/**
+ * 用户管理业务服务
+ *
+ * 功能描述：
+ * - 用户状态管理业务逻辑
+ * - 批量用户操作
+ * - 用户状态统计
+ * - 状态变更审计
+ *
+ * 职责分离：
+ * - 专注于用户管理相关的业务逻辑实现
+ * - 调用底层AdminService提供的技术能力
+ * - 提供用户管理特定的业务规则和流程控制
+ *
+ * 最近修改：
+ * - 2026-01-07: 代码规范优化 - 修正文件命名规范，完善注释规范，更新作者信息 (修改者: moyin)
+ *
+ * @author moyin
+ * @version 1.0.1
+ * @since 2025-12-24
+ * @lastModified 2026-01-07
+ */
+
+import { Injectable, Logger } from '@nestjs/common';
+import { AdminService } from '../admin/admin.service';
+import { UserStatusDto, BatchUserStatusDto } from './user_status.dto';
+import {
+  UserStatusResponseDto,
+  BatchUserStatusResponseDto,
+  UserStatusStatsResponseDto
+} from './user_status_response.dto';
+import { BATCH_OPERATION, DEFAULTS, ERROR_CODES, MESSAGES, UTILS } from './user_mgmt.constants';
+
+/**
+ * 用户管理业务服务
+ *
+ * 职责：
+ * - 实现用户状态管理的完整业务逻辑
+ * - 提供批量操作和状态统计的业务能力
+ * - 执行业务规则验证和审计日志记录
+ *
+ * 主要方法：
+ * - updateUserStatus() - 单个用户状态修改业务逻辑
+ * - batchUpdateUserStatus() - 批量用户状态修改业务逻辑
+ * - getUserStatusStats() - 用户状态统计业务逻辑
+ * - getUserStatusHistory() - 用户状态变更历史查询
+ *
+ * 使用场景：
+ * - 管理员执行用户状态管理操作
+ * - 系统自动化用户生命周期管理
+ * - 用户状态监控和数据分析
+ */
+@Injectable()
+export class UserManagementService {
+  private readonly logger = new Logger(UserManagementService.name);
+
+  constructor(private readonly adminService: AdminService) {}
+
+  /**
+   * 修改用户状态
+   *
+   * 业务逻辑：
+   * 1. 验证状态变更的业务规则
+   * 2. 记录状态变更原因
+   * 3. 调用底层服务执行变更
+   * 4. 记录业务审计日志
+   *
+   * @param userId 用户ID
+   * @param userStatusDto 状态修改数据
+   * @returns 修改结果
+   * @throws NotFoundException 用户不存在时
+   * @throws BadRequestException 状态变更不符合业务规则时
+   *
+   * @example
+   * ```typescript
+   * const result = await service.updateUserStatus(BigInt(123), {
+   *   status: UserStatus.ACTIVE,
+   *   reason: '用户申诉通过，恢复正常状态'
+   * });
+   * ```
+   */
+  async updateUserStatus(userId: bigint, userStatusDto: UserStatusDto): Promise<UserStatusResponseDto> {
+    this.logger.log('用户管理：开始修改用户状态', {
+      operation: 'user_mgmt_update_status',
+      userId: userId.toString(),
+      newStatus: userStatusDto.status,
+      reason: userStatusDto.reason,
+      timestamp: UTILS.getCurrentTimestamp()
+    });
+
+    // 调用底层管理员服务
+    const result = await this.adminService.updateUserStatus(userId, userStatusDto);
+
+    // 记录业务层日志
+    if (result.success) {
+      this.logger.log('用户管理：用户状态修改成功', {
+        operation: 'user_mgmt_update_status_success',
+        userId: userId.toString(),
+        newStatus: userStatusDto.status,
+        timestamp: UTILS.getCurrentTimestamp()
+      });
+    }
+
+    return result;
+  }
+
+  /**
+   * 批量修改用户状态
+   *
+   * 业务逻辑：
+   * 1. 验证批量操作的业务规则
+   * 2. 分批处理大量用户
+   * 3. 提供批量操作的进度反馈
+   * 4. 记录批量操作审计
+   *
+   * @param batchUserStatusDto 批量状态修改数据
+   * @returns 批量修改结果
+   * @throws BadRequestException 批量操作数量超限或参数无效时
+   * @throws InternalServerErrorException 批量操作执行失败时
+   *
+   * @example
+   * ```typescript
+   * const result = await service.batchUpdateUserStatus({
+   *   userIds: ['123', '456'],
+   *   status: UserStatus.LOCKED,
+   *   reason: '批量锁定违规用户'
+   * });
+   * ```
+   */
+  async batchUpdateUserStatus(batchUserStatusDto: BatchUserStatusDto): Promise<BatchUserStatusResponseDto> {
+    this.logger.log('用户管理：开始批量修改用户状态', {
+      operation: 'user_mgmt_batch_update_status',
+      userCount: batchUserStatusDto.userIds.length,
+      newStatus: batchUserStatusDto.status,
+      reason: batchUserStatusDto.reason,
+      timestamp: UTILS.getCurrentTimestamp()
+    });
+
+    // 业务规则：限制批量操作的数量
+    if (batchUserStatusDto.userIds.length > BATCH_OPERATION.MAX_USER_COUNT) {
+      this.logger.warn('用户管理：批量操作数量超限', {
+        operation: 'user_mgmt_batch_update_limit_exceeded',
+        requestCount: batchUserStatusDto.userIds.length,
+        maxAllowed: BATCH_OPERATION.MAX_USER_COUNT
+      });
+
+      return {
+        success: false,
+        message: MESSAGES.BATCH_OPERATION_LIMIT_ERROR,
+        error_code: ERROR_CODES.BATCH_OPERATION_LIMIT_EXCEEDED
+      };
+    }
+
+    // 调用底层管理员服务
+    const result = await this.adminService.batchUpdateUserStatus(batchUserStatusDto);
+
+    // 记录业务层日志
+    if (result.success) {
+      this.logger.log('用户管理：批量用户状态修改完成', {
+        operation: 'user_mgmt_batch_update_status_success',
+        successCount: result.data?.result.success_count || 0,
+        failedCount: result.data?.result.failed_count || 0,
+        timestamp: UTILS.getCurrentTimestamp()
+      });
+    }
+
+    return result;
+  }
+
+  /**
+   * 获取用户状态统计
+   *
+   * 业务逻辑：
+   * 1. 获取基础统计数据
+   * 2. 计算业务相关的指标
+   * 3. 提供状态分布分析
+   * 4. 缓存统计结果
+   *
+   * @returns 状态统计信息
+   * @throws InternalServerErrorException 统计数据获取失败时
+   *
+   * @example
+   * ```typescript
+   * const stats = await service.getUserStatusStats();
+   * // 返回包含各状态用户数量和分析指标的统计数据
+   * ```
+   */
+  async getUserStatusStats(): Promise<UserStatusStatsResponseDto> {
+    this.logger.log('用户管理：获取用户状态统计', {
+      operation: 'user_mgmt_get_status_stats',
+      timestamp: UTILS.getCurrentTimestamp()
+    });
+
+    // 调用底层管理员服务
+    const result = await this.adminService.getUserStatusStats();
+
+    // 业务层可以在这里添加额外的统计分析
+    if (result.success && result.data) {
+      const stats = result.data.stats;
+
+      // 计算业务指标
+      const activeRate = stats.total > 0 ? (stats.active / stats.total * 100).toFixed(2) : '0';
+      const problemUserCount = stats.locked + stats.banned + stats.deleted;
+
+      this.logger.log('用户管理：用户状态统计分析', {
+        operation: 'user_mgmt_status_analysis',
+        totalUsers: stats.total,
+        activeUsers: stats.active,
+        activeRate: `${activeRate}%`,
+        problemUsers: problemUserCount,
+        timestamp: UTILS.getCurrentTimestamp()
+      });
+    }
+
+    return result;
+  }
+
+  /**
+   * 获取用户状态变更历史
+   *
+   * 业务逻辑：
+   * 1. 查询指定用户的状态变更记录
+   * 2. 提供状态变更的审计追踪
+   * 3. 支持时间范围和数量限制查询
+   * 4. 格式化历史记录数据
+   *
+   * @param userId 用户ID
+   * @param limit 返回数量限制
+   * @returns 状态变更历史
+   * @throws NotFoundException 用户不存在时
+   * @throws BadRequestException 查询参数无效时
+   *
+   * @example
+   * ```typescript
+   * const history = await service.getUserStatusHistory(BigInt(123), 20);
+   * // 返回用户最近20条状态变更记录
+   * ```
+   */
+  async getUserStatusHistory(userId: bigint, limit: number = DEFAULTS.STATUS_HISTORY_LIMIT) {
+    this.logger.log('用户管理：获取用户状态变更历史', {
+      operation: 'user_mgmt_get_status_history',
+      userId: userId.toString(),
+      limit,
+      timestamp: UTILS.getCurrentTimestamp()
+    });
+
+    // 注意：此功能当前返回模拟数据，实际实现需要集成审计日志服务
+    // 建议在后续版本中实现完整的状态变更历史查询功能
+
+    return {
+      success: true,
+      data: {
+        user_id: userId.toString(),
+        history: [] as any[],
+        total_count: 0
+      },
+      message: '状态变更历史获取成功（当前返回空数据，待实现完整功能）'
+    };
+  }
+}
--- a/src/business/user_mgmt/user_mgmt.constants.ts
+++ b/src/business/user_mgmt/user_mgmt.constants.ts
@@ -0,0 +1,71 @@
+/**
+ * 用户管理业务常量
+ *
+ * 功能描述：
+ * - 定义用户管理模块的业务常量
+ * - 统一管理魔法数字和配置参数
+ * - 提供类型安全的常量访问
+ *
+ * 职责分离：
+ * - 业务规则常量定义和管理
+ * - 验证规则参数统一配置
+ * - 系统限制和默认值设置
+ *
+ * 最近修改：
+ * - 2026-01-07: 代码规范优化 - 创建常量定义文件，消除魔法数字 (修改者: moyin)
+ *
+ * @author moyin
+ * @version 1.0.1
+ * @since 2026-01-07
+ * @lastModified 2026-01-07
+ */
+
+/**
+ * 批量操作相关常量
+ */
+export const BATCH_OPERATION = {
+  /** 批量操作最大用户数量限制 */
+  MAX_USER_COUNT: 100,
+  /** 批量操作最小用户数量限制 */
+  MIN_USER_COUNT: 1,
+} as const;
+
+/**
+ * 验证规则相关常量
+ */
+export const VALIDATION = {
+  /** 状态修改原因最大长度 */
+  REASON_MAX_LENGTH: 200,
+} as const;
+
+/**
+ * 默认参数常量
+ */
+export const DEFAULTS = {
+  /** 状态变更历史查询默认数量限制 */
+  STATUS_HISTORY_LIMIT: 10,
+} as const;
+
+/**
+ * 错误代码常量
+ */
+export const ERROR_CODES = {
+  /** 批量操作数量超限错误代码 */
+  BATCH_OPERATION_LIMIT_EXCEEDED: 'BATCH_OPERATION_LIMIT_EXCEEDED',
+} as const;
+
+/**
+ * 业务消息常量
+ */
+export const MESSAGES = {
+  /** 批量操作数量超限错误消息 */
+  BATCH_OPERATION_LIMIT_ERROR: `批量操作数量不能超过${BATCH_OPERATION.MAX_USER_COUNT}个用户`,
+} as const;
+
+/**
+ * 工具函数
+ */
+export const UTILS = {
+  /** 获取当前时间戳 */
+  getCurrentTimestamp: (): string => new Date().toISOString(),
+} as const;
--- a/src/business/user_mgmt/user_mgmt.module.ts
+++ b/src/business/user_mgmt/user_mgmt.module.ts
@@ -0,0 +1,52 @@
+/**
+ * 用户管理业务模块
+ *
+ * 功能描述：
+ * - 整合用户状态管理相关的所有组件
+ * - 提供用户生命周期管理功能
+ * - 支持批量操作和状态统计
+ *
+ * 职责分离：
+ * - 模块配置和依赖管理
+ * - 组件注册和导出控制
+ * - 业务模块边界定义
+ *
+ * 最近修改：
+ * - 2026-01-07: 代码规范优化 - 修正文件命名规范，完善注释规范，更新作者信息 (修改者: moyin)
+ *
+ * @author moyin
+ * @version 1.0.1
+ * @since 2025-12-24
+ * @lastModified 2026-01-07
+ */
+
+import { Module } from '@nestjs/common';
+import { UserStatusController } from './user_status.controller';
+import { UserManagementService } from './user_management.service';
+import { AdminModule } from '../admin/admin.module';
+import { AdminCoreModule } from '../../core/admin_core/admin_core.module';
+
+/**
+ * 用户管理业务模块
+ *
+ * 职责：
+ * - 整合用户状态管理的所有业务组件
+ * - 管理模块间的依赖关系和配置
+ * - 提供统一的用户管理业务入口
+ *
+ * 主要组件：
+ * - UserStatusController - 用户状态管理API控制器
+ * - UserManagementService - 用户管理业务逻辑服务
+ *
+ * 使用场景：
+ * - 管理员进行用户状态管理操作
+ * - 批量用户操作和状态统计
+ * - 用户生命周期管理流程
+ */
+@Module({
+  imports: [AdminModule, AdminCoreModule],
+  controllers: [UserStatusController],
+  providers: [UserManagementService],
+  exports: [UserManagementService],
+})
+export class UserMgmtModule {}
--- a/src/business/user_mgmt/user_status.controller.ts
+++ b/src/business/user_mgmt/user_status.controller.ts
@@ -0,0 +1,243 @@
+/**
+ * 用户状态管理控制器
+ *
+ * 功能描述：
+ * - 管理员管理用户账户状态
+ * - 支持批量状态操作
+ * - 提供状态变更审计日志
+ *
+ * 职责分离：
+ * - HTTP请求处理和参数验证
+ * - API文档生成和接口规范定义
+ * - 业务服务调用和响应格式化
+ *
+ * API端点：
+ * - PUT /admin/users/:id/status - 修改用户状态
+ * - POST /admin/users/batch-status - 批量修改用户状态
+ * - GET /admin/users/status-stats - 获取用户状态统计
+ *
+ * 最近修改：
+ * - 2026-01-07: 代码规范优化 - 修正文件命名规范，完善注释规范，更新作者信息 (修改者: moyin)
+ *
+ * @author moyin
+ * @version 1.0.1
+ * @since 2025-12-24
+ * @lastModified 2026-01-07
+ */
+
+import { Body, Controller, Get, HttpCode, HttpStatus, Param, Put, Post, UseGuards, ValidationPipe, UsePipes, Logger } from '@nestjs/common';
+import { ApiBearerAuth, ApiBody, ApiOperation, ApiParam, ApiResponse, ApiTags } from '@nestjs/swagger';
+import { AdminGuard } from '../admin/admin.guard';
+import { UserManagementService } from './user_management.service';
+import { Throttle, ThrottlePresets } from '../../core/security_core/throttle.decorator';
+import { Timeout, TimeoutPresets } from '../../core/security_core/timeout.decorator';
+import { UserStatusDto, BatchUserStatusDto } from './user_status.dto';
+import { UserStatusResponseDto, BatchUserStatusResponseDto, UserStatusStatsResponseDto } from './user_status_response.dto';
+import { BATCH_OPERATION, UTILS } from './user_mgmt.constants';
+
+/**
+ * 用户状态管理控制器
+ *
+ * 职责：
+ * - 处理用户状态管理相关的HTTP请求
+ * - 提供RESTful API接口和Swagger文档
+ * - 执行请求参数验证和权限控制
+ *
+ * 主要方法：
+ * - updateUserStatus() - 修改单个用户状态
+ * - batchUpdateUserStatus() - 批量修改用户状态
+ * - getUserStatusStats() - 获取用户状态统计
+ *
+ * 使用场景：
+ * - 管理员通过API管理用户状态
+ * - 系统集成和自动化用户管理
+ * - 用户状态监控和统计分析
+ */
+@ApiTags('user_management')
+@Controller('admin/users')
+export class UserStatusController {
+  private readonly logger = new Logger(UserStatusController.name);
+
+  constructor(private readonly userManagementService: UserManagementService) {}
+
+  /**
+   * 修改用户状态
+   *
+   * 业务逻辑：
+   * 1. 验证管理员权限和操作频率限制
+   * 2. 验证用户ID格式和状态参数有效性
+   * 3. 记录状态修改操作的审计日志
+   * 4. 调用业务服务执行状态变更
+   * 5. 返回操作结果和用户最新状态
+   *
+   * @param id 用户ID
+   * @param userStatusDto 状态修改数据
+   * @returns 修改结果
+   * @throws ForbiddenException 管理员权限不足时
+   * @throws NotFoundException 用户不存在时
+   * @throws TooManyRequestsException 操作过于频繁时
+   *
+   * @example
+   * ```typescript
+   * const result = await controller.updateUserStatus('123', {
+   *   status: UserStatus.LOCKED,
+   *   reason: '用户违反社区规定'
+   * });
+   * ```
+   */
+  @ApiBearerAuth('JWT-auth')
+  @ApiOperation({
+    summary: '修改用户状态',
+    description: '管理员修改指定用户的账户状态，支持激活、锁定、禁用等操作'
+  })
+  @ApiParam({ name: 'id', description: '用户ID' })
+  @ApiBody({ type: UserStatusDto })
+  @ApiResponse({
+    status: 200,
+    description: '状态修改成功',
+    type: UserStatusResponseDto
+  })
+  @ApiResponse({
+    status: 403,
+    description: '权限不足'
+  })
+  @ApiResponse({
+    status: 404,
+    description: '用户不存在'
+  })
+  @ApiResponse({
+    status: 429,
+    description: '操作过于频繁'
+  })
+  @UseGuards(AdminGuard)
+  @Throttle(ThrottlePresets.ADMIN_OPERATION)
+  @Timeout(TimeoutPresets.NORMAL)
+  @Put(':id/status')
+  @HttpCode(HttpStatus.OK)
+  @UsePipes(new ValidationPipe({ transform: true }))
+  async updateUserStatus(
+    @Param('id') id: string,
+    @Body() userStatusDto: UserStatusDto
+  ): Promise<UserStatusResponseDto> {
+    this.logger.log('管理员修改用户状态', {
+      operation: 'update_user_status',
+      userId: id,
+      newStatus: userStatusDto.status,
+      reason: userStatusDto.reason,
+      timestamp: UTILS.getCurrentTimestamp()
+    });
+
+    return await this.userManagementService.updateUserStatus(BigInt(id), userStatusDto);
+  }
+
+  /**
+   * 批量修改用户状态
+   *
+   * 业务逻辑：
+   * 1. 验证管理员权限和批量操作频率限制
+   * 2. 验证用户ID列表和状态参数有效性
+   * 3. 检查批量操作数量限制（最多${BATCH_OPERATION.MAX_USER_COUNT}个用户）
+   * 4. 记录批量操作的审计日志
+   * 5. 调用业务服务执行批量状态变更
+   * 6. 返回批量操作结果统计
+   *
+   * @param batchUserStatusDto 批量状态修改数据
+   * @returns 批量修改结果
+   * @throws ForbiddenException 管理员权限不足时
+   * @throws BadRequestException 批量操作数量超限时
+   * @throws TooManyRequestsException 操作过于频繁时
+   *
+   * @example
+   * ```typescript
+   * const result = await controller.batchUpdateUserStatus({
+   *   userIds: ['123', '456', '789'],
+   *   status: UserStatus.LOCKED,
+   *   reason: '批量处理违规用户'
+   * });
+   * ```
+   */
+  @ApiBearerAuth('JWT-auth')
+  @ApiOperation({
+    summary: '批量修改用户状态',
+    description: '管理员批量修改多个用户的账户状态'
+  })
+  @ApiBody({ type: BatchUserStatusDto })
+  @ApiResponse({
+    status: 200,
+    description: '批量修改成功',
+    type: BatchUserStatusResponseDto
+  })
+  @ApiResponse({
+    status: 403,
+    description: '权限不足'
+  })
+  @ApiResponse({
+    status: 429,
+    description: '操作过于频繁'
+  })
+  @UseGuards(AdminGuard)
+  @Throttle(ThrottlePresets.ADMIN_OPERATION)
+  @Timeout(TimeoutPresets.SLOW)
+  @Post('batch-status')
+  @HttpCode(HttpStatus.OK)
+  @UsePipes(new ValidationPipe({ transform: true }))
+  async batchUpdateUserStatus(
+    @Body() batchUserStatusDto: BatchUserStatusDto
+  ): Promise<BatchUserStatusResponseDto> {
+    this.logger.log('管理员批量修改用户状态', {
+      operation: 'batch_update_user_status',
+      userCount: batchUserStatusDto.userIds.length,
+      newStatus: batchUserStatusDto.status,
+      reason: batchUserStatusDto.reason,
+      timestamp: UTILS.getCurrentTimestamp()
+    });
+
+    return await this.userManagementService.batchUpdateUserStatus(batchUserStatusDto);
+  }
+
+  /**
+   * 获取用户状态统计
+   *
+   * 业务逻辑：
+   * 1. 验证管理员权限
+   * 2. 调用业务服务获取状态统计数据
+   * 3. 记录统计查询的审计日志
+   * 4. 返回各种状态的用户数量统计
+   * 5. 提供状态分布分析数据
+   *
+   * @returns 状态统计信息
+   * @throws ForbiddenException 管理员权限不足时
+   * @throws InternalServerErrorException 统计数据获取失败时
+   *
+   * @example
+   * ```typescript
+   * const stats = await controller.getUserStatusStats();
+   * // 返回: { active: 1250, inactive: 45, locked: 12, ... }
+   * ```
+   */
+  @ApiBearerAuth('JWT-auth')
+  @ApiOperation({
+    summary: '获取用户状态统计',
+    description: '获取各种用户状态的数量统计信息'
+  })
+  @ApiResponse({
+    status: 200,
+    description: '获取成功',
+    type: UserStatusStatsResponseDto
+  })
+  @ApiResponse({
+    status: 403,
+    description: '权限不足'
+  })
+  @UseGuards(AdminGuard)
+  @Timeout(TimeoutPresets.DATABASE_QUERY)
+  @Get('status-stats')
+  async getUserStatusStats(): Promise<UserStatusStatsResponseDto> {
+    this.logger.log('管理员获取用户状态统计', {
+      operation: 'get_user_status_stats',
+      timestamp: UTILS.getCurrentTimestamp()
+    });
+
+    return await this.userManagementService.getUserStatusStats();
+  }
+}
--- a/src/business/user_mgmt/user_status.dto.ts
+++ b/src/business/user_mgmt/user_status.dto.ts
@@ -0,0 +1,132 @@
+/**
+ * 用户状态管理 DTO
+ *
+ * 功能描述：
+ * - 定义用户状态管理相关的请求数据结构
+ * - 提供数据验证规则和错误提示
+ * - 确保状态管理操作的数据格式一致性
+ *
+ * 职责分离：
+ * - 请求数据结构定义和类型约束
+ * - 数据验证规则配置和错误消息定义
+ * - Swagger API文档生成支持
+ *
+ * 最近修改：
+ * - 2026-01-07: 代码规范优化 - 修正文件命名规范，完善注释规范，更新作者信息 (修改者: moyin)
+ *
+ * @author moyin
+ * @version 1.0.1
+ * @since 2025-12-24
+ * @lastModified 2026-01-07
+ */
+
+import { IsString, IsNotEmpty, IsEnum, IsOptional, IsArray, ArrayMinSize, ArrayMaxSize } from 'class-validator';
+import { ApiProperty } from '@nestjs/swagger';
+import { UserStatus } from './user_status.enum';
+import { BATCH_OPERATION, VALIDATION } from './user_mgmt.constants';
+
+/**
+ * 用户状态修改请求DTO
+ *
+ * 职责：
+ * - 定义单个用户状态修改的请求数据格式
+ * - 提供状态值和修改原因的验证规则
+ * - 支持Swagger文档自动生成
+ *
+ * 主要字段：
+ * - status - 新的用户状态（必填）
+ * - reason - 状态修改原因（可选）
+ *
+ * 使用场景：
+ * - 管理员修改单个用户状态的API请求
+ * - 用户状态变更操作的数据传输
+ */
+export class UserStatusDto {
+  /**
+   * 新的用户状态
+   */
+  @ApiProperty({
+    description: '用户状态',
+    enum: UserStatus,
+    example: UserStatus.ACTIVE,
+    enumName: 'UserStatus'
+  })
+  @IsEnum(UserStatus, { message: '用户状态必须是有效的枚举值' })
+  @IsNotEmpty({ message: '用户状态不能为空' })
+  status: UserStatus;
+
+  /**
+   * 状态修改原因
+   */
+  @ApiProperty({
+    description: '状态修改原因（可选）',
+    example: '用户违反社区规定',
+    required: false,
+    maxLength: VALIDATION.REASON_MAX_LENGTH
+  })
+  @IsOptional()
+  @IsString({ message: '修改原因必须是字符串' })
+  reason?: string;
+}
+
+/**
+ * 批量用户状态修改请求DTO
+ *
+ * 职责：
+ * - 定义批量用户状态修改的请求数据格式
+ * - 提供用户ID列表和状态值的验证规则
+ * - 限制批量操作的数量范围（${BATCH_OPERATION.MIN_USER_COUNT}-${BATCH_OPERATION.MAX_USER_COUNT}个用户）
+ *
+ * 主要字段：
+ * - userIds - 用户ID列表（必填，${BATCH_OPERATION.MIN_USER_COUNT}-${BATCH_OPERATION.MAX_USER_COUNT}个）
+ * - status - 新的用户状态（必填）
+ * - reason - 批量修改原因（可选）
+ *
+ * 使用场景：
+ * - 管理员批量修改用户状态的API请求
+ * - 系统自动化批量用户管理操作
+ */
+export class BatchUserStatusDto {
+  /**
+   * 用户ID列表
+   */
+  @ApiProperty({
+    description: '用户ID列表',
+    example: ['1', '2', '3'],
+    type: [String],
+    minItems: BATCH_OPERATION.MIN_USER_COUNT,
+    maxItems: BATCH_OPERATION.MAX_USER_COUNT
+  })
+  @IsArray({ message: '用户ID列表必须是数组' })
+  @ArrayMinSize(BATCH_OPERATION.MIN_USER_COUNT, { message: '至少需要选择一个用户' })
+  @ArrayMaxSize(BATCH_OPERATION.MAX_USER_COUNT, { message: `一次最多只能操作${BATCH_OPERATION.MAX_USER_COUNT}个用户` })
+  @IsString({ each: true, message: '用户ID必须是字符串' })
+  @IsNotEmpty({ each: true, message: '用户ID不能为空' })
+  userIds: string[];
+
+  /**
+   * 新的用户状态
+   */
+  @ApiProperty({
+    description: '用户状态',
+    enum: UserStatus,
+    example: UserStatus.LOCKED,
+    enumName: 'UserStatus'
+  })
+  @IsEnum(UserStatus, { message: '用户状态必须是有效的枚举值' })
+  @IsNotEmpty({ message: '用户状态不能为空' })
+  status: UserStatus;
+
+  /**
+   * 状态修改原因
+   */
+  @ApiProperty({
+    description: '批量修改原因（可选）',
+    example: '批量处理违规用户',
+    required: false,
+    maxLength: VALIDATION.REASON_MAX_LENGTH
+  })
+  @IsOptional()
+  @IsString({ message: '修改原因必须是字符串' })
+  reason?: string;
+}
--- a/src/business/user_mgmt/user_status.enum.ts
+++ b/src/business/user_mgmt/user_status.enum.ts
@@ -0,0 +1,31 @@
+/**
+ * 用户状态枚举（Business层兼容性导出）
+ *
+ * 功能描述：
+ * - 重新导出Core层的用户状态枚举
+ * - 保持向后兼容性
+ * - 符合架构分层原则
+ *
+ * 职责分离：
+ * - 提供Business层对Core层用户状态的访问接口
+ * - 维护现有代码的兼容性
+ * - 遵循依赖倒置原则
+ *
+ * 最近修改：
+ * - 2026-01-07: 架构优化 - 改为重新导出Core层枚举，符合架构分层原则 (修改者: moyin)
+ *
+ * @author moyin
+ * @version 1.0.2
+ * @since 2025-12-24
+ * @lastModified 2026-01-07
+ */
+
+// 重新导出Core层的用户状态枚举和相关函数
+export {
+  UserStatus,
+  getUserStatusDescription,
+  canUserLogin,
+  getUserStatusErrorMessage,
+  getAllUserStatuses,
+  isValidUserStatus
+} from '../../core/db/users/user_status.enum';
--- a/src/business/user_mgmt/user_status_response.dto.ts
+++ b/src/business/user_mgmt/user_status_response.dto.ts
@@ -0,0 +1,303 @@
+/**
+ * 用户状态管理响应 DTO
+ *
+ * 功能描述：
+ * - 定义用户状态管理相关的响应数据结构
+ * - 提供Swagger文档生成支持
+ * - 确保状态管理API响应的数据格式一致性
+ *
+ * 职责分离：
+ * - 响应数据结构定义和类型约束
+ * - API响应格式标准化和文档生成
+ * - 错误信息和成功结果的统一封装
+ *
+ * 最近修改：
+ * - 2026-01-07: 代码规范优化 - 修正文件命名规范，完善注释规范，更新作者信息 (修改者: moyin)
+ *
+ * @author moyin
+ * @version 1.0.1
+ * @since 2025-12-24
+ * @lastModified 2026-01-07
+ */
+
+import { ApiProperty } from '@nestjs/swagger';
+import { UserStatus } from './user_status.enum';
+
+/**
+ * 用户状态信息DTO
+ */
+export class UserStatusInfoDto {
+  @ApiProperty({
+    description: '用户ID',
+    example: '1'
+  })
+  id: string;
+
+  @ApiProperty({
+    description: '用户名',
+    example: 'testuser'
+  })
+  username: string;
+
+  @ApiProperty({
+    description: '用户昵称',
+    example: '测试用户'
+  })
+  nickname: string;
+
+  @ApiProperty({
+    description: '用户状态',
+    enum: UserStatus,
+    example: UserStatus.ACTIVE
+  })
+  status: UserStatus;
+
+  @ApiProperty({
+    description: '状态描述',
+    example: '正常'
+  })
+  status_description: string;
+
+  @ApiProperty({
+    description: '状态修改时间',
+    example: '2025-12-24T10:00:00.000Z'
+  })
+  updated_at: Date;
+}
+
+/**
+ * 用户状态修改响应数据DTO
+ */
+export class UserStatusDataDto {
+  @ApiProperty({
+    description: '用户信息',
+    type: UserStatusInfoDto
+  })
+  user: UserStatusInfoDto;
+
+  @ApiProperty({
+    description: '修改原因',
+    example: '用户违反社区规定',
+    required: false
+  })
+  reason?: string;
+}
+
+/**
+ * 用户状态修改响应DTO
+ */
+export class UserStatusResponseDto {
+  @ApiProperty({
+    description: '请求是否成功',
+    example: true
+  })
+  success: boolean;
+
+  @ApiProperty({
+    description: '响应数据',
+    type: UserStatusDataDto,
+    required: false
+  })
+  data?: UserStatusDataDto;
+
+  @ApiProperty({
+    description: '响应消息',
+    example: '用户状态修改成功'
+  })
+  message: string;
+
+  @ApiProperty({
+    description: '错误代码',
+    example: 'USER_STATUS_UPDATE_FAILED',
+    required: false
+  })
+  error_code?: string;
+}
+
+/**
+ * 批量操作结果DTO
+ */
+export class BatchOperationResultDto {
+  @ApiProperty({
+    description: '成功处理的用户列表',
+    type: [UserStatusInfoDto]
+  })
+  success_users: UserStatusInfoDto[];
+
+  @ApiProperty({
+    description: '处理失败的用户列表',
+    type: [Object],
+    example: [
+      {
+        user_id: '999',
+        error: '用户不存在'
+      }
+    ]
+  })
+  failed_users: Array<{
+    user_id: string;
+    error: string;
+  }>;
+
+  @ApiProperty({
+    description: '成功处理数量',
+    example: 5
+  })
+  success_count: number;
+
+  @ApiProperty({
+    description: '失败处理数量',
+    example: 1
+  })
+  failed_count: number;
+
+  @ApiProperty({
+    description: '总处理数量',
+    example: 6
+  })
+  total_count: number;
+}
+
+/**
+ * 批量用户状态修改响应数据DTO
+ */
+export class BatchUserStatusDataDto {
+  @ApiProperty({
+    description: '批量操作结果',
+    type: BatchOperationResultDto
+  })
+  result: BatchOperationResultDto;
+
+  @ApiProperty({
+    description: '修改原因',
+    example: '批量处理违规用户',
+    required: false
+  })
+  reason?: string;
+}
+
+/**
+ * 批量用户状态修改响应DTO
+ */
+export class BatchUserStatusResponseDto {
+  @ApiProperty({
+    description: '请求是否成功',
+    example: true
+  })
+  success: boolean;
+
+  @ApiProperty({
+    description: '响应数据',
+    type: BatchUserStatusDataDto,
+    required: false
+  })
+  data?: BatchUserStatusDataDto;
+
+  @ApiProperty({
+    description: '响应消息',
+    example: '批量用户状态修改完成'
+  })
+  message: string;
+
+  @ApiProperty({
+    description: '错误代码',
+    example: 'BATCH_USER_STATUS_UPDATE_FAILED',
+    required: false
+  })
+  error_code?: string;
+}
+
+/**
+ * 用户状态统计DTO
+ */
+export class UserStatusStatsDto {
+  @ApiProperty({
+    description: '正常用户数量',
+    example: 1250
+  })
+  active: number;
+
+  @ApiProperty({
+    description: '未激活用户数量',
+    example: 45
+  })
+  inactive: number;
+
+  @ApiProperty({
+    description: '锁定用户数量',
+    example: 12
+  })
+  locked: number;
+
+  @ApiProperty({
+    description: '禁用用户数量',
+    example: 8
+  })
+  banned: number;
+
+  @ApiProperty({
+    description: '已删除用户数量',
+    example: 3
+  })
+  deleted: number;
+
+  @ApiProperty({
+    description: '待审核用户数量',
+    example: 15
+  })
+  pending: number;
+
+  @ApiProperty({
+    description: '总用户数量',
+    example: 1333
+  })
+  total: number;
+}
+
+/**
+ * 用户状态统计响应数据DTO
+ */
+export class UserStatusStatsDataDto {
+  @ApiProperty({
+    description: '用户状态统计',
+    type: UserStatusStatsDto
+  })
+  stats: UserStatusStatsDto;
+
+  @ApiProperty({
+    description: '统计时间',
+    example: '2025-12-24T10:00:00.000Z'
+  })
+  timestamp: string;
+}
+
+/**
+ * 用户状态统计响应DTO
+ */
+export class UserStatusStatsResponseDto {
+  @ApiProperty({
+    description: '请求是否成功',
+    example: true
+  })
+  success: boolean;
+
+  @ApiProperty({
+    description: '响应数据',
+    type: UserStatusStatsDataDto,
+    required: false
+  })
+  data?: UserStatusStatsDataDto;
+
+  @ApiProperty({
+    description: '响应消息',
+    example: '用户状态统计获取成功'
+  })
+  message: string;
+
+  @ApiProperty({
+    description: '错误代码',
+    example: 'USER_STATUS_STATS_FAILED',
+    required: false
+  })
+  error_code?: string;
+}