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

14 KiB

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

  • Der Mollie-Gateway-Vertrag lädt aktive Zahlarten nach Betrag, Währung, Locale und sequenceType; Providerantworten und gewählte Methoden werden strikt validiert.
  • 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.
  • Der Server prüft Auswahl, Betrag, Zahlart und SEPA-Vertrag erneut. Eine manipulierte oder nicht passende Zahlart erzeugt keine Freischaltung.
  • 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.
  • 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.
  • 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.
  • Unit-, Route-, Provider-, Webhook-/Sync-, i18n-, A11y-, Visual- und Hot-Swap-Tests decken Auswahl, Rückkehr, Tierwechsel, Usage sowie Manipulations-/Fehlerpfade ab.
  • Der kontrollierte Staging-Proof validiert Katalogdrift, Mollie-Auswahl, Redirect/Return, Webhook-Freischaltung, direkten Tierwechsel und Cleanup ohne offene Testzahlung oder Test-Subscription.
  • 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.