Refresh HiveGrid Cloud reference snapshot

This commit is contained in:
david committed 2026-08-03 15:31:14 +02:00
1 parent 5e99e14772
commit 7f88026f79
5955 files changed
+1177325 -188362

No files matched your search

@@ -0,0 +1,282 @@
# 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.