93 lines
3.9 KiB
Markdown
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.**
|