// SPDX-FileCopyrightText: 2026 FocusFlow contributors
// SPDX-License-Identifier: AGPL-3.0-only

part of '../../document_migration.dart';

/// Typed dry-run report for one document migration attempt.
class DocumentMigrationReport {
  /// Creates a `DocumentMigrationReport` instance with the values required by its invariants.
  /// Callers should pass already-normalized scheduler data because validation and defaulting belong at the model or service boundary, not in arbitrary UI code.
  const DocumentMigrationReport({
    required this.entity,
    required this.status,
    required this.documentId,
    required this.fromSchemaVersion,
    this.targetSchemaVersion = v1SchemaVersion,
    this.failureCode,
    this.mappingFailureCode,
    this.fieldName,
    this.detailCode,
    this.notes = const <DocumentMigrationNote>[],
  });

  /// Stores the `entity` value for this object.
  /// This field is part of the explicit state that downstream scheduling, persistence, or UI code reads when composing behavior.
  final DocumentMigrationEntity entity;

  /// Stores the `status` value for this object.
  /// This field is part of the explicit state that downstream scheduling, persistence, or UI code reads when composing behavior.
  final DocumentMigrationStatus status;

  /// Stores the `documentId` value for this object.
  /// This field is part of the explicit state that downstream scheduling, persistence, or UI code reads when composing behavior.
  final String? documentId;

  /// Stores the `fromSchemaVersion` value for this object.
  /// This field is part of the explicit state that downstream scheduling, persistence, or UI code reads when composing behavior.
  final int? fromSchemaVersion;

  /// Stores the `targetSchemaVersion` value for this object.
  /// This field is part of the explicit state that downstream scheduling, persistence, or UI code reads when composing behavior.
  final int targetSchemaVersion;

  /// Stores the `failureCode` value for this object.
  /// This field is part of the explicit state that downstream scheduling, persistence, or UI code reads when composing behavior.
  final DocumentMigrationFailureCode? failureCode;

  /// Stores the `mappingFailureCode` value for this object.
  /// This field is part of the explicit state that downstream scheduling, persistence, or UI code reads when composing behavior.
  final DocumentMappingFailureCode? mappingFailureCode;

  /// Stores the `fieldName` value for this object.
  /// This field is part of the explicit state that downstream scheduling, persistence, or UI code reads when composing behavior.
  final String? fieldName;

  /// Stores the `detailCode` value for this object.
  /// This field is part of the explicit state that downstream scheduling, persistence, or UI code reads when composing behavior.
  final String? detailCode;

  /// Stores the `notes` value for this object.
  /// This field is part of the explicit state that downstream scheduling, persistence, or UI code reads when composing behavior.
  final List<DocumentMigrationNote> notes;

  /// Returns the derived `canWrite` value for this object.
  /// Keeping this as an accessor gives callers a stable read surface while the owning type controls how the value is calculated.
  bool get canWrite => status != DocumentMigrationStatus.failed;
}
