/**
 * 会话管理核心接口定义
 * 
 * 功能描述：
 * - 定义会话管理的抽象接口
 * - 供 Business 层实现，Core 层依赖
 * - 实现 Business 层模块间的解耦
 * 
 * 架构层级：Core Layer（核心层）
 * 
 * 使用场景：
 * - ZulipEventProcessorService 需要查询玩家会话信息
 * - 其他需要会话信息的服务
 * 
 * 最近修改：
 * - 2026-01-14: 代码规范优化 - 完善方法注释，添加@param和@returns (修改者: moyin)
 * - 2026-01-14: 代码规范优化 - 完善文件头注释，替换AI标识 (修改者: moyin)
 * 
 * @author moyin
 * @version 1.0.2
 * @since 2026-01-14
 * @lastModified 2026-01-14
 */

/**
 * 位置信息接口
 */
export interface IPosition {
  x: number;
  y: number;
}

/**
 * 游戏会话接口
 */
export interface IGameSession {
  socketId: string;
  userId: string;
  username: string;
  zulipQueueId: string;
  currentMap: string;
  position: IPosition;
  lastActivity: Date;
  createdAt: Date;
}

/**
 * 上下文信息接口
 */
export interface IContextInfo {
  stream: string;
  topic?: string;
}

/**
 * 会话查询服务接口
 * 
 * 提供只读的会话查询能力，用于跨模块查询会话信息
 * 不包含会话的创建、更新、删除操作
 */
export interface ISessionQueryService {
  /**
   * 获取会话信息
   * @param socketId WebSocket连接ID
   * @returns 会话信息，不存在返回null
   */
  getSession(socketId: string): Promise<IGameSession | null>;

  /**
   * 获取指定地图的所有Socket ID
   * @param mapId 地图ID
   * @returns Socket ID列表
   */
  getSocketsInMap(mapId: string): Promise<string[]>;
}

/**
 * 会话管理服务接口
 * 
 * 提供完整的会话管理能力，包括创建、更新、删除
 * 继承自 ISessionQueryService
 */
export interface ISessionManagerService extends ISessionQueryService {
  /**
   * 创建会话
   * @param socketId WebSocket连接ID
   * @param userId 用户ID
   * @param zulipQueueId Zulip事件队列ID
   * @param username 用户名（可选）
   * @param initialMap 初始地图ID（可选）
   * @param initialPosition 初始位置（可选）
   * @returns 创建的会话信息
   */
  createSession(
    socketId: string,
    userId: string,
    zulipQueueId: string,
    username?: string,
    initialMap?: string,
    initialPosition?: IPosition,
  ): Promise<IGameSession>;

  /**
   * 上下文注入：根据位置确定Stream/Topic
   * @param socketId WebSocket连接ID
   * @param mapId 地图ID（可选）
   * @returns 上下文信息，包含stream和topic
   */
  injectContext(socketId: string, mapId?: string): Promise<IContextInfo>;

  /**
   * 更新玩家位置
   * @param socketId WebSocket连接ID
   * @param mapId 地图ID
   * @param x X坐标
   * @param y Y坐标
   * @returns 更新是否成功
   */
  updatePlayerPosition(socketId: string, mapId: string, x: number, y: number): Promise<boolean>;

  /**
   * 销毁会话
   * @param socketId WebSocket连接ID
   * @returns 销毁是否成功
   */
  destroySession(socketId: string): Promise<boolean>;

  /**
   * 清理过期会话
   * @param timeoutMinutes 超时时间（分钟），可选
   * @returns 清理结果，包含清理数量和对应的Zulip队列ID列表
   */
  cleanupExpiredSessions(timeoutMinutes?: number): Promise<{ cleanedCount: number; zulipQueueIds: string[] }>;
}

/**
 * 依赖注入 Token
 */
export const SESSION_QUERY_SERVICE = 'SESSION_QUERY_SERVICE';
export const SESSION_MANAGER_SERVICE = 'SESSION_MANAGER_SERVICE';
