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

15 KiB

BILL-20 · Bezahlten Workspace mit Welcome-Setup statt CRM-Sprung starten

Typ Launch-Fix · Welcome-/Billing-UX
Owner Raffael
Phase Pilot-Härtung
Cycle/Fenster gestartet 2026-08-02
Status Done
Plane HIVEGRID-241

🎨 design-nachzug: offen — der Pilot-Slice nutzt gemaess AD-28 die bestehenden ~/ui-Bausteine. VD-P24 enthaelt weiterhin kein finales Welcome-/Billing-Delta.

Abhängigkeiten & Parallelität

  • Blocked by: BILL-19 liefert den klaren, app-chrome-freien Erstaktivierungscheckout. AK-P20 liefert die RLS-gebundene, resumierbare Erste-Schritte-Session. VA-P24a, BILL-13, BILL-14, BILL-15 und MAIL-01 liefern Self-Service-Billing, Mollie-Return, Registrierung, Customer-Portal-Kaufvertrag und Willkommensmail.
  • Blocks: visuelle und funktionale Pilotabnahme vom Signup ueber Mollie TEST bis zum eingerichteten Workspace sowie die abschliessende BILL-19-Journey-Abnahme.
  • Keine Reaktivierung von VA-P24b: Der gecancelte 10-Schritt-Wizard mit YAML-Branchen-Template, irreversiblem Step-Cursor und Demo-Daten-Orchestrierung bleibt ausserhalb dieses Launch-Slices. BILL-20 baut eine fokussierte Welcome-/Setup-Surface auf der vorhandenen AK-P20-Session.
  • Abhängigkeitsschutz: Katalog, Preise, Trial-Policy, Checkout, Webhook-/Return-Sync, Rechnungen, Entitlements, Customer-Portal-Commerce und transaktionale Mailzustellung bleiben autoritativ und unveraendert. Es gibt keine neue Testphase, kein Provider-Embedding und keine Schema-Migration.

Was / Warum

Nach einer bestaetigten Zahlung zeigt HiveGrid derzeit eine eigenstaendige Erfolgsseite mit drei gleichrangigen Abzweigungen und leitet nach zehn Sekunden automatisch auf das Dashboard weiter. Dadurch bestimmt ein Timer statt des Nutzers den naechsten Schritt; die vorhandene Erste-Schritte-Session wird nicht als Welcome-Phase genutzt und die wichtige Team-Einladung bleibt vom resumierbaren Setup getrennt.

Die aktive Billing-Seite stapelt zugleich aktuellen Vertrag, Nutzung, allgemeine Trial-Policy, kompletten Tarif-/Seat-/Speicher-Builder und E-Mail-Marketing-Pakete in einer langen Flaeche. Laufender Vertrag, Tarifaenderung und Zusatzmodule sind unterschiedliche Nutzeraufgaben und werden deshalb getrennt.

Der Pilot-Flow wird zu einer klaren Journey:

  1. Registrierung und Team-/Tarifempfehlung.
  2. App-chrome-freie Basisaktivierung mit serverseitiger Preisvorschau.
  3. Mollie Hosted Checkout im TEST-Modus.
  4. Bestaetigung ohne automatischen CRM-/Dashboard-Sprung.
  5. Eigene Welcome-/Setup-Surface mit automatisch fortschreitenden Aufgaben fuer Profil, Team-Einladung, ersten Kontakt, erstes Projekt und Billing.
  6. Bewusster Wechsel ins Dashboard; das Setup bleibt dort resumierbar.

Nicht im Scope

  • Kein 10-Schritt-Wizard, keine Branchenwahl und keine neuen Demo-Seeds.
  • Keine neuen Preise, Plaene, Add-ons, Trial-Tage oder Entitlements.
  • Kein eingebetteter Mollie-Checkout; Hosted Checkout bleibt der sichere Provider-Schritt.
  • Keine neue Team-Einladungs-Domain und kein Multi-Invite-Backend; die bestehende tenantgebundene Einladungsroute wird als Setup-Aktion verwendet.
  • Keine neue Customer-Portal-Kauflogik; das Billing verweist auf den bestehenden VA-P26c-Kauf-/Domain-Flow.
  • Keine neue Willkommensmail. Der mit CR-015 gehaertete MAIL-01-Flow wird als Teil der Launch-Abnahme erneut visuell und technisch auditiert.

