import '../entities/inspiration_image.dart';

/// 图片仓库接口 - 定义图片数据访问的业务逻辑契约
/// 作为领域层和数据层之间的桥梁，屏蔽数据源实现细节
abstract class ImageRepository {
  /// 保存单张图片 - 将图片持久化存储
  /// [image] 要保存的图片实体
  /// 返回保存后的图片ID
  Future<String> saveImage(InspirationImage image);

  /// 批量保存图片 - 一次性保存多张图片
  /// [images] 要保存的图片实体列表
  /// 返回保存成功的图片ID列表
  Future<List<String>> saveImages(List<InspirationImage> images);

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

  /// 获取所有图片 - 获取用户保存的所有图片
  /// 返回所有图片实体列表，通常按创建时间倒序排列
  Future<List<InspirationImage>> getAllImages();

  /// 分页获取图片 - 支持大数据集的懒加载
  /// [page] 页码，从0开始
  /// [pageSize] 每页数量
  /// 返回指定页码的图片列表
  Future<List<InspirationImage>> getImagesPaginated(int page, int pageSize);

  /// 根据文件夹获取图片 - 获取指定文件夹内的所有图片
  /// [folderId] 文件夹的唯一标识符
  /// 返回该文件夹内的图片列表
  Future<List<InspirationImage>> getImagesByFolder(String folderId);

  /// 根据标签获取图片 - 获取包含指定标签的所有图片
  /// [tagId] 标签的唯一标识符
  /// 返回包含该标签的图片列表
  Future<List<InspirationImage>> getImagesByTag(String tagId);

  /// 搜索图片 - 根据关键词模糊搜索图片
  /// [query] 搜索关键词，会搜索文件夹名称、标签名称和备注内容
  /// 返回匹配的图片列表
  Future<List<InspirationImage>> searchImages(String query);

  /// 获取收藏图片 - 获取用户标记为收藏的所有图片
  /// 返回收藏的图片列表
  Future<List<InspirationImage>> getFavoriteImages();

  /// 更新图片信息 - 修改图片的元数据（如备注、标签等）
  /// [image] 包含更新数据的图片实体
  /// 返回更新后的图片实体
  Future<InspirationImage> updateImage(InspirationImage image);

  /// 批量更新图片 - 一次性更新多张图片
  /// [images] 要更新的图片实体列表
  /// 返回更新后的图片实体列表
  Future<List<InspirationImage>> updateImages(List<InspirationImage> images);

  /// 删除单张图片 - 从存储中移除指定图片
  /// [id] 要删除的图片ID
  /// 返回是否删除成功
  Future<bool> deleteImage(String id);

  /// 批量删除图片 - 一次性删除多张图片
  /// [ids] 要删除的图片ID列表
  /// 返回是否删除成功
  Future<bool> deleteImages(List<String> ids);

  /// 根据文件夹删除图片 - 清空指定文件夹内的所有图片
  /// [folderId] 要清空的文件夹ID
  /// 返回删除的图片数量
  Future<int> deleteImagesByFolder(String folderId);

  /// 获取图片总数 - 统计用户保存的图片数量
  /// 返回图片总数
  Future<int> getImageCount();

  /// 获取文件夹图片数量 - 统计指定文件夹内的图片数量
  /// [folderId] 文件夹ID
  /// 返回该文件夹内的图片数量
  Future<int> getImageCountByFolder(String folderId);

  /// 检查图片是否存在 - 验证指定ID的图片是否存在
  /// [id] 图片ID
  /// 返回图片是否存在
  Future<bool> imageExists(String id);
}