register-referentie/services/acl/Acl.Application/AclService.cs

namespace Acl.Application;

/// <summary>The ACL's single operation: open a zaak from a domain payload,
/// default-filling the ZGW-mandatory fields (ADR-0003).</summary>
public sealed class AclService(
    IZaakGateway gateway,
    IRegisterRecordGateway register,
    IDefaultFillStore fill,
    IZaaktypeCatalog catalog,
    IClock clock)
{
    public async Task<Uri> OpenZaakAsync(DomainRegistration registration, CancellationToken ct = default)
    {
        ArgumentNullException.ThrowIfNull(registration);

        // Read the current default-fill per zaak (not at construction), so a beheerder edit (S-15b)
        // takes effect on the next zaak without a restart.
        var defaults = fill.Current;
        var request = new ZaakRequest(
            defaults.Bronorganisatie,
            defaults.VerantwoordelijkeOrganisatie,
            defaults.Vertrouwelijkheidaanduiding,
            await catalog.GetZaaktypeUrlAsync(ct),
            clock.Today,
            registration.Reference);

        var zaakUrl = await gateway.OpenZaakAsync(request, ct);

        // The register — not ZGW — is what the read projection is sourced from (ADR-0028/ADR-0030),
        // so the record exists from submission, not only from approval. Same two-writes-converging
        // posture as ApproveZaakAsync: the upsert is keyed on the zaak id, so a retried submit
        // updates the record rather than adding a second one (§8.6).
        await register.UpsertAsync(
            new RegisterRecord(ZaakId(zaakUrl), RegisterRecordStatus.Ingediend, registration.Reference), ct);

        return zaakUrl;
    }

    /// <summary>
    /// Approve a zaak: set it to the eindstatus of the BIG zaaktype (resolved by identificatie, S-27),
    /// then write the register record to Objecten (S-19a). The domain hands over only the zaak URL; the
    /// ACL owns which statustype means "approved" and what the register record looks like (§8.1).
    /// </summary>
    /// <remarks>
    /// OpenZaak holds the process, Objecten holds the register (ADR-0028), so approval is two writes
    /// across two modules and is eventually consistent by construction. Both are idempotent — a status
    /// is a log entry, the record upsert is keyed on the zaak id — so a caller that retries a failed
    /// approval converges rather than duplicating.
    /// </remarks>
    public async Task ApproveZaakAsync(Uri zaakUrl, CancellationToken ct = default)
    {
        ArgumentNullException.ThrowIfNull(zaakUrl);

        await gateway.SetZaakToEindstatusAsync(zaakUrl, await catalog.GetZaaktypeUrlAsync(ct), clock.Today, ct);

        await register.UpsertAsync(
            new RegisterRecord(
                ZaakId(zaakUrl),
                RegisterRecordStatus.Ingeschreven,
                await gateway.GetZaakIdentificatieAsync(zaakUrl, ct)),
            ct);
    }

    /// <summary>
    /// The register record held by an object in Objecten, for the Event Subscriber (S-19b-2). The
    /// subscriber gets only an object URL on the notification and may not read Objecten itself
    /// (§8.1, ADR-0028), so the ACL reads it back.
    /// </summary>
    public Task<RegisterRecord?> GetRegisterRecordAsync(Uri objectUrl, CancellationToken ct = default)
    {
        ArgumentNullException.ThrowIfNull(objectUrl);

        return register.GetAsync(objectUrl, ct);
    }

    /// <summary>The zaak's UUID — the key the register record and the read projection rows share.</summary>
    private static string ZaakId(Uri zaakUrl) => zaakUrl.Segments[^1].TrimEnd('/');

    /// <summary>
    /// Cancel a zaak on document-timeout expiry (S-10c): set it to the BIG zaaktype's cancellation
    /// statustype + resultaat. The domain hands over only the zaak URL; the ACL owns which
    /// statustype/resultaat means "cancelled" (§8.1).
    /// </summary>
    public async Task CancelZaakAsync(Uri zaakUrl, CancellationToken ct = default)
    {
        ArgumentNullException.ThrowIfNull(zaakUrl);

        await gateway.SetZaakToCancellationStatusAsync(zaakUrl, await catalog.GetZaaktypeUrlAsync(ct), clock.Today, ct);
    }

    /// <summary>The published zaaktypen, for the beheer catalogus viewer (S-15a). Read-only passthrough:
    /// no default-fill, the ACL is simply the only code allowed to read ZGW (§8.1).</summary>
    public Task<IReadOnlyList<ZaaktypeSummary>> ListZaaktypenAsync(CancellationToken ct = default) =>
        gateway.ListZaaktypenAsync(ct);

    /// <summary>The current default-fill settings, for the beheer config viewer (S-15b).</summary>
    public DefaultFillSettings GetDefaultFill() => fill.Current;

    /// <summary>Replace the default-fill settings from the beheer portal (S-15b). Takes effect on the
    /// next zaak (the fill is read per zaak, not cached).</summary>
    public void UpdateDefaultFill(DefaultFillSettings settings)
    {
        ArgumentNullException.ThrowIfNull(settings);
        fill.Update(settings);
    }

    /// <summary>The zaak's reference (its ZGW identificatie), for the read projection (#78).</summary>
    public Task<string> GetZaakReferenceAsync(Uri zaakUrl, CancellationToken ct = default)
    {
        ArgumentNullException.ThrowIfNull(zaakUrl);

        return gateway.GetZaakIdentificatieAsync(zaakUrl, ct);
    }

    /// <summary>
    /// Store an uploaded diploma against the zaak (S-10b): default-fill the ZGW-mandatory document
    /// fields (informatieobjecttype, bronorganisatie, vertrouwelijkheidaanduiding, taal, creatiedatum)
    /// and hand the file to the gateway, which creates the informatieobject and relates it to the zaak.
    /// The domain supplies only the zaak, the bytes, and the file's name/type (§8.1).
    /// </summary>
    public async Task<Uri> StoreDiplomaAsync(Uri zaakUrl, byte[] content, string fileName, string contentType, CancellationToken ct = default)
    {
        ArgumentNullException.ThrowIfNull(zaakUrl);
        ArgumentNullException.ThrowIfNull(content);
        ArgumentException.ThrowIfNullOrWhiteSpace(fileName);
        ArgumentException.ThrowIfNullOrWhiteSpace(contentType);

        var defaults = fill.Current;
        var request = new DocumentRequest(
            defaults.Bronorganisatie,
            await catalog.GetInformatieobjecttypeUrlAsync(ct),
            defaults.Vertrouwelijkheidaanduiding,
            zaakUrl,
            clock.Today,
            Titel: "Diploma",
            Auteur: "zorgprofessional",
            Taal: "nld",
            Bestandsnaam: fileName,
            Formaat: contentType,
            Inhoud: content);

        return await gateway.StoreDocumentAsync(request, ct);
    }
}