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

5.0 KiB

BILL-03 · Lago-Gateway fuer Customers, Plans, Subscriptions und Invoices

Typ Dev (Code)
Owner Raffael
Phase Billing-Recut nach AD-27
Cycle/Fenster nach BILL-01/BILL-02
Status Umgesetzt / bereit fuer Review

Abhaengigkeiten & Parallelitaet

  • Blocked by: BILL-01, BILL-02
  • Blocks: BILL-05, BILL-06, BILL-07

Was wir bauen

Ein serverseitiges Lago-Gateway in HiveGrid. HiveGrid erstellt/liest Customers, Plans, Subscriptions und Invoice-Status ueber Lago, aber UI-Komponenten sprechen nie direkt mit Lago.

Definition of Done

  • Lago-API-Client mit klarer Env-Konfiguration fuer Staging.
  • Customer-Erstellung fuer Tenant.
  • Plan-/Seat-Subscription erstellen und lesen.
  • Invoice-/Subscription-Status abrufen.
  • Lago-Webhook-Endpunkt oder Pull-Sync-Job definiert und idempotent.
  • Outbox/Retry fuer ausgehende Billing-Sync-Aktionen.
  • Fehlertexte klar und ohne Stacktrace.
  • Tests gegen Mock/Fixture der Lago-API.

Fortschritt: BILL-03: 8/8 DoD = 100 % done.

Nicht im Scope

  • Mollie-Zahlung.
  • Usage Events.
  • Customer-facing Billing UI.

Technische Bausteine

  • BillingGateway-Interface, konkrete Implementierung LagoBillingGateway.
  • Zod-Schemas fuer Lago-Antworten.
  • Redaction fuer API-Keys und Payment-/Invoice-IDs in Logs.

Umsetzungsnotiz

2026-07-04: Server-Gateway fuer Lago umgesetzt. Neues Package @hivegrid/billing enthaelt das BillingGateway-Interface, LagoBillingGateway, Zod-Response-Schemas, Redaction-Helfer, Webhook-Event-Parsing und idempotente Outbox-Args fuer billing.lago.sync. Die API-Konfiguration kennt jetzt LAGO_API_URL, LAGO_API_KEY, LAGO_WEBHOOK_SECRET und LAGO_TIMEOUT_MS; .env.example ist aktualisiert.

Bewusst noch nicht gebaut: Customer-facing UI und Mollie-Zahlung. Der ausgehende Pull-Sync ist als Outbox-Event-Kontrakt definiert und wird in BILL-05 konsumiert.

2026-07-28: Den zuvor nur als Parser-/Outbox-Vertrag vorhandenen Lago-Webhook als echte API-Grenze POST /v1/billing/lago/webhooks geschlossen. Die Route verarbeitet das reale Lago-v1.50-Format mit verschachteltem subscription-/invoice-/customer-Objekt, prueft den Base64-HMAC ueber den unveraenderten Request-Body in konstanter Zeit und verlangt X-Lago-Signature-Algorithm sowie X-Lago-Unique-Key. Rate-Limits laufen vor Body-Parsing; erst nach erfolgreicher Signatur wird der eingebettete Tenant per RLS gebunden. Basisplan-Subscription-Events landen replay-sicher in IdempotencyKey(scope=billing:provider-sync). Pending-, Invoice-, Customer-, unbekannte Plan- und Add-on-Events werden ohne Subscription-Mutation bestaetigt; damit kann ein generisches Lago-Event weder den Basisplan ersetzen noch den separaten, Mollie-gezaeunten Product-Acquisition-Ledger umgehen. OpenAPI, Route-/CSRF-Inventar und Klartext-Fehler wurden nachgezogen.

Proof:

  • pnpm --filter @hivegrid/billing typecheck
  • pnpm --filter @hivegrid/billing test
  • pnpm --filter @hivegrid/config test
  • pnpm exec vitest run packages/db/src/billing-sync.server.test.ts apps/api/src/billing/lago-webhook-route.test.ts apps/api/src/route-access-inventory.test.ts apps/api/src/route-access-inventory-doc.test.ts apps/api/src/csrf-inventory.test.ts apps/api/src/openapi.test.ts packages/billing/src/sync-outbox.test.ts
  • pnpm --filter @hivegrid/api typecheck
  • pnpm exec eslint packages/billing/src/webhook.ts packages/billing/src/sync-outbox.test.ts apps/api/src/billing/lago-webhook-route.ts apps/api/src/billing/lago-webhook-route.test.ts apps/api/src/public-ingress-rate-limit.ts apps/api/src/app.ts apps/api/src/openapi.ts apps/api/src/openapi.test.ts apps/api/src/route-access-inventory.ts apps/api/src/route-access-inventory.test.ts apps/api/src/csrf-inventory.test.ts --max-warnings=0

2026-07-29: Den Lago-v1.50-Webhook auf Staging ausgerollt und den Provider-Vertrag live geschlossen. Der Lago Workspace hat genau einen HMAC-Webhook-Endpunkt. Ein signierter subscription.started-Event fuer die kanonische aktive business-Subscription von demo-pro-crm wurde einmal synchronisiert; der identische Replay wurde als Replay quittiert. Danach existierten exakt ein Idempotency-Datensatz, ein Audit-Event und ein Activity-Eintrag, der lokale Zustand blieb business|active.

Vor dem Live-Proof wurden sechs veraltete synthetische Parallel-Subscriptions ohne Abschlussrechnung oder Gutschrift terminiert. Genau eine aktive business-Subscription bleibt; der Rechnungsbestand blieb bei 27. Der Cleanup ist ueber den verschluesselten Post-Upgrade-Snapshot wiederherstellbar.

Live-Proof:

  • PR #287, Merge-Commit ba1e14c12
  • Unsigned Probe HTTP 401
  • Signierter Erstlauf synced, Replay replayed
  • Persistenz nach Replay: 1 Idempotency-Key, 1 Audit-Event, 1 Activity

Fortschritt: BILL-03: 8/8 DoD = 100 % done.

Quellen

  • AD-27
  • Lago API Docs
  • BILL-01, BILL-02