/**
 * 核心服务接口定义
 * 
 * 功能描述：
 * - 定义位置广播系统核心服务的接口规范
 * - 提供服务间交互的标准化接口
 * - 支持依赖注入和模块化设计
 * - 实现核心技术功能的抽象层
 * 
 * 职责分离：
 * - 接口定义：核心服务的方法签名和契约
 * - 类型安全：TypeScript接口约束
 * - 模块解耦：服务间的松耦合设计
 * - 可测试性：支持Mock和单元测试
 * 
 * 最近修改：
 * - 2026-01-08: 文件重命名 - 修正kebab-case为snake_case命名规范 (修改者: moyin)
 * - 2026-01-08: 功能新增 - 创建核心服务接口定义
 * 
 * @author moyin
 * @version 1.0.1
 * @since 2026-01-08
 * @lastModified 2026-01-08
 */

import { Position, PositionUpdate, PositionHistory, PositionQuery, PositionStats } from './position.interface';
import { GameSession, SessionUser, JoinSessionRequest, JoinSessionResponse, LeaveSessionRequest, SessionQuery, SessionStats } from './session.interface';

/**
 * 位置广播核心服务接口
 * 
 * 职责：
 * - 提供位置广播系统的核心功能
 * - 管理用户会话和位置数据
 * - 协调Redis缓存和数据库持久化
 * - 处理位置更新和广播逻辑
 */
export interface ILocationBroadcastCore {
  // 会话数据管理
  /**
   * 添加用户到会话
   * @param sessionId 会话ID
   * @param userId 用户ID
   * @param socketId WebSocket连接ID
   */
  addUserToSession(sessionId: string, userId: string, socketId: string): Promise<void>;

  /**
   * 从会话中移除用户
   * @param sessionId 会话ID
   * @param userId 用户ID
   */
  removeUserFromSession(sessionId: string, userId: string): Promise<void>;

  /**
   * 获取会话中的用户列表
   * @param sessionId 会话ID
   * @returns 会话用户列表
   */
  getSessionUsers(sessionId: string): Promise<SessionUser[]>;

  // 位置数据管理
  /**
   * 设置用户位置
   * @param userId 用户ID
   * @param position 位置信息
   */
  setUserPosition(userId: string, position: Position): Promise<void>;

  /**
   * 获取用户位置
   * @param userId 用户ID
   * @returns 用户位置信息
   */
  getUserPosition(userId: string): Promise<Position | null>;

  /**
   * 获取会话中所有用户的位置
   * @param sessionId 会话ID
   * @returns 位置信息列表
   */
  getSessionPositions(sessionId: string): Promise<Position[]>;

  /**
   * 获取地图中所有用户的位置
   * @param mapId 地图ID
   * @returns 位置信息列表
   */
  getMapPositions(mapId: string): Promise<Position[]>;

  // 清理操作
  /**
   * 清理用户数据
   * @param userId 用户ID
   */
  cleanupUserData(userId: string): Promise<void>;

  /**
   * 清理空会话
   * @param sessionId 会话ID
   */
  cleanupEmptySession(sessionId: string): Promise<void>;

  /**
   * 清理过期数据
   * @param expireTime 过期时间
   * @returns 清理的记录数
   */
  cleanupExpiredData(expireTime: Date): Promise<number>;
}

/**
 * 会话管理核心服务接口
 * 
 * 职责：
 * - 管理游戏会话的生命周期
 * - 处理用户加入和离开会话
 * - 维护会话状态和配置
 * - 提供会话查询和统计功能
 */
export interface ILocationSessionCore {
  /**
   * 创建新会话
   * @param sessionId 会话ID
   * @param config 会话配置
   */
  createSession(sessionId: string, config?: any): Promise<GameSession>;

  /**
   * 用户加入会话
   * @param request 加入会话请求
   * @returns 加入会话响应
   */
  joinSession(request: JoinSessionRequest): Promise<JoinSessionResponse>;

  /**
   * 用户离开会话
   * @param request 离开会话请求
   */
  leaveSession(request: LeaveSessionRequest): Promise<void>;

  /**
   * 获取会话信息
   * @param sessionId 会话ID
   * @returns 会话信息
   */
  getSession(sessionId: string): Promise<GameSession | null>;

  /**
   * 获取用户当前会话
   * @param userId 用户ID
   * @returns 会话ID
   */
  getUserSession(userId: string): Promise<string | null>;

  /**
   * 查询会话列表
   * @param query 查询条件
   * @returns 会话列表
   */
  querySessions(query: SessionQuery): Promise<GameSession[]>;

  /**
   * 获取会话统计信息
   * @param sessionId 会话ID
   * @returns 统计信息
   */
  getSessionStats(sessionId: string): Promise<SessionStats>;

  /**
   * 更新会话配置
   * @param sessionId 会话ID
   * @param config 新配置
   */
  updateSessionConfig(sessionId: string, config: any): Promise<void>;

  /**
   * 结束会话
   * @param sessionId 会话ID
   * @param reason 结束原因
   */
  endSession(sessionId: string, reason: string): Promise<void>;
}

/**
 * 位置管理核心服务接口
 * 
 * 职责：
 * - 管理用户位置数据的缓存
 * - 处理位置更新和验证
 * - 提供位置查询和统计功能
 * - 协调位置数据的持久化
 */
export interface ILocationPositionCore {
  /**
   * 更新用户位置
   * @param userId 用户ID
   * @param update 位置更新数据
   */
  updatePosition(userId: string, update: PositionUpdate): Promise<Position>;

