"use client";

/**
 * IChatRepository 接口
 *
 * 对齐 Dart 端 `ChatRepository` 抽象（lib/data/repositories/chat_repository.dart）：
 *   - 远程：发送消息、获取历史
 *   - 本地：写入 / 批量覆盖 / 读取 / 清空 / 计数
 *
 * 私有助手（`_chatToLocal` / `_localToChat` / `_mapLocalStorageResult`）不暴露。
 * 
 */

import type { Result } from "@/utils";
import type {
  ChatHistoryResponse,
  ChatMediaKind,
  ChatMessage,
  ChatSendResponse,
  UnlockHistoryResponse,
  UnlockPrivateResponse,
} from "@/data/dto/chat";
import type { ChatLockDetailData } from "@/data/schemas/chat";
import type { LocalChatMediaRow } from "@/data/storage/chat";

export interface ChatMediaLookupInput {
  messageId: string;
  kind: ChatMediaKind;
}

export interface CacheRemoteChatMediaInput extends ChatMediaLookupInput {
  remoteUrl: string;
}

export interface IChatRepository {
  /** 发送一条消息。 */
  sendMessage(
    message: string,
    options?: { image?: string; useWebSocket?: boolean },
  ): Promise<Result<ChatSendResponse>>;

  /** 获取聊天历史，分页参数默认 limit=50, offset=0。 */
  getHistory(limit?: number, offset?: number): Promise<Result<ChatHistoryResponse>>;

  /** 解锁单条历史付费 / 私密消息。 */
  unlockPrivateMessage(messageId: string): Promise<Result<UnlockPrivateResponse>>;

  /** 一键解锁历史锁定消息。 */
  unlockHistory(): Promise<Result<UnlockHistoryResponse>>;

  /** 把本地缓存中的单条锁定消息标记为已解锁。 */
  markPrivateMessageUnlockedInLocal(
    messageId: string,
    lockDetail?: ChatLockDetailData,
  ): Promise<Result<void>>;

  /** 把一条消息写入本地存储。 */
  saveMessageToLocal(message: ChatMessage): Promise<Result<void>>;

  /** 批量覆盖写入：先清空本地存储，再写入新列表。 */
  saveMessagesToLocal(messages: readonly ChatMessage[]): Promise<Result<void>>;

  /** 读取所有本地消息，按 dbId 升序。 */
  getLocalMessages(): Promise<Result<ChatMessage[]>>;

  /** 清空本地消息。 */
  clearLocalMessages(): Promise<Result<void>>;

  /** 获取本地消息数量。 */
  getLocalMessageCount(): Promise<Result<number>>;

  /** 获取本地缓存的图片 / 音频 Blob。 */
  getCachedMedia(
    input: ChatMediaLookupInput,
  ): Promise<Result<LocalChatMediaRow | null>>;

  /** 下载并缓存远程图片 / 音频 Blob。 */
  cacheRemoteMedia(
    input: CacheRemoteChatMediaInput,
  ): Promise<Result<LocalChatMediaRow>>;

  /** 后台预缓存历史消息中的图片 / 音频。失败不影响聊天主流程。 */
  prefetchMediaForMessages(
    messages: readonly ChatMessage[],
  ): Promise<Result<void>>;

  /** 后台预缓存发送响应中的图片 / 音频。失败不影响聊天主流程。 */
  prefetchMediaForSendResponse(
    response: ChatSendResponse,
  ): Promise<Result<void>>;
}