whale-town-end/src/core/zulip/interfaces/zulip-core.interfaces.ts

/**
 * Zulip核心服务接口定义
 * 
 * 功能描述：
 * - 定义Zulip核心服务的抽象接口
 * - 分离业务逻辑与技术实现
 * - 支持依赖注入和接口切换
 * 
 * @author angjustinl
 * @version 1.0.0
 * @since 2025-12-31
 */

/**
 * Zulip客户端配置接口
 */
export interface ZulipClientConfig {
  username: string;
  apiKey: string;
  realm: string;
}

/**
 * Zulip客户端实例接口
 */
export interface ZulipClientInstance {
  userId: string;
  config: ZulipClientConfig;
  client: any;
  queueId?: string;
  lastEventId: number;
  createdAt: Date;
  lastActivity: Date;
  isValid: boolean;
}

/**
 * 发送消息结果接口
 */
export interface SendMessageResult {
  success: boolean;
  messageId?: number;
  error?: string;
}

/**
 * 事件队列注册结果接口
 */
export interface RegisterQueueResult {
  success: boolean;
  queueId?: string;
  lastEventId?: number;
  error?: string;
}

/**
 * 获取事件结果接口
 */
export interface GetEventsResult {
  success: boolean;
  events?: any[];
  error?: string;
}

/**
 * 客户端池统计信息接口
 */
export interface PoolStats {
  totalClients: number;
  activeClients: number;
  clientsWithQueues: number;
  clientIds: string[];
}

/**
 * Zulip客户端核心服务接口
 * 
 * 职责：
 * - 封装Zulip REST API调用
 * - 处理API Key验证和错误处理
 * - 提供消息发送、事件队列管理等核心功能
 */
export interface IZulipClientService {
  /**
   * 创建并初始化Zulip客户端
   */
  createClient(userId: string, config: ZulipClientConfig): Promise<ZulipClientInstance>;

  /**
   * 验证API Key有效性
   */
  validateApiKey(clientInstance: ZulipClientInstance): Promise<boolean>;

  /**
   * 发送消息到指定Stream/Topic
   */
  sendMessage(
    clientInstance: ZulipClientInstance,
    stream: string,
    topic: string,
    content: string,
  ): Promise<SendMessageResult>;

  /**
   * 注册事件队列
   */
  registerQueue(
    clientInstance: ZulipClientInstance,
    eventTypes?: string[],
  ): Promise<RegisterQueueResult>;

  /**
   * 注销事件队列
   */
  deregisterQueue(clientInstance: ZulipClientInstance): Promise<boolean>;

  /**
   * 获取事件队列中的事件
   */
  getEvents(
    clientInstance: ZulipClientInstance,
    dontBlock?: boolean,
  ): Promise<GetEventsResult>;

  /**
   * 销毁客户端实例
   */
  destroyClient(clientInstance: ZulipClientInstance): Promise<void>;
}

/**
 * Zulip客户端池服务接口
 * 
 * 职责：
 * - 管理用户专用的Zulip客户端实例
 * - 维护客户端连接池和生命周期
 * - 处理客户端的创建、销毁和状态管理
 */
export interface IZulipClientPoolService {
  /**
   * 为用户创建专用Zulip客户端
   */
  createUserClient(userId: string, config: ZulipClientConfig): Promise<ZulipClientInstance>;

  /**
   * 获取用户的Zulip客户端
   */
  getUserClient(userId: string): Promise<ZulipClientInstance | null>;

  /**
   * 检查用户客户端是否存在
   */
  hasUserClient(userId: string): boolean;

  /**
   * 发送消息到指定Stream/Topic
   */
  sendMessage(
    userId: string,
    stream: string,
    topic: string,
    content: string,
  ): Promise<SendMessageResult>;

  /**
   * 注册事件队列
   */
  registerEventQueue(userId: string): Promise<RegisterQueueResult>;

  /**
   * 注销事件队列
   */
  deregisterEventQueue(userId: string): Promise<boolean>;

  /**
   * 销毁用户客户端
   */
  destroyUserClient(userId: string): Promise<void>;

  /**
   * 获取客户端池统计信息
   */
  getPoolStats(): PoolStats;

  /**
   * 清理过期客户端
   */
  cleanupIdleClients(maxIdleMinutes?: number): Promise<number>;
}

/**
 * Zulip配置管理服务接口
 * 
 * 职责：
 * - 管理地图到Zulip Stream的映射配置
 * - 提供Zulip服务器连接配置
 * - 支持配置文件的热重载
 */
export interface IZulipConfigService {
  /**
   * 根据地图获取对应的Stream
   */
  getStreamByMap(mapId: string): string | null;

  /**
   * 根据Stream名称获取地图ID
   */
  getMapIdByStream(streamName: string): string | null;

  /**
   * 根据交互对象获取Topic
   */
  getTopicByObject(mapId: string, objectId: string): string | null;

  /**
   * 获取Zulip配置
   */
  getZulipConfig(): any;

  /**
   * 检查地图是否存在
   */
  hasMap(mapId: string): boolean;

  /**
   * 检查Stream是否存在
   */
  hasStream(streamName: string): boolean;

  /**
   * 获取所有地图ID列表
   */
  getAllMapIds(): string[];

  /**
   * 获取所有Stream名称列表
   */
  getAllStreams(): string[];

  /**
   * 热重载配置
   */
  reloadConfig(): Promise<void>;

  /**
   * 验证配置有效性
   */
  validateConfig(): Promise<{ valid: boolean; errors: string[] }>;
}

/**
 * Zulip事件处理服务接口
 * 
 * 职责：
 * - 处理从Zulip接收的事件队列消息
 * - 将Zulip消息转换为游戏协议格式
 * - 管理事件队列的生命周期
 */
export interface IZulipEventProcessorService {
  /**
   * 启动事件处理循环
   */
  startEventProcessing(): Promise<void>;

  /**
   * 停止事件处理循环
   */
  stopEventProcessing(): Promise<void>;

  /**
   * 注册事件队列
   */
  registerEventQueue(queueId: string, userId: string, lastEventId?: number): Promise<void>;

  /**
   * 注销事件队列
   */
  unregisterEventQueue(queueId: string): Promise<void>;

  /**
   * 处理Zulip消息事件
   */
  processMessageEvent(event: any, senderUserId: string): Promise<void>;

  /**
   * 设置消息分发器
   */
  setMessageDistributor(distributor: any): void;

  /**
   * 获取事件处理统计信息
   */
  getProcessingStats(): any;
}