  /**
   * 获取用户位置
   * @param userId 用户ID
   * @returns 位置信息
   */
  getPosition(userId: string): Promise<Position | null>;

  /**
   * 批量获取用户位置
   * @param userIds 用户ID列表
   * @returns 位置信息列表
   */
  getBatchPositions(userIds: string[]): Promise<Position[]>;

  /**
   * 查询位置数据
   * @param query 查询条件
   * @returns 位置信息列表
   */
  queryPositions(query: PositionQuery): Promise<Position[]>;

  /**
   * 获取位置统计信息
   * @returns 统计信息
   */
  getPositionStats(): Promise<PositionStats>;

  /**
   * 验证位置数据
   * @param position 位置信息
   * @returns 验证结果
   */
  validatePosition(position: Position): Promise<boolean>;

  /**
   * 清理用户位置
   * @param userId 用户ID
   */
  cleanupUserPosition(userId: string): Promise<void>;

  /**
   * 清理地图位置数据
   * @param mapId 地图ID
   * @returns 清理的记录数
   */
  cleanupMapPositions(mapId: string): Promise<number>;
}

/**
 * 用户位置持久化核心服务接口
 * 
 * 职责：
 * - 管理用户位置的数据库持久化
 * - 处理位置历史记录
 * - 提供位置数据的长期存储
 * - 支持位置数据的恢复和迁移
 */
export interface IUserPositionCore {
  /**
   * 保存用户位置到数据库
   * @param userId 用户ID
   * @param position 位置信息
   */
  saveUserPosition(userId: string, position: Position): Promise<void>;

  /**
   * 从数据库加载用户位置
   * @param userId 用户ID
   * @returns 位置信息
   */
  loadUserPosition(userId: string): Promise<Position | null>;

  /**
   * 保存位置历史记录
   * @param userId 用户ID
   * @param position 位置信息
   * @param sessionId 会话ID（可选）
   */
  savePositionHistory(userId: string, position: Position, sessionId?: string): Promise<void>;

  /**
   * 获取位置历史记录
   * @param userId 用户ID
   * @param limit 限制数量
   * @returns 历史记录列表
   */
  getPositionHistory(userId: string, limit?: number): Promise<PositionHistory[]>;

  /**
   * 批量更新用户状态
   * @param userIds 用户ID列表
   * @param status 状态值
   * @returns 更新的记录数
   */
  batchUpdateUserStatus(userIds: string[], status: number): Promise<number>;

  /**
   * 清理过期位置数据
   * @param expireTime 过期时间
   * @returns 清理的记录数
   */
  cleanupExpiredPositions(expireTime: Date): Promise<number>;

  /**
   * 获取用户位置统计
   * @param userId 用户ID
   * @returns 统计信息
   */
  getUserPositionStats(userId: string): Promise<any>;

  /**
   * 迁移位置数据
   * @param fromUserId 源用户ID
   * @param toUserId 目标用户ID
   */
  migratePositionData(fromUserId: string, toUserId: string): Promise<void>;
}

/**
 * 位置广播事件服务接口
 * 
 * 职责：
 * - 处理位置广播相关的事件
 * - 管理事件的发布和订阅
 * - 提供事件驱动的系统架构
 * - 支持异步事件处理
 */
export interface ILocationBroadcastEventService {
  /**
   * 发布位置更新事件
   * @param userId 用户ID
   * @param position 位置信息
   * @param sessionId 会话ID
   */
  publishPositionUpdate(userId: string, position: Position, sessionId: string): Promise<void>;

  /**
   * 发布用户加入事件
   * @param userId 用户ID
   * @param sessionId 会话ID
   */
  publishUserJoined(userId: string, sessionId: string): Promise<void>;

  /**
   * 发布用户离开事件
   * @param userId 用户ID
   * @param sessionId 会话ID
   * @param reason 离开原因
   */
  publishUserLeft(userId: string, sessionId: string, reason: string): Promise<void>;

  /**
   * 订阅位置更新事件
   * @param callback 回调函数
   */
  subscribePositionUpdates(callback: (userId: string, position: Position) => void): void;

  /**
   * 订阅会话事件
   * @param callback 回调函数
   */
  subscribeSessionEvents(callback: (event: any) => void): void;

  /**
   * 取消订阅
   * @param eventType 事件类型
   * @param callback 回调函数
   */
  unsubscribe(eventType: string, callback: Function): void;
}

/**
 * 位置广播配置服务接口
 * 
 * 职责：
 * - 管理位置广播系统的配置
 * - 提供配置的动态更新
 * - 支持配置的验证和默认值
 * - 处理配置的持久化存储
 */
export interface ILocationBroadcastConfigService {
  /**
   * 获取配置值
   * @param key 配置键
   * @param defaultValue 默认值
   * @returns 配置值
   */
  get<T>(key: string, defaultValue?: T): T;

  /**
   * 设置配置值
   * @param key 配置键
   * @param value 配置值
   */
  set<T>(key: string, value: T): Promise<void>;

  /**
   * 获取所有配置
   * @returns 配置对象
   */
  getAll(): Record<string, any>;

  /**
   * 重新加载配置
   */
  reload(): Promise<void>;

  /**
   * 验证配置
   * @param config 配置对象
   * @returns 验证结果
   */
  validate(config: Record<string, any>): boolean;

  /**
   * 获取默认配置
   * @returns 默认配置对象
   */
  getDefaults(): Record<string, any>;
}