Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/.planning/ticket-docs/BILL-25.md
T

13 KiB
Raw Blame History

BILL-25 · Egress-resiliente Speicherpreise und Traffic-Transparenz

Typ Produktentscheidung · Billing-/Storage-Launch-Härtung
Owner Raffael
Phase Pilot-Härtung
Cycle/Fenster gestartet 2026-08-03
Status In Arbeit
Plane HIVEGRID-248

Abhängigkeiten & Parallelität

  • Blocked by: BILL-24 liefert die drei neu kaufbaren Speicherstufen, stabile technische Codes und die Trennung zwischen Neu- und Bestandsvertrag.
  • Blocks: BILL-08 darf den Production-Katalog erst nach grünem Staging-Katalog-, Checkout-, Invoice- und Journey-Proof nachziehen.
  • Abhängigkeitsschutz: Basispläne, Inklusivspeicher, Wachstum je Zusatznutzer, Add-on-Codes, historische Preise und bereits ausgestellte Rechnungen bleiben unverändert. Nur künftige Neukäufe erhalten die neue Katalogversion.

Was / Warum

Die Preise aus BILL-24 decken direkte Speicherkosten, aber nur ungefähr 3,7 vollständige externe Auslieferungen des gebuchten Zusatzspeichers, bevor die Deckung negativ wird. Für den Piloten soll der Katalog konservativ fünf vollständige Auslieferungen pro Monat tragen, ohne tatsächliche Nutzung vorzutäuschen oder Kunden mit variablen Traffic-Nachberechnungen zu überraschen.

Der neue Vertrag verwendet weiterhin drei feste, monatliche Zusatzpools:

Zusatzpool Preis netto Speicher-COGS 4× Egress-COGS Marge bei 4× 5× Egress-COGS Marge bei 5×
+500 GB 6,99 EUR 3,36 EUR 2,15 EUR 21,2 % 2,68 EUR 13,5 %
+1 TB 12,99 EUR 6,72 EUR 4,29 EUR 15,2 % 5,37 EUR 6,9 %
+5 TB 60,99 EUR 33,61 EUR 21,47 EUR 9,7 % 26,84 EUR 0,9 %

Die Kalkulation verwendet 6,26 EUR/TB-Monat zusätzliche Speicherkosten und 1,00 EUR/TB externen Mehrtraffic. HiveGrid gewährt Quota in Einheiten von 1024^3 Bytes, Hetzner rechnet dagegen dezimale TB; der Nachweis verwendet deshalb die tatsächlich gewährten Bytes statt einer vereinfachten GB-durch-1000-Rechnung. Hetzners monatlich ungefähr 1 TB großer, accountweiter Egress-Freibetrag ist ein gemeinsamer Plattformpuffer und wird keinem Workspace oder Paket versprochen. Ohne Egress liegt die direkte Rohmarge bei 51,9 / 48,3 / 44,9 Prozent. Die kleinste Stufe überschreitet die angestrebte 50-Prozent-Marke minimal: 5,99 EUR wäre unter realen Binäreinheiten bei 5× Egress negativ, 6,99 EUR ist die kleinste freigegebene ,99-Stufe.

Hetzners Abrechnungsminimum von 64 kB je gespeichertem Objekt ist kein weiterer pauschaler Egress-Zyklus und rechtfertigt ohne reale Objektverteilung keine zusätzliche Preiserhöhung. Es wird im Pilot separat als Differenz zwischen logischen HiveGrid-Bytes und providerseitig abgerechnetem Speicher überwacht; bei auffälliger Abweichung werden Objektmix, unvollständige Multipart-Uploads, Versionen und fremde Account-Buckets geprüft.

Traffic-Transparenz trennt drei Werte sauber:

  1. Provider-Istkosten: accountweiter, extern abgerechneter Hetzner-Egress.
  2. Autorisierter Traffic: Anzahl und Objektgröße der von HiveGrid freigegebenen Downloads, aggregiert nach stabiler Produktoberfläche ohne Tenant-/Datei-Labels in Prometheus.
  3. Workspace-Näherung: nur für Support-/Kostenprüfung; keine automatische Rechnung und keine Behauptung, ein ausgestellter Signed Link sei tatsächlich vollständig geladen worden.

Der komplette Registrierungs-, Verifikations-, Aktivierungs-, Mollie-TEST-, Welcome-, Invoice- und Add-on-Pfad wird gegen Staging neu geprüft. Nur konkret reproduzierte Fehler innerhalb dieser Journey werden in diesem Ticket behoben; weitergehende Features bleiben eigene Change-Requests.

Nicht im Scope

  • Kein Traffic-Overage-Billing, keine nachträgliche Einzel-GB-Rechnung und kein „unlimited traffic“-Versprechen.
  • Kein Tenant als Prometheus-Label, keine Dateinamen/Objektschlüssel in Logs und keine Speicherung von Signed URLs.
  • Kein Proxy aller Downloads durch den Webprozess und keine neue CDN-, Server- oder Bucket-Infrastruktur in diesem Ticket.
  • Keine eigenen Zahlungsfelder, kein Mollie-Iframe und keine echte Production-Zahlung vor den zwei externen Gates aus BILL-08.
  • Keine Änderung an Basisplan-, Sitz-, E-Mail-Marketing- oder Portalpreisen.

