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/core/zulip_core/README.md
+++ b/src/core/zulip_core/README.md
@@ -0,0 +1,360 @@
+# Zulip Core 聊天集成核心模块
+
+Zulip Core 是应用的核心聊天集成模块，提供完整的Zulip聊天服务技术实现，为Business层的聊天功能提供底层技术支撑。该模块专注于Zulip API集成、客户端管理、消息处理和配置管理等核心技术能力。
+
+## 客户端管理功能
+
+### createClient()
+创建并验证Zulip客户端实例，支持API Key验证和连接测试。
+
+### createUserClient()
+为指定用户创建专用的Zulip客户端，包含事件队列注册和连接池管理。
+
+### getUserClient()
+获取用户的现有Zulip客户端实例，支持连接状态检查和自动重连。
+
+### destroyClient()
+安全销毁Zulip客户端，清理事件队列和释放连接资源。
+
+### destroyUserClient()
+销毁用户的专用客户端，包含完整的资源清理和状态重置。
+
+### validateApiKey()
+验证Zulip API Key的有效性，确保客户端连接的可靠性。
+
+## 消息处理功能
+
+### sendMessage()
+发送消息到指定的Zulip Stream和Topic，支持消息格式化和错误处理。
+
+### getEvents()
+获取Zulip事件队列中的新事件，支持长轮询和事件过滤。
+
+### startEventPolling()
+启动用户的事件轮询机制，实现实时消息接收和处理。
+
+### stopEventPolling()
+停止用户的事件轮询，清理轮询定时器和相关资源。
+
+## 事件队列管理功能
+
+### registerQueue()
+注册Zulip事件队列，配置事件类型和接收参数。
+
+### registerEventQueue()
+为用户注册专用事件队列，支持个性化事件订阅。
+
+### deregisterQueue()
+注销Zulip事件队列，清理服务器端队列资源。
+
+### deregisterEventQueue()
+注销用户的专用事件队列，确保资源完全释放。
+
+## Stream管理功能
+
+### initializeStreams()
+系统启动时自动检查并创建所有配置的Zulip Streams，确保消息路由正常。
+
+### reinitializeStreams()
+手动重新初始化Streams，用于配置更新后的重新同步。
+
+### isInitializationComplete()
+检查Stream初始化是否完成，用于系统状态监控。
+
+## 账号管理功能
+
+### initializeAdminClient()
+初始化Zulip管理员客户端，用于用户账号创建和管理操作。
+
+### createZulipAccount()
+自动创建Zulip用户账号，包含邮箱验证和密码生成。
+
+### generateApiKeyForUser()
+为用户生成Zulip API Key，支持安全存储和加密处理。
+
+### validateZulipAccount()
+验证Zulip账号的有效性和状态，确保账号可正常使用。
+
+### linkGameAccount()
+建立游戏账号与Zulip账号的关联映射，支持跨平台用户识别。
+
+### unlinkGameAccount()
+解除游戏账号与Zulip账号的关联，清理映射关系。
+
+### getAccountLink()
+获取指定游戏账号的Zulip关联信息，用于用户身份验证。
+
+### getAllAccountLinks()
+获取所有活跃的账号关联信息，用于系统管理和监控。
+
+## 配置管理功能
+
+### getAllMapConfigs()
+获取所有地图配置信息，包含Stream映射和交互对象配置。
+
+### getZulipConfig()
+获取Zulip服务器配置，包含连接参数和安全设置。
+
+### getMapConfigByStream()
+根据Stream名称获取对应的地图配置信息。
+
+### validateConfig()
+验证配置文件的完整性和正确性，确保系统正常运行。
+
+## 安全管理功能
+
+### encryptApiKey()
+加密存储用户的API Key，确保敏感信息安全。
+
+### decryptApiKey()
+解密用户的API Key，用于客户端连接认证。
+
+### rotateApiKey()
+轮换用户的API Key，提升账号安全性。
+
+### validateSecurityLevel()
+评估API Key的安全等级，提供安全建议。
+
+## 监控统计功能
+
+### getPoolStats()
+获取客户端连接池的统计信息，包含活跃连接数和资源使用情况。
+
+### cleanupIdleClients()
+清理长时间未活动的客户端连接，释放系统资源。
+
+### getSystemHealth()
+获取Zulip集成系统的健康状态，用于运维监控。
+
+### getPerformanceMetrics()
+获取系统性能指标，包含响应时间和吞吐量统计。
+
+## 使用的项目内部依赖
+
+### RedisModule (来自 ../redis/redis.module)
+用于API Key缓存和会话状态存储，提供高性能的数据缓存能力。
+
+### AppLoggerService (来自 ../../utils/logger/logger.service)
+提供结构化日志记录功能，支持操作追踪和错误监控。
+
+### ZulipAPI (来自 ../interfaces/zulip.interfaces)
+定义Zulip API的接口规范，确保类型安全和API一致性。
+
+### ZulipClientConfig (来自 ../interfaces/zulip_core.interfaces)
+定义客户端配置接口，规范连接参数和认证信息。
+
+### IZulipConfigService (来自 ../interfaces/zulip_core.interfaces)
+定义配置服务接口，支持配置的动态加载和热更新。
+
+### IRedisService (来自 ../../../core/redis/redis.interface)
+Redis服务接口，用于缓存和会话管理的底层技术实现。
+
+### ConfigManagerService (本模块)
+配置管理服务，负责加载和验证Zulip相关配置文件。
+
+### ZulipClientService (本模块)
+Zulip客户端核心服务，提供基础的API调用和连接管理功能。
+
+### ZulipClientPoolService (本模块)
+客户端连接池服务，管理多用户的Zulip客户端实例和资源分配。
+
+### ApiKeySecurityService (本模块)
+API Key安全管理服务，提供加密存储和安全验证功能。
+
+### ErrorHandlerService (本模块)
+错误处理服务，提供统一的异常处理和重试机制。
+
+### MonitoringService (本模块)
+监控服务，收集系统性能指标和健康状态信息。
+
+### StreamInitializerService (本模块)
+Stream初始化服务，确保Zulip Streams的自动创建和配置同步。
+
+### ZulipAccountService (本模块)
+Zulip账号管理服务，处理用户账号的创建、验证和关联功能。
+
+## 核心特性
+
+### 高可用连接管理
+- 自动重连机制：网络中断时自动重新建立连接
+- 连接池管理：高效管理多用户并发连接，避免资源浪费
+- 健康检查：定期检查连接状态，及时发现和处理异常
+- 负载均衡：智能分配连接资源，确保系统稳定性
+
+### 实时消息处理
+- 事件队列管理：为每个用户维护独立的事件队列
+- 长轮询支持：高效的实时消息接收机制
+- 消息过滤：支持按类型和来源过滤事件
+- 批量处理：优化消息处理性能，减少API调用次数
+
+### 安全认证体系
+- API Key加密存储：使用AES-256加密保护敏感信息
+- 密钥轮换机制：定期更新API Key，提升安全性
+- 访问控制：基于用户权限的API访问限制
+- 安全审计：记录所有安全相关操作，支持合规要求
+
+### 配置热更新
+- 动态配置加载：支持运行时配置更新，无需重启服务
+- 配置验证：自动验证配置文件的完整性和正确性
+- 版本管理：支持配置版本控制和回滚机制
+- 环境隔离：支持多环境配置管理
+
+### 智能错误处理
+- 指数退避重试：智能的重试策略，避免系统过载
+- 错误分类：自动识别错误类型，采用不同的处理策略
+- 降级机制：在系统异常时提供基础功能保障
+- 错误恢复：自动从临时故障中恢复，提升系统可用性
+
+### 性能监控优化
+- 实时性能指标：监控响应时间、吞吐量等关键指标
+- 资源使用统计：跟踪内存、连接数等资源使用情况
+- 性能预警：在性能指标异常时及时告警
+- 自动优化：根据使用模式自动调整系统参数
+
+## 潜在风险
+
+### 网络连接风险
+- Zulip服务器不可用时会导致所有聊天功能失效
+- 网络延迟或不稳定可能影响实时消息的及时性
+- 建议配置多个Zulip服务器实例，实现高可用部署
+- 建议实施网络监控和自动故障转移机制
+
+### API限制风险
+- Zulip API有频率限制，高并发时可能触发限流
+- 大量用户同时在线时可能超出连接数限制
+- 建议实施请求队列和限流机制，避免API调用过频
+- 建议与Zulip管理员协调，适当提升API限制配额
+
+### 内存泄漏风险
+- 长时间运行的事件轮询可能导致内存累积
+- 未正确清理的客户端连接会占用系统资源
+- 建议定期执行内存清理和连接池维护
+- 建议设置合理的连接超时和自动清理机制
+
+### 配置同步风险
+- 配置文件更新时可能出现不一致状态
+- 多实例部署时配置同步可能存在延迟
+- 建议使用配置中心统一管理配置信息
+- 建议实施配置变更的原子性操作和回滚机制
+
+### 安全密钥风险
+- API Key泄露可能导致未授权访问
+- 加密密钥丢失会导致已存储的API Key无法解密
+- 建议定期轮换API Key和加密密钥
+- 建议实施密钥备份和恢复机制
+
+### 依赖服务风险
+- Redis服务不可用会影响缓存和会话功能
+- 日志服务异常可能影响问题排查和监控
+- 建议为关键依赖服务配置备用方案
+- 建议实施服务健康检查和自动恢复机制
+
+### 数据一致性风险
+- 分布式环境下可能出现数据不一致问题
+- 并发操作可能导致状态冲突和数据竞争
+- 建议使用分布式锁保证关键操作的原子性
+- 建议实施数据一致性检查和修复机制
+
+## 使用示例
+
+### 基本服务使用
+```typescript
+@Injectable()
+export class ZulipIntegrationService {
+  constructor(
+    @Inject('IZulipClientPoolService')
+    private readonly clientPool: IZulipClientPoolService,
+    @Inject('IZulipConfigService')
+    private readonly configService: IZulipConfigService
+  ) {}
+
+  async initializeUserClient(userId: string, apiKey: string) {
+    // 创建用户客户端
+    const client = await this.clientPool.createUserClient(userId, {
+      username: `user_${userId}`,
+      apiKey: apiKey,
+      realm: 'https://your-zulip.zulipchat.com'
+    });
+    
+    return client;
+  }
+
+  async sendGameMessage(userId: string, mapId: string, content: string) {
+    // 获取地图配置
+    const config = await this.configService.getMapConfigByStream(mapId);
+    
+    // 发送消息
+    const result = await this.clientPool.sendMessage(userId, {
+      type: 'stream',
+      to: config.streamName,
+      topic: config.defaultTopic,
+      content: content
+    });
+    
+    return result;
+  }
+}
+```
+
+### 客户端池管理
+```typescript
+// 创建用户客户端
+const clientInstance = await zulipClientPoolService.createUserClient('user123', {
+  username: 'game_user_123',
+  apiKey: 'encrypted_api_key',
+  realm: 'https://game.zulipchat.com'
+});
+
+// 注册事件队列
+const queueResult = await zulipClientPoolService.registerEventQueue('user123', {
+  eventTypes: ['message', 'presence'],
+  allPublicStreams: true
+});
+
+// 发送消息
+const messageResult = await zulipClientPoolService.sendMessage('user123', {
+  type: 'stream',
+  to: 'game-chat',
+  topic: 'whale_port',
+  content: '玩家进入了鲸鱼港'
+});
+
+// 清理客户端
+await zulipClientPoolService.destroyUserClient('user123');
+```
+
+### 配置管理使用
+```typescript
+// 获取所有地图配置
+const mapConfigs = await configManagerService.getAllMapConfigs();
+
+// 获取特定地图配置
+const whalePortConfig = await configManagerService.getMapConfigByStream('whale_port');
+
+// 验证配置
+const isValid = await configManagerService.validateConfig();
+
+// 获取Zulip服务器配置
+const zulipConfig = await configManagerService.getZulipConfig();
+```
+
+### 安全服务使用
+```typescript
+// 加密API Key
+const encryptedKey = await apiKeySecurityService.encryptApiKey('raw_api_key');
+
+// 解密API Key
+const decryptedKey = await apiKeySecurityService.decryptApiKey(encryptedKey);
+
+// 验证API Key
+const isValid = await apiKeySecurityService.validateApiKey('api_key');
+
+// 轮换API Key
+const newKey = await apiKeySecurityService.rotateApiKey('user123');
+```
+
+## 版本信息
+- **版本**: 1.1.1
+- **作者**: moyin
+- **创建时间**: 2025-12-25
+- **最后修改**: 2026-01-07