/**
 * 存储适配器接口
 * 
 * 支持多种存储实现：
 * - LocalAdapter: 本地文件系统（开发环境）
 * - OSSAdapter: 阿里云OSS（生产环境）
 * 
 * 使用场景：
 * - 上传PDF文献文件
 * - 上传Excel批量导入文件
 * - 上传用户头像等静态资源
 * 
 * @example
 * ```typescript
 * import { storage } from '@/common/storage'
 * 
 * // 上传文件
 * const url = await storage.upload('literature/123.pdf', buffer)
 * 
 * // 下载文件
 * const buffer = await storage.download('literature/123.pdf')
 * 
 * // 删除文件
 * await storage.delete('literature/123.pdf')
 * 
 * // 获取URL
 * const url = storage.getUrl('literature/123.pdf')
 * ```
 */
export interface StorageAdapter {
  /**
   * 上传文件
   * @param key 文件存储路径（相对路径，如：literature/123.pdf）
   * @param buffer 文件内容（二进制数据）
   * @returns 文件访问URL
   */
  upload(key: string, buffer: Buffer): Promise<string>

  /**
   * 下载文件
   * @param key 文件存储路径
   * @returns 文件内容（二进制数据）
   */
  download(key: string): Promise<Buffer>

  /**
   * 删除文件
   * @param key 文件存储路径
   */
  delete(key: string): Promise<void>

  /**
   * 获取文件访问URL
   * @param key 文件存储路径
   * @returns 文件访问URL（本地：http://localhost:3001/uploads/xxx，OSS：https://xxx.oss-cn-hangzhou.aliyuncs.com/xxx）
   */
  getUrl(key: string): string

  /**
   * 检查文件是否存在
   * @param key 文件存储路径
   * @returns 是否存在
   */
  exists(key: string): Promise<boolean>
}