264 lines
14 KiB
Markdown
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.**
|