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

11 KiB

BILL-16 · Exaktes Settlement wiederkehrender Add-on-Erstrechnungen

Typ Pilot-Bugfix · Billing-Settlement
Owner Raffael
Phase Billing-/Customer-Portal-Pilot-Readiness
Cycle/Fenster gestartet 2026-08-01
Status In Progress
Plane ausstehend, Plane aktuell HTTP 502

Abhängigkeiten & Parallelität

  • Auslöser: Der vollständige Live-UAT von BILL-14/BILL-15 hat zwei erfolgreiche Mollie-Testzahlungen für wiederkehrende Add-ons mit aktiven Entitlements, aber weiterhin ausstehenden Lago-Rechnungen nachgewiesen.
  • Erfüllte Grundlagen: BILL-11, BILL-13, BILL-14, BILL-15, AK-P14b und VA-P26c liefern Katalog, Produktledger, Checkout, Freischaltung, Rechnungsansicht und Portal-Gate.
  • Blocks: fachlicher Abschluss von BILL-14 und BILL-15 sowie ein doppelabbuchungssicherer Pilotbetrieb wiederkehrender Add-ons.
  • Abhängigkeitsschutz: TenantProductAcquisition.invoiceExternalId bleibt die unveränderte Mollie-Attempt-Referenz. Preise, Entitlements, Produkt-Scope und Base-Plan-Lifecycle ändern sich nicht.

Was wir bauen

HiveGrid persistiert bei einem wiederkehrenden Produktkauf neben der externen Lago-Subscription-ID auch deren Provider-ID und die exakt zugehörige initiale Lago-Invoice-ID. Die bestehende transaktionale Outbox markiert ausschließlich diese Invoice nach bewiesenem, aktuellem Mollie-Payment als bezahlt.

Die Korrelation verlangt Tenant, beide Subscription-IDs, Betrag, Währung, Subscription-Invoice und Lagos subscription_starting-Grund. Null oder mehrere Treffer bleiben fail-closed. Der bestehende bounded 5-Minuten-Reconciler zieht aktive Bestandskäufe ohne Mirror selbstheilend nach.

Der Lago-Webhook darf eine bereits durch den Produkt-Checkout bezahlte subscription_starting-Invoice nur als skipped_initial markieren und nie in das Recurring-Inkasso geben. Ausschließlich subscription_periodic darf eine neue Mollie-Folgezahlung erzeugen.

Nicht im Scope

  • Preise, Tarife, Entitlements oder Produkt-Scope ändern.
  • Mollie-Live-Zahlungen oder Aufhebung von BILL-08 / EXT-16.
  • Amount-/Newest-Heuristiken ohne exakten Subscription- und Invoice-Reason- Vertrag.
  • Provider-Mutationen aus einer SQL-Migration oder ein ungebundener Cross-Tenant-Backfill.
  • Neue Billing-Features außerhalb des Settlement- und Collection-Vertrags.

Definition of Done

  • Provider-Subscription-ID und initiale Lago-Invoice-ID werden getrennt von der unveränderten Mollie-Attempt-Referenz nullable und tenant-gebunden persistiert und in den lokalen Produkt-Mirror übernommen.
  • Der Lago-Invoice-Contract bildet billing_periods.invoicing_reason ab; der Matcher akzeptiert genau eine subscription_starting-Invoice mit Tenant, beiden Subscription-IDs, Betrag und Währung.
  • Neue Add-on-Checkouts berechnen aus dem unveränderten Nettokatalog den kanonischen Bruttobetrag mit 19 Prozent Umsatzsteuer, persistieren und belasten exakt diesen Betrag; Portal-Plan und One-off-Fee tragen den expliziten de-vat-19-Vertrag und Fixed-Price-Produkte erlauben keine Mengenmanipulation.
  • Die transaktionale Outbox markiert nur die exakt persistierte initiale Invoice eines aktuell aktiven, exakt passenden Mollie-Attempts als bezahlt; stale, refundete, mehrdeutige und gefälschte Jobs bleiben fail-closed.
  • Der bestehende bounded Reconciler repariert aktive Bestandskäufe ohne Provider-Mirror tenantweise, CAS-/RLS-sicher und ohne ungebundene Provider-Mutation.
  • subscription_starting wird nach aktiver bezahlter Acquisition idempotent als skipped_initial markiert und nie erneut eingezogen; ausschließlich subscription_periodic wird als Folgerechnung gequeued.
  • Forward-only-Migration mit Inverse-SQL, fokussierte Unit-/Worker-/API- Tests, Typecheck, Lint, Gesamttests und passende Billing-/RLS-/Migration- Verifier sind grün.
  • PR-CI, normaler Merge, Staging-Deploy und Live-UAT belegen bezahlte Add-on-Rechnungen ohne zweite Mollie-Zahlung; Screenshots liegen im Desktop-Review-Ordner.

