HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/docs/ops/billing-e2e-sandbox.md

Billing E2E Sandbox-Flow

Stand: 2026-07-05

Dieses Runbook dokumentiert den reproduzierbaren BILL-07-Proof fuer den v1-Billing-Kern. Der Standardlauf nutzt lokale Sandbox-Stubs fuer Lago und Mollie, fuehrt aber dieselbe HiveGrid-Sync-Schicht aus, die auch Provider-Webhooks in den lokalen Billing-State spiegelt.

Ziel

Der Flow beweist:

• Test-Tenant wird als Lago-Customer angelegt.
• Plan + Seat-Subscription wird in Lago angelegt.
• Mollie-Zahlung wird erzeugt und als bezahlt simuliert.
• Provider-Sync aktualisiert TenantSubscription lokal.
• Entitlement-/Modul-Gate und Read-only-State reagieren auf den lokalen Billing-State.
• Invoice- und Payment-Referenzen sind sichtbar.
• Sync-Audit und Activity-Eintraege werden geschrieben.
• Negativfaelle failed, expired und frozen setzen den Tenant read-only.

Stub-Proof ausfuehren

Vom Repo-Root:

pnpm exec tsx scripts/billing-e2e-sandbox.ts --run-id=manual-$(date -u +%Y%m%d%H%M%S)

Erwartung:

• JSON-Ausgabe mit "ok": true.
• steps[] enthaelt acht erfolgreiche Schritte.
• activeState.status ist active.
• activeState.readOnly ist false.
• gate.activeAllowed ist true.
• failedState.status ist past_due und failedState.readOnly ist true.
• pastDueState.status ist past_due und pastDueState.readOnly ist true.
• frozenState.status ist frozen und frozenState.readOnly ist true.
• referencesVisible ist true.
• audit.auditEvents und audit.activities sind groesser/gleich 5.

Der Lauf schreibt nicht in die echte Datenbank. Er nutzt deterministische In-Memory-Stubs fuer Provider und DB-Client, ruft aber applyLagoSubscriptionSync, applyMolliePaymentSync und resolveTenantBillingState aus der echten HiveGrid-Codebase auf.

Automatischer Test

pnpm --dir packages/billing test -- sandbox-flow.test.ts

Dieser Test ist CI-tauglich, weil keine externen Lago-/Mollie-Credentials gebraucht werden.

Testdaten-Konvention fuer echte Sandbox

Falls der Flow spaeter gegen lago-staging erweitert wird:

• Customer external ID: hg-stg-bill-07-<short-id>
• Plan: hg-stg-plan-bill-07-<short-id>
• Subscription external ID: subscription-<short-id>
• Payment external ID: payment-<short-id>

Zugang und Tunnel fuer lago-staging stehen in docs/ops/lago-staging.md.

Live-Sandbox-Erweiterung

Der urspruengliche BILL-07-Abschluss war provider-stubbed. Seit 2026-07-04 ist die echte Staging-Verbindung vorbereitet:

• lago-staging ist initialisiert.
• HiveGrid-Staging erreicht Lago ueber http://10.42.0.4:3108.
• HiveGrid-Staging hat LAGO_* und MOLLIE_* Runtime-Env auf API/Web/Worker.
• Provider-Smoke aus dem laufenden hivegrid-api-Container: Lago HTTP 200, Mollie HTTP 200.
• Synthetischer Lago-Customer und Mollie-Testpayment koennen aus Staging erzeugt werden.
• POST /v1/billing/mollie/webhooks ist im API-Runtime registriert. Die Route nimmt Mollies id entgegen, refetcht die Zahlung serverseitig bei Mollie und schreibt den lokalen Billing-State ueber applyMolliePaymentSync. Fuer Self-Service-Checkout-Zahlungen mit Plan-Metadaten schreibt sie zusaetzlich den lokalen Lago-/HiveGrid-Subscription-State ueber applyLagoSubscriptionSync.

Erledigt fuer den manuellen Staging-E2E:

• Abschluss eines echten Mollie-Test-Checkout-Flows gegen die echte Staging-Tenant demo-pro-crm.
• Mollie-Payment tr_Nn3WsWmtkTXXYRCenmVTJ wurde bezahlt, Webhook kam mit HTTP 200 an, Tenant-Billing-Status steht lokal auf active.
• Staging-Admin fuer interne Billing-Pruefung ist unter https://staging-admin.hivegrid.de/accounts/billing erreichbar.
• Lago-Staging hat echte Demo-Rechnungen fuer demo-starter-crm, demo-pro-crm und demo-business-crm. Der HiveGrid-Kundenbereich /:tenant/settings/subscription zeigt die Rechnungen fuer alle drei Demo-Tenants an.
• Lago-Staging speichert neue Invoice-PDFs im Hetzner-Bucket hivegrid-staging-lago; der Kunden-Download laeuft ueber HiveGrid als serverseitiger Proxy nach Permission-/Tenant-Pruefung.
• Die alten lokalen Demo-Invoices *-001 wurden in Lago voided; aktuelle S3-Demo-Invoices sind *-002.
• Billing entity, Logo, German document locale, 14-day payment terms and the neutral Mollie footer are configured in Lago staging.
• Enriched demo invoice HIV-6711-002-008 for demo-pro-crm verifies the current customer-facing PDF shape through HiveGrid's download route.
• Die funktionale Self-Service-Basis ist in HiveGrid verdrahtet: /:tenant/settings/subscription kann oeffentliche Plaene/Seats auswaehlen, erstellt Lago-Customer/Subscription, startet Mollie und verarbeitet Return/Webhook idempotent.

Offen fuer den vollautomatischen Staging-E2E:

• Cleanup-Schritt fuer Lago-/Mollie-Testdaten.
• Wiederholbarer Script-Schritt fuer echte Lago-Plan-/Subscription-/Invoice-Testdaten.
• Browser-Smoke fuer den echten Self-Service-Checkout gegen Staging-Testdaten.

Bis dahin bleibt der Stub-Proof der kanonische, wiederholbare Regressionstest fuer den HiveGrid-Billing-Kern; der Live-Smoke beweist zusaetzlich Provider-Reachability, Checkout-Link-Erzeugung und die API-WebHook-Grenze aus Staging.