Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/.planning/ticket-docs/BILL-05.md
T
2026-07-08 16:15:37 +02:00

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|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.