109 lines
5.0 KiB
Markdown
109 lines
5.0 KiB
Markdown
# 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-<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.
|