150 lines
7.7 KiB
Markdown
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.
|