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

using DramaLing.Api.Models.Entities;
using DramaLing.Api.Models.DTOs;

namespace DramaLing.Api.Repositories;

public interface IFlashcardReviewRepository : IRepository<FlashcardReview>
{
    /// <summary>
    /// 獲取待複習的詞卡（包含複習記錄）
    /// </summary>
    Task<IEnumerable<(Flashcard Flashcard, FlashcardReview? Review)>> GetDueFlashcardsAsync(
        Guid userId,
        DueFlashcardsQuery query);

    /// <summary>
    /// 獲取或創建詞卡的複習記錄
    /// </summary>
    Task<FlashcardReview> GetOrCreateReviewAsync(Guid userId, Guid flashcardId);

    /// <summary>
    /// 根據用戶ID和詞卡ID獲取複習記錄
    /// </summary>
    Task<FlashcardReview?> GetByUserAndFlashcardAsync(Guid userId, Guid flashcardId);

    /// <summary>
    /// 獲取用戶的複習統計
    /// </summary>
    Task<(int TodayDue, int Overdue, int TotalReviews)> GetReviewStatsAsync(Guid userId);

    /// <summary>
    /// 獲取今天到期的詞卡數量
    /// </summary>
    Task<int> GetTodayDueCountAsync(Guid userId);

    /// <summary>
    /// 獲取過期的詞卡數量
    /// </summary>
    Task<int> GetOverdueCountAsync(Guid userId);

    /// <summary>
    /// 更新複習記錄
    /// </summary>
    Task UpdateReviewAsync(FlashcardReview review);
}