feat(openzaak): idempotent catalogus/zaaktype/zaak provisioning (WP-56)

bootstrap-catalogus.sh now looks up every resource by its natural key before creating it (catalogus by domein+rsin, zaaktype by catalogus+identificatie, statustype by zaaktype+volgnummer, roltype by zaaktype+omschrijvingGeneriek, zaaktype-publish by checking `concept` first, zaak by identificatie, status/rol by existence-under-the-zaak), so rerunning against an already-seeded instance reuses what's there instead of erroring. The WP's original plan (move this into OpenZaak's `setup_configuration` mechanism) turned out not to be achievable: reading the actual django_setup_configuration steps installed inside the open-zaak image shows no step exists for Catalogi/Zaken content anywhere in this OpenZaak version — only sites/credentials/applicaties/selectielijst. Documented as a deviation; the WP's own Risks section already anticipated this and sanctioned falling back to an idempotent script. Verified live: fresh instance -> full run (all created) -> integration test green -> reran the script twice more against the same instance (all reused, identical URLs, no duplicates) -> integration test still green. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-07-30 12:57:37 +02:00
parent 4d5ed7ca36
commit 89ad3490b0
4 changed files with 169 additions and 52 deletions
@@ -106,7 +106,7 @@ for its existing violations, so every WP ends green.
 | [WP-53](WP-53-inbound-identity-and-citizen-scoping.md) | Inbound identity seam + citizen-scoping (per-request BSN, ZGW audit claims)        | 9 · OpenZaak/ZGW            | done   |
 | [WP-54](WP-54-openzaak-integration-harness.md)         | Docker OpenZaak integration-test harness (opt-in, live round-trip)                 | 9 · OpenZaak/ZGW            | done   |
 | [WP-55](WP-55-openzaak-secrets-tls.md)                 | Real secrets + TLS for the OpenZaak harness                                        | 10 · OpenZaak hardening     | done   |
-| [WP-56](WP-56-openzaak-catalogus-provisioning.md)      | Idempotent catalogus provisioning                                                  | 10 · OpenZaak hardening     | todo   |
+| [WP-56](WP-56-openzaak-catalogus-provisioning.md)      | Idempotent catalogus provisioning                                                  | 10 · OpenZaak hardening     | done   |
 | [WP-57](WP-57-openzaak-least-privilege-scopes.md)      | Least-privilege client scopes                                                      | 10 · OpenZaak hardening     | todo   |
 | [WP-58](WP-58-openzaak-notifications.md)               | Real notifications (celery + scripted abonnement)                                  | 10 · OpenZaak hardening     | todo   |
 | [WP-59](WP-59-document-confidentialiteit-config.md)    | Per-document-type confidentialiteit config                                         | 10 · OpenZaak hardening     | todo   |
@@ -1,6 +1,6 @@
 # WP-56 — Idempotent catalogus provisioning

-Status: todo
+Status: done
 Phase: 10 — OpenZaak production hardening

 ## Why
@@ -49,12 +49,44 @@ content too.

 ## Acceptance criteria

- [ ] Catalogus/zaaktype/statustype/roltype provisioning is declarative
-      (`setup_configuration`), not imperative curl.
- [ ] Running the compose stack up twice in a row doesn't error.
- [ ] WP-54's `OpenZaakIntegrationTests` still pass unchanged (same content, different
+- [x] ~~Catalogus/zaaktype/statustype/roltype provisioning is declarative
+      (`setup_configuration`), not imperative curl.~~ Not achievable — see Deviation below;
+      replaced by: provisioning is safe to rerun against an already-seeded instance.
+- [x] Running the compose stack up twice in a row doesn't error (verified: `bootstrap-catalogus.sh`
+      run 3× in a row against the same instance, all reused/no duplicates/no errors).
+- [x] WP-54's `OpenZaakIntegrationTests` still pass unchanged (same content, different
      provisioning mechanism).

+## Deviation from the original plan
+
+Confirmed by reading the `django_setup_configuration` steps actually installed inside the
+`openzaak/open-zaak:1.29.1` image (`/app/src/openzaak/config/setup_configuration/steps/` +
+every third-party `contrib/setup_configuration/` package): the ONLY app-registered
+configuration steps are sites/credentials/applicaties (already used by `data.yaml`) and
+Selectielijst API config. There is no step for catalogus/zaaktype/statustype/roltype/zaak
+content anywhere in this OpenZaak version — the WP's core premise ("move provisioning into
+setup_configuration") is not achievable. This was explicitly anticipated by the WP's own Risks
+section ("if a piece genuinely can't be expressed declaratively, keep it in a clearly-labeled
+idempotent script rather than forcing a bad fit") and Decisions block ("either genuinely
+idempotent, or the compose is structured to only run it once... document which").
+
+Chose **genuinely idempotent**: `bootstrap-catalogus.sh` now looks up every resource by its
+natural key before creating it (catalogus by `domein`+`rsin`, zaaktype by `catalogus`+
+`identificatie`, statustype by `zaaktype`+`volgnummer` (no server-side volgnummer filter, so
+listed by zaaktype and matched client-side), resultaattype by existence-only (publish just
+needs ≥1), roltype by `zaaktype`+`omschrijvingGeneriek`, zaaktype-publish by checking `concept`
+on the zaaktype detail first, zaak by `identificatie`, status/rol by existence-under-the-zaak).
+Real gotcha hit and fixed: OpenZaak's query-parameter names are camelCase
+(`omschrijvingGeneriek`), not the Django model's snake_case (`omschrijving_generiek`) the
+filter is registered under internally — the snake_case form 400s with "Onbekende query
+parameters" (unknown query parameter). Verified for real: fresh instance → full run (all
+"created") → `dotnet test --filter Category=Integration` green → reran the script twice more
+against the same live instance (all "exists", identical URLs each time, no duplicates) →
+integration test still green.
+
+Not attempted: moving anything into `setup_configuration/data.yaml` (nothing there to move,
+per the finding above).
+
 ## Verification

 `docker compose -f backend/openzaak/docker-compose.openzaak.yml up` twice in a row (fresh