🎯 Epic: Betrouwbaar publiceren van grote documentaantallen

[MarcoKlerks]

🎯 Epic: Betrouwbaar publiceren van grote documentaantallen

Stakeholders

• Product Owner: Marco Klerks
• Lead Designer:
• Tech Lead:

---

Bounded Context

Primair de Publicatiebank-context (GPP-publicatiebank) — deze blijft source of truth voor Document/Publicatie, inclusief de nieuwe verwerkingsstatus en de zelf-throttlende ophaallogica. Raakvlak:

• GPP-app (redactie/backoffice): krijgt een nieuwe verantwoordelijkheid — geüploade bestanden tijdelijk zelf opslaan en ontsluiten via een eigen, lichtgewicht Documenten API, zodat GPP-publicatiebank ze kan ophalen via het bestaande "ophalen"-aanlevermechanisme (aanlevering_bestand = ophalen).

---

Context

Gemeenten ervaren problemen wanneer meerdere redacteuren tegelijk grote aantallen en/of omvangrijke documenten via GPP-app publiceren. Vandaag ("ontvangen"-modus) hakt GPP-app elk bestand op in bestandsdelen en pusht die naar GPP-publicatiebank, die ze moet samenvoegen, de metadata strippen en aanbieden aan GPP-Zoeken ter indexering. Bij veel gelijktijdige of grote uploads loopt het geheugen van GPP-publicatiebank vol, wat na verloop van tijd tot een time-out leidt — documenten worden dan niet of niet volledig gepubliceerd.

