/**
 * 缓存适配器接口
 * 
 * 支持多种缓存实现：
 * - MemoryCacheAdapter: 内存缓存（开发环境）
 * - RedisCacheAdapter: Redis缓存（生产环境）
 * 
 * 使用场景：
 * - LLM响应缓存（减少API调用成本）
 * - 数据库查询结果缓存
 * - Session缓存
 * - API限流计数器
 * 
 * @example
 * ```typescript
 * import { cache } from '@/common/cache'
 * 
 * // 设置缓存（30分钟过期）
 * await cache.set('user:123', userData, 30 * 60)
 * 
 * // 获取缓存
 * const user = await cache.get<User>('user:123')
 * 
 * // 删除缓存
 * await cache.delete('user:123')
 * ```
 */
export interface CacheAdapter {
  /**
   * 获取缓存值
   * @param key 缓存键
   * @returns 缓存值，不存在或已过期返回null
   */
  get<T = any>(key: string): Promise<T | null>

  /**
   * 设置缓存值
   * @param key 缓存键
   * @param value 缓存值（会自动序列化为JSON）
   * @param ttl 过期时间（秒），不传则永不过期
   */
  set(key: string, value: any, ttl?: number): Promise<void>

  /**
   * 删除缓存
   * @param key 缓存键
   */
  delete(key: string): Promise<void>

  /**
   * 清空所有缓存
   * ⚠️ 慎用，生产环境可能影响其他应用
   */
  clear(): Promise<void>

  /**
   * 检查缓存是否存在
   * @param key 缓存键
   */
  has(key: string): Promise<boolean>

  /**
   * 批量获取缓存
   * @param keys 缓存键数组
   * @returns 缓存值数组（按keys顺序，不存在则为null）
   */
  mget<T = any>(keys: string[]): Promise<(T | null)[]>

  /**
   * 批量设置缓存
   * @param entries 键值对数组
   * @param ttl 过期时间（秒）
   */
  mset(entries: Array<{ key: string; value: any }>, ttl?: number): Promise<void>
}




