# BILL-10 · Self-Service-Checkout fuer Planwechsel | | | |---|---| | **Typ** | Dev ohne finale Screens | | **Owner** | Raffael | | **Phase** | Billing-Recut nach AD-27 | | **Cycle/Fenster** | vorgezogen aus `VA-P24a` | | **Status** | Done | ## Abhaengigkeiten & Parallelitaet - **Blocked by:** `BILL-03`, `BILL-04`, `BILL-05`, `BILL-07`, `BILL-09` - **Blocks:** finale Self-Service-Billing-Screens (`VA-P24a`/`VD-P24`) - **Screen-Status:** finale Designs offen; bestehende Tenant-Subscription-Settings werden als funktionale Basis genutzt. ## Was wir bauen Kunden koennen in `/:tenant/settings/subscription` einen oeffentlichen Plan und eine Seat-Anzahl auswaehlen. HiveGrid erstellt serverseitig einen Lago-Customer, eine Lago-Subscription und eine Mollie-Zahlung. Mollie bleibt nur Payment-Processor; Lago/HiveGrid bilden den lokalen Subscription-/Entitlement-State. Rueckkehr aus Mollie und Webhook sind idempotent, damit der Tenant auch dann aktiviert wird, wenn der Browser nicht sauber zurueckkehrt. ## Definition of Done - [x] Subscription-Settings zeigen oeffentliche Plaene und erlauben Plan-/Seat-Auswahl mit vorhandenen Plan-Karten. - [x] Checkout-Action validiert Tenant, Permission, CSRF, Produkt, Preis, Billing-Period, Currency und Quantity. - [x] Lago-Customer und Lago-Subscription werden vor der Zahlung erzeugt. - [x] Mollie-Zahlung enthaelt nur Billing-Minimum plus technische Checkout-Metadaten fuer Tenant, Invoice, Plan und Seats. - [x] CheckoutSessionStatus speichert Provider-Payment-ID, Lago-Subscription-ID, Plan-Code, Preis, Menge und Status. - [x] Mollie-Webhook aktiviert bei bezahlten Self-Service-Zahlungen den lokalen Lago-/HiveGrid-Billing-State. - [x] Checkout-Success-Route prueft die Zahlung erneut und kann den Sync nachziehen, falls der Webhook noch nicht lief. - [x] Tests fuer Billing-Metadaten, Webhook, DB-Checkout-Status, Subscription-Route und Success-Route. ## Umsetzungs-Notiz 2026-07-05 · Raffael - Neuer Service `apps/web/app/services/billing/self-service-checkout.server.ts` kapselt den Checkout: `LagoBillingGateway` fuer Customer/Subscription, `MolliePaymentGateway` fuer Checkout-Link, lokale `CheckoutSessionStatus`-Persistenz. - `/:tenant/settings/subscription` rendert wieder Plan-Karten (`PlansGrouped`) und leitet nach `action=subscribe` auf Mollie weiter. - `POST /v1/billing/mollie/webhooks` spiegelt bezahlte Checkout-Metadaten zusaetzlich ueber `applyLagoSubscriptionSync`, nicht nur ueber `applyMolliePaymentSync`. - `subscribe.$tenant.$session.success` nutzt den neuen Self-Service-Checkout-Status und zieht den idempotenten Sync bei Rueckkehr aus Mollie nach. - Prisma-Migration `20260705123000_billing_self_service_checkout` erweitert `CheckoutSessionStatus`. Proof: - `pnpm --dir apps/web typecheck` - `pnpm --filter @hivegrid/api typecheck` - `pnpm --filter @hivegrid/billing typecheck` - `pnpm --filter @hivegrid/api exec vitest run src/billing/mollie-webhook-route.test.ts src/app.test.ts` - `pnpm --filter @hivegrid/db exec vitest run src/subscriptions.server.test.ts src/billing-sync.server.test.ts` - `pnpm --dir apps/web exec vitest run app/routes/app.\\$tenant/settings/subscription.test.tsx app/routes/subscribe.\\$tenant.\\$session.success.test.tsx` - `pnpm --filter @hivegrid/billing test -- --run src/mollie.test.ts src/sync-outbox.test.ts` **BILL-10: 8/8 DoD = 100 % done.** ## Nicht im Scope - Finale Subframe-Screens fuer Billing. - Vollautomatischer Staging-E2E gegen echte Lago-/Mollie-Testdaten. - Production-Billing-Livegang. - Steuer-/Rechnungssteller-Freigabe. - Usage-Billing, Credits oder Add-on-Metering. ## Quellen - AD-27 - `BILL-03` - `BILL-04` - `BILL-05` - `BILL-07` - `BILL-09` - `VA-P24a`