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

11 KiB

BILL-11 · Pricing-Katalog, Jahresbindung und Recurring Payments

Typ Dev + kontrollierter Provider-Sync
Owner Raffael
Phase Billing-Recut nach AD-27
Cycle/Fenster gestartet 2026-07-29
Status Done
Plane HIVEGRID-210

Abhaengigkeiten & Parallelitaet

  • Blocked by: BILL-10 (Done). Die technische Arbeit und der Katalog-Sync sind frei.
  • Production-Aktivierung blockiert durch: BILL-08 / EXT-16 fuer Mollie-Live-KYC sowie Rechnungssteller-, Steuer- und Impressumsfreigabe.
  • Blocks: produktives Self-Service-Billing, J-SEO-Pricing-Inhalte und den finalen Founding-/Vertriebs-Zahlungsweg.
  • Parallelitaet: Staging-E2E und Production-Katalog-Provisionierung duerfen parallel vorbereitet werden. Echte Production-Zahlungen bleiben bis zu den externen Gates fail-closed.
  • Abhaengigkeitsschutz: Bestehende technische Codes und Tenant-/Webhook-Referenzen starter / pro / business werden nicht umbenannt. Die neuen Kundennamen sind eine versionierte Katalogeigenschaft.

Was wir bauen

Einen einzigen versionierten HiveGrid-Billing-Katalog, der in Staging und Production identisch ausgerollt und gegen Drift geprueft wird. Die Kundennamen sind:

Technischer Code Kundename Monatlich netto 12 Monate, monatliche Rate netto Inklusive Nutzer Inklusive Speicher
starter Core 199 EUR 179 EUR 2 Buero + 5 Baustelle 100 GB
pro Swarm 499 EUR 449 EUR 5 Buero + 15 Baustelle 250 GB
business Colony 999 EUR 899 EUR 10 Buero + 30 Baustelle 500 GB

Der Jahresvertrag ist keine Vorauszahlung von 12 Monatsraten, sondern eine Mindestlaufzeit von 12 Monaten mit monatlichem Einzug. Bis 1.000,00 EUR brutto kann der bestehende SEPA-Mandatsweg genutzt werden; ab 1.000,01 EUR erzwingt BILL-21 eine Kartenautorisierung. Monatliche Vertraege bleiben monatlich kuendbar. Enterprise bleibt ein individueller, manuell freigegebener Vertrag und ist kein oeffentlicher Lago-Self-Service-Plan.

Zusatznutzer werden nach Rolle berechnet. Fuer die 12-Monatsbindung gilt jeweils 10 Prozent Rabatt:

Zusatznutzer Core monatlich Swarm monatlich Colony monatlich
Buero 59 EUR 39 EUR 35 EUR
Baustelle 25 EUR 19 EUR 15 EUR

Feste Speicher-Add-ons werden als wiederkehrende Pakete, nicht als verbrauchsbasierte Einzel-GB-Abrechnung, angeboten: +100 GB fuer 9 EUR, +500 GB fuer 29 EUR, +1 TB fuer 49 EUR und +5 TB fuer 199 EUR netto pro Monat.

Nicht im Scope

  • Echte Production-Zahlungen vor Mollie-Live-KYC und Legal-/Steuerfreigabe.
  • Verbrauchsbasierte Abrechnung, Credits oder Einzel-GB-Metering.
  • Automatische Enterprise-Angebote.
  • Finale Subframe-Optik der Billing-Screens.
  • Neue Feature-Unterschiede zwischen Core, Swarm und Colony; alle Pakete enthalten denselben HiveGrid-Core.

