refactor：项目架构重构和命名规范化

- 统一文件命名为snake_case格式（kebab-case snake_case） - 重构zulip模块为zulip_core，明确Core层职责 - 重构user-mgmt模块为user_mgmt，统一命名规范 - 调整模块依赖关系，优化架构分层 - 删除过时的文件和目录结构 - 更新相关文档和配置文件本次重构涉及大量文件重命名和模块重组，旨在建立更清晰的项目架构和统一的命名规范。
2026-01-08 00:14:14 +08:00
parent 4fa4bd1a70
commit bb796a2469
178 changed files with 24767 additions and 3484 deletions
--- 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: '状态变更历史获取成功（当前返回空数据，待实现完整功能）'
+    };
+  }
+}