/**
 * 位置相关接口定义
 * 
 * 功能描述：
 * - 定义位置数据的核心接口和类型
 * - 提供位置广播系统的数据结构规范
 * - 支持多地图和多用户的位置管理
 * - 实现类型安全的位置数据传输
 * 
 * 职责分离：
 * - 数据结构：定义位置相关的数据模型
 * - 类型安全：提供TypeScript类型约束
 * - 接口规范：统一的数据交换格式
 * - 扩展性：支持未来功能扩展
 * 
 * 最近修改：
 * - 2026-01-08: 功能新增 - 创建位置接口定义，支持位置广播系统
 * 
 * @author moyin
 * @version 1.0.0
 * @since 2026-01-08
 * @lastModified 2026-01-08
 */

/**
 * 位置坐标接口
 * 
 * 职责：
 * - 定义二维坐标系统的基础数据结构
 * - 支持浮点数精度的位置表示
 * - 提供位置计算的基础数据类型
 */
export interface Coordinates {
  /** X轴坐标 */
  x: number;
  /** Y轴坐标 */
  y: number;
}

/**
 * 位置信息接口
 * 
 * 职责：
 * - 定义完整的用户位置信息
 * - 包含用户标识、坐标、地图和时间戳
 * - 支持位置数据的完整传输和存储
 */
export interface Position extends Coordinates {
  /** 用户ID */
  userId: string;
  /** 地图ID */
  mapId: string;
  /** 位置更新时间戳 */
  timestamp: number;
  /** 扩展元数据 */
  metadata?: Record<string, any>;
}

/**
 * 位置更新数据接口
 * 
 * 职责：
 * - 定义位置更新操作的数据结构
 * - 支持增量位置更新
 * - 提供位置变化的核心信息
 */
export interface PositionUpdate extends Coordinates {
  /** 目标地图ID */
  mapId: string;
  /** 更新时间戳 */
  timestamp?: number;
}

/**
 * 位置历史记录接口
 * 
 * 职责：
 * - 定义位置历史数据的存储结构
 * - 支持位置轨迹的记录和查询
 * - 提供历史数据分析的基础
 */
export interface PositionHistory extends Position {
  /** 历史记录ID */
  id: number;
  /** 关联的游戏会话ID */
  sessionId?: string;
  /** 记录创建时间 */
  createdAt: Date;
}

/**
 * 地图边界接口
 * 
 * 职责：
 * - 定义地图的有效坐标范围
 * - 支持位置验证和边界检查
 * - 提供地图约束的数据结构
 */
export interface MapBounds {
  /** 地图ID */
  mapId: string;
  /** 最小X坐标 */
  minX: number;
  /** 最大X坐标 */
  maxX: number;
  /** 最小Y坐标 */
  minY: number;
  /** 最大Y坐标 */
  maxY: number;
}

/**
 * 位置查询条件接口
 * 
 * 职责：
 * - 定义位置查询的过滤条件
 * - 支持多维度的位置数据筛选
 * - 提供灵活的查询参数组合
 */
export interface PositionQuery {
  /** 地图ID过滤 */
  mapId?: string;
  /** 用户ID列表过滤 */
  userIds?: string[];
  /** 时间范围过滤 - 开始时间 */
  startTime?: number;
  /** 时间范围过滤 - 结束时间 */
  endTime?: number;
  /** 坐标范围过滤 */
  bounds?: {
    minX: number;
    maxX: number;
    minY: number;
    maxY: number;
  };
  /** 分页限制 */
  limit?: number;
  /** 分页偏移 */
  offset?: number;
}

/**
 * 位置统计信息接口
 * 
 * 职责：
 * - 定义位置数据的统计结果
 * - 支持位置分析和监控
 * - 提供系统性能指标
 */
export interface PositionStats {
  /** 总用户数 */
  totalUsers: number;
  /** 在线用户数 */
  onlineUsers: number;
  /** 按地图分组的用户数 */
  usersByMap: Record<string, number>;
  /** 位置更新频率 (次/分钟) */
  updateRate: number;
  /** 平均响应时间 (毫秒) */
  averageResponseTime: number;
  /** 统计时间戳 */
  timestamp: number;
}

/**
 * 位置验证结果接口
 * 
 * 职责：
 * - 定义位置数据验证的结果
 * - 支持位置合法性检查
 * - 提供验证错误的详细信息
 */
export interface PositionValidationResult {
  /** 验证是否通过 */
  isValid: boolean;
  /** 验证错误信息 */
  errors: string[];
  /** 修正后的位置 (如果可以自动修正) */
  correctedPosition?: Position;
}

/**
 * 位置服务配置接口
 * 
 * 职责：
 * - 定义位置服务的配置参数
 * - 支持系统行为的自定义配置
 * - 提供性能调优的配置选项
 */
export interface PositionServiceConfig {
  /** Redis缓存过期时间 (秒) */
  cacheExpireTime: number;
  /** 位置更新频率限制 (次/秒) */
  updateRateLimit: number;
  /** 批量操作大小限制 */
  batchSizeLimit: number;
  /** 历史记录保留天数 */
  historyRetentionDays: number;
  /** 是否启用位置验证 */
  enableValidation: boolean;
  /** 默认地图边界 */
  defaultMapBounds: MapBounds;
}