Zahlungs-Recovery-Pipeline und Runbooks (Zahlungs Recovery Pipeline Und Runbooks)

Im vorherigen Teil haben wir gesehen, wie Korrelation über Payment-ID, Step-Event-Log und Deferred-Finalize-Metriken den Betrieb speisen. Dieser Teil behandelt die darauf aufgebaute Recovery-Pipeline: Wenn eine Zahlung hängt, was kann das System selbst — und wann greift ein Mensch ein?

Das Prinzip einer guten Recovery-Pipeline ist einfach: Automatisierung zuerst. Abgleich-Worker, Stuck Watcher, Retry-Worker — diese räumen die meiste Drift ohne menschlichen Eingriff auf. Menschliche Runbooks greifen nur ein, wenn Automatisierung an Uniqueness-Wänden oder mehrdeutiger Evidenz scheitert.

Zahlung hängt
  → automatisch: Abgleich-Scan
  → automatisch: Retry mit Backoff
  → automatisch: PSP-Status-Abfrage
  → Mensch: Uniqueness-Wand / mehrdeutige Evidenz

Wo die Begriffe zuerst auftauchen

📦 Recovery Pipeline
Eine Abfolge von Stufen, die hängende oder inkonsistente Zahlungen automatisch diagnostiziert und zu beheben versucht.

📦 Uniqueness-Wand
Ein Zustand, in dem eine DB-Uniqueness-Constraint einen sicheren Replay- oder Heal-Versuch blockiert.

📦 Evidenzbasiertes Runbook
Eine Betriebsanleitung, bei der jeder Schritt definiert, welche Evidenz (Step-Log, PSP-Abfrage, Audit) zuerst vorliegen muss.

📦 Manual Review Queue
Ein sichtbarer Wartebereich, in dem Datensätze sammeln, die Automatisierung nicht lösen konnte.

Ein Runbook beantwortet 'was tun'; ein evidenzbasiertes Runbook beantwortet 'was darf ohne diese Evidenz niemals getan werden'.

Automatisierung zuerst: Schichten der Recovery-Pipeline

Die Recovery-Pipeline ist kein einzelner Worker — es sind ergänzende Schichten. Jede Schicht behandelt, was die vorherige nicht konnte; keine sollte die Aufgabe der nächsten übernehmen.

Schicht 1: Retry-Worker
  → wiederholt transiente Fehler mit Backoff

Schicht 2: Stuck Watcher
  → setzt nach Lease-Ablauf in Processing hängende Datensätze zurück

Schicht 3: Abgleich-Sweeper
  → vergleicht gealterte FinalizePending-/Expired-Datensätze mit dem PSP

Schicht 4: Manual Review Queue
  → Datensätze, die Automatisierung nicht lösen konnte

Schichten 1–3 sind vollautomatisch und meist ausreichend. Schicht 4 ist kein Pipeline-Versagen — sie ist die sichtbare Grenze dessen, was Automatisierung sicher leisten kann.

Die Uniqueness-Wand: wo Automatisierung stoppt

Ein Abgleich-Worker sieht 'Succeeded' vom PSP und versucht, den lokalen Datensatz auf Captured zu setzen — aber eine Captured-Zeile mit demselben Idempotency Key existiert bereits. Insert oder Update schlägt fehl; Automatisierung stoppt.

Abgleich: payment #5521 → PSP sagt Captured
  → lokaler UPDATE-Versuch
  → UNIQUE constraint violation on idempotency_key
  → Automatisierung stoppt
  → in Manual Review Queue schreiben

Das ist kein Bug — es ist ein Schutzmechanismus. Die Uniqueness-Wand verhindert Doppelfinalisierung — stoppt aber auch Automatisierung daran, 'behoben' zu melden. Genau hier übernimmt ein evidenzbasiertes Runbook.

Evidenzbasiertes Runbook: Prozedur, kein Reflex

Wenn menschlicher Eingriff nötig ist, folgt das Runbook dieser Sequenz:

1. Step-Event-Log lesen (über Payment-ID)
2. PSP-Status-Abfrage (über Provider-Gateway)
3. Lokale Datensätze vergleichen (Payment, Order, Idempotency)
4. Evidenztabelle ausfüllen
5. Entscheidung: heal / refund / no-action
6. Audit-Datensatz schreiben