Definition of Done

  • Der bestehende Signup-/Aktivierungsflow bleibt fachlich unveraendert: Ohne bestaetigte Basiszahlung oder echte Katalog-Testphase gibt es keinen Produktzugriff.
  • Der erfolgreiche Checkout-Return bestaetigt Plan/Zahlungszustand, hat keinen Timer und fuehrt mit genau einer primaeren Aktion in das Setup.
  • Eine responsive, app-chrome-freie Welcome-Surface zeigt Workspace, naechsten Nutzen und Setup-Fortschritt; das Dashboard ist eine bewusste Sekundaeraktion, nicht der automatische Zielort.
  • Profil, Team-Einladung, erster Kontakt, erstes Projekt und Billing werden tenant-/usergebunden erkannt. Bestehende Membership oder ausstehende Einladung erfuellt den Team-Schritt; Deep-Links nutzen die bestehenden geschuetzten Routen.
  • Das Setup bleibt ueber die vorhandene Onboarding-Session und das Dashboard-Widget resumierbar; manuelles Erledigen ist nur fuer echte Session-Schritte moeglich.
  • Die aktive Billing-Hauptseite startet mit einer kompakten Uebersicht und trennt Tarif & Nutzer von Zusatzmodule, statt alle Editoren dauerhaft untereinander zu stapeln.
  • Speicher, E-Mail-Marketing und Customer-Portal sind als getrennte Zusatzmodul-Aufgaben erklaert. Checkout und Freischaltung verwenden ausschliesslich die vorhandenen serverautoritativen Vertraege.
  • Loading-, Empty-, Error-, Permission- und Read-only-Zustaende sowie alle neuen Texte sind in de/en und informell/formell verstaendlich; Tastatur, Fokus und mobile Darstellung sind abgedeckt.
  • Pure View-Model-, Service-, Route-, Component-, Accessibility-, Hot-Swap- und Desktop-/Mobile-Visualtests decken Welcome, Team-Erkennung, Checkout-Return und die Billing-Navigation ab.
  • Typecheck, Lint, vollstaendige Testsuite und passende Release-/Source-/ i18n-/A11y-/Visual-Verifier sind gruen.
  • Jeder sichtbare Registrierungs-, Zahlungs-, Welcome-, Setup- und Billing-Zustand liegt nach manueller Bildpruefung als fertig geladener Screenshot im Desktop-Review-Ordner.
  • PR-CI, normaler Merge, Staging-Deploy und ein ausschliesslich mit Mollie TEST ausgefuehrter Signup-zu-Zahlung-zu-Welcome-UAT inklusive Rechnung, Entitlements und Zusatzmodul-Einstiegen sind gruen.

BILL-20: 12/12 DoD = 100 % done. 0 Punkte offen.

2026-08-02 · Abhängigkeitsschutz für BILL-22

  • BILL-22 führt Speicher und E-Mail-Marketing bereits vor der Zahlung als getrennte, optionale Entscheidungen. Die Welcome-Surface, der bewusste Dashboard-Wechsel und die bestätigungsgebundene Add-on-Freischaltung aus diesem Ticket bleiben unverändert.

2026-08-02 · Erster Staging-UAT und fail-closed Nachzug

  • PR #350 wurde nach vollstaendig gruener CI normal als b55fd29e8 nach main gemergt; Staging-Deploy 11792 war fuer Web und API gesund.
  • Der echte Registrierungs-UAT bestaetigte die neue Passwortgrenze, die Swarm-Empfehlung fuer 5 Buero-/15 Baustellen-Nutzer und den direkten Weg in Billing statt CRM. Dabei zeigte sich eine reale Umgebungsluecke: Auf Staging war subscription.required=false, wodurch die persistierte Tarifwahl aus der Registrierung den appweiten Aktivierungs-Gate nicht einschaltete.
  • 92845ec15 macht die persistierte Signup-Billing-Praeferenz zur serverseitigen Aktivierungsentscheidung. Ohne bestaetigte Zahlung oder echte Trial-Berechtigung sind App-Chrome und Fachrouten nun auch bei global optionalem Billing gesperrt; die exakte Aktivierungsroute bleibt erreichbar.
  • Proof des Nachzugs: 25/25 fokussierte Root-/Gate-Tests, Typecheck, Lint und die vollstaendige Suite mit 1.184 Testdateien / 8.238 Tests sind gruen. Vier vollstaendig geladene Live-Screens der Registrierung liegen bereits im Review-Ordner; Zahlung, Welcome und Billing folgen erst nach dem Hotfix- Deploy mit Mollie TEST.

BILL-20: 11/12 DoD = ~92 % done. 1 Punkt offen und selbst machbar: Hotfix-CI, normaler Merge, Staging-Deploy und Fortsetzung desselben Live-UAT.