Definition of Done

  • Ein kanonischer, versionierter Katalog definiert Core/Swarm/Colony samt stabiler technischer Codes, Monatsrate, 12-Monats-SEPA-Rate, inkludierten Nutzerrollen, Zusatznutzerpreisen und Speicher.
  • Die lokale Preis-/Checkout-Domain berechnet Monats- und 12-Monats-Vertraege korrekt; eine Jahresrate wird niemals faelschlich als kompletter Jahrespreis oder als einmalige Vorauszahlung behandelt.
  • Buero- und Baustellen-Nutzer werden getrennt validiert und oberhalb der Inklusivmengen korrekt berechnet.
  • Die vier festen Speicher-Add-ons sind als wiederkehrende Produkte modelliert; es entsteht kein Usage-Metering.
  • Der Lago-Katalog-Sync ist idempotent, unterstuetzt Dry-Run/Apply, laeuft als kontrollierter Operator-Workflow und verwendet keinen Runtime-Seed.
  • Staging und Production enthalten denselben Katalog-Contract; ein maschinenlesbarer Driftcheck prueft Codes, Namen, Intervalle, Preise, Steuern und Katalogversion.
  • Der Checkout waehlt die richtige Lago-Planvariante, uebergibt Nutzerrollen/Add-ons und erzwingt fuer die 12-Monatsbindung ein explizites Vertragsende. BILL-21 bestimmt die Zahlart anhand des Bruttobetrags.
  • Der erste Mollie-Einzug erzeugt ein Mandat; spaetere Lago-Rechnungen starten idempotent eine sequenceType=recurring-Zahlung und spiegeln Erfolg/Fehlschlag zurueck nach Lago und HiveGrid.
  • Die deutsche 19-Prozent-Umsatzsteuer ist im Katalog vorbereitet. Production bleibt ohne Rechnungssteller-/Steuerfreigabe und Mollie-Live-Konfiguration fail-closed.
  • Staging-E2E prueft mindestens Monatsvertrag, 12-Monatsbindung, Zusatznutzer, Speicher-Add-on, erste Zahlung und einen simulierten Folgemonat.
  • Production-Proof prueft Katalogparitaet und deaktivierte Side-Effects, ohne eine echte Zahlung oder Kundenrechnung auszulosen.
  • Typecheck, Lint, Tests, passende Billing-Verifier, RLS-/Security-Gates und Betriebsdokumentation sind gruen.

Fortschritt: BILL-11: 12/12 DoD = 100 % done. Offen im Ticket: nichts. Extern blockiert bleibt nur die Production-Live-Aktivierung; sie ist ausdruecklich nicht Teil dieses Tickets.

Technische Bausteine

  • Kanonischer Katalog im bestehenden @hivegrid/entitlements-/Billing-Contract, nicht als zweite Preisquelle.
  • Provider-Planvarianten fuer monatlich und 12 Monate bei weiterhin monatlichem Lago-Intervall.
  • Explizite Vertragslaufzeit und Rollen-Mengen im lokalen Billing-State; eigenes Billing-Prisma-Schema gemaess AD-21.
  • Kontrolliertes Sync-/Drift-CLI fuer Lago Staging und Lago Production mit redigierten Ausgaben.
  • Invoice-getriebener Recurring-Payment-Flow ueber vorhandene Billing-Outbox, Lago-Gateway und Mollie-Gateway.
  • Bestehende tenantHasModule()-/Entitlement-Gates, Audit/Activity und RLS-Kontext bleiben verbindlich.
  • Keine Provider-Secrets, Fachdaten oder CRM-Inhalte in Logs, Katalog oder Mollie-Metadaten.

Rollback

  • Katalog-Sync exportiert vor Apply einen redigierten Snapshot und deaktiviert ersetzte Varianten erst nach erfolgreichem Paritaetscheck.
  • Bestehende Subscriptions behalten ihre technischen Codes und Provider-Referenzen.
  • Der Recurring-Subscriber kann ueber den bestehenden Production-Side-Effect-Gate deaktiviert werden.
  • Ein Code-Rollback darf keine bereits ausgestellte Rechnung oder bestaetigte Mollie-Zahlung loeschen; Korrekturen erfolgen ueber Gutschrift/Refund und append-only Provider-/Audit-Events.

Quellen

  • docs/ARCHITECTURE-DECISIONS.md AD-27
  • .planning/ticket-docs/BILL-08.md
  • .planning/ticket-docs/BILL-10.md
  • docs/pricing-draft.md
  • docs/pricing-draft.md
  • packages/entitlements/src/seat-packages.ts
  • docs/ops/lago-staging.md
  • docs/ops/lago-production-prep.md

Umsetzungs-Notiz

