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

import { Position } from './position.interface';

/**
 * 会话用户接口
 * 
 * 职责：
 * - 定义会话中用户的基本信息
 * - 包含用户标识、连接状态和时间信息
 * - 支持用户会话状态的管理
 */
export interface SessionUser {
  /** 用户ID */
  userId: string;
  /** WebSocket连接ID */
  socketId: string;
  /** 加入会话时间 */
  joinedAt: number;
  /** 最后活跃时间 */
  lastSeen: number;
  /** 用户当前位置 */
  position?: Position;
  /** 用户状态 */
  status: SessionUserStatus;
  /** 用户元数据 */
  metadata?: Record<string, any>;
}

/**
 * 会话用户状态枚举
 * 
 * 职责：
 * - 定义用户在会话中的状态类型
 * - 支持用户状态的精确管理
 * - 提供状态转换的基础
 */
export enum SessionUserStatus {
  /** 在线状态 */
  ONLINE = 'online',
  /** 离线状态 */
  OFFLINE = 'offline',
  /** 忙碌状态 */
  BUSY = 'busy',
  /** 隐身状态 */
  INVISIBLE = 'invisible',
  /** 暂时离开 */
  AWAY = 'away'
}

/**
 * 游戏会话接口
 * 
 * 职责：
 * - 定义完整的游戏会话信息
 * - 包含会话标识、用户列表和配置
 * - 支持会话的创建、管理和销毁
 */
export interface GameSession {
  /** 会话ID */
  sessionId: string;
  /** 会话中的用户列表 */
  users: SessionUser[];
  /** 会话创建时间 */
  createdAt: number;
  /** 最后活动时间 */
  lastActivity: number;
  /** 会话配置 */
  config: SessionConfig;
  /** 会话状态 */
  status: SessionStatus;
  /** 会话元数据 */
  metadata?: Record<string, any>;
}

/**
 * 会话状态枚举
 * 
 * 职责：
 * - 定义会话的生命周期状态
 * - 支持会话状态的管理和监控
 * - 提供会话清理的依据
 */
export enum SessionStatus {
  /** 活跃状态 */
  ACTIVE = 'active',
  /** 空闲状态 */
  IDLE = 'idle',
  /** 暂停状态 */
  PAUSED = 'paused',
  /** 已结束 */
  ENDED = 'ended'
}

/**
 * 会话配置接口
 * 
 * 职责：
 * - 定义会话的配置参数
 * - 支持会话行为的自定义
 * - 提供会话管理的策略配置
 */
export interface SessionConfig {
  /** 最大用户数限制 */
  maxUsers: number;
  /** 会话超时时间 (秒) */
  timeoutSeconds: number;
  /** 是否允许观察者 */
  allowObservers: boolean;
  /** 是否需要密码 */
  requirePassword: boolean;
  /** 会话密码 (如果需要) */
  password?: string;
  /** 地图限制 (如果指定，只能在特定地图中) */
  mapRestriction?: string[];
  /** 位置广播范围 (米) */
  broadcastRange?: number;
}

/**
 * 加入会话请求接口
 * 
 * 职责：
 * - 定义用户加入会话的请求数据
 * - 包含认证和配置信息
 * - 支持会话加入的验证
 */
export interface JoinSessionRequest {
  /** 会话ID */
  sessionId: string;
  /** 用户认证token */
  token: string;
  /** 会话密码 (如果需要) */
  password?: string;
  /** 初始位置 */
  initialPosition?: Position;
  /** 用户偏好设置 */
  preferences?: SessionUserPreferences;
}

/**
 * 加入会话响应接口
 * 
 * 职责：
 * - 定义加入会话的响应数据
 * - 包含会话信息和用户列表
 * - 提供会话状态的完整视图
 */
export interface JoinSessionResponse {
  /** 是否成功加入 */
  success: boolean;
  /** 错误信息 (如果失败) */
  error?: string;
  /** 会话信息 */
  session?: GameSession;
  /** 当前用户在会话中的信息 */
  userInfo?: SessionUser;
  /** 其他用户的位置信息 */
  otherPositions?: Position[];
}

/**
 * 离开会话请求接口
 * 
 * 职责：
 * - 定义用户离开会话的请求数据
 * - 支持主动离开和被动清理
 * - 提供离开原因的记录
 */
