# Location Broadcast Core 位置广播核心模块

Location Broadcast Core 是位置广播系统的核心技术实现模块，专门为位置广播业务提供技术支撑。该模块负责管理用户会话、位置数据缓存、数据持久化等核心技术功能，确保位置广播系统的高性能和可靠性。

## 对外提供的接口

### addUserToSession(sessionId: string, userId: string, socketId: string): Promise<void>
添加用户到会话，建立用户与WebSocket连接的映射关系。

### removeUserFromSession(sessionId: string, userId: string): Promise<void>
从会话中移除用户，自动清理相关数据和空会话。

### getSessionUsers(sessionId: string): Promise<SessionUser[]>
获取会话中的用户列表，包含用户ID和Socket连接信息。

### setUserPosition(userId: string, position: Position): Promise<void>
设置用户位置到Redis缓存，支持地图切换和位置更新。

### getUserPosition(userId: string): Promise<Position | null>
从Redis获取用户当前位置，返回完整的位置信息。

### getSessionPositions(sessionId: string): Promise<Position[]>
获取会话中所有用户的位置信息，用于批量位置查询。

### getMapPositions(mapId: string): Promise<Position[]>
获取指定地图中所有用户的位置信息，支持地图级别的位置管理。

### cleanupUserData(userId: string): Promise<void>
清理用户相关的所有数据，包括会话、位置、Socket映射等。

### cleanupEmptySession(sessionId: string): Promise<void>
清理空会话及其相关数据，维护系统数据整洁性。

### cleanupExpiredData(expireTime: Date): Promise<number>
清理过期数据，返回清理的记录数量。

### saveUserPosition(userId: string, position: Position): Promise<void>
保存用户位置到数据库，支持数据验证和持久化存储。

### loadUserPosition(userId: string): Promise<Position | null>
从数据库加载用户位置，提供数据恢复和查询功能。

### savePositionHistory(userId: string, position: Position, sessionId?: string): Promise<void>
保存位置历史记录，支持用户轨迹追踪和数据分析。

### getPositionHistory(userId: string, limit?: number): Promise<PositionHistory[]>
获取用户位置历史记录，支持分页和数量限制。

### batchUpdateUserStatus(userIds: string[], status: number): Promise<number>
批量更新用户状态，支持高效的批量操作。

### cleanupExpiredPositions(expireTime: Date): Promise<number>
清理过期的位置数据，返回清理的记录数量。

### getUserPositionStats(userId: string): Promise<any>
获取用户位置统计信息，提供数据分析支持。

### migratePositionData(fromUserId: string, toUserId: string): Promise<void>
迁移用户位置数据，支持用户数据转移和合并。

## 使用的项目内部依赖

### REDIS_SERVICE (来自 core/redis)
Redis缓存服务，用于高性能位置数据缓存和会话状态管理。

### IUserProfilesService (来自 core/db/user_profiles)
用户档案服务，用于位置数据持久化和用户信息查询操作。

### Position (本模块)
位置数据结构定义，包含用户ID、坐标、地图ID、时间戳等信息。

### SessionUser (本模块)
会话用户数据结构，包含用户ID、Socket连接ID和状态信息。

### PositionHistory (本模块)
位置历史记录结构，用于存储用户位置变化轨迹。

### ILocationBroadcastCore (本模块)
位置广播核心服务接口，定义会话管理和位置缓存的标准操作。

### IUserPositionCore (本模块)
用户位置核心服务接口，定义位置数据持久化的标准操作。

## 核心特性

### 技术特性

#### 高性能缓存
- **Redis缓存**: 位置数据存储在Redis中，支持毫秒级读写
- **过期策略**: 会话数据3600秒过期，位置数据1800秒过期
- **批量操作**: 支持批量数据读写，优化性能

#### 数据一致性
- **双写策略**: 位置数据同时写入Redis缓存和MySQL数据库
- **事务处理**: 确保数据操作的原子性
- **异常恢复**: 完善的错误处理和数据恢复机制

#### 可扩展性
- **接口抽象**: 通过依赖注入实现服务解耦
- **模块化设计**: 清晰的职责分离和边界定义
- **配置化**: 关键参数通过常量定义，便于调整

