# 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 - [x] Payment-Events koennen Subscription-/Invoice-State aktualisieren. - [x] Lago-Subscription-State wird in lokalen HiveGrid-Billing-State gespiegelt. - [x] `tenantHasModule()` nutzt den neuen lokalen Entitlement-State. - [x] Read-only/Frozen-State blockiert mutierende Tenant-Aktionen zentral. - [x] Recovery-/Billing-Routen bleiben erreichbar, wenn Tenant frozen ist. - [x] Audit/Activity fuer relevante Billing-State-Wechsel. - [x] Idempotenz fuer alle eingehenden Events. - [x] 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|cancelled` normalisiert und in `TenantSubscription` gespiegelt. - Lago-Plan/Seats/Perioden werden, wenn ein passendes `SubscriptionProduct` existiert, in `TenantSubscriptionProduct` gespiegelt. - Mollie-Payment-Events aktualisieren `lastPaymentExternalId`, `lastInvoiceExternalId`, `mollieCustomerId` und 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 `AuditEvent` und einen tenantbezogenen Activity-Eintrag `billing_state_changed`. - `tenantHasModule()` und `requireTenantProductAccess()` lesen Entitlements aus dem lokalen Billing-State (`resolveTenantEntitlements`) statt aus der alten aktiven Subscription-Abfrage. - `getTenantBillingReadOnlyState()` nutzt `resolveTenantBillingState`; Marker wie `frozenAt` und `cancelledAt` gewinnen damit zentral vor rohen Status-Werten. - Public-API-Webhooks blockieren nun auch `cancelled`/`frozen` explizit als read-only Zustand. Proof: - `pnpm --dir packages/db test -- billing-sync.server.test.ts` - `pnpm --dir packages/activity typecheck` - `pnpm --dir apps/web test -- billingStatusService.test.ts tenantConnector.server.test.ts app.\$tenant.test.tsx productAccess.server.test.ts` - `pnpm exec vitest run apps/api/src/app.test.ts` - `pnpm 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 `applyLagoSubscriptionSync` jetzt tenantgebunden und mit dem gehashten `X-Lago-Unique-Key` als persistentem Replay-Schluessel auf. - Nur im lokalen Catalog als `base_plan` bekannte 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.**