# SessionCore 会话核心模块

SessionCore 是为会话管理业务提供技术支撑的核心模块，定义了会话管理的抽象接口，实现 Business 层模块间的解耦。

## 对外提供的接口

### ISessionQueryService（会话查询服务接口）

提供只读的会话查询能力，用于跨模块查询会话信息。

#### getSession(socketId: string): Promise<IGameSession | null>
获取指定 WebSocket 连接的会话信息，不存在时返回 null。

#### getSocketsInMap(mapId: string): Promise<string[]>
获取指定地图中所有活跃的 Socket ID 列表。

### ISessionManagerService（会话管理服务接口）

提供完整的会话管理能力，包括创建、更新、删除操作，继承自 ISessionQueryService。

#### createSession(socketId, userId, zulipQueueId, username?, initialMap?, initialPosition?): Promise<IGameSession>
创建新的游戏会话，关联 WebSocket 连接、用户信息和 Zulip 事件队列。

#### injectContext(socketId: string, mapId?: string): Promise<IContextInfo>
根据玩家位置确定 Zulip Stream 和 Topic，实现上下文注入。

#### updatePlayerPosition(socketId: string, mapId: string, x: number, y: number): Promise<boolean>
更新玩家在地图中的位置坐标。

#### destroySession(socketId: string): Promise<boolean>
销毁指定的会话，清理相关资源。

#### cleanupExpiredSessions(timeoutMinutes?: number): Promise<{ cleanedCount: number; zulipQueueIds: string[] }>
清理超时的过期会话，返回清理数量和对应的 Zulip 队列 ID 列表。

### SessionCoreModule（会话核心模块）

#### forFeature(options: SessionCoreModuleOptions): DynamicModule
注册会话服务提供者，支持动态配置会话查询和管理服务的实现。

## 使用的项目内部依赖

### IPosition (本模块)
位置信息接口，定义 x 和 y 坐标。

### IGameSession (本模块)
游戏会话接口，包含 socketId、userId、username、zulipQueueId、currentMap、position、lastActivity、createdAt 等字段。

### IContextInfo (本模块)
上下文信息接口，包含 stream 和可选的 topic 字段。

### SESSION_QUERY_SERVICE (本模块)
会话查询服务的依赖注入 Token。

### SESSION_MANAGER_SERVICE (本模块)
会话管理服务的依赖注入 Token。

## 核心特性

### 接口抽象设计
- 定义抽象接口，不包含具体实现
- 实现由 Business 层的 ChatModule 提供
- 支持依赖注入和模块解耦

### 动态模块配置
- 使用 forFeature 方法支持灵活配置
- 可单独注册查询服务或管理服务
- 支持同时注册多个服务提供者

### 分离查询和管理职责
- ISessionQueryService 提供只读查询能力
- ISessionManagerService 提供完整管理能力
- 清晰的职责分离，便于权限控制

### 跨模块会话查询
- 其他模块可通过 SESSION_QUERY_SERVICE 查询会话信息
- 不需要直接依赖 Business 层实现
- 实现模块间的松耦合

## 潜在风险

### 接口实现缺失风险
- Core 层只定义接口，不提供实现
- 如果 Business 层未正确注册实现，会导致运行时错误
- 缓解措施：在模块导入时验证服务提供者配置

### 依赖注入配置错误风险
- forFeature 配置不当可能导致服务无法注入
- Token 名称错误会导致依赖解析失败
- 缓解措施：使用 TypeScript 类型检查和单元测试验证

### 接口变更影响范围风险
- 接口定义变更会影响所有实现和使用方
- 可能导致多个模块需要同步修改
- 缓解措施：保持接口稳定，使用版本化管理

### 循环依赖风险
- 如果 Business 层实现反向依赖 Core 层其他模块
- 可能形成循环依赖导致模块加载失败
- 缓解措施：严格遵守分层架构，Core 层不依赖 Business 层
