dramaling-vocab-learning/backend/DramaLing.Api/Repositories/IFlashcardRepository.cs

using DramaLing.Api.Models.Entities;

namespace DramaLing.Api.Repositories;

/// <summary>
/// Flashcard 專門的 Repository 介面，包含業務特定的查詢方法
/// </summary>
public interface IFlashcardRepository : IRepository<Flashcard>
{
    // 用戶相關查詢
    Task<IEnumerable<Flashcard>> GetFlashcardsByUserIdAsync(Guid userId);
    Task<IEnumerable<Flashcard>> GetFlashcardsByCardSetIdAsync(Guid cardSetId);

    // 學習相關查詢
    Task<IEnumerable<Flashcard>> GetDueFlashcardsAsync(Guid userId, DateTime dueDate);
    Task<IEnumerable<Flashcard>> GetFlashcardsByDifficultyAsync(Guid userId, string difficultyLevel);
    Task<IEnumerable<Flashcard>> GetRecentlyAddedAsync(Guid userId, int count);
    Task<IEnumerable<Flashcard>> GetMostReviewedAsync(Guid userId, int count);

    // 統計查詢
    Task<int> GetTotalFlashcardsCountAsync(Guid userId);
    Task<int> GetMasteredFlashcardsCountAsync(Guid userId);
    Task<Dictionary<string, int>> GetFlashcardsByDifficultyStatsAsync(Guid userId);

    // 搜尋功能
    Task<IEnumerable<Flashcard>> SearchFlashcardsAsync(Guid userId, string searchTerm);
    Task<IEnumerable<Flashcard>> GetFavoriteFlashcardsAsync(Guid userId);
    Task<IEnumerable<Flashcard>> GetArchivedFlashcardsAsync(Guid userId);

    // 批次操作
    Task<bool> BulkUpdateMasteryLevelAsync(IEnumerable<Guid> flashcardIds, int newMasteryLevel);
    Task<bool> BulkUpdateNextReviewDateAsync(IEnumerable<Guid> flashcardIds, DateTime newDate);

    // 性能優化查詢
    Task<IEnumerable<Flashcard>> GetFlashcardsWithIncludesAsync(Guid userId,
        bool includeTags = false,
        bool includeStudyRecords = false);
}