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

15 KiB

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

  • 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.
  • Die Registrierung zeigt Kontoangaben und Teamgröße/Tarif als zwei getrennte, per Tastatur bedienbare Seiten mit Zurück-Navigation und erhaltenen Werten.
  • 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.
  • Der Server akzeptiert ausschließlich ganzzahlige, begrenzte Mengen und eine aktive kanonische Monats-Preis-ID; manipulierte Daten erzeugen keine Registrierung oder Provider-Mutation.
  • 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.
  • 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.
  • Unit-, Component-, Route-, DB-, i18n-, A11y-, Visual- und Hot-Swap-Tests decken Empfehlung, Override, Rücknavigation, Persistenz, Manipulation und Billing-Prefill ab.
  • Die Forward-only-Migration ist von einer leeren Datenbank reproduzierbar, enthält Inverse-SQL als Kommentar und verändert keine RLS-Policy.
  • 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.