Extrudex/backend/Domain/Entities/UsageLog.cs

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; }
}