/**
 * HTTP 相关类型定义
 */

/**
 * 统一 API 响应结构
 */
export interface ApiResponse<T> {
  /** 业务状态码，0 表示成功 */
  code: number
  /** 响应消息 */
  message: string
  /** 响应数据 */
  data: T | null
}

/**
 * 分页数据结构（传统 offset 模式）
 */
export interface PaginatedData<T> {
  /** 数据列表 */
  items: T[]
  /** 总数量 */
  total: number
  /** 当前页码 */
  page?: number
  /** 每页数量 */
  page_size?: number
}

/**
 * 游标分页响应结构（Cursor/Keyset Pagination）
 * 推荐用于大数据量分页，性能 O(limit) 不受翻页深度影响
 */
export interface CursorPaginatedData<T> {
  /** 数据列表 */
  items: T[]
  /** 下一页游标，空字符串表示没有更多数据 */
  next_cursor: string
  /** 是否有更多数据 */
  has_more: boolean
  /** 本页数量 */
  page_size: number
}

/**
 * 分页请求参数
 */
export interface PaginationParams {
  /** 页码，从 1 开始 */
  page?: number
  /** 每页数量 */
  page_size?: number
}

/**
 * 排序参数
 */
export interface SortParams {
  /** 排序字段 */
  sort_by?: string
  /** 排序方向 */
  sort_order?: 'asc' | 'desc'
}

/**
 * 通用列表查询参数
 */
export interface ListParams extends PaginationParams, SortParams {
  /** 关键词搜索 */
  keyword?: string
}

/**
 * HTTP 请求方法
 */
export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH'

/**
 * HTTP 请求配置
 */
export interface RequestOptions {
  /** 请求方法 */
  method?: HttpMethod
  /** 请求头 */
  headers?: Record<string, string>
  /** 请求体 */
  body?: unknown
  /** 查询参数 */
  params?: Record<string, string | number | boolean | undefined>
  /** 是否需要认证 */
  auth?: boolean
  /** Fetch credentials mode */
  credentials?: RequestCredentials
  /** 信号（用于取消请求） */
  signal?: AbortSignal
}
