Files
2026-07-08 16:15:37 +02:00

66 lines
2.2 KiB
Markdown

# BILL-03 · Lago-Gateway fuer Customers, Plans, Subscriptions und Invoices
| | |
|---|---|
| **Typ** | Dev (Code) |
| **Owner** | Raffael |
| **Phase** | Billing-Recut nach AD-27 |
| **Cycle/Fenster** | nach `BILL-01`/`BILL-02` |
| **Status** | Umgesetzt / bereit fuer Review |
## Abhaengigkeiten & Parallelitaet
- **Blocked by:** `BILL-01`, `BILL-02`
- **Blocks:** `BILL-05`, `BILL-06`, `BILL-07`
## Was wir bauen
Ein serverseitiges Lago-Gateway in HiveGrid. HiveGrid erstellt/liest Customers, Plans, Subscriptions und Invoice-Status
ueber Lago, aber UI-Komponenten sprechen nie direkt mit Lago.
## Definition of Done
- [x] Lago-API-Client mit klarer Env-Konfiguration fuer Staging.
- [x] Customer-Erstellung fuer Tenant.
- [x] Plan-/Seat-Subscription erstellen und lesen.
- [x] Invoice-/Subscription-Status abrufen.
- [x] Lago-Webhook-Endpunkt oder Pull-Sync-Job definiert und idempotent.
- [x] Outbox/Retry fuer ausgehende Billing-Sync-Aktionen.
- [x] Fehlertexte klar und ohne Stacktrace.
- [x] Tests gegen Mock/Fixture der Lago-API.
**Fortschritt:** `BILL-03`: 8/8 DoD = 100 % done.
## Nicht im Scope
- Mollie-Zahlung.
- Usage Events.
- Customer-facing Billing UI.
## Technische Bausteine
- `BillingGateway`-Interface, konkrete Implementierung `LagoBillingGateway`.
- Zod-Schemas fuer Lago-Antworten.
- Redaction fuer API-Keys und Payment-/Invoice-IDs in Logs.
## Umsetzungsnotiz
2026-07-04: Server-Gateway fuer Lago umgesetzt. Neues Package `@hivegrid/billing` enthaelt das
`BillingGateway`-Interface, `LagoBillingGateway`, Zod-Response-Schemas, Redaction-Helfer,
Webhook-Event-Parsing und idempotente Outbox-Args fuer `billing.lago.sync`. Die API-Konfiguration kennt jetzt
`LAGO_API_URL`, `LAGO_API_KEY`, `LAGO_WEBHOOK_SECRET` und `LAGO_TIMEOUT_MS`; `.env.example` ist aktualisiert.
Bewusst noch nicht gebaut: Customer-facing UI, Mollie-Zahlung und echte Worker-Ausfuehrung des Syncs. Der
idempotente Pull/Webhook-Sync ist als Outbox-Event-Kontrakt definiert und wird in `BILL-05` konsumiert.
Proof:
- `pnpm --filter @hivegrid/billing typecheck`
- `pnpm --filter @hivegrid/billing test`
- `pnpm --filter @hivegrid/config test`
## Quellen
- AD-27
- Lago API Docs
- `BILL-01`, `BILL-02`