namespace Extrudex.Domain.Interfaces;

/// <summary>
/// Detects low-stock filament spools based on configurable weight thresholds.
/// Determines whether a spool's remaining filament falls below a critical level
/// so that alerts and API flags can be surfaced to the user.
/// </summary>
public interface ILowStockDetector
{
    /// <summary>
    /// Determines whether a spool is considered low stock based on its remaining
    /// weight relative to its total weight and the configured threshold percentage.
    /// </summary>
    /// <param name="weightRemainingGrams">The current remaining weight in grams.</param>
    /// <param name="weightTotalGrams">The total spool weight in grams when full.</param>
    /// <returns>
    /// <c>true</c> if the remaining weight percentage is at or below the configured
    /// low-stock threshold; <c>false</c> otherwise. Returns <c>false</c> for spools
    /// with zero total weight to avoid division-by-zero.
    /// </returns>
    bool IsLowStock(decimal weightRemainingGrams, decimal weightTotalGrams);

    /// <summary>
    /// Calculates the remaining weight as a percentage of total weight.
    /// </summary>
    /// <param name="weightRemainingGrams">The current remaining weight in grams.</param>
    /// <param name="weightTotalGrams">The total spool weight in grams when full.</param>
    /// <returns>
    /// A value between 0 and 100 representing the percentage of filament remaining.
    /// Returns 0 if total weight is zero to avoid division-by-zero.
    /// </returns>
    decimal GetRemainingWeightPercent(decimal weightRemainingGrams, decimal weightTotalGrams);

    /// <summary>
    /// Gets the currently configured low-stock threshold percentage.
    /// Useful for API responses so clients know what threshold is in effect.
    /// </summary>
    decimal LowStockThresholdPercent { get; }
}