# 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: ```bash 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 ```bash 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-` - Plan: `hg-stg-plan-bill-07-` - Subscription external ID: `subscription-` - Payment external ID: `payment-` 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.