feat(zulip): 添加全面的 Zulip 集成系统

* **新增 Zulip 模块**：包含完整的集成服务，涵盖客户端池（client pool）、会话管理及事件处理。 * **新增 WebSocket 网关**：用于处理 Zulip 的实时事件监听与双向通信。 * **新增安全服务**：支持 API 密钥加密存储及凭据的安全管理。 * **新增配置管理服务**：支持配置热加载（hot-reload），实现动态配置更新。 * **新增错误处理与监控服务**：提升系统的可靠性与可观测性。 * **新增消息过滤服务**：用于内容校验及速率限制（流控）。 * **新增流初始化与会话清理服务**：优化资源管理与回收。 * **完善测试覆盖**：包含单元测试及端到端（e2e）集成测试。 * **完善详细文档**：包括 API 参考手册、配置指南及集成概述。 * **新增地图配置系统**：实现游戏地点与 Zulip Stream（频道）及 Topic（话题）的逻辑映射。 * **新增环境变量配置**：涵盖 Zulip 服务器地址、身份验证及监控相关设置。 * **更新 App 模块**：注册并启用新的 Zulip 集成模块。 * **更新 Redis 接口**：以支持增强型的会话管理功能。 * **实现 WebSocket 协议支持**：确保与 Zulip 之间的实时双向通信。
2025-12-25 22:22:30 +08:00
parent f6fa1ca1e3
commit 55cfda0532
46 changed files with 21488 additions and 2 deletions
--- a/src/business/zulip/zulip.module.ts
+++ b/src/business/zulip/zulip.module.ts
@@ -0,0 +1,122 @@
+/**
+ * Zulip集成业务模块
+ * 
+ * 功能描述：
+ * - 整合Zulip集成相关的控制器、服务和依赖
+ * - 提供完整的Zulip集成功能模块
+ * - 实现游戏与Zulip的无缝通信桥梁
+ * - 支持WebSocket网关、会话管理、消息过滤等核心功能
+ * - 启动时自动检查并创建所有地图对应的Zulip Streams
+ * 
+ * 核心服务：
+ * - ZulipService: 主协调服务，处理登录、消息发送等核心业务
+ * - ZulipWebSocketGateway: WebSocket统一网关，处理客户端连接
+ * - ZulipClientPoolService: Zulip客户端池管理
+ * - SessionManagerService: 会话状态管理
+ * - MessageFilterService: 消息过滤和安全控制
+ * - ConfigManagerService: 配置管理和热重载
+ * - StreamInitializerService: Stream初始化和自动创建
+ * - ErrorHandlerService: 错误处理和服务降级
+ * - MonitoringService: 系统监控和告警
+ * - ApiKeySecurityService: API Key安全存储
+ * 
+ * 依赖模块：
+ * - LoginModule: 用户认证和会话管理
+ * - RedisModule: 会话状态缓存
+ * - LoggerModule: 日志记录服务
+ * 
+ * 使用场景：
+ * - 游戏客户端通过WebSocket连接进行实时聊天
+ * - 游戏内消息与Zulip社群的双向同步
+ * - 基于位置的聊天上下文管理
+ * - 系统启动时自动初始化所有地图对应的Streams
+ * 
+ * @author 开发团队
+ * @version 1.0.0
+ * @since 2025-12-25
+ */
+
+import { Module } from '@nestjs/common';
+import { ZulipWebSocketGateway } from './zulip-websocket.gateway';
+import { ZulipService } from './zulip.service';
+import { ZulipClientService } from './services/zulip-client.service';
+import { ZulipClientPoolService } from './services/zulip-client-pool.service';
+import { SessionManagerService } from './services/session-manager.service';
+import { SessionCleanupService } from './services/session-cleanup.service';
+import { MessageFilterService } from './services/message-filter.service';
+import { ZulipEventProcessorService } from './services/zulip-event-processor.service';
+import { ConfigManagerService } from './services/config-manager.service';
+import { ErrorHandlerService } from './services/error-handler.service';
+import { MonitoringService } from './services/monitoring.service';
+import { ApiKeySecurityService } from './services/api-key-security.service';
+import { StreamInitializerService } from './services/stream-initializer.service';
+import { RedisModule } from '../../core/redis/redis.module';
+import { LoggerModule } from '../../core/utils/logger/logger.module';
+import { LoginModule } from '../login/login.module';
+
+@Module({
+  imports: [
+    // Redis模块 - 提供会话状态缓存和数据存储
+    RedisModule,
+    // 日志模块 - 提供统一的日志记录服务
+    LoggerModule,
+    // 登录模块 - 提供用户认证和Token验证
+    LoginModule,
+  ],
+  providers: [
+    // 主协调服务 - 整合各子服务，提供统一业务接口
+    ZulipService,
+    // Zulip客户端服务 - 封装Zulip REST API调用
+    ZulipClientService,
+    // Zulip客户端池服务 - 管理用户专用Zulip客户端实例
+    ZulipClientPoolService,
+    // 会话管理服务 - 维护Socket_ID与Zulip_Queue_ID的映射关系
+    SessionManagerService,
+    // 会话清理服务 - 定时清理过期会话
+    SessionCleanupService,
+    // 消息过滤服务 - 敏感词过滤、频率限制、权限验证
+    MessageFilterService,
+    // Zulip事件处理服务 - 处理Zulip事件队列消息
+    ZulipEventProcessorService,
+    // 配置管理服务 - 地图映射配置和系统配置管理
+    ConfigManagerService,
+    // Stream初始化服务 - 启动时检查并创建所有地图对应的Streams
+    StreamInitializerService,
+    // 错误处理服务 - 错误处理、重试机制、服务降级
+    ErrorHandlerService,
+    // 监控服务 - 系统监控、健康检查、告警
+    MonitoringService,
+    // API Key安全服务 - API Key加密存储和安全日志
+    ApiKeySecurityService,
+    // WebSocket网关 - 处理游戏客户端WebSocket连接
+    ZulipWebSocketGateway,
+  ],
+  controllers: [],
+  exports: [
+    // 导出主服务供其他模块使用
+    ZulipService,
+    // 导出Zulip客户端服务
+    ZulipClientService,
+    // 导出客户端池服务
+    ZulipClientPoolService,
+    // 导出会话管理服务
+    SessionManagerService,
+    // 导出会话清理服务
+    SessionCleanupService,
+    // 导出消息过滤服务
+    MessageFilterService,
+    // 导出配置管理服务
+    ConfigManagerService,
+    // 导出Stream初始化服务
+    StreamInitializerService,
+    // 导出错误处理服务
+    ErrorHandlerService,
+    // 导出监控服务
+    MonitoringService,
+    // 导出API Key安全服务
+    ApiKeySecurityService,
+    // 导出WebSocket网关
+    ZulipWebSocketGateway,
+  ],
+})
+export class ZulipModule {}