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

96 lines
4.6 KiB
Markdown

# 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`