# BILL-09 · Kunden-Rechnungszugriff in HiveGrid | | | |---|---| | **Typ** | Dev/UI ohne finale Screens | | **Owner** | Raffael | | **Phase** | Billing-Recut nach AD-27 | | **Cycle/Fenster** | nach `BILL-07` | | **Status** | Done | ## Abhaengigkeiten & Parallelitaet - **Blocked by:** `BILL-03`, `BILL-05`, `BILL-07` - **Blocks:** spaetere Self-Service-Billing-Screens (`VA-P24a`/`VD-P24`) - **Screen-Status:** finale Designs offen; bestehende Subscription-Settings-Flaeche wird minimal erweitert. ## Was wir bauen Kunden sollen ihre Lago-Rechnungen in HiveGrid sehen und herunterladen koennen. Mollie bleibt nur Payment-Processor; Rechnungsdaten und PDF-Link kommen aus Lago. HiveGrid ist die sichtbare Kundenflaeche und prueft Tenant + Permission, bevor ein Download-Link ausgegeben wird. ## Definition of Done - [x] Lago-Gateway kann Rechnungen inklusive Nummer und generiertem PDF-Link lesen. - [x] Tenant-Subscription-Seite laedt Rechnungen nur mit `app.settings.subscription.invoices.view`. - [x] Rechnungen werden tenant-gefiltert angezeigt und koennen nicht tenant-uebergreifend geladen werden. - [x] Download laeuft ueber eine HiveGrid-Route mit Permission-Check, nicht ueber direkte Lago-Secrets im Browser. - [x] Klartext/i18n fuer Rechnungstypen, Payment-Status und Fehlerfaelle. - [x] Tests fuer Gateway, Service, Loader und Download-Route. ## Umsetzungs-Notiz 2026-07-04 · Raffael - `@hivegrid/billing` erweitert: Lago-Invoices enthalten `number` und `fileUrl`; `downloadInvoice()` nutzt `POST /api/v1/invoices/:id/download`. - Web-Server-Config liest `LAGO_API_URL`, `LAGO_API_KEY`, `LAGO_WEBHOOK_SECRET`, `LAGO_TIMEOUT_MS` serverseitig. - Neuer Service `apps/web/app/services/billing/customer-invoices.server.ts`: listet tenant-gefilterte Rechnungen und verifiziert Tenant-Ownership vor Download. - Bestehende Route `/:tenant/settings/subscription` zeigt einen Rechnungsblock, wenn die Invoice-Permission vorhanden ist. Bei temporarem Lago-Fehler bleibt die Abo-Seite erreichbar und zeigt einen Klartext-Hinweis. - Neue Resource-Route `/:tenant/settings/subscription/invoices/:invoiceId/download` prueft Permission und leitet erst danach auf die von Lago erzeugte PDF-URL weiter. Proof: - `pnpm --dir packages/billing test -- lago.test.ts sandbox-flow.test.ts` - `pnpm exec vitest run apps/web/app/services/billing/customer-invoices.server.test.ts apps/web/app/routes/app.\\$tenant/settings/subscription.test.tsx apps/web/app/routes/app.\\$tenant/settings/subscription/invoices.\\$invoiceId.download.test.tsx packages/config/src/web.test.ts packages/config/src/catalog.test.ts` - `pnpm typecheck` - `pnpm lint` - `git diff --check` Nachtrag 2026-07-04: - Lago-Staging war nach dem UI-Deploy noch leer: 0 Plans, 0 Subscriptions, 0 Invoices. Der Empty-State in HiveGrid war dadurch korrekt. - Echte Lago-Demo-Testdaten angelegt: Plans `starter`/`pro`/`business`, je eine Subscription fuer `demo-starter-crm`, `demo-pro-crm`, `demo-business-crm`, je eine finalized `EUR 1.00` Invoice. - Live-Proof auf Staging: alle drei Routen `/:tenant/settings/subscription` zeigen ihre Rechnungsnummer, der Empty-State ist weg. - Lago-Staging auf dedizierten Hetzner-Bucket `hivegrid-staging-lago` umgestellt; synthetische Rechnung `HIV-6711-005-001` erzeugte ein PDF-Objekt im Bucket. - Download-Fix: HiveGrid streamt PDFs nun ueber die eigene Download-Route, statt Kunden auf Lago/Bucket-URLs zu redirecten. Ownership wird vorab ueber die tenant-gefilterte Lago-Invoice-Liste geprueft, weil `POST /api/v1/invoices/:id/download` keine Customer-Felder zurueckgibt. - Alte lokale Demo-Invoices `HIV-6711-002-001`, `HIV-6711-003-001`, `HIV-6711-004-001` wurden voided; neue S3-backed Demo-Invoices `HIV-6711-002-002`, `HIV-6711-003-002`, `HIV-6711-004-002` erzeugt. **BILL-09: 6/6 DoD = 100 % done.** Nachtrag 2026-07-05: - Kunden-Rechnungszugriff erneut mit einer volleren Lago-Rechnung geprueft: `HIV-6711-002-008` fuer `demo-pro-crm`, inklusive Business-Plan, Zusatznutzern, Storage, Email-Marketing, Add-ons, Datenmigration, Schulung und Onboarding. - Die Rechnung nutzt den aktuellen neutralen Mollie-Footer und `14` Tage Zahlungsziel. - HiveGrid-Route: `https://staging-app.hivegrid.de/demo-pro-crm/settings/subscription/invoices/41c8e519-d871-4ead-9a0f-6b33fc592e71/download` liefert `200 application/pdf` und streamt das PDF serverseitig nach Permission-/Tenant-Pruefung. **BILL-09: 6/6 DoD = 100 % done.** ## Nicht im Scope - Self-Service-Planwechsel/Seat-Wechsel. - Finale Subframe-Screens fuer Billing. - Production-Billing-Livegang. - Rechnungssteller-/Steuerfreigabe. ## Quellen - AD-27 - `BILL-03` - `BILL-05` - `BILL-07` - `VA-P24a`