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

4.6 KiB

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

  • Lago-Gateway kann Rechnungen inklusive Nummer und generiertem PDF-Link lesen.
  • Tenant-Subscription-Seite laedt Rechnungen nur mit app.settings.subscription.invoices.view.
  • Rechnungen werden tenant-gefiltert angezeigt und koennen nicht tenant-uebergreifend geladen werden.
  • Download laeuft ueber eine HiveGrid-Route mit Permission-Check, nicht ueber direkte Lago-Secrets im Browser.
  • Klartext/i18n fuer Rechnungstypen, Payment-Status und Fehlerfaelle.
  • 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