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

11 KiB

VA-P24a · P24 Self-Service-Abo-Baukasten-UI (M28-Delta)

⚠️ Billing-Recut 2026-07-04 (AD-27): Self-Service-Billing baut auf Lago + Mollie + HiveGrid-Entitlements auf. Payment-Checkout, Legacy-Provider-Webhooks und Legacy-Provider-Customer-Portal werden nicht wiederverwendet. v1 bleibt Plans + Seats; die funktionale Self-Service-Checkout-Basis wurde am 2026-07-05 in BILL-10 vorgezogen. Dieses Ticket bleibt fuer finale Screens, Preisvorschau-UX und Produkt-/Wizard-Delta.

⚠️ KI→MCP-Pivot (AD-26): Das „AI-Credits"-Add-On entfällt. Kein LLM-Gateway/AiCredits in v1.

Typ Dev (Code)
Owner Raffael
Phase P24 — Self-Service-Billing & Onboarding-Wizard · v2-P3
Cycle/Fenster v2-W1 — Public-API/Postfach/Abo/KI-Start · fällig 2026-07-15
Status Plane Done · 100 % ursprüngliche DoD · separater AD-30-Nachzug 1/1 erfüllt

🎨 design-nachzug: offen (seit 2026-07-15) — VD-P24 enthaelt noch kein Davids Delta; die ticket-faehige Vorschau ist gemaess AD-28 als Interim-UI aus ~/ui umgesetzt.

Abhängigkeiten & Parallelität

  • Blocked by: BILL-02 bis BILL-07 plus BILL-09 bis BILL-12 (Plans/Seats-Domain, Provider-Gateways, Sync/Entitlements, Kunden-Rechnungszugriff, Self-Service-Checkout, Pricing-Katalog und konsistente Kundennamen) — erfuellt; externe Production-Aktivierung bleibt separat in BILL-08 / EXT-16.
  • Blocks: VA-P24b nur fuer gemeinsame Onboarding-/Plan-Kontexte, nicht fuer den Wizard-Kern; VA-P24b ist in Plane aktuell Cancelled.
  • Erfüllter Downstream-Handoff: VA-P26c hat den Vertrag fuer ein pauschales Portal-Add-on und eine einmalige Custom-Domain-Einrichtung auf Staging konsumiert; daraus besteht kein offener Block mehr.
  • Läuft parallel zu: VA-P23 im selben v2-Fenster, sofern Billing-Interfaces stabil sind
  • Konflikt-Risiko: mittel — Self-Service berührt Billing-State, Payment-Callbacks und Entitlements; keine Legacy-Provider-Altpfade erweitern

Uebernahme-Notiz

2026-07-15 · Raffael: Ticket war bei Übernahme in Plane Raffael zugewiesen und stand auf In Progress; aktuell steht es auf In Review. Isolierter Arbeitsstand auf Branch feat/va-p24a-self-service-billing im Worktree HiveGrid-Cloud-va-p24a. Die Upstream-Billing-Blocker sind erfuellt; der fruehere Downstream-Konsument VA-P24b ist in Plane Cancelled. Durch die Uebernahme werden keine Billing-Contracts oder Schemas geaendert.

Startstand: VA-P24a: 2/6 DoD = rund 33 % done · 4 Punkte offen.

Pre-Flight 2026-07-15: Workspace-Struktur und EU-Import-Check sind gruen. Der erste interaktive Volltest lief unter Last in users.mfa.test.ts in einen 20-Sekunden-Timeout; der direkte Wiederholungslauf war mit 11/11 Tests gruen. Der anschliessende saubere CI-Modus-Lauf aus Typecheck und Volltest war vollstaendig gruen: 777 Testdateien bestanden, 8 uebersprungen, 5061 Tests bestanden.

Umsetzungs-Notiz

2026-07-15 · Raffael: Der Self-Service-Abo-Baukasten ist auf feat/va-p24a-self-service-billing umgesetzt. Die Route baut ein reines View-Model aus dem kanonischen Lago-/Mollie-/Entitlement-State und injiziert es in eine AD-28-Interim-UI. Plan, Abrechnungszeitraum und Seats werden serverseitig validiert; die Preisvorschau beruecksichtigt Flat- und Per-Seat-Preise. Trial, sofortige oder zum Periodenende wirksame Aenderungen, Mollie-Return/Webhook-Sync und der lokale Billing-/Entitlement-State sind tenant- und RLS-gebunden. Es wurden keine Prisma-Schemas oder Migrationen geaendert. Der finale Subframe-Nachzug bleibt als design-nachzug offen.

