Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/.planning/ticket-docs/BILL-07.md
T
2026-07-08 16:15:37 +02:00

6.9 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/expired getestet.
  • 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-01 bis BILL-06
  • docs/ops/billing-e2e-sandbox.md
  • docs/ops/lago-staging.md

Umsetzung

2026-07-04: Stub-basierten, reproduzierbaren BILL-07-Sandbox-Flow gebaut.

  • packages/billing/src/sandbox-flow.ts fuehrt den kompletten Kern-Flow mit deterministischen Lago-/Mollie-Stubs aus, nutzt dabei aber die echten lokalen Sync-/State-Bausteine applyLagoSubscriptionSync, applyMolliePaymentSync und resolveTenantBillingState.
  • scripts/billing-e2e-sandbox.ts gibt den Proof als JSON aus.
  • docs/ops/billing-e2e-sandbox.md dokumentiert Runbook, Testdaten-Konvention und spaetere Live-Sandbox-Erweiterung.
  • Proof: pnpm exec tsx scripts/billing-e2e-sandbox.ts --run-id=manual-proof ergibt ok: true, 8/8 Steps gruen, active nicht read-only, failed/expired -> past_due read-only, frozen read-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-staging auf node1 initialisiert: Organisation, Default-Billing-Entity, API-Key.
  • Mesh-only Proxy lago-staging-mesh-proxy.service auf node1: 10.42.0.4:3108 -> 127.0.0.1:3108.
  • HiveGrid-Staging (hivegrid-api, hivegrid-web, worker-general, worker-webhook) mit LAGO_* und MOLLIE_* 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 Status open und Checkout-Link erzeugt.

2026-07-04 Nachtrag Mollie-Webhook-Grenze:

  • API-Route POST /v1/billing/mollie/webhooks in apps/api registriert.
  • Route nimmt Mollies form-urlencoded id entgegen, refetcht die Zahlung serverseitig via MOLLIE_API_KEY, validiert tenantId/invoiceExternalId aus den verifizierten Payment-Metadaten und schreibt ueber applyMolliePaymentSync.
  • Security-Doku bewusst als provider-refetch-webhook statt 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 zusaetzlich apps/api/src/billing/mollie-webhook-route.test.ts und API-Inventar/OpenAPI-Tests.

2026-07-04 Nachtrag echter Staging-Checkout:

  • Realer Staging-Tenant demo-pro-crm fuer Mollie-Testcheckout genutzt.
  • Mollie-Payment tr_Nn3WsWmtkTXXYRCenmVTJ im Mollie-Testscreen auf paid gesetzt.
  • Mollie-WebHook kam bei https://staging-api.hivegrid.de/v1/billing/mollie/webhooks mit HTTP 200 an.
  • HiveGrid-Staging setzte TenantSubscription.status=active und speicherte lastInvoiceExternalId=hg-stg-invoice-20260704073025 / lastPaymentExternalId=hg-stg-mollie-20260704073025.
  • Direct replay gegen den Webhook ergab replayed: true, billingStatus: active.
  • staging-admin.hivegrid.de wurde 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.de erreichbar.
  • DNS-Pattern fuer Staging bleibt staging-*.hivegrid.de; staging-lago zeigt vorerst auf node1, 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: curl gegen https://staging-lago.hivegrid.de liefert HTTP 200; GraphQL __typename liefert 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_URL auf https://staging-lago.hivegrid.de gesetzt und Traefik fuer /graphql und /api auf den Lago-API-Container geroutet. Traefik Basic Auth wurde danach wieder entfernt; Schutz laeuft ueber Lago-Login.
  • Proof: env-config.js zeigt window.API_URL = "https://staging-lago.hivegrid.de"; GraphQL __typename ueber https://staging-lago.hivegrid.de/graphql liefert HTTP 200; echte loginUser-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_storage ebenfalls auf den Lago-API-Container geht.
  • Proof: Fake-ActiveStorage-Pfad liefert jetzt API-404 statt Frontend-HTML; echte Billing-Entity-logo_url liefert 200 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 de und 14 Tagen Zahlungsziel konfiguriert.
  • Footer bewusst Mollie-neutral formuliert, damit er sowohl fuer automatische Karten-/Mandatsabbuchung als auch fuer manuelle Zahlung passt.
  • Beispielrechnung HIV-6711-002-008 fuer demo-pro-crm erzeugt und ueber HiveGrid-Kundendownload geprueft: 200 application/pdf, Dateiname HIV-6711-002-008.pdf, Footer im PDF-Text vorhanden.
  • DoD bleibt: 8/8 = 100 % done.