228 lines
13 KiB
Markdown
228 lines
13 KiB
Markdown
# 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
|
||
|
||
- [x] Neu buchbare Speicherpakete kosten 6,99 / 12,99 / 60,99 EUR netto pro
|
||
Monat; stabile Codes und historische Verträge bleiben auflösbar.
|
||
- [x] 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.
|
||
- [x] 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.
|
||
- [x] 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
|
||
|
||
- `docs/CHANGE-REQUESTS.md` · CR-025
|
||
- `.planning/ticket-docs/BILL-08.md`
|
||
- `.planning/ticket-docs/BILL-22.md`
|
||
- `.planning/ticket-docs/BILL-24.md`
|
||
- https://www.hetzner.com/storage/object-storage/
|
||
- https://docs.hetzner.com/storage/object-storage/overview/
|
||
|
||
## 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.**
|