CUB-38: implement low filament alert logic with configurable threshold

backend/API/Controllers/FilamentsController.cs

@@ -1,6 +1,7 @@
 using Extrudex.API.DTOs;
 using Extrudex.API.DTOs.Filaments;
 using Extrudex.Domain.Entities;
+using Extrudex.Domain.Interfaces;
 using Extrudex.Infrastructure.Data;
 using Microsoft.AspNetCore.Mvc;
 using Microsoft.EntityFrameworkCore;
@@ -17,16 +18,22 @@ namespace Extrudex.API.Controllers;
 public class FilamentsController : ControllerBase
 {
     private readonly ExtrudexDbContext _dbContext;
+    private readonly ILowStockDetector _lowStockDetector;
     private readonly ILogger<FilamentsController> _logger;
 
     /// <summary>
     /// Initializes a new instance of the <see cref="FilamentsController"/> class.
     /// </summary>
     /// <param name="dbContext">The database context for data access.</param>
+    /// <param name="lowStockDetector">The low-stock detection service for filament alerts.</param>
     /// <param name="logger">The logger for diagnostic output.</param>
-    public FilamentsController(ExtrudexDbContext dbContext, ILogger<FilamentsController> logger)
+    public FilamentsController(
+        ExtrudexDbContext dbContext,
+        ILowStockDetector lowStockDetector,
+        ILogger<FilamentsController> logger)
     {
         _dbContext = dbContext;
+        _lowStockDetector = lowStockDetector;
         _logger = logger;
     }
 
@@ -83,7 +90,7 @@ public class FilamentsController : ControllerBase
             .OrderByDescending(s => s.CreatedAt)
             .Skip((pageNumber - 1) * pageSize)
             .Take(pageSize)
-            .Select(s => MapToFilamentResponse(s))
+            .Select(s => MapToFilamentResponse(s, _lowStockDetector))
             .ToListAsync();
 
         var response = new PagedResponse<FilamentResponse>
@@ -124,7 +131,7 @@ public class FilamentsController : ControllerBase
             return NotFound(new { error = $"Filament with ID '{id}' not found." });
         }
 
-        return Ok(MapToFilamentResponse(spool));
+        return Ok(MapToFilamentResponse(spool, _lowStockDetector));
     }
 
     /// <summary>
@@ -197,7 +204,7 @@ public class FilamentsController : ControllerBase
         if (entity.MaterialModifierId.HasValue)
             await _dbContext.Entry(entity).Reference(s => s.MaterialModifier).LoadAsync();
 
-        var response = MapToFilamentResponse(entity);
+        var response = MapToFilamentResponse(entity, _lowStockDetector);
         return CreatedAtAction(nameof(GetFilament), new { id = entity.Id }, response);
     }
 
@@ -276,7 +283,37 @@ public class FilamentsController : ControllerBase
         if (entity.MaterialModifierId.HasValue)
             await _dbContext.Entry(entity).Reference(s => s.MaterialModifier).LoadAsync();
 
-        return Ok(MapToFilamentResponse(entity));
+        return Ok(MapToFilamentResponse(entity, _lowStockDetector));
+    }
+
+    /// <summary>
+    /// Gets only the filament spools that are flagged as low stock.
+    /// A spool is considered low stock when its remaining weight percentage
+    /// is at or below the configured threshold.
+    /// </summary>
+    /// <returns>A list of low-stock filament spools with alert metadata.</returns>
+    /// <response code="200">Returns the list of low-stock filament spools.</response>
+    [HttpGet("low-stock")]
+    [ProducesResponseType(typeof(List<FilamentResponse>), StatusCodes.Status200OK)]
+    public async Task<ActionResult<List<FilamentResponse>>> GetLowStockFilaments()
+    {
+        _logger.LogDebug("Getting low-stock filaments (threshold: {Threshold}%)",
+            _lowStockDetector.LowStockThresholdPercent);
+
+        var spools = await _dbContext.Spools
+            .Include(s => s.MaterialBase)
+            .Include(s => s.MaterialFinish)
+            .Include(s => s.MaterialModifier)
+            .Where(s => s.IsActive)
+            .OrderByDescending(s => s.CreatedAt)
+            .ToListAsync();
+
+        var lowStockItems = spools
+            .Where(s => _lowStockDetector.IsLowStock(s.WeightRemainingGrams, s.WeightTotalGrams))
+            .Select(s => MapToFilamentResponse(s, _lowStockDetector))
+            .ToList();
+
+        return Ok(lowStockItems);
     }
 
     // ── Mapping helper ─────────────────────────────────────────
@@ -285,10 +322,12 @@ public class FilamentsController : ControllerBase
     /// Maps a Spool domain entity to a FilamentResponse DTO.
     /// Denormalizes material names for display convenience.
     /// Populates the QrCodeUrl for easy frontend access to the spool's QR code.
+    /// Calculates low-stock status and remaining weight percentage.
     /// </summary>
     /// <param name="s">The spool entity to map.</param>
-    /// <returns>A FilamentResponse DTO with denormalized material names and QR code URL.</returns>
-    private static FilamentResponse MapToFilamentResponse(Spool s) => new()
+    /// <param name="lowStockDetector">The low-stock detection service for computing alert flags.</param>
+    /// <returns>A FilamentResponse DTO with denormalized material names, QR code URL, and low-stock metadata.</returns>
+    private static FilamentResponse MapToFilamentResponse(Spool s, ILowStockDetector lowStockDetector) => new()
     {
         Id = s.Id,
         MaterialBaseId = s.MaterialBaseId,
@@ -309,6 +348,8 @@ public class FilamentsController : ControllerBase
         IsActive = s.IsActive,
         CreatedAt = s.CreatedAt,
         UpdatedAt = s.UpdatedAt,
-        QrCodeUrl = $"/api/qr/spool/{s.Id}"
+        QrCodeUrl = $"/api/qr/spool/{s.Id}",
+        IsLowStock = lowStockDetector.IsLowStock(s.WeightRemainingGrams, s.WeightTotalGrams),
+        RemainingWeightPercent = lowStockDetector.GetRemainingWeightPercent(s.WeightRemainingGrams, s.WeightTotalGrams)
     };
 }

backend/API/DTOs/Filaments/FilamentDtos.cs

@@ -70,6 +70,19 @@ public class FilamentResponse
     /// Encodes a deep link to the spool's detail page.
     /// </summary>
     public string QrCodeUrl { get; set; } = string.Empty;
+
+    /// <summary>
+    /// Whether this spool is flagged as low stock — remaining weight is at or
+    /// below the configured low-stock threshold percentage.
+    /// Useful for UI alerts and inventory dashboards.
+    /// </summary>
+    public bool IsLowStock { get; set; }
+
+    /// <summary>
+    /// Remaining filament weight as a percentage of total weight (0–100).
+    /// Rounded to one decimal place. Returns 0 if total weight is zero.
+    /// </summary>
+    public decimal RemainingWeightPercent { get; set; }
 }
 
 /// <summary>