Merge remote-tracking branch 'origin/dev' into fix-pr-22

# Conflicts:
#	backend/Domain/Interfaces/IMoonrakerClient.cs
#	backend/Infrastructure/Services/MoonrakerClient.cs
#	backend/Program.cs
#	backend/appsettings.json

backend/Domain/Interfaces/ICostPerPrintService.cs

@@ -0,0 +1,76 @@
+namespace Extrudex.Domain.Interfaces;
+
+/// <summary>
+/// Service interface for calculating the cost of goods sold (COGS) per print job.
+/// Uses the spool's purchase price and the print job's derived grams consumed
+/// to produce a cost breakdown. Handles missing cost data gracefully by returning
+/// warnings rather than throwing exceptions.
+/// </summary>
+public interface ICostPerPrintService
+{
+    /// <summary>
+    /// Calculates the cost per print for a specific print job.
+    /// </summary>
+    /// <param name="printJobId">The unique identifier of the print job.</param>
+    /// <param name="cancellationToken">Optional cancellation token.</param>
+    /// <returns>
+    /// A <see cref="CostPerPrintResult"/> containing the cost breakdown,
+    /// or warnings if cost data is missing or incomplete.
+    /// </returns>
+    Task<CostPerPrintResult> CalculateAsync(Guid printJobId, CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Calculates cost breakdowns for all print jobs associated with a specific spool.
+    /// Useful for spool-level COGS reporting.
+    /// </summary>
+    /// <param name="spoolId">The unique identifier of the spool.</param>
+    /// <param name="cancellationToken">Optional cancellation token.</param>
+    /// <returns>
+    /// A list of <see cref="CostPerPrintResult"/> for each print job on the spool.
+    /// Jobs with missing cost data will include warnings.
+    /// </returns>
+    Task<IReadOnlyList<CostPerPrintResult>> CalculateBySpoolAsync(Guid spoolId, CancellationToken cancellationToken = default);
+}
+
+/// <summary>
+/// Result of a cost-per-print calculation. Contains the cost breakdown
+/// and any warnings about missing or incomplete cost data.
+/// </summary>
+public class CostPerPrintResult
+{
+    /// <summary>The print job identifier this result belongs to.</summary>
+    public Guid PrintJobId { get; set; }
+
+    /// <summary>Human-readable name of the print job.</summary>
+    public string PrintName { get; set; } = string.Empty;
+
+    /// <summary>The spool identifier that provided filament.</summary>
+    public Guid SpoolId { get; set; }
+
+    /// <summary>Serial number of the spool.</summary>
+    public string SpoolSerial { get; set; } = string.Empty;
+
+    /// <summary>Total millimeters of filament extruded.</summary>
+    public decimal MmExtruded { get; set; }
+
+    /// <summary>Derived grams consumed for this print.</summary>
+    public decimal GramsDerived { get; set; }
+
+    /// <summary>The spool's purchase price. Null if not recorded.</summary>
+    public decimal? PurchasePrice { get; set; }
+
+    /// <summary>The spool's total weight in grams when full.</summary>
+    public decimal? WeightTotalGrams { get; set; }
+
+    /// <summary>Cost per gram of filament. Null if purchase price or total weight is missing.</summary>
+    public decimal? CostPerGram { get; set; }
+
+    /// <summary>Calculated cost of this print job. Null if cost data is incomplete.</summary>
+    public decimal? CostPerPrint { get; set; }
+
+    /// <summary>
+    /// Warnings about missing or incomplete data that prevented a full calculation.
+    /// Empty when all data is available and the calculation succeeded.
+    /// </summary>
+    public List<string> Warnings { get; set; } = new();
+}

backend/Domain/Interfaces/IFilamentUsageSyncService.cs

@@ -0,0 +1,19 @@
+namespace Extrudex.Domain.Interfaces;
+
+/// <summary>
+/// Service interface for syncing filament usage data from printers
+/// into the Extrudex database. Handles querying Moonraker printers,
+/// computing derived usage metrics, and persisting updates to spools
+/// and print job records.
+/// </summary>
+public interface IFilamentUsageSyncService
+{
+    /// <summary>
+    /// Performs a single sync cycle: queries all active Moonraker printers,
+    /// fetches their current filament usage data, and persists updates to
+    /// the database.
+    /// </summary>
+    /// <param name="cancellationToken">Cancellation token for graceful shutdown.</param>
+    /// <returns>The number of printers successfully synced.</returns>
+    Task<int> SyncAllAsync(CancellationToken cancellationToken = default);
+}

backend/Domain/Interfaces/IMoonrakerClient.cs

@@ -1,76 +1,39 @@
 namespace Extrudex.Domain.Interfaces;
 
 /// <summary>
-/// Client for communicating with Moonraker REST API on Klipper-based printers
-/// (e.g., Elegoo Centauri Carbon). Retrieves print job metadata including
-/// filament usage data.
+/// Client interface for communicating with Moonraker REST API endpoints
+/// on Klipper-based printers (e.g., Elegoo Centauri Carbon).
+/// Used to retrieve filament usage data, print job status, and
+/// remaining spool weight from the printer.
 /// </summary>
 public interface IMoonrakerClient
 {
     /// <summary>
-    /// Retrieves the current printer status from Moonraker.
+    /// Fetches the current filament usage data from the Moonraker server.
+    /// Returns a dictionary of usage metrics reported by the printer.
     /// </summary>
-    /// <param name="hostnameOrIp">Printer hostname or IP address.</param>
-    /// <param name="port">Moonraker port (default: 7125).</param>
+    /// <param name="hostnameOrIp">The printer's hostname or IP address.</param>
+    /// <param name="port">The Moonraker API port (default: 7125).</param>
     /// <param name="apiKey">Optional API key for authentication.</param>
-    /// <param name="cancellationToken">Cancellation token.</param>
-    /// <returns>The printer status string (e.g., "idle", "printing", "paused", "error").</returns>
-    Task<string> GetPrinterStatusAsync(
+    /// <param name="cancellationToken">Cancellation token for the HTTP request.</param>
+    /// <returns>A dictionary of usage metric names to their decimal values.</returns>
+    Task<Dictionary<string, decimal>> GetFilamentUsageAsync(
         string hostnameOrIp,
         int port,
-        string? apiKey = null,
+        string? apiKey,
         CancellationToken cancellationToken = default);
 
     /// <summary>
-    /// Retrieves filament usage data from the current or most recent print job.
-    /// Moonraker exposes this via the /api/objects endpoint querying
-    /// "history" and "print_stats" objects.
+    /// Checks whether the Moonraker server is reachable and responding.
     /// </summary>
-    /// <param name="hostnameOrIp">Printer hostname or IP address.</param>
-    /// <param name="port">Moonraker port (default: 7125).</param>
+    /// <param name="hostnameOrIp">The printer's hostname or IP address.</param>
+    /// <param name="port">The Moonraker API port (default: 7125).</param>
     /// <param name="apiKey">Optional API key for authentication.</param>
-    /// <param name="cancellationToken">Cancellation token.</param>
-    /// <returns> Filament usage data from Moonraker, or null if unavailable.</returns>
-    Task<MoonrakerFilamentUsage?> GetFilamentUsageAsync(
+    /// <param name="cancellationToken">Cancellation token for the HTTP request.</param>
+    /// <returns><c>true</c> if the server responded successfully; otherwise <c>false</c>.</returns>
+    Task<bool> IsReachableAsync(
         string hostnameOrIp,
         int port,
-        string? apiKey = null,
+        string? apiKey,
         CancellationToken cancellationToken = default);
-}
-
-/// <summary>
-/// Represents filament usage data retrieved from a Moonraker-equipped printer.
-/// Maps to Moonraker's print_stats and history objects.
-/// </summary>
-public class MoonrakerFilamentUsage
-{
-    /// <summary>
-    /// Millimeters of filament extruded during the print job.
-    /// </summary>
-    public decimal MmExtruded { get; set; }
-
-    /// <summary>
-    /// The filename of the G-code file being or recently printed.
-    /// </summary>
-    public string? GcodeFileName { get; set; }
-
-    /// <summary>
-    /// Current print state from Moonraker (e.g., "printing", "complete", "error").
-    /// </summary>
-    public string PrintState { get; set; } = string.Empty;
-
-    /// <summary>
-    /// Total print time in seconds, if available from Moonraker.
-    /// </summary>
-    public double? PrintDurationSeconds { get; set; }
-
-    /// <summary>
-    /// Timestamp (UTC) when the print job was started, if available.
-    /// </summary>
-    public DateTime? StartedAt { get; set; }
-
-    /// <summary>
-    /// Timestamp (UTC) when the print job completed, if available.
-    /// </summary>
-    public DateTime? CompletedAt { get; set; }
 }