### 功能特性

#### 实时会话管理
- **用户加入/离开**: 实时更新会话状态
- **Socket映射**: 维护用户与WebSocket连接的映射关系
- **自动清理**: 空会话和过期数据的自动清理

#### 位置数据处理
- **多地图支持**: 支持用户在不同地图间切换
- **位置历史**: 记录用户位置变化轨迹
- **地理查询**: 按地图或会话查询用户位置

#### 数据维护
- **定期清理**: 支持过期数据的批量清理
- **数据迁移**: 支持用户数据的迁移操作
- **统计分析**: 提供位置数据的统计功能

### 质量特性

#### 可靠性
- **异常处理**: 全面的错误处理和日志记录
- **数据校验**: 严格的输入参数验证
- **容错机制**: 部分失败不影响整体功能

#### 可观测性
- **详细日志**: 操作开始、成功、失败的完整日志
- **性能监控**: 记录操作耗时和性能指标
- **错误追踪**: 完整的错误堆栈和上下文信息

#### 可测试性
- **单元测试**: 60个测试用例，100%方法覆盖
- **Mock支持**: 完善的依赖Mock机制
- **边界测试**: 包含正常、异常、边界条件测试

## 潜在风险

### 技术风险

#### Redis依赖风险
- **风险描述**: Redis服务不可用导致位置数据无法缓存
- **影响程度**: 高 - 影响实时位置功能
- **缓解措施**: 
  - 实现Redis连接重试机制
  - 考虑Redis集群部署
  - 添加降级策略，临时使用数据库

#### 内存使用风险
- **风险描述**: 大量用户同时在线导致Redis内存占用过高
- **影响程度**: 中 - 可能影响系统性能
- **缓解措施**:
  - 合理设置数据过期时间
  - 监控内存使用情况
  - 实现数据清理策略

#### 数据一致性风险
- **风险描述**: Redis和数据库数据不一致
- **影响程度**: 中 - 可能导致数据错误
- **缓解措施**:
  - 实现数据同步检查机制
  - 添加数据修复功能
  - 定期进行数据一致性校验

### 业务风险

#### 位置数据丢失
- **风险描述**: 系统故障导致用户位置数据丢失
- **影响程度**: 中 - 影响用户体验
- **缓解措施**:
  - 实现位置数据备份机制
  - 添加数据恢复功能
  - 提供位置重置选项

#### 会话状态错误
- **风险描述**: 用户会话状态不正确，影响位置广播
- **影响程度**: 中 - 影响功能正常使用
- **缓解措施**:
  - 实现会话状态校验
  - 添加会话修复机制
  - 提供手动会话管理功能

### 运维风险

#### 性能监控缺失
- **风险描述**: 缺乏有效的性能监控，问题发现滞后
- **影响程度**: 中 - 影响问题响应速度
- **缓解措施**:
  - 集成APM监控工具
  - 设置关键指标告警
  - 建立性能基线

#### 日志存储风险
- **风险描述**: 大量日志导致存储空间不足
- **影响程度**: 低 - 可能影响日志记录
- **缓解措施**:
  - 实现日志轮转机制
  - 设置日志级别控制
  - 定期清理历史日志

### 安全风险

#### 数据访问控制
- **风险描述**: 位置数据可能被未授权访问
- **影响程度**: 高 - 涉及用户隐私
- **缓解措施**:
  - 实现严格的权限控制
  - 添加数据访问审计
  - 对敏感数据进行加密

#### 注入攻击风险
- **风险描述**: 恶意输入可能导致数据库注入攻击
- **影响程度**: 高 - 可能导致数据泄露
- **缓解措施**:
  - 使用参数化查询
  - 严格输入验证
  - 实现SQL注入检测

#### 缓存投毒风险
- **风险描述**: 恶意数据写入Redis缓存
- **影响程度**: 中 - 可能影响数据准确性
- **缓解措施**:
  - 实现数据校验机制
  - 添加缓存数据签名
  - 定期缓存数据校验

---

## 版本信息
- **当前版本**: 1.0.6
- **最后更新**: 2026-01-08
- **维护者**: moyin
- **测试覆盖**: 60个测试用例全部通过