Refresh HiveGrid Cloud reference snapshot
This commit is contained in:
1 parent
5e99e14772
commit
7f88026f79
5955 files changed
+1177325
-188362
No files matched your search
@@ -0,0 +1,190 @@
|
||||
# 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
|
||||
|
||||
- [x] 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.
|
||||
- [x] 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.
|
||||
- [x] 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.
|
||||
- [x] 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.
|
||||
- [x] Der bestehende bounded Reconciler repariert aktive Bestandskäufe ohne
|
||||
Provider-Mirror tenantweise, CAS-/RLS-sicher und ohne ungebundene
|
||||
Provider-Mutation.
|
||||
- [x] `subscription_starting` wird nach aktiver bezahlter Acquisition
|
||||
idempotent als `skipped_initial` markiert und nie erneut eingezogen;
|
||||
ausschließlich `subscription_periodic` wird als Folgerechnung gequeued.
|
||||
- [x] 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.**
|
||||
Reference in new issue
Block a user