register-referentie/services/domain/Big.Domain/Registration.cs

namespace Big.Domain;

/// <summary>
/// The Registration aggregate root (CLAUDE.md §2.2): a zorgprofessional's submission to the BIG
/// register. It owns its lifecycle invariants — it starts <see cref="RegistrationStatus.Ingediend"/>
/// on submission, remembers the Flowable process that drives it, and records the zaak the ACL opens.
/// </summary>
public sealed class Registration
{
    private Registration(RegistrationId id, string bsn)
    {
        Id = id;
        Bsn = bsn;
        Status = RegistrationStatus.Ingediend;
    }

    public RegistrationId Id { get; }

    /// <summary>The citizen-service number of the submitting zorgprofessional. Handed to the ACL
    /// as the domain payload; the domain never constructs ZGW concepts from it (§8.1).</summary>
    public string Bsn { get; }

    public RegistrationStatus Status { get; private set; }

    /// <summary>The Flowable process instance driving this registration, once started.</summary>
    public string? ProcessInstanceId { get; private set; }

    /// <summary>The zaak the ACL opened for this registration, once the external task has run.</summary>
    public Uri? ZaakUrl { get; private set; }

    /// <summary>Submit a new registration. It begins in <see cref="RegistrationStatus.Ingediend"/>.</summary>
    public static Registration Submit(string bsn)
    {
        ArgumentException.ThrowIfNullOrWhiteSpace(bsn);
        return new Registration(RegistrationId.New(), bsn);
    }

    /// <summary>Record that the registratie workflow process has been started for this registration.</summary>
    public void RecordProcessStarted(string processInstanceId)
    {
        ArgumentException.ThrowIfNullOrWhiteSpace(processInstanceId);
        ProcessInstanceId = processInstanceId;
    }

    /// <summary>
    /// Attach the zaak the ACL opened. The external-task worker may deliver the same job more than
    /// once (at-least-once), so re-attaching the identical URL is a no-op; a different URL signals a
    /// genuine conflict and is rejected. The status stays <see cref="RegistrationStatus.Ingediend"/>:
    /// opening the zaak does not advance the registration's lifecycle in this slice.
    /// </summary>
    public void AttachZaak(Uri zaakUrl)
    {
        ArgumentNullException.ThrowIfNull(zaakUrl);

        if (ZaakUrl is not null)
        {
            if (ZaakUrl != zaakUrl)
                throw new InvalidOperationException(
                    $"Registration {Id} already has zaak {ZaakUrl}; cannot attach a different zaak {zaakUrl}.");
            // Stryker disable once Statement : equivalent — re-assigning the identical URL below is a
            // no-op, so removing this early return is behaviourally indistinguishable.
            return;
        }

        ZaakUrl = zaakUrl;
    }

    /// <summary>
    /// Approve the registration — the behandelaar's decision to enter it in the register. Advances
    /// <see cref="RegistrationStatus.Ingediend"/> → <see cref="RegistrationStatus.Ingeschreven"/>.
    /// Requires an opened zaak (the approval sets that zaak's status via the ACL), and only a
    /// submitted registration can be approved: re-approving is rejected as an invalid transition.
    /// </summary>
    public void Approve()
    {
        if (ZaakUrl is null)
            throw new InvalidOperationException(
                $"Registration {Id} has no zaak yet; it cannot be approved before its zaak is opened.");

        if (Status != RegistrationStatus.Ingediend)
            throw new InvalidOperationException(
                $"Registration {Id} is {Status}; only an INGEDIEND registration can be approved.");

        Status = RegistrationStatus.Ingeschreven;
    }
}