DeutschLernen/GermanApp/Domain/Interfaces/IStoryProgressRepository.cs

using System.Collections.Generic;
using System.Threading;
using System.Threading.Tasks;
using GermanApp.Domain.Entities;

namespace GermanApp.Domain.Interfaces;

/// <summary>
/// Repository interface for managing StoryProgress entities.
/// This is part of the Domain layer.
/// </summary>
public interface IStoryProgressRepository
{
    /// <summary>
    /// Gets story progress for a specific user and level.
    /// </summary>
    /// <param name="userId">The user ID</param>
    /// <param name="levelId">The level ID</param>
    /// <param name="cancellationToken">Cancellation token</param>
    /// <returns>List of story progress records for the user and level</returns>
    Task<IReadOnlyList<StoryProgress>> GetByUserAndLevelAsync(
        int userId,
        int levelId,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Gets story progress for a specific user and segment.
    /// </summary>
    /// <param name="userId">The user ID</param>
    /// <param name="storySegmentId">The story segment ID</param>
    /// <param name="cancellationToken">Cancellation token</param>
    /// <returns>The story progress record, or null if not found</returns>
    Task<StoryProgress?> GetByUserAndSegmentAsync(
        int userId,
        int storySegmentId,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Gets the highest unlocked segment order for a user in a level.
    /// </summary>
    /// <param name="userId">The user ID</param>
    /// <param name="levelId">The level ID</param>
    /// <param name="cancellationToken">Cancellation token</param>
    /// <returns>The highest order of unlocked segments, or 0 if none</returns>
    Task<int> GetHighestUnlockedOrderAsync(
        int userId,
        int levelId,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Checks if a user has unlocked a specific story segment.
    /// </summary>
    /// <param name="userId">The user ID</param>
    /// <param name="storySegmentId">The story segment ID</param>
    /// <param name="cancellationToken">Cancellation token</param>
    /// <returns>True if the segment is unlocked</returns>
    Task<bool> IsSegmentUnlockedAsync(
        int userId,
        int storySegmentId,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Checks if a user has completed (read/listened to) a specific story segment.
    /// </summary>
    /// <param name="userId">The user ID</param>
    /// <param name="storySegmentId">The story segment ID</param>
    /// <param name="cancellationToken">Cancellation token</param>
    /// <returns>True if the segment is completed</returns>
    Task<bool> IsSegmentCompletedAsync(
        int userId,
        int storySegmentId,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Adds a new story progress record.
    /// </summary>
    /// <param name="progress">The story progress to add</param>
    /// <param name="cancellationToken">Cancellation token</param>
    /// <returns>The added progress with generated ID</returns>
    Task<StoryProgress> AddAsync(StoryProgress progress, CancellationToken cancellationToken = default);

    /// <summary>
    /// Updates an existing story progress record.
    /// </summary>
    /// <param name="progress">The story progress to update</param>
    /// <param name="cancellationToken">Cancellation token</param>
    Task UpdateAsync(StoryProgress progress, CancellationToken cancellationToken = default);

    /// <summary>
    /// Gets the total count of story segments for a level.
    /// </summary>
    /// <param name="levelId">The level ID</param>
    /// <param name="cancellationToken">Cancellation token</param>
    /// <returns>The total number of segments in the level</returns>
    Task<int> GetTotalSegmentsForLevelAsync(int levelId, CancellationToken cancellationToken = default);

    /// <summary>
    /// Gets the count of unlocked segments for a user in a level.
    /// </summary>
    /// <param name="userId">The user ID</param>
    /// <param name="levelId">The level ID</param>
    /// <param name="cancellationToken">Cancellation token</param>
    /// <returns>The number of unlocked segments</returns>
    Task<int> GetUnlockedCountAsync(
        int userId,
        int levelId,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Gets the count of completed segments for a user in a level.
    /// </summary>
    /// <param name="userId">The user ID</param>
    /// <param name="levelId">The level ID</param>
    /// <param name="cancellationToken">Cancellation token</param>
    /// <returns>The number of completed segments</returns>
    Task<int> GetCompletedCountAsync(
        int userId,
        int levelId,
        CancellationToken cancellationToken = default);
}