Technische Bausteine

  • apps/web/app/routes/subscribe.$tenant.$session.success.tsx
  • neue Route apps/web/app/routes/app.$tenant/onboarding/welcome.tsx
  • apps/web/app/routes/app.$tenant.tsx
  • apps/web/app/utils/services/.server/akP20OnboardingService.ts
  • packages/view-models/src/onboarding/**
  • apps/web/app/components/screens/onboarding/**
  • apps/web/app/components/screens/billing/SelfServiceSubscriptionPage.tsx
  • apps/web/app/routes/app.$tenant/settings/billing/index.tsx
  • bestehende ~/ui-Komponenten, keine Direktimporte aus ui-subframe
  • CR-018 in docs/CHANGE-REQUESTS.md

Rollback

Reiner Code-/UI-Rollback auf Checkout-Erfolgsseite, vorhandene Checklistenroute und den bisher dauerhaft ausgeklappten Billing-Builder. Es gibt keine Migration, keinen Backfill und keine Provider-Mutation. Bereits bestaetigte Zahlungen, Rechnungen, Entitlements, Einladungen und Onboarding-Sessions bleiben unveraendert. Der Subscription-Gate aus BILL-19 bleibt auch beim Rollback fail-closed.

Quellen

  • docs/CHANGE-REQUESTS.md · CR-018
  • .planning/ticket-docs/BILL-19.md
  • .planning/ticket-docs/AK-P20.md
  • .planning/ticket-docs/VA-P24a.md
  • .planning/ticket-docs/VA-P24b.md · explizite Nicht-Uebernahme
  • .planning/ticket-docs/BILL-15.md
  • .planning/ticket-docs/MAIL-01.md
  • docs/AGENT-CHECKLIST.md

Umsetzungs-Notiz

2026-08-02 · Diagnose und Start

  • origin/main nach PR #347/Merge 5a2a82224 in einem isolierten Worktree ausgecheckt. EU-Provider-Guard, Workspace-Typecheck und der vollstaendige Baseline-Lauf mit 1.176 Testdateien / 8.280 Tests sind gruen. Staging-Deploy 11737 ist ebenfalls gruen.
  • Bestehenden Provider-/App-Flow bis in Return, Billing-Loader, Portal-Commerce, Onboarding-Session und Dashboard-Widget verfolgt. Der Bruch ist praesentationsseitig: Der Return besitzt einen 10-Sekunden-Timer, waehrend die aktive Billing-Seite drei verschiedene Aufgaben in einer langen Editor-Flaeche vermischt.
  • Offizielle Muster von Linear, Notion, Slack und Intercom verglichen: Einladungen sind eine eigene, klar bepreiste Setup-Aufgabe; Billing trennt Plan, Zahlungsdaten/Rechnungen und Add-ons; Onboarding arbeitet mit kleinen, automatisch fortschreitenden Aufgaben statt eines erzwungenen Tours.
  • Abhaengigkeiten in beide Richtungen in den Ticket-Docs und in Plane gelesen. BILL-20 konsumiert bestehende Vertraege und reaktiviert VA-P24b nicht.
  • Plane-Identitaet als raffael@tool-ctrl.de bestaetigt; HIVEGRID-241 angelegt, Raffael zugewiesen und auf In Progress gesetzt.

BILL-20: 0/12 DoD = 0 % done. 12 Punkte selbst machbar.

2026-08-02 · Lokale Implementierung und Abnahme

  • f99d03624 ersetzt Timer und CRM-/Dashboard-Sprung durch einen app-chrome-freien, responsiven Welcome-/Setup-Screen. Profil, Team-Einladung, Kontakt, Projekt und Billing werden tenant- und usergebunden aus der vorhandenen AK-P20-Session abgeleitet; das Dashboard-Widget nimmt den Flow wieder auf.
  • 738eaef12 strukturiert die aktive Billing-Verwaltung in die drei Hauptaufgaben Uebersicht, Nutzung und Rechnungen. Tarif/Nutzer sowie Speicher, E-Mail-Marketing und Customer-Portal liegen als getrennte, erklaerte Unteraufgaben vor; Checkout-, Preis- und Entitlement-Vertraege bleiben serverautoritativ.
  • ab6c9b447 macht den Checkout-Beleg autoritativ: Er unterscheidet bestaetigte Zahlung, echte Katalog-Testphase und nullpreisige Aenderung, zeigt den gespeicherten Plan sowie den monatlichen Bruttobetrag inklusive Zusatznutzern, Speicher und Umsatzsteuer und erfindet kein Rechnungsdatum.
  • 45a5d327b registriert die neue Welcome-Route in den harten Runtime- und Route-Inventar-Baselines.
  • Vollstaendige Regression: 1.178 Testdateien / 8.286 Tests gruen, 60 umgebungsgebundene Integrationstests erwartungsgemaess uebersprungen. Zusaetzlich sind pnpm test:packages, Typecheck, Lint, Billing-Katalog, Billing-Boundary, Route-Inventar, Sidebar-Routen, i18n, Onboarding, Phase-C-Grenzen, Hot-Swap, 45 fokussierte A11y-Tests, A11y-Coverage, Source-Health, CI-Baseline und Staging-UAT-Readiness gruen. Der globale verify:a11y-baseline-Altbestand auf main meldet 66 statt historisch 56 jsx-a11y/no-autofocus-Treffer; der Branch fuegt keinen autoFocus-Treffer hinzu und veraendert diese Altlast nicht.
  • 35 vollstaendig geladene und manuell gepruefte lokale beziehungsweise vorherige Staging-Nachweise liegen in ~/Desktop/HiveGrid-BILL-20-Welcome-Billing-UAT-2026-08-02. Der getrennte Ordner live-staging/ wird erst nach Merge und Deploy gefuellt.

BILL-20: 11/12 DoD = ~92 % done. 1 Punkt offen und selbst machbar: PR-CI, normaler Merge, Staging-Deploy und Live-UAT.

2026-08-02 · Finaler Merge, Deploy und Live-UAT

  • PR #350 lieferte Welcome-Setup, resumierbares Dashboard-Widget und die aufgeteilte Billing-Verwaltung; PR #351 zog den fail-closed Gate fuer eine persistierte, noch unbezahlte Signup-Auswahl nach. PR #352 behob die im echten UAT gefundenen Restabweichungen: autoritativer Bruttobetrag im Return, aktuelle Core-/Swarm-/Colony-Namen und kein verschachtelter Settings-Chrome auf der Erstaktivierung.
  • PR #352 wurde nach gruener Bundle-, Coverage- und Voll-CI normal als 0172889382 nach main gemergt. Ein erster Docker-Smoke lief bei drei parallelen Runtime-Dateisystemscans in das gemeinsame 90-Sekunden-Limit; der unveraenderte SHA bestand Attempt 2 vollstaendig. Main-Runs 11817 bis 11820, Build-once-Images und der komplette Coolify-Staging-Deploy sind gruen.
  • Echte Staging-Journey ausschliesslich mit Mollie TEST: Swarm, 5 Buero- und 15 Baustellen-Nutzer, 12 Monate SEPA, 449,00 EUR netto plus 85,31 EUR USt. Die Testzahlung und die bezahlte Rechnung stimmen mit 534,31 EUR ueberein; Plan, 20 Plaetze und 250 GB sind aktiv. Der Return bleibt auch nach 13 Sekunden stehen und fuehrt erst per bewusster Aktion ins Setup.
  • Das Welcome-Setup wurde durch eine ausstehende Testeinladung, den Kontakt Pilot Kontakt und das Projekt Pilotprojekt Nord von 2/5 auf 5/5 fortgeschrieben. Das Dashboard-Widget bleibt danach sichtbar und meldet alle Setup-Schritte als erledigt.
  • Zusatzmodul-Einstiege wurden getrennt geprueft: Speicher +100 GB, E-Mail-Marketing S mit 10.000 Nachrichten und Customer Portal bis zum Mollie-TEST-Checkout. Der zweite Customer-Portal-Checkout wurde nicht bezahlt; die bereits abgenommene BILL-14/15-Staging-Referenz belegt Zahlung, Rechnung und Entitlement fuer Speicher, E-Mail-Marketing und Customer Portal.
  • Ein zweiter, frischer Signup nach dem finalen Deploy belegt den unbezahlten Zustand: Activation-Shell 1, Workspace-Shell 0, Settings-Hub 0; ein direkter Dashboard-Aufruf endet auf plan-required ohne Produkt-Chrome.
  • 37 vollstaendig geladene und manuell gepruefte Live-Bilder plus lokale und vorherige Provider-Referenzen liegen in ~/Desktop/HiveGrid-BILL-20-Welcome-Billing-UAT-2026-08-02. Die Welcome-Mail wurde anhand der lokalisierten HTML-/Plaintext-Staging-Zustellung erneut auditiert; BILL-20 fuegt keinen konkurrierenden Mail-Flow hinzu.

BILL-20: 12/12 DoD = 100 % done. 0 Punkte offen.