/// Status der Scan-Pipeline eines einzelnen `DeliveryItem`.
///
/// - `inProgress`: Soll-Menge noch nicht erreicht, Scanner darf weiterzählen.
/// - `done`: Soll-Menge erreicht; weitere Scans werden serverseitig abgewiesen.
/// - `held`: Pausiert (z. B. „Ware beschädigt, klärt der Fahrer mit dem Lager") —
///           `ScanProgress.heldReason` trägt die Begründung.
/// - `removed`: Item wurde nach dem Laden wieder abgebucht (Retoure, Falschladung).
enum ScanStatus { inProgress, done, held, removed }

/// Embedded Value-Object am `DeliveryItem`. Beschreibt, wie weit der Fahrer
/// mit dem Scannen dieses Items ist — *nicht*, wo das Item logistisch steht.
class ScanProgress {
  const ScanProgress({
    required this.status,
    required this.scannedQuantity,
    required this.lastUpdatedAt,
    this.creditedQuantity = 0,
    this.heldReason,
  });

  final ScanStatus status;
  final int scannedQuantity;

  /// Als Gutschrift entfernte Menge (0..=requiredQuantity). Eigene Dimension
  /// neben [scannedQuantity]: „wie viele Stück dieser Zeile hat der Kunde
  /// nicht angenommen". `status == removed` entspricht voller Gutschrift
  /// (creditedQuantity == requiredQuantity).
  final int creditedQuantity;

  final DateTime lastUpdatedAt;
  final String? heldReason;

  ScanProgress copyWith({
    ScanStatus? status,
    int? scannedQuantity,
    int? creditedQuantity,
    DateTime? lastUpdatedAt,
    String? heldReason,
  }) {
    return ScanProgress(
      status: status ?? this.status,
      scannedQuantity: scannedQuantity ?? this.scannedQuantity,
      creditedQuantity: creditedQuantity ?? this.creditedQuantity,
      lastUpdatedAt: lastUpdatedAt ?? this.lastUpdatedAt,
      heldReason: heldReason ?? this.heldReason,
    );
  }
}