Fortschritt: BILL-16: 7/8 DoD = ~88 % done. 1 Punkt selbst machbar: PR-CI, normaler Merge, Staging-Deploy und Live-UAT mit Screenshots. Kein externer Blocker. Plane-Synchronisierung wartet auf Verfügbarkeit.

Rollback

  • Die zwei neuen Provider-Mirror-Felder sind nullable; alter Code ignoriert sie sicher. Die Migration enthält streng begrenzte Inverse-SQL.
  • Bereits bezahlte Rechnungen, Zahlungen und Entitlements werden niemals gelöscht. Ein Code-Rollback stoppt nur neue automatische Korrelationen.
  • Die Reconciler- und Collection-Änderungen sind getrennt atomar revertierbar. Bestehende Outbox-Receipts und skipped_initial-Marker bleiben append-only.

Quellen

  • docs/CHANGE-REQUESTS.md CR-011
  • .planning/ticket-docs/BILL-14.md
  • .planning/ticket-docs/BILL-15.md
  • Lago API: Invoice-Objekt und billing_periods.invoicing_reason
  • docs/AGENT-CHECKLIST.md

Umsetzungs-Notiz

2026-08-01 · gestartet

  • Live-Proof: Basisplan-Invoice bezahlt; wiederkehrende E-Mail-Marketing- und Customer-Portal-Invoices trotz jeweils erfolgreicher Mollie-Testzahlung und aktivem Entitlement weiterhin ausstehend.
  • Root Cause: Der Produkt-Sync publiziert nach Aktivierung einen durable Provider-Side-Effect, dessen Builder für recurring_add_on + active bisher jedoch null liefert. Die gespeicherte invoiceExternalId ist bei diesem Produkttyp bewusst nur die Mollie-Attempt-Referenz und darf nicht als Lago- Invoice-ID verwendet werden.
  • Zweiter Vertragsfehler: Der lokale TenantSubscriptionProduct übernimmt die Lago-Provider-Subscription-ID nicht. Der Recurring-Collector kann deshalb weder initiale noch spätere Invoices exakt an den Produkt-Mirror binden.
  • Offizielle Lago-Dokumentation verifiziert: billing_periods koppelt externe und Provider-Subscription-ID; invoicing_reason=subscription_starting kennzeichnet die initiale, subscription_periodic die spätere Rechnung.
  • Isolierter Worktree auf origin/main (0141ad43b), EU-Provider-Guard leer, Workspace-Typecheck grün und 1.168 Testdateien / 8.200 Tests grün (60 bewusst übersprungen).
  • Plane ist beim Start mit HTTP 502 nicht verfügbar. Keine Plane-Schreibaktion ohne erneute erfolgreiche Identitätsprüfung.
  • Implementiert in den atomaren Commits 4f91b00eb, 07daa4d61, ef8830f82, 24973c050, c5d2c02da, d022e16b1 und 48a8a3e24: exakter Lago-Invoice-Reason-Vertrag, getrennte Provider-Referenzen, RLS-/CAS-sicherer Bestands-Reconciler, exklusiver Outbox-Claim sowie doppelabbuchungssichere Trennung von Start- und Folgerechnung.
  • Ein unabhängiger Code-Review fand sieben konkrete Race-/Kompatibilitäts- und Settlement-Risiken. Alle sieben sind behoben; der zuletzt geschlossene High-Fund bewahrt eine bereits bezahlte Startrechnung bei freiwilliger Kündigung und ist durch einen gezielten Regressionstest belegt.
  • Abschlussprüfung vor Push: Typecheck und Lint grün; 1.168 Testdateien mit 8.200 bestandenen Tests (60 bewusst übersprungen); Prisma-Schema valid; Billing-Katalog 21/21; Tenant-Policy-Vertrag 377/377; Migrations-Parität ohne Diff; Billing-Boundary-, CI- und Source-Health-Baselines grün.
  • Der strenge Live-RLS-Check lief in allen 8 Phasen grün: frische Migrationskette, eingeschränkte App-/Worker-/Chat-/Portal-Rollen, Portal-Policy-Parität und Produkt-Tenant-Bootstrap. Der direkte lokale prisma migrate status war mangels laufender Standard-DB auf Port 6432 nicht erreichbar; die stärkere isolierte Fresh-DB-Prüfung war erfolgreich.
  • PR #320 wurde normal gemergt (ea48f1102) und das Staging-Deployment #11648 rollte Web, API und Worker erfolgreich aus. Der anschließende Live-UAT blieb bei 6/7 DoD: Der General-Worker lief im 5-Minuten-Takt und inspizierte die drei synthetischen Acquisitions, meldete für beide Add-ons aber reproduzierbar active_initial_invoice_missing; die Rechnungen HIV-25FE-013-002 und HIV-25FE-013-003 blieben ausstehend.
  • Live-Root-Cause: Lago v1.50 liefert billing_periods im Listen-Endpunkt für diese Rechnungen als leeres Array, obwohl der jeweilige Invoice-Detail- Endpunkt exakt eine Periode mit beiden Subscription-IDs und subscription_starting enthält. Der Matcher war korrekt fail-closed, der Reconciler hatte jedoch nur den Listen-Vertrag geladen.
  • Nachzug implementiert: Der Reconciler filtert Listenzeilen zunächst exakt nach Tenant, Subscription-Invoice, Final-/Zahlungsstatus, Betrag und Währung und hydriert ausschließlich fehlende Perioden über den Invoice-Detail- Endpunkt. Eine tenantweit geteilte Momentaufnahme begrenzt jeden Sweep auf höchstens vier Listen- und 25 deduplizierte Detail-Requests. Eine vierte nichtleere Seite, Detailfehler, Summary-/Detail-Widersprüche und jeder Budget-Overflow bleiben ohne Provider-Mutation fail-closed und erzeugen eigene Operator-Alarmcodes.
  • Der Live-UAT deckte zusätzlich einen finanziell relevanten Altfehler auf: Die E-Mail-Marketing-Acquisition und Mollie-Testzahlung betragen 59,00 EUR netto, während Lago wegen des bereits korrekten 19-Prozent-Steuervertrags 70,21 EUR brutto fakturiert. Diese um 11,21 EUR unterbezahlte Alt-Rechnung wird ausdrücklich nicht künstlich als bezahlt markiert. Die Portal- Altzahlung über 19,99 EUR stimmt dagegen mit ihrer damaligen steuerfreien Lago-Rechnung überein und bleibt exakt settlebar.
  • Für neue Käufe nutzt der Produktcheckout jetzt den zentralen Brutto-/Rundungsvertrag: E-Mail-Marketing S wird mit 70,21 EUR statt 59,00 EUR belastet, Customer Portal mit 23,79 EUR statt 19,99 EUR und das einmalige Domain-Setup mit 356,99 EUR statt 299,99 EUR. Lago erhält beim Portal-Plan, Add-on und der konkreten One-off-Fee explizit de-vat-19; ausschließlich Tax-only-Katalogdrift darf der auditierte Staging-Operator automatisch nachziehen. Alle anderen Provider-Drifts bleiben blockiert.
  • Die Kaufoberflächen zeigen vor Mollie denselben Vertrag ohne Preisüberraschung: E-Mail-Marketing weist Nettobetrag, 19 Prozent Umsatzsteuer und Zahlbetrag separat aus; Portal-Monatspreis und Domain-Setup nennen Brutto- und Nettobetrag gemeinsam. Das View-Model lehnt widersprüchliche Netto-/Steuer-/Bruttowerte ab.
  • Alte Mollie-Testzahlungen ohne das später ergänzte lagoProviderSubscriptionId-Metadatum bleiben über die übrige vollständige Ledger-Bindung kompatibel; ein vorhandener abweichender Wert wird weiterhin deterministisch abgelehnt. 110 fokussierte Tests belegen die neuen Steuer-, Hydrierungs-, Request-Budget-, Overflow- und Legacy-Verträge.

BILL-16: 7/8 DoD = ~88 % done. Offen: PR-CI, normaler Merge, Staging-Deploy und Live-UAT mit Screenshots.