using Extrudex.Domain.Entities;

namespace Extrudex.Domain.Interfaces;

/// <summary>
/// Service for persisting and querying filament usage records.
/// Tracks consumption per print job and per spool for COGS and inventory tracking.
/// </summary>
public interface IFilamentUsageService
{
    /// <summary>
    /// Records a new filament usage entry for a print job.
    /// </summary>
    /// <param name="printJobId">The print job that consumed the filament.</param>
    /// <param name="spoolId">The spool that provided the filament.</param>
    /// <param name="printerId">The printer that executed the print.</param>
    /// <param name="gramsUsed">Grams of filament consumed.</param>
    /// <param name="mmExtruded">Millimeters of filament extruded.</param>
    /// <param name="notes">Optional notes about this usage record.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>The created FilamentUsage entity.</returns>
    Task<FilamentUsage> RecordUsageAsync(
        Guid printJobId,
        Guid spoolId,
        Guid printerId,
        decimal gramsUsed,
        decimal mmExtruded,
        string? notes = null,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Retrieves all filament usage records for a specific print job.
    /// </summary>
    /// <param name="printJobId">The print job ID.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>Collection of filament usage records for the print job.</returns>
    Task<IReadOnlyList<FilamentUsage>> GetByPrintJobAsync(
        Guid printJobId,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Retrieves all filament usage records for a specific spool.
    /// </summary>
    /// <param name="spoolId">The spool ID.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>Collection of filament usage records for the spool.</returns>
    Task<IReadOnlyList<FilamentUsage>> GetBySpoolAsync(
        Guid spoolId,
        CancellationToken cancellationToken = default);
}