3.9 KiB
3.9 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.
2026-07-28 · Abhaengigkeits-Nachzug aus BILL-03
- Die produktive API-Grenze fuer Lago-v1.50-Subscription-Events ruft den bestehenden
applyLagoSubscriptionSyncjetzt tenantgebunden und mit dem gehashtenX-Lago-Unique-Keyals persistentem Replay-Schluessel auf. - Nur im lokalen Catalog als
base_planbekannte Lago-Plaene duerfen den Basiszustand veraendern. Add-on-Events bleiben beim getrennten Product-Acquisition-Ledger und koennen dessen Fence nicht umgehen. - Der bestehende State-, Audit-, Activity- und Idempotenz-Vertrag bleibt unveraendert; die BILL-05-Konsumenten bleiben gruen.
BILL-05: 8/8 DoD = 100 % done.