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

264 lines
14 KiB
Markdown

# BILL-13 · Immersiver Mollie-Checkout und Usage-Transparenz
| | |
| ----------------- | ------------------------------------------------------ |
| **Typ** | Dev/QA + kontrollierter Staging-Provider-Proof |
| **Owner** | Raffael |
| **Phase** | Billing-Recut nach AD-27 |
| **Cycle/Fenster** | gestartet 2026-07-30 |
| **Status** | Done |
| **Plane** | HIVEGRID-212 |
## Abhängigkeiten & Parallelität
- **Blocked by:** kein technischer Blocker. `BILL-10`, `BILL-11` und `BILL-12`
sind Done; der katalog- und webhook-basierte Zahlungsweg steht.
- **Production-Aktivierung blockiert durch:** `BILL-08` / `EXT-16` für
Mollie-Live-KYC, SEPA-Limit und Rechnungssteller-/Steuer-/Impressumsfreigabe.
- **Blocks:** keinen bestehenden Ticketvertrag. Der Slice verbessert den
Pilot-Checkout und schließt beobachtete Self-Service-Lücken.
- **Abhängigkeitsschutz:** Lago bleibt Billing-Source-of-Truth, Mollie bleibt
Payment Processor und HiveGrid bleibt Entitlement-Schicht. Bestehende
technische Produktcodes, Preise, Provider-Referenzen und Quoten ändern sich
nicht.
## Was wir bauen
HiveGrid zeigt die Kaufentscheidung vollständig in der eigenen Billing-Oberfläche:
Preis, Leistung, Wirksamkeit und die aktuell bei Mollie für Betrag und
Zahlungssequenz freigeschalteten Zahlarten. Erst nach der Bestätigung erzeugt
der Server den providerseitigen Checkout und übergibt die gewählte Zahlart an
Mollie. Die eigentliche Bank-, Wallet- oder 3DS-Bestätigung bleibt im sicheren
Mollie Hosted Checkout und wird als Top-Level-Navigation geöffnet.
Wiederkehrende Produktkäufe erhalten eine eigene tenant-gebundene Rückkehrseite,
die den Mollie-Status erneut liest und ausschließlich über den idempotenten
Billing-Sync freischaltet. Für E-Mail-Marketing kann direkt in ein anderes
festes Kontingent gewechselt werden: Das bisherige Paket bleibt bis zur
bestätigten neuen Zahlung aktiv; danach wird es in derselben lokalen
Transaktion beendet und sein exakter Lago-Vertrag über die vorhandene
Outbox gekündigt.
Die Billing-Seite zeigt zusätzlich den realen Speicherverbrauch einschließlich
laufender Upload-Reservierungen sowie die im aktuellen Zeitraum versendeten
E-Mail-Marketing-Sendungen. Die Anzeige ist read-only und erzeugt weder
verbrauchsbasierte Rechnungen noch Credits.
## Nicht im Scope
- Echte Production-Zahlungen vor `BILL-08` / `EXT-16`.
- Einbettung des Mollie Hosted Checkout in ein Iframe.
- Nutzung der privaten Mollie Checkout-Session-/Custom-Components-Beta.
- Eigene Kartenfelder oder Speicherung von Karten-/Bankdaten in HiveGrid.
- Usage-Metering, Einzel-GB-Abrechnung, Credits oder automatische Overages.
- Neue Preise, Tarife, Feature-Unterschiede oder finale Subframe-Optik.
## Definition of Done
- [x] Der Mollie-Gateway-Vertrag lädt aktive Zahlarten nach Betrag, Währung,
Locale und `sequenceType`; Providerantworten und gewählte Methoden werden
strikt validiert.
- [x] Tarif- und E-Mail-Marketing-Checkout zeigen in HiveGrid eine klare
Zusammenfassung samt Zahlart. Mollie übernimmt nur den sicheren
Top-Level-Zahlungsschritt; ein Hosted-Checkout-Fallback bleibt verfügbar.
- [x] Der Server prüft Auswahl, Betrag, Zahlart und SEPA-Vertrag erneut. Eine
manipulierte oder nicht passende Zahlart erzeugt keine Freischaltung.
- [x] Wiederkehrende Produktkäufe kehren auf eine tenant-/permission-gebundene
Statusseite zurück, die den Providerstatus idempotent synchronisiert und
aktive, offene sowie fehlgeschlagene Zahlungen verständlich anzeigt.
- [x] Ein E-Mail-Marketing-Tierwechsel hält das alte Paket bis zur bestätigten
Zahlung aktiv, aktiviert nie zwei Kontingente gleichzeitig und terminiert
das ersetzte Lago-Abo über die bestehende durable Outbox.
- [x] Speicherverbrauch, Upload-Reservierungen und E-Mail-Marketing-Verbrauch
werden RLS-gebunden und read-only in der Billing-VM angezeigt; die
bestehenden atomaren Quotenprüfungen bleiben die Schreib-Grenze.
- [x] Unit-, Route-, Provider-, Webhook-/Sync-, i18n-, A11y-, Visual- und
Hot-Swap-Tests decken Auswahl, Rückkehr, Tierwechsel, Usage sowie
Manipulations-/Fehlerpfade ab.
- [x] Der kontrollierte Staging-Proof validiert Katalogdrift, Mollie-Auswahl,
Redirect/Return, Webhook-Freischaltung, direkten Tierwechsel und Cleanup
ohne offene Testzahlung oder Test-Subscription.
- [x] Typecheck, Lint, vollständige Testsuite, Billing-/RLS-/Security-Verifier,
PR-CI und Staging-Deploy sind grün.
**Fortschritt:** `BILL-13`: 9/9 DoD = 100 % done. Kein selbst machbarer Punkt
offen. Production-Live-Aktivierung bleibt bewusst außerhalb des Ticket-Scopes
und durch `BILL-08` / `EXT-16` blockiert.
## Technische Bausteine
- `@hivegrid/billing`: typisierte Mollie Methods API und validierte
`method`-/`locale`-Übergabe.
- Pure Checkout-/Usage-VMs in `packages/view-models`.
- Bestehende `~/ui`-Komponenten in der `VA-P24a`-Interim-Oberfläche.
- Tenant-gebundene Return-Route und vorhandener `completeProductAcquisition`-
/`applyMolliePaymentSync`-Pfad.
- Bestehende Product-Acquisition-Outbox für die exakte Lago-Terminierung.
- Read-only Usage-Projektionen auf Basis von `OutboundEmail`, `File`,
`FileUpload`, Billing-State und den vorhandenen Quotenservices.
## Rollback
- Die Zahlungsmethoden-Auswahl kann auf den bisherigen Hosted-Checkout ohne
vorausgewählte Methode zurückfallen; Provider-IDs und Mandate bleiben
unverändert.
- Ein Code-Rollback darf bestätigte Zahlungen oder Rechnungen nicht löschen.
Provider-Korrekturen laufen ausschließlich über bestehende
Refund-/Kündigungs- und append-only Audit-/Outbox-Pfade.
- Usage-Anzeigen sind read-only und können ohne Datenmigration entfernt werden.
- Ein begonnener Tierwechsel lässt das alte Kontingent bis zum erfolgreichen
neuen Payment aktiv; fehlgeschlagene oder abgebrochene Zahlungen entziehen
keine bestehende Leistung.
## Quellen
- `docs/CHANGE-REQUESTS.md` CR-008
- `.planning/ticket-docs/BILL-10.md`
- `.planning/ticket-docs/BILL-11.md`
- `.planning/ticket-docs/BILL-08.md`
- `.planning/ticket-docs/EXT-16.md`
- Mollie Docs: Hosted Checkout, Build your own checkout, Methods API,
Create payment und Recurring payments
## Umsetzungs-Notiz
2026-07-30 · gestartet
- Explizite Produktfreigabe im Chat für die offenen Billing-Nachzüge und eine
stärker in HiveGrid eingebettete Mollie-Erfahrung.
- Plane-Identität als `raffael@tool-ctrl.de` bestätigt; `HIVEGRID-212`
angelegt, Raffael zugewiesen und auf In Progress gesetzt.
- Saubere Worktree
`/Users/raffaelsheikh/Documents/GitHub/HiveGrid-Cloud-billing-completion`
auf `origin/main` (`9dfde216e`) und Branch
`feat/billing-checkout-usage-20260730`.
- Preflight-Proof: SOPS-Dev-Env geladen, EU-Provider-Guard leer,
vollständiger Typecheck grün und 8.064 Tests grün (60 übersprungen).
- Offizielle Mollie-Auslegung: Zahlungsmethoden-Auswahl über die Methods API
in HiveGrid, danach Top-Level-Redirect zu `_links.checkout`. Mollie empfiehlt
diesen Weg für einen eigenen Checkout. Der vollständige eingebettete
Components-Checkout ist Private Beta und daher kein Launch-Vertrag.
2026-07-30 · Implementierung und lokaler Proof
- Mollie Methods API wird für Tarif- und E-Mail-Marketing-Checkout nach
Bruttobetrag, Währung, Sequenz, Locale und SEPA-Anforderung geladen; die
gewählte Methode wird unmittelbar vor jeder Provider-Mutation erneut
validiert (`73b92d996`, `7dc123557`, `ebc8fbaa3`).
- Die Billing-Interim-UI zeigt Kaufzusammenfassung, verfügbare Zahlarten und
Hosted-Checkout-Fallback. Der E-Mail-Marketing-Wechsel hält das alte
Kontingent bis zum bestätigten Payment aktiv und beendet es danach lokal
atomar samt exaktem Lago-Outbox-Cleanup (`5d0897404`, `9557be6bb`).
- Produktkäufe kehren über eine tenant-, permission- und RLS-gebundene
Statusroute zurück. Sie pollt ausschließlich den idempotenten
`completeProductAcquisition`-Pfad und unterscheidet aktive, offene,
fehlgeschlagene, abgebrochene, abgelaufene und erstattete Zahlungen
(`05d1b7747`).
- Speicherverbrauch einschließlich laufender Upload-Reservierungen sowie
E-Mail-Sendungen im aktuellen Abrechnungszeitraum sind read-only in der
Billing-VM sichtbar (`4dc218667`).
- Deferred Annual-SEPA ohne belastbaren Nullbetrags-Mandatsweg bricht
fail-closed vor Lago-/Mollie-Mutationen ab; der bestehende Vertrag bleibt
unverändert (`374ce57dc`).
- Lokaler Proof: Root-Typecheck und Lint grün; Core-Suite 8.086 Tests grün
(60 übersprungen); Billing-Paket 54 Tests grün; fokussierte Return-, Billing-
und Portal-Suite 100 Tests grün; i18n 15.228 Keys, Hot-Swap,
Route-Inventar, Billing-/RLS-/Security-Verifier und Sandbox-Flow grün.
- Fresh-DB-Proof: RLS-Rollen auf einer leeren Wegwerf-Postgres-Instanz
provisioniert, alle 25 Migrationen von null angewandt, kanonische lokale
Credentials und E2E-Readiness erzeugt. Der reale Chromium-Flow
Login → Billing → E-Mail-Paket → Zahlungsart/Hosted-Fallback → Abbruch ist
grün. Die Wegwerf-Datenbank wurde danach entfernt.
**BILL-13: 7/9 DoD = ~78 % done. Offen: Staging-Provider-Proof und
PR-CI/Staging-Deploy.**
2026-07-31 · kontrollierter Staging-Proof und Abschluss
- Der kanonische Katalog `2026-07-30.1` mit Digest
`6b64ff563c3077f7010aa74a1c2b0ecbd22bf35536560a4e34ae3c9b1b628064`
wurde auf Staging angewandt. Die anschließende Verifikation meldete alle
16 Ressourcen ohne Drift und ohne weitere Änderung.
- Ein vollständig neu registrierter und verifizierter synthetischer
Staging-Tenant übernahm den gewählten Core-/Starter-Tarif korrekt. Die
HiveGrid-Auswahl zeigte die für den Betrag verfügbaren Mollie-Methoden
einschließlich iDEAL und Wero; eine reale Mollie-Testzahlung wurde im
Hosted Checkout über iDEAL/ABN AMRO abgeschlossen und schaltete den
Basistarif frei.
- E-Mail-Marketing S wurde über denselben echten Checkout bezahlt und danach
direkt auf M gewechselt. Das alte S-Kontingent blieb bis zur bestätigten
M-Zahlung aktiv, wurde anschließend atomar beendet und sein exakter
Lago-Vertrag über die durable Outbox terminiert. Alle zwei
Provider-Side-Effects endeten mit `DONE`, ohne Retry oder Fehler.
- Drei echte Mollie-Webhook-Aufrufe wurden mit HTTP 200 verarbeitet und
hinterließen genau die erwarteten dauerhaften Idempotenz- und Audit-Spuren.
Manipulierte Methoden, offene Zahlungen und der sichere Return-/Polling-Pfad
waren im selben Staging-Flow abgedeckt.
- Beim Cleanup wurde ein echter Lifecycle-Randfall gefunden: Der verwaltete
Lago-Preiscode `hg_price_*_<tarif>_<digest>` wurde bei einer
`subscription.terminated`-Nachricht nicht auf den kanonischen Basistarif
zurückgeführt; außerdem blieb dessen lokales Entitlement bei Kündigung
aktiv. Commit `5fe992bb6` ordnet verwaltete Monats- und
Annual-SEPA-Varianten dem Basistarif zu und beendet auch das
Basistarif-Entitlement.
- Der signierte Replay des echten terminierten Lago-Abos auf der
ausgerollten Fix-Revision wechselte den lokalen Zustand von `past_due` auf
`cancelled`. Danach bestanden 0 aktive Produkte, 0 offene
Add-on-Akquisitionen, 0 pending Checkout-Sessions, 0 unfertige
Outbox-Einträge, 0 Outbox-Retries/-Fehler und 0 aktive Lago-Subscriptions.
Bei Mollie blieben 3 bezahlte und 2 bewusst abgebrochene Testzahlungen,
aber keine offene Zahlung.
- Feature-PR `#298` wurde als normaler Merge
`a4d3381d91441a073a07bc0a4021356cf180646b` übernommen; Staging-Deploy
`11559` war grün. Fix-PR `#300` bestand CI-Run `11564` mit 11/11 Jobs,
wurde als normaler Merge
`e7dfff48209132c5d00480d3e3a389a0072e3fce` übernommen und bestand
Staging-Deploy `11565` einschließlich Migration, Primary- und acht
abhängigen Deploys. API-Health und Readiness meldeten exakt diese Revision.
- Finaler lokaler Proof für den Fix: Root-Typecheck, Lint und vollständige
Core-Suite mit 8.127 grünen Tests (60 übersprungen), 48 fokussierte
Billing-Sync-Tests sowie `verify:ci-baseline` und `verify:source-health`
waren grün.
**BILL-13: 9/9 DoD = 100 % done. Kein selbst machbarer Punkt offen.**
2026-08-02 · Abhängigkeitsschutz für `BILL-21`
- Die bestehende HiveGrid-Auswahl und der Mollie Hosted Checkout bleiben
unverändert. `BILL-21` verengt die serverseitig geladene Methodenauswahl ab
1.000,01 EUR brutto auf `creditcard` und zeigt fehlende
Kartenverfügbarkeit als blockierenden Klartextzustand.
- Unterhalb der Grenze bleiben SEPA-Mandatsmethoden und sonstige von Mollie
für `sequenceType=first` gelieferte Methoden unverändert. `BILL-13` bleibt
9/9 DoD = 100 % done.
2026-08-01 · Post-Close-Regression aus finalem Billing-UAT
- Ein frischer, aktiver Swarm-Tenant mit `storage_100gb` zeigte auf der
Billing-Hauptseite korrekt 350 GB, im separaten Usage-Tab jedoch
„0 BYTES / Kein Limit konfiguriert“.
- Root Cause: Die dedizierte Route nutzte noch die Legacy-Projektion aus
`SubscriptionFeature` und `TenantSubscriptionUsageRecord`; nach dem
RLS-gebundenen Modul-Gate liefen ihre eigenen Reads zudem wieder ohne
gebundenen Tenant-Kontext.
- `BILL-17` korrigiert ausschließlich diese Anzeige über den bereits
kanonischen Storage-Resolver. Checkout, Entitlement, Upload-Grenze, Preise
und Provider-Sync waren im selben UAT korrekt und bleiben unverändert.
**BILL-13: 8/9 DoD = ~89 % done. Offen: `BILL-17` CI, Staging-Deploy und
Live-Proof; kein externer Blocker.**
2026-08-01 · Post-Close-Regression erneut abgenommen
- `BILL-17` / PR `#331` bindet den dedizierten Usage-Read an Tenant-RLS und
verwendet für Speicher dieselbe kommerzielle Kapazitätsprojektion wie
Billing-Hauptseite und Upload-Grenze.
- CI `11690`, normaler Merge `a47d6e13e` und Staging-Deploy `11691` waren
vollständig grün. Der Live-Chromium-Proof zeigt beim aktiven Swarm-Tenant
mit `storage_100gb` exakt 0 Bytes Verbrauch, 350 GB Limit und 350 GB Rest.
- Screenshot `59-final-usage-tab-350gb.png` ergänzt den finalen Desktop-UAT-
Ordner. Checkout, Freischaltung, Rechnungen und Provider-Sync blieben
unverändert und waren im selben Tenant bereits erfolgreich belegt.
**BILL-13: 9/9 DoD = 100 % done. Kein selbst machbarer Punkt offen.**