# Location Broadcast Core 模块

## 模块概述

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

### 模块组成
- **LocationBroadcastCore**: 位置广播核心服务，处理会话管理和位置缓存
- **UserPositionCore**: 用户位置持久化核心服务，处理数据库操作
- **接口定义**: 核心服务接口和数据结构定义

### 技术架构
- **架构层级**: Core层（核心技术实现）
- **命名规范**: 使用`_core`后缀，表明为业务支撑模块
- **职责边界**: 专注技术实现，不包含业务逻辑

## 对外接口

### LocationBroadcastCore 服务接口

#### 会话管理
- `addUserToSession(sessionId, userId, socketId)` - 添加用户到会话
- `removeUserFromSession(sessionId, userId)` - 从会话中移除用户
- `getSessionUsers(sessionId)` - 获取会话中的用户列表

#### 位置数据管理
- `setUserPosition(userId, position)` - 设置用户位置到Redis缓存
- `getUserPosition(userId)` - 从Redis获取用户位置
- `getSessionPositions(sessionId)` - 获取会话中所有用户位置
- `getMapPositions(mapId)` - 获取地图中所有用户位置

#### 数据清理维护
- `cleanupUserData(userId)` - 清理用户相关数据
- `cleanupEmptySession(sessionId)` - 清理空会话
- `cleanupExpiredData(expireTime)` - 清理过期数据

### UserPositionCore 服务接口

#### 数据持久化
- `saveUserPosition(userId, position)` - 保存用户位置到数据库
- `loadUserPosition(userId)` - 从数据库加载用户位置

#### 历史记录管理
- `savePositionHistory(userId, position, sessionId?)` - 保存位置历史记录
- `getPositionHistory(userId, limit?)` - 获取位置历史记录

#### 批量操作
- `batchUpdateUserStatus(userIds, status)` - 批量更新用户状态
- `cleanupExpiredPositions(expireTime)` - 清理过期位置数据

#### 统计分析
- `getUserPositionStats(userId)` - 获取用户位置统计信息
- `migratePositionData(fromUserId, toUserId)` - 迁移位置数据

## 内部依赖

### 项目内部依赖

#### Redis服务依赖
- **依赖标识**: `REDIS_SERVICE`
- **用途**: 高性能位置数据缓存、会话状态管理
- **关键操作**: sadd, setex, get, del, smembers, scard等

#### 用户档案服务依赖
- **依赖标识**: `IUserProfilesService`
- **用途**: 用户位置数据持久化、用户信息查询
- **关键操作**: updatePosition, findByUserId, batchUpdateStatus

### 数据结构依赖
- **Position接口**: 位置数据结构定义
- **SessionUser接口**: 会话用户数据结构
- **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个测试用例全部通过