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

part of '../../document_mapping.dart';

/// Typed mapping failure for malformed V1 documents.
class DocumentMappingException implements Exception {
  /// Creates a `DocumentMappingException` 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 DocumentMappingException({
    required this.code,
    this.fieldName,
    this.detailCode,
  });

  /// Stable category for caller branching.
  final DocumentMappingFailureCode code;

  /// Field related to the failure, when known.
  final String? fieldName;

  /// Optional narrower reason.
  final String? detailCode;

  /// Converts scheduler data for `toString` without changing the source object.
  /// Conversion helpers keep persistence and export shapes explicit so domain models do not depend on storage-specific details.
  @override
  String toString() {
    return 'DocumentMappingException($code, field: $fieldName, detail: '
        '$detailCode)';
  }
}