Jeder Entscheidungspunkt im Runbook erfordert Evidenz. 'PSP sagt Captured, lokal Expired' → Heal-Kandidat. 'PSP Not Found, lokal Processing' → kein Refund-Kandidat; warten oder eskalieren. 'Zwei Captured-Zeilen, verschiedene Idempotency Keys' → Doppelbelastung; eine erstatten.

Manual Review Queue: sichtbares Warten

Datensätze, die Automatisierung nicht lösen konnte, dürfen nicht still verschwinden. Die Manual Review Queue ist, wo sie sammeln, altern und priorisiert werden.

Feld	Zweck
paymentId	Korrelation
stuckReason	UniquenessWall / AmbiguousEvidence / PSPUnknown
evidenceSummary	Step-Log + PSP-Abfrage-Zusammenfassung
age	Wie lange schon wartend
priority	Betrag, Kundenbeschwerde, SLA

Jeder Datensatz in der Queue sollte einem Runbook-Schritt entsprechen; der Operator soll 'was tun' aus der Queue lesen können.

Runbook-Beispiel: nach Uniqueness-Wand

Zustand: Abgleich konnte Captured nicht schreiben — idempotency_key conflict

Evidenz sammeln:
  □ Step-Log: FinalizeAttempted zweimal?
  □ Welcher Webhook erzeugte die bestehende Captured-Zeile?
  □ PSP-Abfrage: wie viele Charges für diese Correlation-ID?

Entscheidungsbaum:
  → Ein PSP-Charge, zwei lokale Zeilen → veraltete Zeile mit Audit schließen
  → Zwei PSP-Charges → einen erstatten (Runbook: duplicate charge)
  → Kein PSP-Charge → lokales Captured falsch → eskalieren

Häufig verwechselte Unterschiede

❌ Manual Review Queue = Automatisierung gescheitert
✓ Manual Review Queue = Grenze der Automatisierung ist sichtbar und sicher

❌ Runbook = Intuition des Senior-Ingenieurs
✓ Runbook = evidenzbasierte, wiederholbare Prozedur

❌ Uniqueness-Wand sollte entfernt werden
✓ Uniqueness-Wand bleibt; Runbook verwaltet, was dahinter liegt

Automatisierung vs menschlicher Eingriff

Situation	Automatisierung	Menschliches Runbook
Transienter Timeout	Retry-Worker	Nicht nötig
Gealtertes FinalizePending	Abgleich	Nicht nötig
Idempotency-Konflikt	Stoppt, schreibt in Queue	Evidenz sammeln, entscheiden
Mehrdeutige PSP-Antwort	Stoppt, schreibt in Queue	Eskalieren oder warten

Checkliste für die Recovery-Pipeline

1. Sind Retry-, Stuck-Watcher- und Abgleich-Schichten getrennt und sequenziell?
2. Schreibt ein Uniqueness-Constraint-Verstoß automatisch in die Manual Review Queue?
3. Definiert jeder Runbook-Schritt explizit, welche Evidenz erfordert wird?
4. Sind Datensätze in der Manual Review Queue nach Alter und Priorität sortiert?
5. Sind Audit-Datensatz und Step-Event-Log-Eintrag nach menschlichem Eingriff Pflicht?
6. Wird die Automatisierungs-Auflösungsrate als Metrik verfolgt (automation_resolution_rate)?

Was bleiben soll

1. Die Recovery-Pipeline ist geschichtet mit Automatisierung zuerst; Menschen sind letzter Ausweg.
2. Die Uniqueness-Wand stoppt Automatisierung — das ist Schutz, kein Bug.
3. Runbooks müssen evidenzbasiert sein; reflexhafte Aktion ist gefährlich.
4. Die Manual Review Queue verhindert, dass ungelöste Datensätze still verschwinden.

Eine gute Recovery-Pipeline versucht nicht, menschlichen Eingriff zu eliminieren — sie begrenzt ihn auf den richtigen Moment, mit der richtigen Evidenz, nach der richtigen Prozedur.

Der nächste Teil geht in die Messaging-Schicht: Exactly-once ist eine Lüge — und wie effectively-once Geschäftsergebnisse durch Defense in Depth erreicht werden.