3.3 KiB
3.3 KiB
BILL-05 · Billing-Sync, Entitlements und Read-only-State
| Typ | Dev (Code) |
| Owner | Raffael |
| Phase | Billing-Recut nach AD-27 |
| Cycle/Fenster | nach BILL-03/BILL-04 |
| Status | Done |
Abhaengigkeiten & Parallelitaet
- Blocked by:
BILL-02,BILL-03,BILL-04 - Blocks:
BILL-06,BILL-07
Was wir bauen
Die Ereignis- und Zustandsbruecke zwischen Lago, Mollie und HiveGrid. Ergebnis: HiveGrid kennt verlaesslich, ob ein Tenant aktiv, past_due, frozen oder cancelled ist und welche Features/Seats erlaubt sind.
Definition of Done
- Payment-Events koennen Subscription-/Invoice-State aktualisieren.
- Lago-Subscription-State wird in lokalen HiveGrid-Billing-State gespiegelt.
tenantHasModule()nutzt den neuen lokalen Entitlement-State.- Read-only/Frozen-State blockiert mutierende Tenant-Aktionen zentral.
- Recovery-/Billing-Routen bleiben erreichbar, wenn Tenant frozen ist.
- Audit/Activity fuer relevante Billing-State-Wechsel.
- Idempotenz fuer alle eingehenden Events.
- Tests fuer State-Matrix und erlaubte/gesperrte Aktionen.
Nicht im Scope
- Usage-Grenzen.
- Dunning-Kommunikation ueber echte Mailsequenzen, falls nicht bereits vorhanden.
- Finale Customer-facing UI.
Technische Bausteine
- Bestehende
IdempotencyKey-Tabelle als replay-sicheres Event-Log fuer Lago/Mollie-Sync (scope=billing:provider-sync), plus Audit/Activity fuer sichtbare State-Wechsel. - State-Resolver mit Cache-Invalidierung.
- zentrale Permission-Boundary-Anbindung.
Quellen
- AD-27
R-P1b- AK-P20-Read-only/Frozen-Vorarbeit
Umsetzung
2026-07-04
- Neuer Sync-Service
@hivegrid/db/billing-sync.server:- Lago-Subscription-Status wird auf
trial|active|past_due|frozen|cancellednormalisiert und inTenantSubscriptiongespiegelt. - Lago-Plan/Seats/Perioden werden, wenn ein passendes
SubscriptionProductexistiert, inTenantSubscriptionProductgespiegelt. - Mollie-Payment-Events aktualisieren
lastPaymentExternalId,lastInvoiceExternalId,mollieCustomerIdund den lokalen Billing-Status. - Eingehende Provider-Events sind idempotent ueber
IdempotencyKey(scope=billing:provider-sync); Replay schreibt weder Audit noch Activity erneut. - Relevante State-Wechsel schreiben
AuditEventund einen tenantbezogenen Activity-Eintragbilling_state_changed.
- Lago-Subscription-Status wird auf
tenantHasModule()undrequireTenantProductAccess()lesen Entitlements aus dem lokalen Billing-State (resolveTenantEntitlements) statt aus der alten aktiven Subscription-Abfrage.getTenantBillingReadOnlyState()nutztresolveTenantBillingState; Marker wiefrozenAtundcancelledAtgewinnen damit zentral vor rohen Status-Werten.- Public-API-Webhooks blockieren nun auch
cancelled/frozenexplizit als read-only Zustand.
Proof:
pnpm --dir packages/db test -- billing-sync.server.test.tspnpm --dir packages/activity typecheckpnpm --dir apps/web test -- billingStatusService.test.ts tenantConnector.server.test.ts app.\$tenant.test.tsx productAccess.server.test.tspnpm exec vitest run apps/api/src/app.test.tspnpm run typecheck
DoD: 8/8 = 100 % done.