228 lines
12 KiB
Markdown
228 lines
12 KiB
Markdown
# BILL-22 · Geführter Checkout mit freier Zahlart und Add-on-Upsells
|
|
|
|
| | |
|
|
| ----------------- | ------------------------------------------------ |
|
|
| **Typ** | Launch-Fix · Registrierungs-/Billing-/Payment-UX |
|
|
| **Owner** | Raffael |
|
|
| **Phase** | Pilot-Härtung |
|
|
| **Cycle/Fenster** | gestartet 2026-08-02 |
|
|
| **Status** | In Arbeit · auf Staging deployed |
|
|
| **Plane** | HIVEGRID-244 |
|
|
|
|
**🎨 design-nachzug: offen** (seit 2026-08-02) — der Pilot-Slice nutzt gemäß
|
|
AD-28 ausschließlich bestehende `~/ui`-Bausteine; ein finales Subframe-Delta
|
|
für den neu geschnittenen Checkout liegt noch nicht vor.
|
|
|
|
## Abhängigkeiten & Parallelität
|
|
|
|
- **Blocked by:** `BILL-11`, `BILL-14`, `BILL-19`, `BILL-20` und `BILL-21`
|
|
sind Done und liefern Katalog, Registrierungspräferenz, Aktivierungs-Gate,
|
|
Welcome-Journey und die EUR-1.000-Kartenregel.
|
|
- **Blocks:** `BILL-08` Production-Aktivierung. Dessen Mollie-Live-/Legal-Gates
|
|
bleiben unverändert extern blockiert.
|
|
- **Abhängigkeitsschutz:** Plan-/Preis-/Entitlement-Codes, Lago-Rechnungen,
|
|
bestätigungsgebundene Freischaltung, Hosted Checkout und bestehende aktive
|
|
Abos bleiben autoritativ. Der technische Cadence-Code `annual_sepa` bleibt
|
|
aus Kompatibilitätsgründen bestehen, erzwingt im Checkout aber keine SEPA-
|
|
Auswahl mehr.
|
|
|
|
## Was / Warum
|
|
|
|
Die aktuelle Registrierung und Erstaktivierung vermischen Teamgröße, Tarif,
|
|
Laufzeit, Speicher, Preisprüfung und Zahlung in langen Karten. Die Empfehlung
|
|
ist dadurch weniger klar als die Eingabe, aus der sie entsteht. Zugleich
|
|
filtert der 12-Monatsvertrag unterhalb von 1.000 EUR Kreditkarten heraus,
|
|
obwohl Mollie diese Zahlart anbietet. Der Recurring-Adapter akzeptiert intern
|
|
außerdem nur `directdebit`, obwohl `BILL-21` oberhalb der Grenze `creditcard`
|
|
anfordert.
|
|
|
|
Der neue Vertrag ist ein geführter, responsiver Ablauf:
|
|
|
|
1. Büro- und Baustellen-Nutzer zuerst erfassen; Slider, Zahleneingabe und
|
|
Rollen-Icons bleiben synchron und tastaturbedienbar.
|
|
2. Die günstigste passende Konfiguration live serverseitig berechnen,
|
|
verständlich begründen und alle Tarife samt echtem Teampreis vergleichen.
|
|
3. Zusatzspeicher auf einer eigenen, überspringbaren Seite anbieten und den im
|
|
Tarif enthaltenen Speicher klar gegen den Mehrbedarf stellen.
|
|
4. E-Mail-Marketing auf einer eigenen Ja/Nein-Seite erklären. Die optionale
|
|
Produktbuchung bleibt ein separater, bestätigter Add-on-Checkout nach der
|
|
Basisaktivierung; es gibt keine vorgetäuschte Bündelzahlung.
|
|
5. Netto, Umsatzsteuer, Brutto, Laufzeit und verfügbare Mollie-Zahlarten auf
|
|
einer fokussierten Zahlungsseite zusammenfassen. Bis einschließlich
|
|
1.000,00 EUR kann der Kunde einschließlich Kreditkarte frei wählen; ab
|
|
1.000,01 EUR ist Karte Pflicht.
|
|
6. Wiederkehrende Belastungen verwenden ein gültiges Mandat der gewählten
|
|
Methodenfamilie. Eine Rechnung fällt nie still von Karte auf SEPA zurück.
|
|
|
|
## Nicht im Scope
|
|
|
|
- Keine eigenen Kartenfelder, kein Mollie-Iframe und keine Speicherung
|
|
sensibler Karten-/Bankdaten in HiveGrid.
|
|
- Keine Änderung der öffentlichen Speicherpreise in diesem Ticket. Die
|
|
Hetzner-Margen werden separat mit Quelle und Preisempfehlung dokumentiert;
|
|
eine Preisänderung braucht eine eigene Produktentscheidung.
|
|
- Keine neue Testphase, kein Enterprise-Self-Service und keine automatische
|
|
Aufteilung großer Rechnungen.
|
|
- Keine Production-Live-Zahlung vor den offenen `BILL-08`-Gates.
|
|
|
|
## Definition of Done
|
|
|
|
- [x] Registrierung trennt Konto, Teamgröße und Tarifentscheidung; Slider,
|
|
Zahleneingabe, Rollen-Icons und vorhandene serverseitige Empfehlung sind
|
|
synchron, responsiv und barrierearm.
|
|
- [x] Aktivierung führt in klar getrennten Schritten durch Team, Tarif,
|
|
Speicher, E-Mail-Marketing und Zahlung; jeder optionale Upsell ist
|
|
explizit überspringbar.
|
|
- [x] Plan- und Zahlungsseiten zeigen den live serverseitig berechneten Netto-,
|
|
Umsatzsteuer- und Bruttobetrag sowie enthaltene und zusätzliche Nutzer/
|
|
Speicher ohne zweite clientseitige Preisquelle.
|
|
- [x] Unterhalb und einschließlich 1.000 EUR bleiben alle für den konkreten
|
|
Betrag von Mollie angebotenen Erstzahlarten wählbar, einschließlich
|
|
Kreditkarte; oberhalb bleibt ausschließlich Kreditkarte zulässig.
|
|
- [x] Wiederkehrende Mollie-Zahlungen akzeptieren Karte und Lastschrift nur mit
|
|
einem gültigen, betragskonformen Mandat; ein fehlendes Kartenmandat
|
|
bricht oberhalb der Grenze fail-closed ab.
|
|
- [x] E-Mail-Marketing wird als eigener, optionaler Folgeschritt transparent
|
|
vom Basischeckout getrennt; Freischaltung erfolgt weiterhin erst nach
|
|
bestätigtem Add-on-Checkout.
|
|
- [x] Unit-, Service-, Worker-, Route-, Component-, i18n-, A11y-, Hot-Swap-
|
|
und Desktop-/Mobile-Visualtests decken Schrittfolge, Livepreise,
|
|
Zahlartwahl, Grenze und Mandatsfehler ab.
|
|
- [x] Typecheck, Lint, vollständige Testsuite und passende Billing-/Source-/
|
|
i18n-/A11y-/Visual-Verifier sind grün.
|
|
- [ ] PR-CI, normaler Merge, Staging-Deploy und ein ausschließlich mit Mollie
|
|
TEST ausgeführter Signup-zu-Zahlung-UAT sind grün; fertige Screenshots
|
|
liegen im Desktop-Review-Ordner.
|
|
|
|
**BILL-22: 8/9 DoD = ~89 % done. Offen: interaktiver Mollie-TEST-UAT.
|
|
PR-CI, normaler Merge, Staging-Deploy und nichtinteraktive Live-Probes sind
|
|
grün.**
|
|
|
|
## Technische Bausteine
|
|
|
|
- `apps/web/app/modules/users/components/RegisterScreen.tsx`
|
|
- `apps/web/app/modules/users/components/RegistrationPlanStep.tsx`
|
|
- `apps/web/app/components/screens/billing/SelfServiceSubscriptionPage.tsx`
|
|
- `apps/web/app/routes/app.$tenant/settings/billing/index.tsx`
|
|
- `apps/web/app/services/billing/payment-methods.server.ts`
|
|
- `packages/billing/src/mollie-payment-policy.ts`
|
|
- `packages/billing/src/mollie.ts` und `packages/billing/src/types.ts`
|
|
- `apps/worker/src/jobs/recurring-invoice-collection.ts`
|
|
- bestehende `~/ui`-Komponenten und serverautoritatives Billing-View-Model
|
|
- `docs/CHANGE-REQUESTS.md` · CR-021
|
|
|
|
## Rollback
|
|
|
|
- UI-Schrittfolge und freie Auswahl unterhalb der Grenze können gemeinsam auf
|
|
den bisherigen Aktivierungsbuilder zurückgesetzt werden. Serverseitige
|
|
Preis-, Gate- und Entitlement-Verträge bleiben bestehen.
|
|
- Bereits erzeugte Mollie-Zahlungen, Mandate und Lago-Rechnungen werden nie
|
|
gelöscht oder umgeschrieben. Bei einem Payment-Rollback bleibt die
|
|
EUR-1.000-Grenze mindestens fail-closed; es gibt keinen SEPA-Fallback.
|
|
|
|
## Quellen
|
|
|
|
- `docs/CHANGE-REQUESTS.md` · CR-021
|
|
- `.planning/ticket-docs/BILL-11.md`
|
|
- `.planning/ticket-docs/BILL-14.md`
|
|
- `.planning/ticket-docs/BILL-19.md`
|
|
- `.planning/ticket-docs/BILL-20.md`
|
|
- `.planning/ticket-docs/BILL-21.md`
|
|
- https://docs.mollie.com/docs/recurring-payments
|
|
- https://docs.mollie.com/reference/mandates-api
|
|
- https://docs.hetzner.com/storage/object-storage/overview/
|
|
- https://www.hetzner.com/storage/object-storage/
|
|
|
|
## Dev-Nachzug
|
|
|
|
- Interim-UI wird gegen Desktop und Mobile visuell geprüft. Nach Davids
|
|
finalem Delta müssen ausschließlich Adapter/Visual-Baselines nachgezogen
|
|
werden; View-Model-, Payment- und Entitlement-Verträge bleiben stabil.
|
|
|
|
## Umsetzungs-Notiz
|
|
|
|
2026-08-02 · gestartet
|
|
|
|
- Explizite Produktfreigabe im Chat für freie Kreditkartenwahl auch unter
|
|
1.000 EUR, Teamgröße vor Tarif, live berechnete Preise und getrennte
|
|
Speicher-/E-Mail-Marketing-Upsells.
|
|
- `blocked-by` und `blocks` in Plane sowie den betroffenen Ticket-Docs in beide
|
|
Richtungen geprüft. Plane-Identität als `raffael@tool-ctrl.de` bestätigt;
|
|
`HIVEGRID-244` angelegt, Raffael zugewiesen und auf In Progress gesetzt.
|
|
- Neuer Worktree `HiveGrid-Cloud-feat-bill-22-guided-checkout` auf aktuellem
|
|
`origin/main`; EU-Provider-Guard leer, Typecheck und vollständige Baseline
|
|
mit 1.187 Testdateien / 8.278 Tests grün (60 bewusst übersprungen).
|
|
- Diagnose: `BILL-21` wählt für wiederkehrende Rechnungen über 1.000 EUR zwar
|
|
`creditcard`, der Mollie-Adapter lehnte für `sequenceType=recurring` jedoch
|
|
weiterhin jede Methode außer `directdebit` ab. Gemockte Worker-Tests hatten
|
|
diesen Integrationswiderspruch nicht erkannt. Der Nachzug ist Teil dieses
|
|
Tickets.
|
|
|
|
2026-08-02 · lokale Umsetzung und Verifikation
|
|
|
|
- Registrierung in Konto, Team und Tarif getrennt. Büro-/Baustellen-Nutzer
|
|
lassen sich per Slider, Zahleneingabe und Plus/Minus bedienen; die
|
|
serverseitige Empfehlung und alle Teampreise aktualisieren sich live.
|
|
- Aktivierung in Team, Tarif, Speicher, E-Mail und Zahlung geteilt. Speicher
|
|
und E-Mail-Marketing sind eigene überspringbare Upsells. Ein ausgewähltes
|
|
E-Mail-Paket wird erst nach bestätigter Basiszahlung in einen eigenen
|
|
Add-on-Checkout überführt.
|
|
- Mollie lässt bis einschließlich 1.000,00 EUR alle für den Betrag verfügbaren
|
|
Erstzahlarten inklusive Kreditkarte zu. Ab 1.000,01 EUR wird ausschließlich
|
|
Kreditkarte angefordert. Recurring Collections prüfen die passende
|
|
Mandatsfamilie und brechen ohne erforderliches Kartenmandat fail-closed ab.
|
|
- Commits: `90c4f4079`, `c1fa42867`, `b15d3b5f6`, `9242ab48c`,
|
|
`3f3aa7903`, `cbb0a071f`, `aee4fb301`, `2cd062114`.
|
|
- Vollständige Testsuite: 1.187 Testdateien und 8.293 Tests grün, 60 bewusst
|
|
übersprungen. Package-Tests, Coverage-Vertrag, Typecheck, Lint, i18n,
|
|
Billing-Boundary/-Catalog, Source-Health, Hot-Swap, A11y-Coverage und
|
|
Visual-Verifier grün. Component-Visualtests: 6/6 Desktop/Mobile grün.
|
|
- Bekannte globale Baseline-Altlast: `verify:a11y-baseline` meldet auf diesem
|
|
Branch unverändert 66 historische `autoFocus`-Treffer gegenüber 56 in der
|
|
Baseline. BILL-22 fügt keinen Treffer hinzu; A11y-Coverage und die neuen
|
|
interaktiven Flows sind grün. Dieser repo-weite Nachzug ist nicht Teil des
|
|
Tickets.
|
|
- 13 fertig gerenderte und visuell geprüfte Screens liegen unter
|
|
`/Users/raffaelsheikh/Desktop/HiveGrid-BILL-22-Checkout-Review-2026-08-02/`.
|
|
Live-Staging-Screens folgen nach dem Deploy.
|
|
- Hetzner-Recherche: 1 TB ist im Object-Storage-Grundpreis von 6,49 EUR/Monat
|
|
enthalten; zusätzlicher Speicher kostet 6,26 EUR/TB/Monat. Die aktuellen
|
|
HiveGrid-Aufpreise erzielen vor Grundpreis, Redundanz, Betrieb und Traffic
|
|
rund 93,0 % (100 GB), 89,2 % (500 GB), 87,2 % (1 TB) und 84,3 % (5 TB)
|
|
Rohmarge. Eine niedrigere Preisstaffel ist in `docs/pricing-draft.md`
|
|
vorgeschlagen, aber bewusst nicht ohne Produktentscheidung aktiviert.
|
|
|
|
2026-08-02 · Merge, Deploy und Live-Probes
|
|
|
|
- PR `#360` nach grüner Bundle-, Coverage- und 11/11-Haupt-CI normal gemergt;
|
|
BILL-22-Head `69f74183c`, Merge-Commit `a44a239e7`.
|
|
- Ein durch den unmittelbar vorausgehenden Parallel-Merge `#359` sichtbar
|
|
gewordener i18n-Paritätskonflikt wurde separat in PR `#362` behoben. Der
|
|
Hotfix lief lokal mit Typecheck, Lint, 8.320 Tests, i18n und Coverage grün
|
|
und wurde nach vollständiger PR-CI normal als `54dab6304` gemergt.
|
|
- Main-Runs `11881` (Bundle), `11882` (Coverage), `11883` (Images, Migration,
|
|
Coolify-Staging) und `11884` (Repository-Metriken) sind grün. Alle zwölf
|
|
Coolify-Ressourcen wurden mit dem immutable Merge-SHA ausgerollt; der
|
|
revisionsgebundene Portal-Domain-Controller-Healthcheck ist grün.
|
|
- Live auf `staging-app.hivegrid.de`: `/healthz`, `/readyz` und `/register`
|
|
antworten mit HTTP 200; Health und Readiness melden Revision `54dab6304`.
|
|
Die serverseitige Tarifberatung empfiehlt und berechnet für 1/0 Core mit
|
|
199 EUR, für 5/15 Swarm mit 499 EUR und für 10/20 Swarm inklusive Extras mit
|
|
789 EUR netto.
|
|
- Der ausschließlich mit Mollie TEST auszuführende interaktive
|
|
Signup-zu-Zahlung-UAT bleibt offen, weil in der ausführenden Sitzung keine
|
|
unterstützte Browser-Verbindung verfügbar war. Es wurde weder eine echte
|
|
Zahlung ausgelöst noch ein Browser-UAT vorgetäuscht.
|
|
|
|
**BILL-22: 8/9 DoD = ~89 % done. Offen: interaktiver Mollie-TEST-UAT
|
|
(extern durch fehlende Browser-Verbindung blockiert; 0 weitere selbst
|
|
machbare Implementierungspunkte).**
|
|
|
|
2026-08-02 · Abhängigkeitsschutz für `BILL-23`:
|
|
|
|
- Die getrennte Speicher-Upsell-Seite bleibt strukturell bestehen und zeigt
|
|
künftig den lizenzbasierten gemeinsamen Workspace-Pool sowie die fairen
|
|
`Cloud-Speicher Plus`-Preise aus derselben serverseitigen Vorschau.
|
|
- Team-, Tarif-, E-Mail- und Zahlartfluss sowie das offene Mollie-TEST-UAT
|
|
ändern sich nicht. `BILL-22` bleibt 8/9 DoD = ~89 % done.
|