Definition of Done

  • Neu buchbare Speicherpakete kosten 6,99 / 12,99 / 60,99 EUR netto pro Monat; stabile Codes und historische Verträge bleiben auflösbar.
  • Automatisierte Kalkulation verwendet die tatsächlich gewährten Binärbytes und beweist für jede kaufbare Stufe positive Deckung nach fünf vollständig kostenpflichtigen externen Auslieferungen der Paketkapazität.
  • Autorisierte Downloadanzahl und bekannte Objektbytes sind auf den zentralen Auslieferungspfaden niedrig-kardinal, secretsicher und ausfallsicher messbar; Signed-URL- und Provider-Blindspots sind im Betriebsvertrag ausdrücklich benannt.
  • Registrierung, Verifikation, Aktivierung, Welcome-Setup, Billing-Hub, Rechnungszugriff und Add-on-Käufe wurden UX-, Security- und Zustands-seitig geprüft; reproduzierte Launch-Blocker sind mit Tests behoben oder als externer Blocker dokumentiert.
  • Typecheck, Lint, vollständige Testsuite sowie Billing-, Source-, i18n-, Security-, ticketbezogene A11y-, Hot-Swap- und Visual-Verifier sind grün; atomare Commits und geprüfte Screenshots liegen vor. Der gegenüber main unveränderte globale no-autofocus-Baseline-Drift ist als bestehender Repository-Nachzug ausgewiesen und nicht still hochgesetzt.
  • PR-CI, normaler Merge, kontrollierter Staging-Katalog-Sync, Deploy und ein ausschließlich mit Mollie TEST ausgeführter End-to-End-UAT sind grün.
  • Production erhält erst danach exakt dieselbe geprüfte Katalogversion und Invoice-Konfiguration; Provider-Side-Effects und echte Zahlungen bleiben bis BILL-08 fail-closed.

BILL-25: 4/7 DoD = ~57 % done. Offen: 3 Punkte; davon Production-Sync zusätzlich durch die externen BILL-08-Gates begrenzt.

Technische Bausteine

  • packages/entitlements/src/commercial-catalog.ts
  • packages/metrics und die bestehenden service-scoped Registries
  • autorisierte Download-Routen und mediaSigning.server.ts
  • scripts/billing-catalog
  • Registrierungs-, Welcome-, Billing-, Invoice- und Add-on-Flows aus BILL-14, BILL-19, BILL-20 und BILL-22
  • docs/ops/lago-staging.md, docs/ops/lago-production-prep.md und ein redaktierter Storage-Traffic-Betriebsvertrag

Rollback

  • Katalog und UI können gemeinsam auf Version 2026-08-03.1 zurückgesetzt werden. Bereits ausgestellte Rechnungen, Zahlungen und historische Providerobjekte werden nie gelöscht oder umgeschrieben.
  • Die neuen Metriken sind rein beobachtend. Ihr Ausfall darf keinen Download blockieren; ein Rollback entfernt nur die Beobachtung, nicht Auth-, RLS-, Scan- oder Signed-URL-Gates.
  • Production wird ausschließlich nach erfolgreichem Staging-Proof und über den kontrollierten idempotenten Katalog-Sync verändert. Der Zahlungs-Side-Effect- Gate bleibt unverändert geschlossen.

Quellen

Umsetzungs-Notiz