export interface LeaveSessionRequest {
  /** 会话ID */
  sessionId: string;
  /** 用户ID */
  userId: string;
  /** 离开原因 */
  reason: LeaveReason;
  /** 是否保存最终位置 */
  saveFinalPosition: boolean;
}

/**
 * 离开会话原因枚举
 * 
 * 职责：
 * - 定义用户离开会话的原因类型
 * - 支持离开行为的分类和统计
 * - 提供会话管理的数据分析基础
 */
export enum LeaveReason {
  /** 用户主动离开 */
  USER_LEFT = 'user_left',
  /** 连接断开 */
  CONNECTION_LOST = 'connection_lost',
  /** 会话超时 */
  SESSION_TIMEOUT = 'session_timeout',
  /** 被管理员踢出 */
  KICKED_BY_ADMIN = 'kicked_by_admin',
  /** 系统错误 */
  SYSTEM_ERROR = 'system_error'
}

/**
 * 用户会话偏好设置接口
 * 
 * 职责：
 * - 定义用户在会话中的个人偏好
 * - 支持个性化的会话体验
 * - 提供用户行为的配置选项
 */
export interface SessionUserPreferences {
  /** 是否接收位置广播 */
  receivePositionUpdates: boolean;
  /** 是否广播自己的位置 */
  broadcastOwnPosition: boolean;
  /** 位置更新频率 (毫秒) */
  updateFrequency: number;
  /** 是否显示其他用户 */
  showOtherUsers: boolean;
  /** 通知设置 */
  notifications: {
    userJoined: boolean;
    userLeft: boolean;
    positionUpdates: boolean;
  };
}

/**
 * 会话统计信息接口
 * 
 * 职责：
 * - 定义会话的统计数据
 * - 支持会话性能监控
 * - 提供会话分析的数据基础
 */
export interface SessionStats {
  /** 会话ID */
  sessionId: string;
  /** 当前用户数 */
  currentUserCount: number;
  /** 历史最大用户数 */
  maxUserCount: number;
  /** 会话持续时间 (秒) */
  duration: number;
  /** 位置更新总数 */
  totalPositionUpdates: number;
  /** 平均用户在线时长 (秒) */
  averageUserDuration: number;
  /** 消息发送总数 */
  totalMessages: number;
  /** 统计时间戳 */
  timestamp: number;
}

/**
 * 会话查询条件接口
 * 
 * 职责：
 * - 定义会话查询的过滤条件
 * - 支持多维度的会话数据筛选
 * - 提供灵活的查询参数组合
 */
export interface SessionQuery {
  /** 会话状态过滤 */
  status?: SessionStatus;
  /** 用户数范围过滤 */
  userCountRange?: {
    min: number;
    max: number;
  };
  /** 创建时间范围过滤 */
  createdTimeRange?: {
    start: number;
    end: number;
  };
  /** 地图过滤 */
  mapIds?: string[];
  /** 分页限制 */
  limit?: number;
  /** 分页偏移 */
  offset?: number;
}

/**
 * 会话事件接口
 * 
 * 职责：
 * - 定义会话中发生的事件类型
 * - 支持事件驱动的会话管理
 * - 提供事件处理的数据结构
 */
export interface SessionEvent {
  /** 事件ID */
  eventId: string;
  /** 会话ID */
  sessionId: string;
  /** 事件类型 */
  type: SessionEventType;
  /** 事件数据 */
  data: any;
  /** 事件时间戳 */
  timestamp: number;
  /** 触发用户ID */
  triggeredBy?: string;
}

/**
 * 会话事件类型枚举
 * 
 * 职责：
 * - 定义会话中可能发生的事件类型
 * - 支持事件的分类和处理
 * - 提供事件监听的基础
 */
export enum SessionEventType {
  /** 用户加入 */
  USER_JOINED = 'user_joined',
  /** 用户离开 */
  USER_LEFT = 'user_left',
  /** 位置更新 */
  POSITION_UPDATED = 'position_updated',
  /** 会话创建 */
  SESSION_CREATED = 'session_created',
  /** 会话结束 */
  SESSION_ENDED = 'session_ended',
  /** 配置更新 */
  CONFIG_UPDATED = 'config_updated',
  /** 错误发生 */
  ERROR_OCCURRED = 'error_occurred'
}