96 lines
4.6 KiB
Markdown
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`
|