using BigRegister.Api.Contracts;
using BigRegister.Domain.Authorization;

namespace BigRegister.Api.Data;

/// <summary>
/// The cases (zaken) READ seam (WP-49). A "zaak" in ZGW terms is an <see cref="Aanvraag"/>
/// here; this interface is the one injection point that lets a real ZGW backend (OpenZaak)
/// replace the local SQLite store <em>behind the same <see cref="ApplicationSummaryDto"/>
/// contract</em> — so the frontend never changes (BFF-lite anti-corruption, ADR-0001).
///
/// Default binding is <see cref="LocalZaakSource"/> (offline). Setting <c>Zgw:Enabled=true</c>
/// swaps in <c>OpenZaakZaakSource</c>. Slice 1 (WP-49) was read-only; <see cref="CreateZaak"/>
/// (WP-50) is the first write. The interface returns the wire DTO (not the domain
/// <see cref="Aanvraag"/>) precisely so each source owns its own mapping — the OpenZaak
/// source maps a ZGW Zaak into this shape, the local source maps the stored aanvraag.
/// </summary>
public interface IZaakSource
{
  /// <summary>Every case across every owner, newest-first (the admin cross-owner list,
  /// WP-36) — cases:manage only, deliberately NOT citizen-scoped.</summary>
  IReadOnlyList<ApplicationSummaryDto> ListCases(DateTimeOffset now);

  /// <summary>
  /// Only <paramref name="caller"/>'s own cases (WP-53) — the citizen-scoped counterpart of
  /// <see cref="ListCases"/>, backing the citizen's own dashboard. The local source filters
  /// <c>ApplicationStore</c> by owner (unchanged behaviour); the OpenZaak source adds ZGW's
  /// <c>rol__betrokkeneIdentificatie__natuurlijkPersoon__inpBsn</c> query filter so a citizen
  /// can never see another citizen's zaken.
  /// </summary>
  IReadOnlyList<ApplicationSummaryDto> ListMyCases(ZorgverlenerCaller caller, DateTimeOffset now);

  /// <summary>
  /// Register a just-submitted <paramref name="aanvraag"/> as a zaak (WP-50). The aanvraag is
  /// already persisted locally (<c>ApplicationStore.Submit</c> already ran) — this is the
  /// integration side-effect, and (Referentie, Status) is what the submit endpoint hands back
  /// to the FE (ADR-0001: route the create through the existing submit response DTO, don't add
  /// a second one). The local source is a pure passthrough of the already-computed local
  /// reference/status (ZaakUrl null — nothing to persist); the OpenZaak source creates a Zaak
  /// (+ status + rol) and maps the result back into the same shape, returning the zaak's URL
  /// so the endpoint can persist it (<see cref="ApplicationStore.SetZaakUrl"/>, WP-51 needs it
  /// to later link documents to this zaak). <paramref name="caller"/> (WP-53) is the acting
  /// citizen — the ZGW JWT's audit claims reflect them, not a static config identity.
  /// </summary>
  (string Referentie, AanvraagStatusDto Status, string? ZaakUrl) CreateZaak(Aanvraag aanvraag, DateTimeOffset now, CallerIdentity caller);
}