2026-08-03 · gestartet

  • Explizite Produktfreigabe im Chat: Preise nur so weit anheben, dass vier bis fünf vollständige externe Auslieferungen wirtschaftlich enthalten sind; Storage-Traffic sauber beobachtbar machen und den gesamten Billing-/Signup- Pfad erneut gegen Staging prüfen.
  • Korrektur nach Cross-Layer-Audit: HiveGrid-Quota nutzt 1024^3 Bytes pro GB, Hetzner rechnet dezimale TB. Die zunächst vereinfachte Kalkulation war damit bei 5× Egress leicht negativ. Der kleinste nötige ,99-Nachzug ist 500 GB für 6,99 EUR, 1 TB für 12,99 EUR und 5 TB für 60,99 EUR netto pro Monat. Bei vollständig kostenpflichtigem 5×-Egress verbleiben 0,94 / 0,90 / 0,54 EUR positive Deckung.
  • Plane-Identität als raffael@tool-ctrl.de bestätigt; HIVEGRID-248 angelegt, Raffael zugewiesen und auf In Progress gesetzt.
  • Isolierter Worktree auf origin/main (b1f14d63e). Workspace-Shape und EU-Provider-Guard sind sauber; Typecheck und vollständige Baseline mit 1.194 Testdateien / 8.324 Tests grün (60 bewusst übersprungen).
  • Katalogversion 2026-08-03.3 ist implementiert. Automatisierte Tests pinnen Preis, unveränderte Codes, Bestandsauflösung, Rohmargen-Obergrenze und positive Deckung nach fünf vollen externen Auslieferungen.
  • Niedrig-kardinale Prometheus-Zähler erfassen autorisierte Downloads und nur serverseitig bekannte Objektbytes auf Core-, Vorschau-, Thumbnail- und Portalpfaden. Der Betriebsvertrag dokumentiert ausdrücklich: Das ist keine Provider-Egress-Messung; Hetzner-Istkosten werden accountweit manuell abgeglichen und führen nicht automatisch zu Kundenabrechnungen.
  • Das 64-kB-Abrechnungsminimum pro Hetzner-Objekt ist als eigener Speicherkosten-Blindspot aufgenommen. Es verändert die freigegebenen Preise ohne belastbare Objektverteilung nicht, wird im Pilot aber gegen die logischen HiveGrid-Bytes abgeglichen.
  • Journey-Härtung in atomaren Commits: Passwortregeln werden vor Submit validiert; die Billing-Präferenz wird atomar im Tenant-Bootstrap gebunden; die Aktivierung berechnet Tarifempfehlung und Preise serverseitig live neu; fehlgeschlagene Checkout-Aktionen entsperren die UI; Mollie-Zustände open/pending/authorized bleiben in Verarbeitung, während cancelled/failed/expired statt einer nutzlosen Status-Neuprüfung einen frischen Checkout starten; nur paid aktiviert Entitlements. Invoice-Listen paginieren vollständig und prüfen Downloads unabhängig von der ersten Seite. Welcome- und Registrierungstexte versprechen weder Direkt-Checkout noch Freischaltung vor bestätigter Zahlung; der Dashboard-Einstieg bleibt eine bewusste Aktion.
  • Read-only Staging-Audit vor Deploy: Katalog-Diff enthält exakt 16 erwartete Updates und keine Creates/Deletes; Invoice-Entity ist eindeutig und auf EUR/de, 14 Tage, Europe/Berlin, Per-Customer-Nummerierung sowie vorhandene Rechts-/Steuer-/Absenderdaten konfiguriert. Ein finalisiertes Testdokument war als PDF abrufbar. Mollie verwendet ausschließlich TEST, aber das Profil ist providerseitig unverified; deshalb bietet Mollie derzeit nur iDEAL und keine Karte/Recurring-Methode an. Das bleibt ein externer BILL-08-Blocker.
  • Read-only Registrierungs-Baseline gegen Staging grün: Account-, Team-, Swarm-Empfehlungs-, Core-Override- und Zurück-Navigation-Screenshots liegen vollständig geladen und visuell geprüft unter ~/Desktop/HiveGrid-BILL-25-Billing-Journey-2026-08-03/00-staging-before-deploy.
  • Provider- und Nebenläufigkeits-Härtung aus dem finalen Cross-Layer-Audit: Basis-, E-Mail- und Portal-Checkouts werden tenantweit serialisiert und berücksichtigen bereits reservierte Erwerbungen bei der kombinierten Zahlungsmethoden-Policy. Wiederholte Tabs teilen ihre persistierte Checkout-Identität. Preis- oder Provider-Drift bricht fail-closed ab. Kündigungen sind nur noch für aktive wiederkehrende Add-ons mit exakt gebundener Lago-Subscription möglich; lokale Entitlements werden nie vor bestätigter Provider-Kündigung entfernt.
  • Quota-Härtung deckt neben Browser-Uploads auch KWP, öffentliche Formulare, E-Mail-Anhänge, Plantafel-Annahmen und Signatur-PDFs ab. Reservierungen erfolgen zentral pro Tenant. Schlägt das Löschen eines hochgeladenen Objekts fehl, bleibt die DB-Zeile quota-wirksam, statt das noch vorhandene Objekt unsichtbar aus der Abrechnung zu entfernen.
  • Lokaler Pre-Push-Proof nach allen Änderungen: pnpm typecheck, pnpm lint und pnpm test grün mit 1.202 Testdateien / 8.508 Tests (60 bewusst übersprungen). Zusätzlich grün: Billing-/Storage-Boundaries, Katalogverträge, i18n, Source-Health, CI-Baseline, Onboarding-Flow, Staging-UAT-Readiness, Hot-Swap, statische Visual-Baseline, 45 Accessibility-Komponententests, Prisma-Validation, Migration-Parität und alle acht Live-RLS-Phasen einschließlich Portal und Tenant-Bootstrap. verify:a11y-baseline meldet auf Branch und main denselben bestehenden Stand von 70 no-autofocus-Fundstellen bei einer veralteten Baseline von 56; diese Branch erhöht die Fundstellenzahl nicht und weitet die Baseline nicht auf.
  • Vor dem Push liegen 64 fachlich getrennte Commits vor. Der EU-Provider-Guard ist leer; Secrets- und Pre-Commit-Gates sind grün.

BILL-25: 4/7 DoD = ~57 % done. Offen: vollständiger Post-Deploy-UAT, PR/CI/Merge/Deploy/Staging-Sync und der durch BILL-08 gegatete Production-Abgleich.