Refresh HiveGrid Cloud reference snapshot
This commit is contained in:
1 parent
5e99e14772
commit
7f88026f79
5955 files changed
+1177325
-188362
No files matched your search
@@ -0,0 +1,94 @@
|
||||
# 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.
|
||||
Reference in new issue
Block a user