/// Domain Repository Interface: Price Policy Repository
///
/// Defines the contract for price policy document data operations.
/// This is an abstract interface following the Repository Pattern.
///
/// The actual implementation will be in the data layer.
/// This allows for dependency inversion and easier testing.
library;

import 'package:worker/features/price_policy/domain/entities/price_document.dart';

/// Price Policy Repository Interface
///
/// Provides methods to:
/// - Get all price policy documents
/// - Filter documents by category
/// - Fetch individual document details
///
/// Implementation will be in data/repositories/price_policy_repository_impl.dart
abstract class PricePolicyRepository {
  /// Get all price policy documents
  ///
  /// Returns list of [PriceDocument] objects.
  /// Returns empty list if no documents available.
  ///
  /// This should fetch from local cache first, then sync with server.
  /// Documents should be ordered by published date (newest first).
  Future<List<PriceDocument>> getAllDocuments();

  /// Get documents filtered by category
  ///
  /// Returns list of [PriceDocument] objects matching the [category].
  /// Returns empty list if no matching documents.
  ///
  /// [category] - The category to filter by (policy or priceList)
  Future<List<PriceDocument>> getDocumentsByCategory(DocumentCategory category);

  /// Get a specific document by ID
  ///
  /// Returns [PriceDocument] if found, null otherwise.
  ///
  /// [documentId] - The unique identifier of the document
  Future<PriceDocument?> getDocumentById(String documentId);

  /// Refresh documents from server
  ///
  /// Force refresh documents from remote source.
  /// Updates local cache after successful fetch.
  Future<List<PriceDocument>> refreshDocuments();
}