Proof: ursprünglicher P24-Commit 81b321d16 (feat(billing): add self-service subscription builder, übernommen über a456b8dc4); pnpm typecheck, pnpm lint und pnpm test gruen (780 Testdateien bestanden, 8 uebersprungen; 5084 Tests bestanden, 46 uebersprungen). verify:test-coverage, verify:i18n, verify:ui-visual (79 Checks), verify:ui-hot-swap, verify:a11y-coverage, verify:ci-baseline und verify:source-health sind gruen. Der neue Chromium-Smoke ist im Playwright-Projekt registriert; dieser Nachweis behauptet keinen Live-Lauf gegen localhost oder Staging.

VA-P24a: 6/6 DoD = 100 % done.

Was wir bauen

Das Self-Service-Delta auf dem v1-Billing: Die Basis fuer Plan-/Seat-Auswahl, Mollie-Zahlungsstart und Return/Webhook-Sync existiert in BILL-10. Dieses Ticket klaert/ergaenzt darauf aufbauend finale Screens, Preisvorschau-UX, pauschale Add-on-/Einmalpositions-Checkout-Verträge, Wizard-/Onboarding-Kontext und noch fehlende Produktentscheidungen. Lago bleibt Billing-Source-of-Truth fuer Subscription und Invoice, HiveGrid bleibt Entitlement-Source fuer Feature-Gates.

Nicht im Scope dieses Recut-Standes:

  • Credits
  • Add-on-Metering/Usage-Billing. Pauschale Monats-Add-ons und einmalige Einrichtungspositionen sind nach AD-30 erlaubt und werden von VA-P26c konsumiert.
  • Legacy-Provider-Kompatibilitaet
  • finale Rechnungssteller-/Steuerfreigabe

Benötigte Screens (Backend bedient — Design liefert VD-P24)

Screen [Route] Kern-Inhalt
Self-Service-Plan-Wechsel [/:tenant/settings/subscription] Aktueller Plan, Seats, verfügbare Pläne, Preis-Vorschau, Mollie-Zahlungsstart, Checkout-Return-/Payment-Status
Seat-Verwaltung [/:tenant/settings/subscription] Seat-Anzahl erhöhen/reduzieren, sofortige Vorschau, serverseitige Validierung, Audit/Reason bei Sonderfällen
Billing-Status [/:tenant/settings/billing] Lago-Invoice-Status, Mollie-Payment-Status, Fehlzahlung/Expired/Refund-Klartext

Definition of Done

  • Self-Service-Trial ohne Vertriebs-Freigabe ist fachlich entschieden und serverseitig modelliert.
  • Basis-Plan-Wechsel und Seat-Auswahl nutzen Lago-Subscription-State, nicht Legacy-Provider-Checkout. (BILL-10)
  • Zahlung wird ueber Mollie erzeugt und nach Return/Webhook idempotent verarbeitet. (BILL-10)
  • Preis-Vorschau ist serverseitig validiert und nutzt keine oeffentlich hartkodierten Preisversprechen.
  • tenantHasModule()/Entitlements reagieren auf den lokalen Billing-State.
  • RLS/Tenant-Scope auf allen Tenant-Tabellen, globale Produkt-/Preisdefinitionen bewusst getrennt.

Separater AD-30-Nachzug fuer den neuen Downstream-Konsumenten VA-P26c

  • Der generische Produktvertrag fuer pauschale Monats-Add-ons und einmalige Einrichtungspositionen ist geliefert. SubscriptionProductKind trennt Basispaket, wiederkehrendes Add-on, einmaliges Setup und Contract-Override; das idempotente TenantProductAcquisition-Ledger bindet den Erwerb an einen scopeKey. Fehler eines Add-ons oder One-offs kündigen weder das Basispaket noch andere Produkte und setzen nicht den gesamten Tenant auf past_due. Dieser nach Abschluss hinzugekommene Consumer-Contract erweitert nicht rueckwirkend die sechs urspruenglichen DoD-Punkte.

Fortschritt 2026-07-16: ursprünglicher Ticket-Scope 6/6 DoD = 100 % done; separater AD-30-Nachzug 1/1 = 100 % done. Repository-Proof: 18dfd4825 (gemeinsames Produkt-Ledger und Schema-Vertrag) sowie 355eead8e (Billing-, Webhook-, Provider-Adapter- und Entitlement-Vertrag). Generische Ledger-, Idempotenz-, Webhook-Replay-, Refund-/Failure-Isolation- und Entitlement-Tests sind lokal gruen. Es wurde dafür kein Migrationsfile angelegt und kein Billing-Provider-, Staging- oder Produktionszustand mutiert. Die portalspezifischen externen Kaufnachweise bleiben DoD von VA-P26c, nicht von P24a.

