CUB-32: Add usage logging service with EF Core entity, service, controller, and migration

backend/Domain/Entities/UsageLog.cs

@@ -0,0 +1,72 @@
+using Extrudex.Domain.Base;
+using Extrudex.Domain.Enums;
+
+namespace Extrudex.Domain.Entities;
+
+/// <summary>
+/// Represents a single filament usage log entry. Records how much filament
+/// was consumed, by which printer, at what time, and optionally linked to
+/// a print job. This provides a fine-grained audit trail of filament consumption
+/// independent of print job lifecycle.
+/// </summary>
+public class UsageLog : AuditableEntity
+{
+    /// <summary>
+    /// Foreign key to the spool that provided the filament.
+    /// </summary>
+    public Guid SpoolId { get; set; }
+
+    /// <summary>
+    /// Navigation to the spool that provided the filament.
+    /// </summary>
+    public Spool Spool { get; set; } = null!;
+
+    /// <summary>
+    /// Foreign key to the printer that consumed the filament.
+    /// Nullable to support manual entries without a specific printer.
+    /// </summary>
+    public Guid? PrinterId { get; set; }
+
+    /// <summary>
+    /// Navigation to the printer that consumed the filament.
+    /// </summary>
+    public Printer? Printer { get; set; }
+
+    /// <summary>
+    /// Foreign key to the print job associated with this usage entry.
+    /// Nullable because usage can be logged before or without a print job.
+    /// </summary>
+    public Guid? PrintJobId { get; set; }
+
+    /// <summary>
+    /// Navigation to the print job associated with this usage entry.
+    /// </summary>
+    public PrintJob? PrintJob { get; set; }
+
+    /// <summary>
+    /// The number of grams of filament consumed in this usage event.
+    /// </summary>
+    public decimal GramsUsed { get; set; }
+
+    /// <summary>
+    /// The number of millimeters of filament extruded in this usage event.
+    /// Optional — may not be available for all data sources.
+    /// </summary>
+    public decimal? MmExtruded { get; set; }
+
+    /// <summary>
+    /// Timestamp when the usage occurred (UTC). This is the actual time of
+    /// consumption, which may differ from CreatedAt if the entry was recorded later.
+    /// </summary>
+    public DateTime UsageTimestamp { get; set; } = DateTime.UtcNow;
+
+    /// <summary>
+    /// The source of the usage data (which integration path provided it).
+    /// </summary>
+    public DataSource DataSource { get; set; } = DataSource.Manual;
+
+    /// <summary>
+    /// Optional notes about this usage entry.
+    /// </summary>
+    public string? Notes { get; set; }
+}