Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/.planning/ticket-docs/BILL-07.md
T

150 lines
7.7 KiB
Markdown

# 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.