/**
 * 通用存储适配器接口
 * 提供统一的数据存储操作方法，支持不同类型的持久化方案（数据库、文件系统、内存等）
 */

/**
 * 存储配置接口
 */
export interface StorageConfig {
  /**
   * 存储类型标识
   */
  type: string;
  
  /**
   * 连接配置或路径配置
   */
  connection?: Record<string, any>;
  
  /**
   * 存储特定的配置参数
   */
  options?: Record<string, any>;
}

/**
 * 查询条件接口
 */
export interface QueryCondition {
  /**
   * 字段名与值的映射
   */
  [key: string]: any;
  
  /**
   * 模糊匹配字段
   */
  $like?: Record<string, string>;
  
  /**
   * 范围查询字段
   */
  $gt?: Record<string, any>;
  $gte?: Record<string, any>;
  $lt?: Record<string, any>;
  $lte?: Record<string, any>;
  
  /**
   * 包含查询字段
   */
  $in?: Record<string, any[]>;
  
  /**
   * 不等于查询字段
   */
  $ne?: Record<string, any>;
  
  /**
   * 逻辑与
   */
  $and?: QueryCondition[];
  
  /**
   * 逻辑或
   */
  $or?: QueryCondition[];
}

/**
 * 排序条件接口
 */
export interface SortOption {
  /**
   * 字段名与排序方向的映射
   */
  [key: string]: 'asc' | 'desc';
}

/**
 * 通用存储适配器接口定义
 */
export interface StorageAdapter {
  /**
   * 初始化存储连接
   * @param config 存储配置
   * @returns Promise<void>
   */
  initialize(config: StorageConfig): Promise<void>;
  
  /**
   * 关闭存储连接
   * @returns Promise<void>
   */
  close(): Promise<void>;
  
  /**
   * 创建记录
   * @param namespace 命名空间/集合/表名
   * @param data 要创建的数据
   * @returns Promise<T> 创建后的记录
   */
  create<T>(namespace: string, data: Partial<T>): Promise<T>;
  
  /**
   * 根据ID获取记录
   * @param namespace 命名空间/集合/表名
   * @param id 记录ID
   * @returns Promise<T | null> 查询到的记录或null
   */
  getById<T>(namespace: string, id: string): Promise<T | null>;
  
  /**
   * 根据条件查询记录
   * @param namespace 命名空间/集合/表名
   * @param query 查询条件
   * @param skip 跳过的记录数
   * @param limit 返回的最大记录数
   * @param sort 排序条件
   * @returns Promise<{data: T[], total: number}> 查询结果和总记录数
   */
  find<T>(
    namespace: string, 
    query?: QueryCondition, 
    skip?: number, 
    limit?: number,
    sort?: SortOption
  ): Promise<{data: T[], total: number}>;
  
  /**
   * 更新记录
   * @param namespace 命名空间/集合/表名
   * @param id 记录ID
   * @param data 更新的数据
   * @returns Promise<T | null> 更新后的记录或null
   */
  update<T>(namespace: string, id: string, data: Partial<T>): Promise<T | null>;
  
  /**
   * 删除记录
   * @param namespace 命名空间/集合/表名
   * @param id 记录ID
   * @returns Promise<boolean> 是否删除成功
   */
  delete(namespace: string, id: string): Promise<boolean>;
  
  /**
   * 批量创建记录
   * @param namespace 命名空间/集合/表名
   * @param dataList 要创建的记录列表
   * @returns Promise<T[]> 创建后的记录列表
   */
  bulkCreate<T>(namespace: string, dataList: Partial<T>[]): Promise<T[]>;
  
  /**
   * 检查存储是否可用
   * @returns Promise<boolean> 存储是否可用
   */
  isAvailable(): Promise<boolean>;
}