# 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 - [x] Der bestehende Signup-/Aktivierungsflow bleibt fachlich unveraendert: Ohne bestaetigte Basiszahlung oder echte Katalog-Testphase gibt es keinen Produktzugriff. - [x] Der erfolgreiche Checkout-Return bestaetigt Plan/Zahlungszustand, hat keinen Timer und fuehrt mit genau einer primaeren Aktion in das Setup. - [x] Eine responsive, app-chrome-freie Welcome-Surface zeigt Workspace, naechsten Nutzen und Setup-Fortschritt; das Dashboard ist eine bewusste Sekundaeraktion, nicht der automatische Zielort. - [x] 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. - [x] Das Setup bleibt ueber die vorhandene Onboarding-Session und das Dashboard-Widget resumierbar; manuelles Erledigen ist nur fuer echte Session-Schritte moeglich. - [x] Die aktive Billing-Hauptseite startet mit einer kompakten Uebersicht und trennt `Tarif & Nutzer` von `Zusatzmodule`, statt alle Editoren dauerhaft untereinander zu stapeln. - [x] Speicher, E-Mail-Marketing und Customer-Portal sind als getrennte Zusatzmodul-Aufgaben erklaert. Checkout und Freischaltung verwenden ausschliesslich die vorhandenen serverautoritativen Vertraege. - [x] 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. - [x] Pure View-Model-, Service-, Route-, Component-, Accessibility-, Hot-Swap- und Desktop-/Mobile-Visualtests decken Welcome, Team-Erkennung, Checkout-Return und die Billing-Navigation ab. - [x] Typecheck, Lint, vollstaendige Testsuite und passende Release-/Source-/ i18n-/A11y-/Visual-Verifier sind gruen. - [x] Jeder sichtbare Registrierungs-, Zahlungs-, Welcome-, Setup- und Billing-Zustand liegt nach manueller Bildpruefung als fertig geladener Screenshot im Desktop-Review-Ordner. - [x] 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.**