Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/docs/ops/product-acquisition-recovery.md
T

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:

  1. Tenant und Acquisition stimmen exakt mit dem RLS-gebundenen Datensatz ueberein.
  2. Der Zustand ist ein explizit mehrdeutiger provider_pending-Versuch ohne providerPaymentId oder ein bereits begonnenes, weiterhin blockiertes cleanup.operator_provider_non_creation_confirmed.
  3. Das unveraenderliche Mollie-Maximalfenster plus Reconciliation-Grace ist abgelaufen. Vorher bleibt der automatische Reconciler alleiniger Owner.
  4. Die Mollie-Customer-ID und das exakte Attempt-Reference sind vorhanden.
  5. 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.
  6. Der Operator bestaetigt bei --apply exakt das vom Plan-Lauf ausgegebene Attempt-Reference und gibt eine Audit-Begruendung an.
  7. Der Ledger wird zuerst in einen cleanup.*-Zustand versetzt. Damit sind Reconciler und User-Retry blockiert, bevor ein externer Cleanup beginnt.
  8. Erst nach erfolgreichem Cleanup der exakt gespeicherten Lago-Subscription beziehungsweise Lago-Invoice wird operator.provider_non_creation_confirmed gespeichert. 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

  1. Den read-only Lauf ausfuehren und nur bei status=absence_verified fortfahren. Das ausgegebene attemptReference und observedAt sind der redigierte Proof; keine Mollie-Antwort anhaengen.
  2. 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
  1. Nur status=released_for_retry erlaubt einen neuen User-Checkout. Der naechste Checkout verwendet einen hoeheren providerAttempt, ein neues externes Attempt-Reference und einen dazu gebundenen Idempotency-Key.
  2. Im Audit muessen die beiden Aktionen billing.product_acquisition.operator_recovery_started und billing.product_acquisition.operator_recovery_released fuer 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.