# 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 - [x] Test-Tenant wird als Lago-Customer angelegt. - [x] Plan + Seat-Subscription wird in Lago erstellt. - [x] Mollie-Testzahlung wird erzeugt und abgeschlossen/simuliert. - [x] Webhook/Synchronisation aktualisiert lokale Subscription. - [x] `tenantHasModule()` und Read-only/Frozen-State reagieren korrekt. - [x] Invoice-/Payment-Referenzen sind sichtbar und auditiert. - [x] Negativfall `payment_failed`/`expired` getestet. - [x] 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. 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.