/**
 * P1-8: 消息列表服务接口。
 *
 * 通过 TypeScript 接口抽象所有客户端可调用的消息列表操作，
 * 使组件依赖接口而非具体 Server Action 实现，便于测试与替换。
 *
 * 默认实现绑定现有 Server Actions；测试时可注入 mock 实现。
 */

import type { ActionState } from "@/shared/types/action-state"

import type { Message, MessageType } from "../types"

/** 消息搜索返回的分页结构 */
export interface MessageSearchResult {
  items: Message[]
  total: number
  page: number
  pageSize: number
  totalPages: number
}

/** 消息搜索参数 */
export interface MessageSearchParams {
  type: MessageType
  keyword?: string
  page?: number
  pageSize?: number
  starredOnly?: boolean
  senderId?: string
  dateFrom?: string
  dateTo?: string
  isRead?: boolean
}

/**
 * 消息列表客户端服务接口。
 * 所有客户端组件通过 useMessageListService() 获取实现，不直接 import actions。
 */
export interface MessageListService {
  /** 搜索消息（支持关键词、星标、发件人、日期范围、已读状态等筛选） */
  search(params: MessageSearchParams): Promise<ActionState<MessageSearchResult>>

  /** 切换消息星标 */
  toggleStar(messageId: string): Promise<ActionState<string>>

  /** 撤回消息（仅发送方，2 分钟窗口内） */
  recall(messageId: string): Promise<ActionState<string>>
}