Twee reeds klaarstaande wijzigingen verkleinen dit risico (PR #452: een langere, toegewijde read-timeout voor bestandsdeel-upload en unlock; PR #454: het periodiek recyclen van Celery-workerprocessen om geheugenopbouw te voorkomen), maar lossen de onderliggende schaalbaarheidsbeperking niet structureel op.

GPP-publicatiebank kent al een alternatieve aanlevermodus ("ophalen"): in plaats van bestandsdelen te ontvangen, haalt GPP-publicatiebank het bronbestand zelf op via een meegegeven document_url, en verwerkt het vervolgens net als in de ontvangen-modus (samenvoegen, metadata strippen, indexeren). Dit epic breidt dat bestaande mechanisme uit: GPP-app wordt zelf een tijdelijke bron waar GPP-publicatiebank documenten ophaalt, in plaats van dat GPP-app bestandsdelen pusht.

Goal

Een Redacteur uploadt een of meer documenten bij een publicatie in GPP-app; deze worden tijdelijk in GPP-app zelf opgeslagen en ontsloten via een lichtgewicht, eigen Documenten API. GPP-app maakt de publicatie aan in GPP-publicatiebank en levert per document de metadata aan, inclusief de document_url die naar GPP-app's tijdelijke opslag wijst. GPP-publicatiebank haalt de documenten vervolgens één voor één op via het bestaande "ophalen"-mechanisme, en haalt een volgend document pas op wanneer er voldoende resources beschikbaar zijn om dit te verwerken. Een publicatie wordt pas als volledig gepubliceerd beschouwd zodra alle bijbehorende documenten zijn opgehaald en verwerkt. Redacteuren zien in GPP-app, en Beheerders zien in GPP-publicatiebank, per document en per publicatie of het ophalen en verwerken is gelukt.

Success Metrics

• Gemeenten kunnen grote aantallen en/of omvangrijke documenten in één publicatie publiceren zonder dat GPP-publicatiebank een out-of-memory-fout of time-out ervaart.
• GPP-app slaat geüploade bestanden tijdelijk zelf op en ontsluit ze via een eigen, lichtgewicht Documenten API.
• GPP-publicatiebank haalt documenten via het bestaande "ophalen"-mechanisme één voor één op, en haalt pas een volgend document op wanneer daarvoor voldoende resources beschikbaar zijn.
• Een publicatie wordt pas als volledig gepubliceerd beschouwd wanneer alle bijbehorende documenten zijn opgehaald en volledig verwerkt (status "Geslaagd").
• Een Redacteur kan op het registratiescherm van een publicatie en in de publicatielijst in GPP-app zien of alle documenten zijn opgehaald en verwerkt.
• Een Beheerder kan in GPP-publicatiebank per document — op het detailscherm, in de documentenlijst en in de lijst met gekoppelde documenten op een publicatie — de verwerkingsstatus zien (Wachtend / In bewerking / Geslaagd / Mislukt).
• Tijdelijk opgeslagen bestanden in GPP-app worden na een vaste bewaartermijn automatisch opgeruimd, ongeacht ophaalstatus.

---

Design Artifacts

• PR #452 (GPP-publicatiebank) — toegewijde read-timeout voor bestandsdeel-upload/unlock (Closes #451)
• PR #454 (GPP-publicatiebank) — Celery-workergeheugen periodiek recyclen (Closes #453)
• Bestaand "ophalen"-aanlevermechanisme (aanlevering_bestand, sinds #274 ) — prototype van de beoogde architectuur; dit epic hergebruikt en breidt dit uit voor gebruik tussen GPP-app en GPP-publicatiebank.

Out of Scope

• Wijzigingen aan OpenZaak of aan de definitieve (permanente) opslag van documenten — deze blijft ongewijzigd; alleen de bron waarvandaan GPP-publicatiebank het brondocument ophaalt, verschuift van GPP-app's bestandsdeel-push naar GPP-app's tijdelijke opslag + Documenten API.
• Volledige implementatie van de ZGW Documenten API-standaard in GPP-app — een lichtgewicht, eigen endpoint volstaat, geen standaard-compliance vereist.

Risks

• Een trage of overbelaste Documenten API in GPP-app kan de publicatieverwerking alsnog vertragen — de nieuwe architectuur verplaatst een deel van het risico, lost het niet volledig op.
• (technisch) Zelf-throttling in GPP-publicatiebank (pas een volgend document ophalen wanneer er resources beschikbaar zijn) bestaat nog niet — het huidige "ophalen"-pad (PartsDownloader) haalt sequentieel op maar heeft geen concurrency-/resource-bewuste doseerlogica.
• Er bestaat nog geen per-document verwerkingsstatus (alleen een boolean upload_complete en een metadata_gestript_op-timestamp) — moet uitgebreid worden naar Wachtend/In bewerking/Geslaagd/Mislukt.
• De bestaande SSRF-validatie (SourceDocumentURLValidator) controleert de bron-URL tegen een geconfigureerde zgw_consumers.Service — GPP-app's nieuwe Documenten API-endpoint moet op dezelfde manier geconfigureerd en vertrouwd worden.
• PR's #452 en #454 verkleinen de kans op time-outs/OOM bij de huidige push-architectuur, maar lossen de onderliggende schaalbaarheidsbeperking niet structureel op — dit epic is aanvullend, niet vervangend.
• De vaste bewaartermijn voor tijdelijk opgeslagen bestanden in GPP-app moet zorgvuldig gekozen worden: te kort riskeert het verwijderen van bestanden voordat GPP-publicatiebank ze heeft opgehaald; te lang laat onnodig bestanden achter.

Feature Breakdown

• Tijdelijke bestandsopslag en een lichtgewicht Documenten API in GPP-app, met een tijdgestuurde opruimtermijn
• GPP-app publiceert via het bestaande "ophalen"-aanlevermechanisme in GPP-publicatiebank (document_url wijst naar GPP-app i.p.v. bestandsdelen te pushen)
• Zelf-throttling in GPP-publicatiebank: een volgend document pas ophalen wanneer voldoende resources beschikbaar zijn
• Per-document verwerkingsstatus (Wachtend/In bewerking/Geslaagd/Mislukt) bijhouden en tonen in GPP-publicatiebank (detailscherm document, documentenlijst, gekoppelde documenten op publicatie)
• Publicatiestatus tonen op basis van of alle documenten zijn opgehaald en verwerkt — zichtbaar op het registratiescherm en in de publicatielijst in GPP-app