import '../entities/image_folder.dart';

/// 文件夹仓库接口 - 定义文件夹数据访问的业务逻辑契约
/// 作为领域层和数据层之间的桥梁，屏蔽数据源实现细节
abstract class FolderRepository {
  /// 创建文件夹 - 创建新的图片文件夹
  /// [folder] 要创建的文件夹实体
  /// 返回创建后的文件夹ID
  Future<String> createFolder(ImageFolder folder);

  /// 根据ID获取文件夹 - 通过唯一标识符查找文件夹
  /// [id] 文件夹的唯一标识符
  /// 返回找到的文件夹实体，如果不存在则返回null
  Future<ImageFolder?> getFolder(String id);

  /// 获取所有文件夹 - 获取用户创建的所有文件夹
  /// 返回所有文件夹实体列表，通常按最近使用时间倒序排列
  Future<List<ImageFolder>> getAllFolders();

  /// 获取最近使用的文件夹 - 获取用户最近访问的文件夹
  /// [limit] 返回数量限制，如果为null则返回所有文件夹
  /// 返回最近使用的文件夹列表
  Future<List<ImageFolder>> getRecentFolders({int? limit});

  /// 更新文件夹信息 - 修改文件夹的元数据（如名称、图标等）
  /// [folder] 包含更新数据的文件夹实体
  /// 返回更新后的文件夹实体
  Future<ImageFolder> updateFolder(ImageFolder folder);

  /// 更新文件夹使用时间 - 记录文件夹的最近访问时间
  /// [folderId] 文件夹ID
  /// 返回更新后的文件夹实体，如果文件夹不存在则返回null
  Future<ImageFolder?> updateFolderLastUsed(String folderId);

  /// 更新文件夹封面 - 设置文件夹的封面图片
  /// [folderId] 文件夹ID
  /// [coverImageId] 封面图片ID，可为null表示移除封面
  /// 返回更新后的文件夹实体，如果文件夹不存在则返回null
  Future<ImageFolder?> updateFolderCover(String folderId, String? coverImageId);

  /// 删除文件夹 - 从存储中移除指定文件夹
  /// [id] 要删除的文件夹ID
  /// 返回是否删除成功
  Future<bool> deleteFolder(String id);

  /// 检查文件夹是否存在 - 验证指定ID的文件夹是否存在
  /// [id] 文件夹ID
  /// 返回文件夹是否存在
  Future<bool> folderExists(String id);

  /// 获取文件夹总数 - 统计用户创建的文件夹数量
  /// 返回文件夹总数
  Future<int> getFolderCount();

  /// 获取默认文件夹 - 获取系统的默认文件夹
  /// 如果默认文件夹不存在，则创建它
  /// 返回默认文件夹实体
  Future<ImageFolder> getDefaultFolder();

  /// 搜索文件夹 - 根据名称模糊搜索文件夹
  /// [query] 搜索关键词
  /// 返回匹配的文件夹列表
  Future<List<ImageFolder>> searchFolders(String query);

  /// 获取未使用的文件夹 - 获取空的文件夹（不包含任何图片）
  /// 返回未使用的文件夹列表
  Future<List<ImageFolder>> getUnusedFolders();
}