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

272 lines
15 KiB
Markdown

# 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.**