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

part of '../../repositories.dart';

/// Repository contract for locked-block and one-day override documents.
abstract interface class LockedBlockRepository {
  /// Return a locked block by stable id, or null when it does not exist.
  Future<LockedBlock?> findBlockById(String id);

  /// Return a locked block plus owner/revision metadata.
  Future<RepositoryRecord<LockedBlock>?> findBlockRecordById(String id);

  /// Return all locked block definitions.
  Future<List<LockedBlock>> findAllBlocks();

  /// Return owner-scoped locked blocks, optionally including archived blocks.
  Future<RepositoryPage<LockedBlock>> findBlocksByOwner({
    required String ownerId,
    bool includeArchived = false,
    RepositoryPageRequest page = const RepositoryPageRequest(),
  });

  /// Return an override by stable id, or null when it does not exist.
  Future<LockedBlockOverride?> findOverrideById(String id);

  /// Return an override plus owner/revision metadata.
  Future<RepositoryRecord<LockedBlockOverride>?> findOverrideRecordById(
    String id,
  );

  /// Return all one-day overrides.
  Future<List<LockedBlockOverride>> findAllOverrides();

  /// Return owner-scoped one-day overrides for [date].
  Future<RepositoryPage<LockedBlockOverride>> findOverridesForDate({
    required String ownerId,
    required CivilDate date,
    RepositoryPageRequest page = const RepositoryPageRequest(),
  });

  /// Save or replace [block] by stable id.
  Future<void> saveBlock(LockedBlock block);

  /// Save or replace [override] by stable id.
  Future<void> saveOverride(LockedBlockOverride override);

  /// Runs the `insertBlock` operation and completes after its asynchronous work finishes.
  /// Callers should await the returned future so repository writes, UI refreshes, and failure handling happen in a predictable order.
  Future<RepositoryMutationResult> insertBlock({
    required LockedBlock block,
    required String ownerId,
  });

  /// Runs the `saveBlockIfRevision` operation and completes after its asynchronous work finishes.
  /// Callers should await the returned future so repository writes, UI refreshes, and failure handling happen in a predictable order.
  Future<RepositoryMutationResult> saveBlockIfRevision({
    required LockedBlock block,
    required String ownerId,
    required int expectedRevision,
  });

  /// Runs the `archiveBlock` operation and completes after its asynchronous work finishes.
  /// Callers should await the returned future so repository writes, UI refreshes, and failure handling happen in a predictable order.
  Future<RepositoryMutationResult> archiveBlock({
    required String blockId,
    required String ownerId,
    required int expectedRevision,
    required DateTime archivedAt,
  });

  /// Runs the `insertOverride` operation and completes after its asynchronous work finishes.
  /// Callers should await the returned future so repository writes, UI refreshes, and failure handling happen in a predictable order.
  Future<RepositoryMutationResult> insertOverride({
    required LockedBlockOverride override,
    required String ownerId,
  });

  /// Runs the `saveOverrideIfRevision` operation and completes after its asynchronous work finishes.
  /// Callers should await the returned future so repository writes, UI refreshes, and failure handling happen in a predictable order.
  Future<RepositoryMutationResult> saveOverrideIfRevision({
    required LockedBlockOverride override,
    required String ownerId,
    required int expectedRevision,
  });
}
