283 lines
15 KiB
Markdown
283 lines
15 KiB
Markdown
# BILL-14 · Registrierung mit Teamgröße und Tarifempfehlung
|
|
|
|
| | |
|
|
| ----------------- | ------------------------------------------------------ |
|
|
| **Typ** | Dev/UX + Billing-Übergabe |
|
|
| **Owner** | Raffael |
|
|
| **Phase** | Billing-Recut nach AD-27 |
|
|
| **Cycle/Fenster** | gestartet 2026-07-31 |
|
|
| **Status** | Done |
|
|
| **Plane** | HIVEGRID-213 |
|
|
|
|
## Abhängigkeiten & Parallelität
|
|
|
|
- **Blocked by:** kein technischer Blocker. `BILL-11` und `BILL-13` sind Done
|
|
und liefern Katalog, Checkout, Mollie-Return und Freischaltung.
|
|
- **Production-Aktivierung blockiert durch:** unverändert `BILL-08` / `EXT-16`
|
|
für Mollie-Live-KYC sowie Legal-/Steuerfreigaben.
|
|
- **Blocks:** keinen bestehenden Ticketvertrag. Der Slice verbessert den
|
|
Registrierungs- und ersten Kauf-Flow.
|
|
- **Abhängigkeitsschutz:** technische Plan-/Preis-Codes, Preise, Leistungen,
|
|
Lago-/Mollie-Referenzen und bestehende Checkout-Validierung ändern sich nicht.
|
|
Neue Registrierungsfelder sind optional und brechen bestehende Pre-Auth-
|
|
Konsumenten oder ausstehende Verifizierungen nicht.
|
|
|
|
## Was wir bauen
|
|
|
|
Die bestehende Registrierung wird als zweistufiger Wizard dargestellt. Nach den
|
|
Konto- und Firmenangaben folgt eine eigenständige Seite „Teamgröße & Tarif“.
|
|
Dort gibt der Nutzer die geplanten Büro- und Monteur-/Baustellen-Nutzer an.
|
|
|
|
HiveGrid berechnet für Core, Swarm und Colony anhand des versionierten
|
|
Monatskatalogs den echten Nettopreis aus Grundpreis und Zusatznutzern. Empfohlen
|
|
wird deterministisch die günstigste Konfiguration für die eingegebenen Mengen.
|
|
Die Empfehlung wird begründet und hervorgehoben, bleibt aber bewusst
|
|
überschreibbar.
|
|
|
|
Die gewählten Mengen und der Tarif werden serverseitig validiert, sowohl im
|
|
direkten Signup als auch über die E-Mail-Verifizierung hinweg gespeichert und
|
|
beim ersten Billing-Aufruf vorausgefüllt. Die verbindliche Preisberechnung und
|
|
Freischaltung bleiben im vorhandenen serverseitigen Billing-/Mollie-Flow.
|
|
|
|
## Nicht im Scope
|
|
|
|
- Neue Preise, Tarife, Leistungen, Rabatte oder Feature-Unterschiede.
|
|
- Automatische Enterprise-Angebote oder Vertriebs-Lead-Erzeugung.
|
|
- Eine verbindliche Bestellung vor dem vorhandenen Billing-/Mollie-Checkout.
|
|
- Production-Zahlungen vor `BILL-08` / `EXT-16`.
|
|
- Finale Subframe-Optik; die vorhandene Auth-Interim-UI aus `~/ui` wird
|
|
konsistent erweitert.
|
|
|
|
## Definition of Done
|
|
|
|
- [x] Eine pure, providerunabhängige Funktion berechnet für gültige Büro-/
|
|
Monteur-Mengen alle monatlichen Katalogpreise und empfiehlt bei Gleichstand
|
|
deterministisch den niedrigeren Tarif.
|
|
- [x] Die Registrierung zeigt Kontoangaben und Teamgröße/Tarif als zwei getrennte,
|
|
per Tastatur bedienbare Seiten mit Zurück-Navigation und erhaltenen Werten.
|
|
- [x] Die Teamgrößen-Seite validiert mindestens einen Büro-Nutzer, null oder mehr
|
|
Monteur-Nutzer und die kanonische Obergrenze; Empfehlung, Preisbestandteile
|
|
und manuelle Tarifabweichung sind verständlich sichtbar.
|
|
- [x] Der Server akzeptiert ausschließlich ganzzahlige, begrenzte Mengen und eine
|
|
aktive kanonische Monats-Preis-ID; manipulierte Daten erzeugen keine
|
|
Registrierung oder Provider-Mutation.
|
|
- [x] Tarif und Mengen werden optional im Pre-Auth-Registrierungsdatensatz
|
|
gespeichert, in exakten Replay-/Resend-Prüfungen berücksichtigt und über
|
|
die E-Mail-Verifizierung hinweg unverändert übernommen.
|
|
- [x] Der erste Billing-Aufruf übernimmt Tarif sowie Büro-/Monteur-Mengen als
|
|
reine Präferenz; belegte Sitze und die vorhandene serverseitige
|
|
Checkout-Preisvalidierung bleiben die verbindlichen Untergrenzen.
|
|
- [x] Unit-, Component-, Route-, DB-, i18n-, A11y-, Visual- und Hot-Swap-Tests
|
|
decken Empfehlung, Override, Rücknavigation, Persistenz, Manipulation und
|
|
Billing-Prefill ab.
|
|
- [x] Die Forward-only-Migration ist von einer leeren Datenbank reproduzierbar,
|
|
enthält Inverse-SQL als Kommentar und verändert keine RLS-Policy.
|
|
- [x] Typecheck, Lint, vollständige Testsuite, Billing-/RLS-/Security-Verifier,
|
|
PR-CI und Staging-Deploy sind grün.
|
|
|
|
**Fortschritt:** `BILL-14`: 9/9 DoD = 100 % done. Kein selbst machbarer Punkt
|
|
offen.
|
|
|
|
## Technische Bausteine
|
|
|
|
- Kanonischer `@hivegrid/entitlements`-Katalog und dessen vorhandene
|
|
Preisberechnung; keine zweite Preisquelle in der UI.
|
|
- Bestehender `RegisterScreen` mit `~/ui`-Primitives und VM-/Callback-Daten.
|
|
- Optionale Mengenfelder auf `Registration` im bestehenden `accounts.prisma`-
|
|
Vertrag; keine neue Tabelle und kein neuer RLS-Umfang.
|
|
- Tenant-dauerhafte Signup-Präferenz auf der bestehenden, RLS-geschützten
|
|
`TenantProductConfiguration`; kein vorgezogenes Abo und kein Checkout-Dummy.
|
|
- Bestehende Registration-Capabilities, Replay-Grenzen und Verification-Flow.
|
|
- Erweiterte optionale `preferredSelection` in der Billing-VM; Checkout bleibt
|
|
serverseitig autoritativ.
|
|
|
|
## Rollback
|
|
|
|
- UI- und Empfehlungs-Slice können atomar zurückgerollt werden; die bisherigen
|
|
Plan-Karten bleiben als kompatibler Fallback nutzbar.
|
|
- Die zwei neuen Datenbankspalten sind optional. Ein Code-Rollback ignoriert sie
|
|
sicher; Inverse-SQL zum späteren kontrollierten Entfernen steht in der
|
|
Migration.
|
|
- Bereits gestartete oder bestätigte Zahlungen werden nie gelöscht oder
|
|
verändert. Providerkorrekturen bleiben im bestehenden append-only
|
|
Billing-/Webhook-Pfad.
|
|
|
|
## Quellen
|
|
|
|
- `docs/CHANGE-REQUESTS.md` CR-009
|
|
- `.planning/ticket-docs/BILL-11.md`
|
|
- `.planning/ticket-docs/BILL-13.md`
|
|
- `packages/entitlements/src/commercial-catalog.ts`
|
|
- `docs/AGENT-CHECKLIST.md`
|
|
|
|
## Umsetzungs-Notiz
|
|
|
|
2026-08-01 · Abhängigkeitsschutz für BILL-18
|
|
|
|
- `BILL-18` überarbeitet ausschließlich Darstellung und CAPTCHA-Retry des hier
|
|
gelieferten Registrierungsflows. Tarifkatalog, serverseitige Empfehlung,
|
|
Sitzgrenzen, persistierter Checkout-Prefill und alle Mollie-/Lago-
|
|
Folgeverträge bleiben unverändert.
|
|
|
|
2026-08-02 · Abhängigkeitsschutz für BILL-19
|
|
|
|
- `BILL-19` stellt den bestehenden ersten Billing-Aufruf als eigenen
|
|
Aktivierungszustand dar. Persistierte Präferenz, Katalog, Preisvorschau,
|
|
Mollie-/Lago-Checkout und Entitlement-Aktivierung aus diesem Ticket bleiben
|
|
autoritativ und unverändert.
|
|
|
|
2026-07-31 · gestartet
|
|
|
|
- Explizite Produktfreigabe im Chat für eine separate Registrierungsseite mit
|
|
Büro-/Monteur-Mengen und daraus abgeleiteter Tarifempfehlung.
|
|
- Abhängigkeiten in den Ticket-Docs und Plane in beide Richtungen geprüft:
|
|
`BILL-11` und `BILL-13` sind Done; kein offener Nachfolger konsumiert einen
|
|
geänderten Plan-, Preis- oder Providervertrag.
|
|
- Plane-Identität als `raffael@tool-ctrl.de` bestätigt; `HIVEGRID-213`
|
|
angelegt, Raffael zugewiesen und auf In Progress gesetzt.
|
|
- Sauberer Worktree
|
|
`/Users/raffaelsheikh/Documents/GitHub/HiveGrid-Cloud-feat-bill-14-registration-plan-advisor-20260731`
|
|
auf `origin/main` (`288e09a33`) und Branch
|
|
`feat/bill-14-registration-plan-advisor-20260731`.
|
|
- Preflight-Proof: EU-Provider-Guard leer, vollständiger Typecheck grün und
|
|
8.133 Tests grün (60 übersprungen).
|
|
|
|
**BILL-14: 0/9 DoD = 0 % done. 9 Punkte selbst machbar.**
|
|
|
|
2026-07-31 · Implementierung und lokaler Release-Proof
|
|
|
|
- Zweistufiger Registrierungs-Wizard mit serverseitiger Tarifempfehlung,
|
|
echtem Preis inklusive Zusatznutzern, verständlicher Aufschlüsselung,
|
|
manueller Abweichung und wertstabiler Zurück-Navigation umgesetzt.
|
|
- Tarif und Büro-/Monteur-Mengen werden streng als Paar validiert, in der
|
|
Pre-Auth-Registration gespeichert, bei Replay/Resend exakt gebunden, nach
|
|
Reload wiederhergestellt und in den ersten Billing-Aufruf übernommen.
|
|
- Der Billing-Prefill bleibt eine Präferenz: aktive Belegung, kanonischer
|
|
Katalog und vorhandene Checkout-Validierung bleiben autoritativ.
|
|
- Fresh-Migration-Parität, Nicht-Superuser-RLS-Kette und Release-Readiness
|
|
grün. Die Migration verändert keine RLS-Policy und dokumentiert die
|
|
koordinierte Inverse-SQL.
|
|
- Lokaler Proof: Typecheck und Lint grün; 1.157 Testdateien und 8.151 Tests
|
|
grün (60 bewusst übersprungen); 104 fokussierte Tests grün; i18n,
|
|
Billing-Katalog/-Boundary, Route-Inventar, Secrets, Hot-Swap, Visual,
|
|
A11y-Coverage/Axe und RLS-Verifier grün.
|
|
|
|
**BILL-14: 8/9 DoD = ~89 % done. Offen: PR-CI, Staging-Deploy und Live-UAT.**
|
|
|
|
2026-08-01 · Live-UAT-Zwischenstand
|
|
|
|
- Registrierung, Tarifempfehlung, Swarm-Basischeckout, Mollie-Testzahlung,
|
|
bestätigte Freischaltung, Rechnungsansicht sowie E-Mail-Marketing-Add-on mit
|
|
zweiter Mollie-Testzahlung sind auf Staging erfolgreich belegt.
|
|
- Die Customer-Portal-Verwaltung zeigte danach einen abhängigen Pilotfehler:
|
|
Frische Tenants besaßen keinen Portal-Scaffold und liefen vor dem Kaufen-Gate
|
|
in `PORTAL_NOT_FOUND`. Der eng begrenzte Nachzug wird als `BILL-15` / CR-010
|
|
umgesetzt; Preise, Entitlements und der BILL-14-Vertrag bleiben unverändert.
|
|
|
|
**BILL-14: 8/9 DoD = ~89 % done. Offen: Abschluss des Live-UAT nach BILL-15;
|
|
kein externer Blocker.**
|
|
|
|
2026-08-01 · Live-Abschluss
|
|
|
|
- Haupt-PR `#304` und die im Live-UAT gefundenen eng begrenzten Nachzüge
|
|
`#306`, `#308`, `#310`, `#311`, `#313`, `#314` und `#315` wurden normal
|
|
gemergt. Die abschließende PR-CI `#11619` sowie die Main-Runs `#11622` und
|
|
`#11623` waren grün.
|
|
- Der synthetische Staging-UAT belegt Registrierung, serverseitige Swarm-
|
|
Empfehlung, manuelle Tarifwahl, Rücknavigation, Billing-Prefill, exakte
|
|
Preisvorschau, Mollie-Testcheckout, bestätigte Freischaltung und
|
|
Rechnungsansicht. Die Screenshots `06` bis `17` liegen im Desktop-Ordner
|
|
`HiveGrid-BILL-14-UAT-2026-07-31/final-live-verified-2026-08-01`.
|
|
- `BILL-15` schloss den während dieses UAT entdeckten Portal-Scaffold-Fehler.
|
|
`BILL-16` bleibt ein nachgelagerter Settlement-Bugfix für wiederkehrende
|
|
Add-on-Erstrechnungen; er ändert den abgeschlossenen Registrierungs-, Tarif-
|
|
und Basischeckout-Vertrag dieses Tickets nicht.
|
|
|
|
**BILL-14: 9/9 DoD = 100 % done. Plane-Sync ausstehend; 0 Punkte selbst
|
|
machbar offen.**
|
|
|
|
2026-08-01 · Live-Reload-Korrektur gestartet
|
|
|
|
- Ein frischer zweiter Staging-UAT bestätigte Registrierung, Captcha,
|
|
Swarm-Empfehlung und 5/15-Sitzpräferenz. Beim späteren direkten Aufruf der
|
|
Billing-Route ohne die einmaligen Redirect-Queryparameter fiel der noch
|
|
unbezahlte Tarif jedoch auf Core zurück; es wurde bewusst keine falsche
|
|
Zahlung gestartet.
|
|
- Root Cause: Die Präferenz war korrekt im konsumierten `Registration`-Datensatz
|
|
gespeichert, der Billing-Loader las bisher aber ausschließlich die URL.
|
|
- Der Nachzug verwendet eine schmale app-only SECURITY-DEFINER-Projektion für
|
|
exakt Tarif, Büro- und Feldsitze. Tenant, User, aktive Mitgliedschaft,
|
|
Runtime-Rolle und transaktionslokaler RLS-Kontext müssen vollständig
|
|
übereinstimmen; direkte Registration-Lesezugriffe bleiben operator-only.
|
|
- URL-Präferenzen bleiben vorrangig, persistierte Werte werden erneut am
|
|
aktiven Katalog validiert und nach bestehendem Abo nicht mehr gelesen.
|
|
- Lokaler Proof: 108 fokussierte Tests, Typecheck, Lint, Policy-Generator
|
|
377/377 und der vollständige achtphasige Fresh-Migration-/FORCE-RLS-Live-Gate
|
|
einschließlich 47/47 Kern-RLS-Tests sind grün.
|
|
|
|
**BILL-14: 8/9 DoD = ~89 % done. Offen: PR-CI, normaler Merge,
|
|
Staging-Deploy und Queryless-Reload-UAT; kein externer Blocker.**
|
|
|
|
2026-08-01 · direkter Signup-Pfad korrigiert
|
|
|
|
- Der erste Korrektur-PR `#324` wurde normal gemergt und als Revision
|
|
`35160c967` auf Staging ausgerollt. Der anschließende frische UAT widerlegte
|
|
jedoch die angenommene Datenquelle: Bei deaktivierter E-Mail-Verifizierung
|
|
erzeugt der direkte Signup absichtlich keine `Registration`-Zeile. Der erste
|
|
Billing-Aufruf war deshalb nur durch die Redirect-Query korrekt; vor einer
|
|
falschen Mollie-Testzahlung wurde der Lauf gestoppt.
|
|
- Der gemeinsame Post-Bootstrap-Pfad speichert die validierte Tarif-/Büro-/
|
|
Monteur-Auswahl jetzt als vollständiges Triplet in der tenant-gebundenen
|
|
`TenantProductConfiguration`. Ein eigener Idempotency-Fingerprint bindet die
|
|
Auswahl an den deterministischen Signup-Key: Exakte Retries sind erlaubt,
|
|
eine abweichende Auswahl unter demselben Key scheitert geschlossen.
|
|
- Der Billing-Loader priorisiert weiterhin eine gültige URL, liest danach die
|
|
Tenant-Präferenz und nutzt die schmale Registration-Capability nur noch als
|
|
Rolling-Compatibility-Fallback für bereits konsumierte Verify-Signups. Nach
|
|
vorhandenem Abo wird keine Signup-Präferenz mehr angewendet.
|
|
- Lokaler Zwischenproof: 77 fokussierte Tests, Prisma-Validierung, Typecheck,
|
|
fokussiertes ESLint, Policy-Generator `377/377` und Diff-Check grün. Der
|
|
FORCE-RLS-Livetest deckt eigene Sichtbarkeit sowie ungebundene und
|
|
Cross-Tenant-Zugriffe ab und läuft im abschließenden Release-Gate.
|
|
|
|
**BILL-14: 8/9 DoD = ~89 % done. Offen: vollständiges Release-Gate, PR-CI,
|
|
normaler Merge, Staging-Deploy und neuer Queryless-Reload-/Mollie-Test-UAT;
|
|
kein externer Blocker.**
|
|
|
|
2026-08-01 · finaler Registrierungs-, Billing- und Add-on-UAT
|
|
|
|
- Der dauerhafte Präferenz-Nachzug `10886efae` wurde über PR `#326` normal
|
|
gemergt. Der abschließende Main-Stand mit dem Mail-Nachzug wurde als Revision
|
|
`137358736` in Deploy `11669` erfolgreich auf Staging ausgerollt.
|
|
- Ein vollständig frischer Signup mit 5 Büro- und 15 Monteur-Nutzern empfahl
|
|
Swarm. Der direkte Billing-Übergang und ein späterer Aufruf ohne einmalige
|
|
Redirect-Query behielten dieselbe Auswahl.
|
|
- Drei ausschließlich in Mollie TEST abgeschlossene Käufe wurden ohne Duplikat
|
|
freigeschaltet: Swarm plus 100 GB für 508,00 EUR netto, E-Mail-Marketing S
|
|
für 59,00 EUR netto und Customer Portal für 19,99 EUR netto. Die jeweiligen
|
|
Rechnungen zeigen 19 % USt. und korrekte Bruttosummen.
|
|
- Der aktive Tenant besitzt 350 GB Speicher, das E-Mail-Marketing-Kontingent
|
|
und den entsperrten Customer-Portal-Admin. Rechnungsansicht, Return-Flows und
|
|
Nachbuchungen sind in den Screenshots `34` bis `57` des finalen Desktop-UAT-
|
|
Ordners belegt; `BILL-17` ergänzt dort den konsistenten Usage-Proof `59`.
|
|
- Die zugehörigen vollständigen lokalen Gates, PR-CIs, normalen Merge-Commits
|
|
und Staging-Deploys sind grün. Es wurde keine Production-Zahlung ausgelöst.
|
|
|
|
**BILL-14: 9/9 DoD = 100 % done. Kein selbst machbarer Punkt offen.**
|
|
|
|
2026-08-02 · Abhängigkeitsschutz für `BILL-21`
|
|
|
|
- Registrierungs-Empfehlung, persistierte Rollen-/Tarifauswahl und der
|
|
Aktivierungs-Gate bleiben unverändert. Erst die serverautoritativ berechnete
|
|
Bruttorate im Billing-Preview entscheidet: ab 1.000,01 EUR ist Karte Pflicht.
|
|
|
|
2026-08-02 · Abhängigkeitsschutz für `BILL-22`
|
|
|
|
- `BILL-22` übernimmt die hier gespeicherten Büro-/Baustellenmengen und die
|
|
serverautoritativ berechnete Empfehlung, trennt deren Darstellung aber in
|
|
Team- und Tarifschritt. Persistenz, Grenzwerte und Checkout-Prefill bleiben
|
|
kompatibel.
|
|
- Ohne vom konkreten Mollie-Profil angebotene Karte entsteht keine
|
|
Provider-Mutation und kein Produktzugriff. `BILL-14` bleibt 9/9 DoD =
|
|
100 % done.
|