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/config/zulip/README.md
+++ b/config/zulip/README.md
@@ -0,0 +1,149 @@
+# Zulip配置目录
+
+本目录包含Zulip集成系统的配置文件。
+
+## 文件说明
+
+### map-config.json
+
+地图映射配置文件，定义游戏地图到Zulip Stream/Topic的映射关系。
+
+#### 配置结构
+
+```json
+{
+  "version": "1.0.0",
+  "lastModified": "2025-12-25T00:00:00.000Z",
+  "description": "配置描述",
+  "maps": [
+    {
+      "mapId": "地图唯一标识",
+      "mapName": "地图显示名称",
+      "zulipStream": "对应的Zulip Stream名称",
+      "interactionObjects": [
+        {
+          "objectId": "交互对象唯一标识",
+          "objectName": "交互对象显示名称",
+          "zulipTopic": "对应的Zulip Topic名称",
+          "position": { "x": 100, "y": 150 }
+        }
+      ]
+    }
+  ]
+}
+```
+
+#### 字段说明
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| version | string | 否 | 配置版本号 |
+| lastModified | string | 否 | 最后修改时间（ISO 8601格式） |
+| description | string | 否 | 配置描述 |
+| maps | array | 是 | 地图配置数组 |
+
+##### 地图配置 (MapConfig)
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| mapId | string | 是 | 地图唯一标识，如 "novice_village" |
+| mapName | string | 是 | 地图显示名称，如 "新手村" |
+| zulipStream | string | 是 | 对应的Zulip Stream名称 |
+| interactionObjects | array | 是 | 交互对象配置数组 |
+
+##### 交互对象配置 (InteractionObject)
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| objectId | string | 是 | 交互对象唯一标识 |
+| objectName | string | 是 | 交互对象显示名称 |
+| zulipTopic | string | 是 | 对应的Zulip Topic名称 |
+| position | object | 是 | 对象在地图中的位置 |
+| position.x | number | 是 | X坐标 |
+| position.y | number | 是 | Y坐标 |
+
+## 配置示例
+
+### 新手村配置
+
+```json
+{
+  "mapId": "novice_village",
+  "mapName": "新手村",
+  "zulipStream": "Novice Village",
+  "interactionObjects": [
+    {
+      "objectId": "notice_board",
+      "objectName": "公告板",
+      "zulipTopic": "Notice Board",
+      "position": { "x": 100, "y": 150 }
+    },
+    {
+      "objectId": "village_well",
+      "objectName": "村井",
+      "zulipTopic": "Village Well",
+      "position": { "x": 200, "y": 200 }
+    }
+  ]
+}
+```
+
+### 酒馆配置
+
+```json
+{
+  "mapId": "tavern",
+  "mapName": "酒馆",
+  "zulipStream": "Tavern",
+  "interactionObjects": [
+    {
+      "objectId": "bar_counter",
+      "objectName": "吧台",
+      "zulipTopic": "Bar Counter",
+      "position": { "x": 150, "y": 100 }
+    },
+    {
+      "objectId": "fireplace",
+      "objectName": "壁炉",
+      "zulipTopic": "Fireplace Chat",
+      "position": { "x": 300, "y": 200 }
+    }
+  ]
+}
+```
+
+## 热重载
+
+配置文件支持热重载，修改后无需重启服务即可生效。
+
+### 启用配置监听
+
+在代码中调用：
+
+```typescript
+configManagerService.enableConfigWatcher();
+```
+
+### 手动重载配置
+
+```typescript
+await configManagerService.reloadConfig();
+```
+
+## 验证配置
+
+系统启动时会自动验证配置文件的有效性。验证规则包括：
+
+1. mapId必须是非空字符串
+2. mapName必须是非空字符串
+3. zulipStream必须是非空字符串
+4. interactionObjects必须是数组
+5. 每个交互对象必须有有效的objectId、objectName、zulipTopic和position
+6. position.x和position.y必须是有效数字
+
+## 注意事项
+
+1. **Stream名称**: Zulip Stream名称区分大小写，请确保与Zulip服务器上的Stream名称完全匹配
+2. **Topic名称**: Topic名称同样区分大小写
+3. **位置坐标**: 位置坐标用于空间过滤，确保与游戏客户端的坐标系统一致
+4. **唯一性**: mapId和objectId在各自范围内必须唯一