Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/.planning/ticket-docs/BILL-05.md
T

93 lines
3.9 KiB
Markdown

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