7.7 KiB
7.7 KiB
BILL-07 · Billing E2E Sandbox-Flow
| Typ | Dev/Test |
| Owner | Raffael |
| Phase | Billing-Recut nach AD-27 |
| Cycle/Fenster | nach BILL-03 bis BILL-06 |
| Status | Done |
Abhaengigkeiten & Parallelitaet
- Blocked by:
BILL-03,BILL-04,BILL-05 - Blocks: Prod-Prep und spaetere Customer-facing Billing-Screens.
Was wir bauen
Ein reproduzierbarer Sandbox-Proof fuer den kompletten v1-Billing-Kern: Tenant bekommt Plan/Seats, Lago kennt die Subscription, Mollie-Testzahlung aktualisiert Payment-Status, HiveGrid-Entitlements greifen.
Definition of Done
- Test-Tenant wird als Lago-Customer angelegt.
- Plan + Seat-Subscription wird in Lago erstellt.
- Mollie-Testzahlung wird erzeugt und abgeschlossen/simuliert.
- Webhook/Synchronisation aktualisiert lokale Subscription.
tenantHasModule()und Read-only/Frozen-State reagieren korrekt.- Invoice-/Payment-Referenzen sind sichtbar und auditiert.
- Negativfall
payment_failed/expiredgetestet. - E2E-Schritte sind in einem Runbook dokumentiert.
Nicht im Scope
- Production-Live-Zahlung.
- echte Rechnungs-/Steuerfreigabe.
Technische Bausteine
- Test-Script oder Playwright/Integration-Test mit externen Sandbox-Stubs.
- Eindeutige Testdaten-Prefixes fuer gemeinsame
lago-staging-Instanz.
Quellen
- AD-27
BILL-01bisBILL-06docs/ops/billing-e2e-sandbox.mddocs/ops/lago-staging.md
Umsetzung
2026-07-04: Stub-basierten, reproduzierbaren BILL-07-Sandbox-Flow gebaut.
packages/billing/src/sandbox-flow.tsfuehrt den kompletten Kern-Flow mit deterministischen Lago-/Mollie-Stubs aus, nutzt dabei aber die echten lokalen Sync-/State-BausteineapplyLagoSubscriptionSync,applyMolliePaymentSyncundresolveTenantBillingState.scripts/billing-e2e-sandbox.tsgibt den Proof als JSON aus.docs/ops/billing-e2e-sandbox.mddokumentiert Runbook, Testdaten-Konvention und spaetere Live-Sandbox-Erweiterung.- Proof:
pnpm exec tsx scripts/billing-e2e-sandbox.ts --run-id=manual-proofergibtok: true, 8/8 Steps gruen,activenicht read-only,failed/expired->past_dueread-only,frozenread-only, Invoice-/Payment-Refs sichtbar, 5 Audit-Events und 5 Activity-Eintraege.
DoD: 8/8 = 100 % done.
2026-07-04 Nachtrag Staging-Live-Smoke:
lago-stagingauf node1 initialisiert: Organisation, Default-Billing-Entity, API-Key.- Mesh-only Proxy
lago-staging-mesh-proxy.serviceauf node1:10.42.0.4:3108 -> 127.0.0.1:3108. - HiveGrid-Staging (
hivegrid-api,hivegrid-web,worker-general,worker-webhook) mitLAGO_*undMOLLIE_*Runtime-Env redeployed; laufende Container enthalten die Keys. - Proof aus dem laufenden
hivegrid-api-Container: Lago API HTTP 200, Mollie API HTTP 200. - Synthetischer Staging-Smoke: Lago-Customer mit Prefix
hg-stg-manual-erstellt; Mollie-Testpayment mit Statusopenund Checkout-Link erzeugt.
2026-07-04 Nachtrag Mollie-Webhook-Grenze:
- API-Route
POST /v1/billing/mollie/webhooksinapps/apiregistriert. - Route nimmt Mollies form-urlencoded
identgegen, refetcht die Zahlung serverseitig viaMOLLIE_API_KEY, validierttenantId/invoiceExternalIdaus den verifizierten Payment-Metadaten und schreibt ueberapplyMolliePaymentSync. - Security-Doku bewusst als
provider-refetch-webhookstatt Signatur-Webhook gefuehrt, weil Mollie keine Signatur fuer diesen Payload liefert. - OpenAPI, Route-Inventar, CSRF-Inventar und Scanner-Snapshot aktualisiert.
- Proof:
pnpm --filter @hivegrid/api typecheck;pnpm typecheck;pnpm test; fokussiert zusaetzlichapps/api/src/billing/mollie-webhook-route.test.tsund API-Inventar/OpenAPI-Tests.
2026-07-04 Nachtrag echter Staging-Checkout:
- Realer Staging-Tenant
demo-pro-crmfuer Mollie-Testcheckout genutzt. - Mollie-Payment
tr_Nn3WsWmtkTXXYRCenmVTJim Mollie-Testscreen aufpaidgesetzt. - Mollie-WebHook kam bei
https://staging-api.hivegrid.de/v1/billing/mollie/webhooksmit HTTP 200 an. - HiveGrid-Staging setzte
TenantSubscription.status=activeund speichertelastInvoiceExternalId=hg-stg-invoice-20260704073025/lastPaymentExternalId=hg-stg-mollie-20260704073025. - Direct replay gegen den Webhook ergab
replayed: true,billingStatus: active. staging-admin.hivegrid.dewurde fuer interne Admin-Pruefung provisioniert; korrekte Route:https://staging-admin.hivegrid.de/accounts/billing(ohne/admin-Prefix).- DoD bleibt: 8/8 = 100 % done.
2026-07-04 Nachtrag Lago-Operator-UI:
- Lago-Staging ist fuer Operator-Pruefung unter
https://staging-lago.hivegrid.deerreichbar. - DNS-Pattern fuer Staging bleibt
staging-*.hivegrid.de;staging-lagozeigt vorerst aufnode1, weil die Lago-Staging-Resource dort laeuft. - Public Route ist nur die Lago-Frontend-UI, geschuetzt durch Lago-Login; die Lago-API bleibt intern ueber
http://10.42.0.4:3108. - Lago-Operator-Zugang liegt lokal in
~/.cli-tokens/lago-staging. - Proof:
curlgegenhttps://staging-lago.hivegrid.deliefert HTTP 200; GraphQL__typenameliefert HTTP 200. - DoD bleibt: 8/8 = 100 % done.
2026-07-04 Nachtrag Login-Fix:
- Ursache: Lago-Frontend hatte noch
API_URL=http://127.0.0.1:3108; der Browser postete Login-GraphQL dadurch gegen das Operator-Geraet statt gegen den Server. - Fix: Frontend-
API_URLaufhttps://staging-lago.hivegrid.degesetzt und Traefik fuer/graphqlund/apiauf den Lago-API-Container geroutet. Traefik Basic Auth wurde danach wieder entfernt; Schutz laeuft ueber Lago-Login. - Proof:
env-config.jszeigtwindow.API_URL = "https://staging-lago.hivegrid.de"; GraphQL__typenameueberhttps://staging-lago.hivegrid.de/graphqlliefert HTTP 200; echteloginUser-Mutation mit gespeicherten Lago-Staging-Credentials liefert HTTP 200 und ein Token. - DoD bleibt: 8/8 = 100 % done.
2026-07-05 Nachtrag ActiveStorage-Logo-Fix:
- Ursache: hochgeladene Lago-Logos nutzen Rails ActiveStorage-URLs unter
/rails/active_storage/...; die Public Route zeigte diesen Pfad noch auf das Lago-Frontend, deshalb renderte die UI ein kaputtes Bild. - Fix: Traefik-Dynamic-Config auf
node1(/data/coolify/proxy/dynamic/lago-staging.yaml) erweitert, sodass/rails/active_storageebenfalls auf den Lago-API-Container geht. - Proof: Fake-ActiveStorage-Pfad liefert jetzt API-404 statt Frontend-HTML; echte Billing-Entity-
logo_urlliefert200 image/png. - DoD bleibt: 8/8 = 100 % done.
2026-07-05 Nachtrag Invoice-Template/Beispielrechnung:
- Default-Billing-Entity in Lago staging mit deutschen Rechnungsdaten, 19 % USt, Logo, Dokumentensprache
deund14Tagen Zahlungsziel konfiguriert. - Footer bewusst Mollie-neutral formuliert, damit er sowohl fuer automatische Karten-/Mandatsabbuchung als auch fuer manuelle Zahlung passt.
- Beispielrechnung
HIV-6711-002-008fuerdemo-pro-crmerzeugt und ueber HiveGrid-Kundendownload geprueft:200 application/pdf, DateinameHIV-6711-002-008.pdf, Footer im PDF-Text vorhanden. - DoD bleibt: 8/8 = 100 % done.
2026-07-28 Nachtrag Lago-v1.50-Webhook:
- Der Live-Sandbox-Flow bekommt zusaetzlich die signierte API-Grenze
POST /v1/billing/lago/webhooks. - Vor Aktivierung des Endpoints in Lago muessen die HiveGrid-Staging-API mit dem Lago-Organisations-HMAC
uebereinstimmen und der neue API-Stand deployed sein; die bisherige Staging-Route liefert erwartungsgemaess
noch
404. - Der lokale Contract-Proof deckt gueltige Signatur, manipulierten Body, fehlende Header, Replay, Tenant-RLS, Pending-Subscription, unbekannten Tenant und die Abgrenzung zum Add-on-Ledger ab.
- DoD bleibt: 8/8 = 100 % done.