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

# Conflicts:
#	backend/Program.cs
#	backend/appsettings.json

backend/Domain/Entities/FilamentUsage.cs

@@ -0,0 +1,73 @@
+using Extrudex.Domain.Base;
+
+namespace Extrudex.Domain.Entities;
+
+/// <summary>
+/// Tracks filament consumption for a specific print job on a specific spool.
+/// Each record captures the grams used, which printer consumed it, and when the
+/// usage was recorded. This enables granular per-job usage analytics, COGS
+/// reconciliation, and spool weight depletion tracking.
+///
+/// A single PrintJob may have multiple FilamentUsage records if multiple spools
+/// were consumed (e.g., multi-material prints via AMS).
+/// </summary>
+public class FilamentUsage : AuditableEntity
+{
+    /// <summary>
+    /// Foreign key to the print job that consumed this filament.
+    /// A usage record is always tied to a print job.
+    /// </summary>
+    public Guid PrintJobId { get; set; }
+
+    /// <summary>
+    /// Navigation to the print job that consumed this filament.
+    /// </summary>
+    public PrintJob PrintJob { get; set; } = null!;
+
+    /// <summary>
+    /// Foreign key to the spool (filament) that provided the material.
+    /// Links usage back to the specific physical spool for inventory tracking.
+    /// </summary>
+    public Guid SpoolId { get; set; }
+
+    /// <summary>
+    /// Navigation to the spool that provided the material.
+    /// </summary>
+    public Spool Spool { get; set; } = null!;
+
+    /// <summary>
+    /// Foreign key to the printer that executed the print job.
+    /// Denormalized from PrintJob for direct querying of per-printer usage.
+    /// </summary>
+    public Guid PrinterId { get; set; }
+
+    /// <summary>
+    /// Navigation to the printer that executed the print job.
+    /// </summary>
+    public Printer Printer { get; set; } = null!;
+
+    /// <summary>
+    /// Grams of filament consumed during this print job.
+    /// Derived from mm_extruded × cross_section_area × material_density,
+    /// or measured directly from AMS weight delta.
+    /// </summary>
+    public decimal GramsUsed { get; set; }
+
+    /// <summary>
+    /// Millimeters of filament extruded for this usage record.
+    /// The primary physical measurement; grams_used is derived from this.
+    /// </summary>
+    public decimal MmExtruded { get; set; }
+
+    /// <summary>
+    /// Timestamp when this usage record was created (UTC).
+    /// Represents when the usage was first logged, which may differ from
+    /// the print job's started_at or completed_at timestamps.
+    /// </summary>
+    public DateTime RecordedAt { get; set; } = DateTime.UtcNow;
+
+    /// <summary>
+    /// Optional notes about this usage record (e.g., "AMS tray 3", "manual weight check").
+    /// </summary>
+    public string? Notes { get; set; }
+}

backend/Domain/Entities/PrintJob.cs

@@ -97,4 +97,10 @@ public class PrintJob : AuditableEntity
     /// Optional notes about the print job (e.g., "First layer adhesion issues").
     /// </summary>
     public string? Notes { get; set; }
+
+    /// <summary>
+    /// Navigation collection of filament usage records for this print job.
+    /// Enables tracking granular per-spool consumption within a print.
+    /// </summary>
+    public ICollection<FilamentUsage> FilamentUsages { get; set; } = new List<FilamentUsage>();
 }

backend/Domain/Entities/Printer.cs

@@ -94,4 +94,10 @@ public class Printer : AuditableEntity
     /// Navigation collection of print jobs executed on this printer.
     /// </summary>
     public ICollection<PrintJob> PrintJobs { get; set; } = new List<PrintJob>();
+
+    /// <summary>
+    /// Navigation collection of filament usage records tracking consumption on this printer.
+    /// Enables querying per-printer filament usage and COGS.
+    /// </summary>
+    public ICollection<FilamentUsage> FilamentUsages { get; set; } = new List<FilamentUsage>();
 }

backend/Domain/Entities/Spool.cs

@@ -102,4 +102,10 @@ public class Spool : AuditableEntity
     /// Navigation collection of print jobs that consumed filament from this spool.
     /// </summary>
     public ICollection<PrintJob> PrintJobs { get; set; } = new List<PrintJob>();
+
+    /// <summary>
+    /// Navigation collection of filament usage records tracking consumption from this spool.
+    /// Enables querying how much filament was consumed per print job.
+    /// </summary>
+    public ICollection<FilamentUsage> FilamentUsages { get; set; } = new List<FilamentUsage>();
 }

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

@@ -0,0 +1,39 @@
+namespace Extrudex.Domain.Interfaces;
+
+/// <summary>
+/// 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>
+    /// Fetches the current filament usage data from the Moonraker server.
+    /// Returns a dictionary of usage metrics reported by the printer.
+    /// </summary>
+    /// <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 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,
+        CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Checks whether the Moonraker server is reachable and responding.
+    /// </summary>
+    /// <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 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,
+        CancellationToken cancellationToken = default);
+}