Downstream-Entscheidung 2026-07-16: Business erhält das Portal inklusive und bezahlt die Custom-Domain als einmalige 299,99-EUR-Einrichtung; Enterprise erhält Portal plus eine Domain über einen separaten Override. Der generische P24-Vertrag bleibt unverändert: pauschales Add-on, einmalige Position und Entitlement ohne Null-Euro-Checkout. Die portalspezifische Abbildung bleibt vollständig in VA-P26c.

Downstream-Handoff 2026-07-21: VA-P26c hat den generischen Vertrag auf Staging erfolgreich konsumiert: Starter-Add-on, Business-Inklusivrecht, Enterprise-Override und genau eine operatorseitig audit-verknüpfte Lago-One-off-Rechnung samt duplikatfreiem Replay sind belegt. Prometheus-, Kill-Switch-, Deprovisionierungs- und finaler 404-Nachweis wurden anschließend vollständig in VA-P26c abgeschlossen und verändern den bereits erfüllten P24-Vertrag nicht. VA-P24a bleibt 6/6 ursprüngliche DoD plus 1/1 AD-30-Nachzug = 100 % done.

Praesentations-Nachzug 2026-08-02: BILL-20 ordnet die bestehende aktive Self-Service-Flaeche in Uebersicht, Tarif/Nutzer und Zusatzmodule. Serverseitige Preisvorschau, Checkout, Payment-Return, Add-on-Ledger und Entitlements aus VA-P24a bleiben unveraendert; es entsteht kein neuer P24-Backend-Contract.

Praesentations-Nachzug 2026-07-29: BILL-12 gleicht die bestehende Interim-UI mit dem versionierten BILL-11-Katalog ab: Die Kundennamen sind Core / Swarm / Colony, waehrend technische Codes und der bestehende pro -> team-Vertrag unveraendert bleiben. Es entsteht keine neue Abhaengigkeit fuer View-Model, Checkout oder Entitlements.

Technische Bausteine

  • Delta auf BILL-02 bis BILL-05 und Rechnungsanzeige aus BILL-09, keine neue Legacy-Provider-Domain.
  • Funktionale Self-Service-Checkout-Basis aus BILL-10.
  • BillingGateway/LagoBillingGateway fuer Plans, Seats, Subscriptions, Invoices.
  • PaymentGateway/MolliePaymentGateway fuer Zahlungsstart und Payment-Status.
  • Checkout-Return-Handler aktualisiert lokalen Billing-State nur ueber idempotente Sync-Events.
  • Generischer Produktvertrag für pauschale wiederkehrende Add-ons und einmalige Setups; kein Portal-spezifischer Domain-Code in P24.
  • PWA-only: reiner Web-Flow, kein App-Store-Billing.

Quellen (granular)

  • docs/ARCHITECTURE-DECISIONS.md → AD-27
  • docs/ARCHITECTURE-DECISIONS.md → AD-30 · Konsument VA-P26c
  • BILL-README.md, BILL-02 bis BILL-07, BILL-09
  • ROADMAP-V2.md → v2-P3 Self-Service-Billing
  • ENTITY-MODEL.md → Domäne 12, nach AD-27 zu recutten
  • designer-briefs/P24-self-service-billing-wizard.md muss nach AD-27 aktualisiert werden

Dev-Nachzug (nach Davids VD-P24-Delta)

Interim-UI (Vorschau, Stand 2026-07-15): Self-Service-Screen aus ~/ui in apps/web/app/components/screens/billing/SelfServiceSubscriptionPage.tsx; die markierte Interim-Baseline liegt unter packages/ui-mock/visual-baseline/va-p24a-interim.snapshot.json. Visual-/Hot-Swap-Proof ist lokal dokumentiert; der Browser-Smoke ist registriert und wird nicht als Staging-/Live-Lauf ausgegeben. Refactor-Nachzug: finale Subframe-Optik aus VD-P24 und Re-Baseline.

  • Spec/ENTITY-MODEL an Davids UI-Entscheidungen angepasst
  • REQUIREMENTS/ROADMAP nachgezogen
  • Plane-Ticket VA-P24a aktualisiert und nach dem Abschlusskommentar auf Done gesetzt (fd270011-4271-4d4d-bf5e-4a635fd214dc, 2026-07-16)