Workflow-Wiederherstellung sicher ausführen

Diese Seite beschreibt, wie Sie einen fehlgeschlagenen Workflow-Schritt prüfen und gezielt zur Wiederherstellung einplanen. Nutzen Sie diesen Ablauf nur für einen vorhandenen Dead-Letter-Eintrag. Workspace wiederholt dabei entweder eine nicht bestätigte Transition oder genau die gespeicherte Action – niemals pauschal den gesamten Workflow.

Voraussetzungen

Sie benötigen:

  • einen angemeldeten nucli-Mandantenalias für den betroffenen Mandanten,
  • die Berechtigung zum Lesen und Wiederholen von Workflow-Dead-Letter-Einträgen,
  • die UUID des Eintrags aus dem Workflow-Monitoring oder aus GET /api/v1/workflow-dead-letters.

Verwenden Sie für einen erreichbaren Server immer nucli oder die tenantgebundene API. Ändern Sie weder Workflow- noch Dead-Letter-Daten direkt in PostgreSQL. numin ist kein Remote-Recovery-Client für diesen Ablauf.

Preflight prüfen

Führen Sie zuerst den read-only Preflight aus:

bash
nucli --tenant <mandantenalias> workflow recovery replay <dead-letter-uuid>

Für eine maschinenlesbare Ausgabe ergänzen Sie --json. Der Preflight liest den Eintrag, zeigt Wiederherstellungsart, Instanz, Status und Ziel und löst keine Mutation aus. Prüfen Sie insbesondere:

  • Ist der richtige Mandant ausgewählt?
  • Gehören Instanz, Transition oder Action zum erwarteten Fachvorgang?
  • Ist der Eintrag noch offen und ist der ursprüngliche Fehler fachlich oder technisch behoben?
  • Ist die Action ausdrücklich replay-sicher? Unklassifizierte Actions bleiben gesperrt.

Wiederherstellung einplanen

Wenn der Preflight den erwarteten Eintrag zeigt, planen Sie die Wiederherstellung explizit ein:

bash
nucli --tenant <mandantenalias> workflow recovery replay <dead-letter-uuid> --apply

nucli wiederholt vor dem mutierenden Request den Preflight. Der Server antwortet erst mit queued, nachdem der Recovery-Auftrag persistent gespeichert wurde. Ein Worker übernimmt ihn anschließend mit Lease und monotonem Fence.

Eine Transition-Wiederherstellung führt nur die noch nicht bestätigte Transition erneut aus. Eine Action-Wiederherstellung führt nur die durch ihre persistente UUID identifizierte Action aus und ändert den Workflow-Status kein zweites Mal. Bereits erfolgreiche Action-Checkpoints werden nicht wiederholt.

Ergebnis prüfen

Prüfen Sie den Eintrag und die Workflow-Instanz erneut. Eine erfolgreiche Wiederherstellung setzt den Eintrag auf einen abgeschlossenen Status. Solange weitere offene Einträge für dieselbe Instanz bestehen, bleibt deren Dead-Letter-Zustand sichtbar.

Behandeln Sie folgende Antworten als Abbruchsignal:

  • 401: Melden Sie den ausgewählten Mandantenalias erneut an.
  • 403: Verwenden Sie keine höheren Rechte ohne betriebliche Freigabe.
  • 404: Prüfen Sie UUID und Mandant; fremde Mandanten bleiben unsichtbar.
  • 409: Der Eintrag wird bereits bearbeitet, ist ein nicht wiederholbarer Legacy-Eintrag oder enthält eine nicht freigegebene Action.

Starten Sie bei einem Konflikt keinen Datenbank-Workaround. Klären Sie zuerst den Eintrag, die Action-Klassifikation und den laufenden Worker.