95 lines
5.6 KiB
Markdown
95 lines
5.6 KiB
Markdown
# 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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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
|
|
```
|
|
|
|
3. 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.
|
|
4. 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.
|