5.6 KiB
Ambiguous Product-Acquisition sicher aufloesen
Dieses Runbook gilt fuer eine TenantProductAcquisition, deren Mollie-POST /payments
moeglicherweise erfolgreich war, deren Antwort HiveGrid aber nicht erhalten hat. Der Ledger bleibt dann
absichtlich als provider_pending ohne providerPaymentId stehen. Dieser Zustand darf weder per
manuellem Datenbank-Update noch durch einen neuen Checkout freigegeben werden: Ein noch existierendes
Mollie-Payment koennte sonst parallel zum neuen Versuch bezahlt werden.
Der einzige freigegebene Operatorpfad ist:
pnpm exec tsx packages/cli/bin/hivegrid-cli.mjs ops product-acquisition-recovery \
--tenant <tenant-id> \
--acquisition-id <acquisition-id> \
--json
Das Kommando ist standardmaessig read-only. Es setzt den Tenant im RLS-Kontext, verlangt einen aktiven
Plattform-AdminUser aus HIVEGRID_CLI_OPERATOR_USER_ID und benoetigt die vorhandenen
DATABASE_URL-, MOLLIE_API_KEY-, LAGO_API_URL- und LAGO_API_KEY-Werte des Ziel-Environments.
Provider-Secrets oder Provider-Payloads duerfen nicht in Shell-History, Tickets oder Logs kopiert werden.
Sicherheitsvertrag
Das Kommando gibt einen neuen Versuch nur frei, wenn alle Bedingungen gleichzeitig erfuellt sind:
- Tenant und Acquisition stimmen exakt mit dem RLS-gebundenen Datensatz ueberein.
- Der Zustand ist ein explizit mehrdeutiger
provider_pending-Versuch ohneproviderPaymentIdoder ein bereits begonnenes, weiterhin blockiertescleanup.operator_provider_non_creation_confirmed. - Das unveraenderliche Mollie-Maximalfenster plus Reconciliation-Grace ist abgelaufen. Vorher bleibt der automatische Reconciler alleiniger Owner.
- Die Mollie-Customer-ID und das exakte Attempt-Reference sind vorhanden.
- Eine live ausgefuehrte, vollstaendig paginierte Mollie-Suche hat auf keiner Seite ein Payment mit diesem Attempt-Reference gefunden. Der Apply-Lauf wiederholt diese Suche nach dem dauerhaften Retry-Block ein zweites Mal und schliesst damit auch die Provider-/DB-Race. Fremde, zyklische, ungueltige oder unbegrenzt fortgesetzte Pagination-Links brechen fail-closed ab.
- Der Operator bestaetigt bei
--applyexakt das vom Plan-Lauf ausgegebene Attempt-Reference und gibt eine Audit-Begruendung an. - Der Ledger wird zuerst in einen
cleanup.*-Zustand versetzt. Damit sind Reconciler und User-Retry blockiert, bevor ein externer Cleanup beginnt. - Erst nach erfolgreichem Cleanup der exakt gespeicherten Lago-Subscription beziehungsweise
Lago-Invoice wird
operator.provider_non_creation_confirmedgespeichert. Erst dieser Zustand darf durch den normalen Checkout in einen neuen, hochgezaehlten Provider-Attempt ueberfuehrt werden.
Ein provider_payment_found ist ausdruecklich kein Retry-Proof. In diesem Fall nichts freigeben:
solange der Ledger noch provider_pending ist, den worker-general-Reconciler beobachten. Steht er
bereits in cleanup.*, bleibt er sicher blockiert und der gefundene Providerzustand muss als
Billing-Incident untersucht werden.
Anwenden
- Den read-only Lauf ausfuehren und nur bei
status=absence_verifiedfortfahren. Das ausgegebeneattemptReferenceundobservedAtsind der redigierte Proof; keine Mollie-Antwort anhaengen. - Das gleiche Kommando erneut ausfuehren. Der Apply-Lauf wiederholt die exhaustive Live-Suche, er vertraut nicht auf das Ergebnis des ersten Prozesses:
pnpm exec tsx packages/cli/bin/hivegrid-cli.mjs ops product-acquisition-recovery \
--tenant <tenant-id> \
--acquisition-id <acquisition-id> \
--apply \
--confirm-attempt '<attempt-reference-aus-dem-plan>' \
--reason 'Mollie-Suche und Incident-Pruefung bestaetigen: kein Payment angelegt.' \
--json
- Nur
status=released_for_retryerlaubt einen neuen User-Checkout. Der naechste Checkout verwendet einen hoeherenproviderAttempt, ein neues externes Attempt-Reference und einen dazu gebundenen Idempotency-Key. - Im Audit muessen die beiden Aktionen
billing.product_acquisition.operator_recovery_startedundbilling.product_acquisition.operator_recovery_releasedfuer dieselbe Acquisition vorhanden sein.
Fehler und Wiederaufnahme
| Ergebnis | Bedeutung | Aktion |
|---|---|---|
absence_verified |
Read-only Mollie-Negativproof erfolgreich | Mit exaktem Attempt und Begruendung erneut als --apply ausfuehren |
provider_payment_found |
Payment existiert oder ist inzwischen sichtbar | Kein Retry; Reconciler beziehungsweise Billing-Incident verfolgen |
refused |
Status, Zeitfenster, Customer-ID oder Provider-Target erfuellt den Vertrag nicht | Ursache korrigieren, nichts manuell freigeben |
raced |
Ledger hat sich waehrend der CAS-Operation geaendert | Von vorne read-only inspizieren |
Prozessfehler nach operator_recovery_started |
Lago-Cleanup oder Abschluss-Persistenz fehlgeschlagen | Dasselbe Kommando erneut ausfuehren; cleanup.* bleibt retry-blocking und der Cleanup ist idempotent |
released_for_retry |
Mollie-Nichtanlage und Lago-Cleanup sind belegt | Neuer Checkout darf normal durch den User gestartet werden |
Direktes BullMQ-Retry, hivegrid-cli outbox requeue, ein Status-Update per SQL oder das Loeschen des
Acquisition-Datensatzes ersetzen diesen Ablauf nicht. Sie koennen weder die Mollie-Nichtanlage noch den
exakten Lago-Cleanup beweisen.
Nachweis ohne Geheimnisse
Fuer Ticket oder Incident reichen: Environment, Acquisition-ID, Status, Attempt-Reference,
observedAt, Audit-Aktionsnamen und der spaetere Reconciler-/Checkout-Status. Nicht aufnehmen:
Provider-API-Antworten, Provider-Customer-/Payment-IDs, Credentials, Datenbank-URLs, Cookies oder
personenbezogene Checkoutdaten.