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

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.