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

228 lines
13 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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.**