2026-07-29 · gestartet

  • Plane-Ticket HIVEGRID-210 angelegt und auf In Progress gesetzt.
  • Namensentscheidung aus der historischen D006-Konfiguration uebernommen: Core / Swarm / Colony.
  • Technische Codes bleiben migrationsstabil als starter / pro / business.
  • Production-Zahlungen bleiben bis BILL-08 / EXT-16 fail-closed.
  • Der kanonische Katalog 2026-07-29.1 wurde kontrolliert auf Staging und Production angewandt. Beide Verifies liefern denselben Digest a8ba1affd93e1b870d016284457594988c7fc5f58fdf70c3d57be80b3c915b2c und keine Drift-Aktion.
  • Implementierungs-Proof: e0f7567fa, e9d475a30, 64f97f65d, c74408076, 2cdc13c22, 03f213997, a51ff2611, ed3503dd1, 2017e887e, d3b6f6d7a, 8b17838dc, e6b03511c, a5c64ad65.
  • Lokaler Proof vor dem Runner: Prisma-Validierung, leere-DB-Migrationsparitaet, Tenant-Policy-Vertrag, Lint, i18n, Deploy-/Docker-Verifier und 173 fokussierte Billing-/Webhook-/Worker-Tests gruen. Den vollstaendigen Typecheck und die komplette Testsuite uebernimmt wegen der lokalen Ressourcenlast der Gitea-Runner.

2026-07-29 · abgeschlossen

  • Der finale Lago-OSS-Fix verwendet fuer ausgewaehlte Seat-/Storage-Mengen deterministische, unveraenderliche Managed-Plan-Codes statt des nur in Premium verfuegbaren plan_overrides. Identische Plaene werden wiederverwendet; Drift bricht fail-closed ab. Implementierungs-Commit 5ec8bd76e, PR #292, normaler Merge 549f708d9.
  • Gitea-PR-CI Run 11474 ist mit 11/11 Jobs gruen, inklusive Typecheck, Lint, Tests, Build, Docker-Smokes, Datenbank-, API-, MCP-, Realtime-, Worker- und Security-Gates.
  • Staging-Deploy Run 11475 ist gruen. Monats-Preview und 12-Monats-Checkout prueften beide Seat-Rollen und Speicherpakete. Die erste Mollie-Testzahlung lief kundenpraesent mit iDEAL und sequenceType=first; ein gueltiges Lastschriftmandat entstand.
  • Eine simulierte folgende Lago-Rechnung erzeugte genau eine directdebit-Zahlung mit sequenceType=recurring ueber EUR 454,22. Nach dem Mollie-Webhook standen HiveGrid-Ledger und Lago-Rechnung auf bezahlt. Der Replay desselben Invoice-Events erzeugte keine zweite Zahlung.
  • Alle deterministischen Staging-Fixtures wurden entfernt. Der verwendete Demo-Benutzer zeigt wieder auf demo-pro-crm; es bleibt keine offene Mollie-Fixture-Zahlung.
  • Der Production-Driftcheck meldet Katalog 2026-07-29.1, Digest a8ba1affd93e1b870d016284457594988c7fc5f58fdf70c3d57be80b3c915b2c und ausschliesslich noop. Der Production-Gate bleibt false, ein Mollie-Key ist nicht hinterlegt und es wurde keine Production-Zahlung ausgeloest.
  • Promote Run 11477 ist gruen. App, Admin, Portal, API, MCP, Realtime und alle fuenf Worker-Gruppen laufen gesund auf Revision 549f708d9.

BILL-11: 12/12 DoD = 100 % done.

2026-08-02 · Abhängigkeitsschutz für BILL-23:

  • BILL-23 versioniert ausschließlich Speicherpool und Add-on-Preise neu. Technische Codes, Laufzeiten, Sitzpreise, Steuervertrag, Lago-Intervall, Mandate und bestehende Providerreferenzen bleiben stabil.
  • Katalog-Sync und Driftcheck müssen den neuen Digest vor BILL-08 auf Staging belegen. BILL-11 bleibt 12/12 DoD = 100 % done.

2026-08-02 · Abhängigkeitsschutz für BILL-21

  • Der technische Variantencode annual_sepa und alle Providerreferenzen bleiben migrationsstabil. Für Zahlungen bis 1.000,00 EUR bleibt der bestehende SEPA-Vertrag unverändert; darüber erzwingt der gemeinsame Payment-Policy-Resolver Karte für Erst- und Folgezahlungen.
  • Katalogpreis, Rabatt, Vertragslaufzeit, Lago-Intervall, Rechnungen und Entitlements bleiben unverändert. BILL-11 bleibt 12/12 DoD = 100 % done.