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

31 KiB

AK-P20 · P20 Billing-Grundlagen + Onboarding + Branding

⚠️ Billing-Recut 2026-07-04 (AD-27): Die Legacy-Provider-Annahmen in diesem Ticket sind Doku-Drift. Zielarchitektur ist Lago self-hosted fuer Billing/Invoicing + Mollie nur fuer Payments + HiveGrid-Entitlements. v1-Scope: Plans + Seats, kein Usage-Billing. Legacy-Provider-Codepfade aus der bisherigen Teilumsetzung sind Migrationsmaterial fuer BILL-02 bis BILL-05, nicht mehr Zielarchitektur.

⚠️ KI→MCP-Pivot (AD-26): Der AI-Credits-Screen + AI-Token-Quota entfallen (kein LLM-Gateway in v1 — HiveGrid wird MCP-Server, VR-MCP; AiCredits/AiTokenUsage gestrichen). Die Verbrauchs-Übersicht bleibt für Automation-Läufe + Speicher. Alle AI-Credits/AI-Token-Stellen unten sind durchgestrichen.

🔄 Provisionierungs-Recut 2026-07-15 (R-CR1/R-P20b, AD-29): AK-P20 bleibt abgeschlossen; der damalige Auto-SHK-Provisionierungs-Slice und seine Proofs zu provisionShkTenantDefaults()/ shkRoles.server.ts bleiben unten ausschließlich als historische Umsetzung dokumentiert. Aktueller Vertrag für neue Workspaces ist der zentrale R-P20b-Bootstrap mit fünf editierbaren Tenant-Rollen und ausschließlich der globalen Rolle Admin für den Owner. Bestehende Tenants werden nicht automatisch verändert.

Typ Dev (Code)
Owner Akeshan
Phase P20 — Billing, Onboarding & Branding
Cycle/Fenster W4 — USP, Härtung & Launch · fällig 2026-07-08 · Gate W4
Status Dev-DoD 8/8 = 100 %; Interim-UI nach AD-28; Ready-to-Verify / Done-Freigabe ausstehend

🎨 design-nachzug: offen (seit 2026-07-12) — Interim-UI aus ~/ui steht; finale Subframe-Optik aus D-P20 ausstehend.

Abhängigkeiten & Parallelität

  • Blocked by: keine selbst machbaren Dev-Blocker. D-P20 ist nach AD-28 nur noch ein nicht blockierender Design-Nachzug.
  • Blocks / gelieferte Verträge: AK-P21 kann den unveränderten Read-only-/Frozen-/Billing-Cancel-Vertrag konsumieren; die BILL-06-Admin-Basis steht bereits. Spätere Customer-Billing-Screens bauen auf den hier stabilisierten VMs/Routen auf.
  • Läuft parallel zu: Raffaels Kern-Kette (Auftrags-/Abnahme-Welt P9). Eigene prisma/schema/billing.prisma + Onboarding-Teile (AD-21); core.prisma (Tenant) nur über Relation.
  • Konflikt-Risiko: gering — additive Tabellen + Read-Only-Middleware (Frozen) auf der Request-Pipeline (Querschnitt, additiv).

Was wir bauen

Drei gebündelte v1-Module:

  1. Billing-Grundlagen: lokaler Billing-/Entitlement-State fuer Plans + Seats, Trial/Dunning/Frozen, Read-only-State und Feature-Gates. Lago ist Billing-/Invoice-Source-of-Truth, Mollie ausschließlich Payment Processor.
  2. Onboarding: Auto-SHK-Provisionierung beim Signup (Seeds M158, ohne Wizard) + Demo-Daten-Knopf + Erste-Schritte-Checkliste.
  3. Branding: Light/Dark-Unterbau bleibt erhalten; Toggle und Dark-Anwendung im App-/Admin-Bereich sind vorerst deaktiviert (PR #81).

Nicht mehr Ziel dieses Tickets: Legacy-Provider-Abo-Baukasten, Legacy-Provider-Customer-Portal, Payment-Checkout, Usage-Billing, AI-Credits oder Pricing-/Upgrade-UI fuer Endkunden.

Benötigte Screens (Backend bedient — Design liefert D-P20)

Screen [Route] Kern-Inhalt
Abo-Übersicht [/:tenant/settings/subscription] Plan + Seats + Feature-Module (read-only), Status/Trial-Countdown, KEIN Upgrade-Button (Hinweis „Plan-Wechsel über Account-Manager/hivegrid.de"), Kündigen falls freigegeben
Verbrauchs-Übersicht [/:tenant/settings/usage] Quota-Balken fuer Automation und Speicher, Warnbanner und Aufgebraucht-Klartext; keine Usage-Billing-Sprache
Rechnungen/Zahlung [/:tenant/settings/billing] Lago-Invoice-Status + Mollie-Payment-Status + Klartext-Hilfe; kein Legacy-Provider-Portal-Embed
Demo-Daten [/:tenant/settings/onboarding/demo-data] Settings-Knopf „Beispieldaten anlegen" (~25 Datensätze, Klartext-Liste), Demo-Zähler + Lösch-Funktion, „Demo ausblenden"-Filter
Erste-Schritte-Checkliste [/:tenant/onboarding/checklist] Auto-erkannte Status-Häkchen, CTA-Links, manuell abhakbar/ausblendbar, Glückwunsch bei 100% (auch Dashboard-Widget)
Status-Banner-System (Shell) AK-P20: Trial-Ende-3-Tage / past_due / frozen mit Klartext + Abo-Aktion; die bestehende 423-Klartext-Hülle bleibt. deletion_pending samt Shell-Aktion gehört zu AK-P21/D-P21; der finale Read-only-Toast bleibt D-P20-Design-Nachzug.
Light/Dark-Toggle [Profil/User-Menü] Vorerst ausgeblendet und im App-/Admin-Bereich deaktiviert (PR #81)

Definition of Done

  • Billing-Recut-Basis: lokaler Plan-/Seat-/Entitlement-State ist auf Lago/Mollie/HiveGrid ausgerichtet; keine Legacy-Provider-IDs als Zielmodell; kein Usage-Billing
  • Trial + Dunning (Tag 1/3/7) + Frozen-Modus (Read-Only-Middleware) greift; Status-Banner pro Zustand; Verbrauchs-Zähler + Drossel (Aufschlags-Abrechnung → v2)
  • In-App keine Pricing-Tabelle/Upgrade-Buttons/Plan-Wechsel-UI (LP-8) — Read-Only + externer Verweis; Kündigen bleibt bei vorhandener Berechtigung erlaubt
  • Auto-SHK-Provisionierung beim Signup (Seeds M158: Pipelines, Custom-Felder, Rollen, Form-Templates, Checkliste) — ohne Wizard-UI (v2)
  • Demo-Daten-Knopf (per Settings, is_demo_data-Flag löschbar) + „Demo ausblenden"-Filter
  • Erste-Schritte-Checkliste (auto-erkannter Status, CTA-Links, abhakbar/ausblendbar; Dashboard-Widget)
  • Light/Dark-Unterbau bleibt erhalten; Toggle und Dark-Anwendung sind vorerst deaktiviert (DARK_MODE_IN_APP=false, PR #81)
  • Konnektor tenantHasModule('billing'); RLS auf allen Tenant-Tabellen

Aktueller Stand (Interim-UI 2026-07-12)

Fortschritt: AK-P20: 8/8 DoD = 100 % done. Es gibt keine selbst machbare Dev-Arbeit mehr. Die finale Subframe-Optik aus D-P20 bleibt als nicht blockierender design-nachzug offen. Das Plane-Ticket wird ohne separate Done-Freigabe nicht auf Done gesetzt.

Erledigt:

  • Lago-/Mollie-/HiveGrid-Recut aus BILL-02 bis BILL-05, Trial/Dunning/Frozen, Shell-Statusbanner für die AK-P20-Billing-Zustände (nicht deletion_pending), zentraler Read-only-Guard sowie nicht abrechenbare Usage-Zähler und Drossel.
  • Read-only Subscription ohne Pricing-, Upgrade-, Planwechsel- oder Checkout-UI; nur Kontakt und erlaubte Kündigung. Rechnungen zeigen Lago-Invoice- und Mollie-Payment-State.
  • Auto-SHK-Provisionierung, Demo-Daten-Verwaltung samt Environment-Gate/Listenfilter und Erste-Schritte- Checkliste samt Dashboard-Widget.
  • App-/Admin-Dark-Mode und Toggle bleiben wie mit PR #81 beabsichtigt deaktiviert; der Unterbau bleibt erhalten.
  • Fünf app-chrome-freie Interim-Screens aus ~/ui, reine VM-Verträge, Smoke-/Hot-Swap- und Interim-Visual-Proof. Der M016-Pixelnachweis liegt in tests/component/ak-p20-interim.ct.tsx mit fünf PNG-Baselines unter tests/component/__screenshots__/; der schnelle React-Markup-Nachweis liegt in apps/web/app/components/screens/ak-p20-interim.visual.test.tsx. Die austauschbare Mock-Baseline liegt unter packages/ui-mock/visual-baseline/ak-p20-interim.*.

Offen, nicht Done-blockierend: finales Layout-/Copy-Delta aus D-P20, anschließender Component-Swap und Re-Baseline. Die fachlichen Loader-, VM- und Action-Verträge bleiben dabei stabil.

Technische Bausteine

  • Entities (eigene prisma/schema/billing.prisma): Subscription-/Feature-/Usage-Tabellen tragen den lokalen HiveGrid-State sowie Lago-/Mollie-Referenzen; Legacy-Felder sind nur noch Migrationskompatibilität, nicht Zielmodell. Onboarding: Onboarding/OnboardingSession/OnboardingDemoProvisioning. Branding: vorhandener User-Theme-Unterbau (kein neues Modell). core.prisma nur ueber noetige Tenant-Relationen (AD-21).
  • Abo-/Entitlement-Schicht: SubscriptionFeature.code (z.B. kwp_integration) = Entitlement-Schicht; tenantHasModule() bleibt zentrale Gate-API.
  • Billing-Integration: Lago-Gateway (BILL-03), Mollie-Payment-Gateway (BILL-04) und Sync/Frozen-State (BILL-05) sind der aktive Vertrag. Historische Legacy-Webhook-/Dunning-Pfade bleiben nur Migrationsinventar.
  • Auto-SHK-Provisionierung orchestriert die Self-Seeds aller Module (AD-12); Demo-Daten-Seed via is_demo_data; Trial-Freischaltung durch Plattform-Admin (AK-P19).
  • RLS überall (global: Produkte/Features/Preise); der bestehende Theme-Unterbau bleibt erhalten, App-/Admin-Dark-Mode wird wegen DARK_MODE_IN_APP=false nicht angewendet.

Quellen (granular)

  • ENTITY-MODEL.md → Domäne 12: Billing (AD-27-Recut: Lago/Mollie/HiveGrid, Plans + Seats) + Domäne 13 (Onboarding, OnboardingDemoProvisioning, bestehender User-Theme-Unterbau)
  • REQUIREMENTS.md → REQ-billing-datenmodell, REQ-billing-trial-dunning, REQ-onboarding-demo-daten, REQ-branding-theme-phase1 (Onboarding-Wizard → v2)
  • ROADMAP.md → Phase 20 · Milestones: (AD-27-Recut, M155 Trial/Read-only, M156 nur Zähler+Drossel, M158 Signup-Provisionierung, M159 nur SHK, M160 Demo gedünnt, M030-Unterbau bei deaktiviertem Toggle)
  • designer-briefs/P20-billing-onboarding-branding.md (read-only Lago/Mollie/HiveGrid, kein Upgrade-UI, Demo-Knopf, Theme-Toggle deaktiviert)

Dev-Nachzug (nach Davids D-P20-Delta)

  • Interim-UI aus ~/ui auf den fünf kanonischen Tenant-Routen integriert; VM + Action-Callbacks stabil.
  • ROADMAP, REQUIREMENTS, Designer-Brief und D-P20 auf AD-27/AD-28 sowie PR #81 ausgerichtet.
  • Finale Subframe-Optik aus D-P20 integrieren und ak-p20-interim neu baselinen.
  • Plane-Kommentar 1dee227f-4726-4b7c-8ef1-7a15108f7e99, Recut-Titel und Label design-nachzug nach dem Push gespiegelt; Status bewusst unverändert.

Umsetzungs-Notiz

2026-07-20 · Stand-Audit + Dunning-Trigger-Nachzug (Branch fix/ak-p20-audit-restwork)

Drei-Quellen-Audit (Doc vs. Plane vs. Code) nach dem RLS-Cutover vom 14.07. Ergebnis: Interim-UI, Onboarding, Frozen/Read-only, Demo-Daten, Checkliste und Layer-Trennung sind vollstaendig belegt; die aktiven Pfade (Mollie-Webhook, Signup-Bootstrap, Checklist-Persistenz) binden den RLS-Kontext korrekt. Ein realer Befund: Die Tag-1/3/7-Dunning-Sequenz (DoD 2) hatte keinen Produktions-Trigger — applyBillingDunningCycle() im Web-Legacy-Service war nur aus Tests aufrufbar, und BILL-05 hat Dunning-Mailsequenzen explizit aus seinem Scope ausgeklammert. Korrigierter Stand vor dem Nachzug: 7/8.

Umgesetzt:

  • Pure Dunning-Entscheidung (evaluateBillingDunning, Tag 1/3/7 + Freeze) nach @hivegrid/db/billing-domain.server gehoben (Commit b30881a0a).
  • Neuer taeglicher Worker-Cron billing-dunning-sweep: Sweep pro Tenant aus der globalen Tenant-Registry, TenantSubscription-Zugriffe in withTenantRLS(), Notices ueber notifyWithTenantRlsContext() (FORCE RLS, R-P1b-Praezedenz, sourceKey-Dedupe pro Attempt), Freeze nach Tag 7 mit AuditEvent + billing_state_changed-Activity im BILL-05-Format. Task in der CleanupJob-Union registriert (Folge-Commit auf dem Branch).
  • Nachzug (per User-Freigabe zum ausgewiesenen Vorschlag): Der tote Legacy-Service billingDunningService.ts (Stripe-Pfade, referenzierte ein nicht existierendes stripeWebhookLog-Modell, keine Konsumenten ausser dem eigenen Test) wurde samt Test entfernt; ebenso die VM-Dublette buildBillingStatusBannerVm + BillingStatusBannerVm aus billingStatusService.ts (der reale Banner laeuft ueber packages/view-models/src/billing/subscription-banner.vm.ts). Damit ist der letzte stripe-Import aus dem Codebestand verschwunden.

Audit-Klarstellungen (kein Code-Delta):

  • Das fehlende tenantHasModule('billing')-Gate auf settings/subscription.tsx ist beabsichtigt: /plan-required/:tenant verlinkt genau dorthin zurueck und BILL-05-DoD verlangt erreichbare Recovery-/Billing-Routen im Frozen-Zustand — ein Gate wuerde einen Redirect-Loop erzeugen. DoD 8 gilt damit als erfuellt (Gates auf settings/usage + settings/billing vorhanden).
  • Proof-Hash-Korrektur zu den 2026-07-12-Notizen: 84f56966c existiert nach dem Rebase als 5c27d7b34 (feat(ak-p20): add interim billing and onboarding UI); 2ddff0ec0 ist als PR-#86-Merge ecca4400a auf main.
  • Das Zielschema liegt real in prisma/schema/subscriptions.prisma (nicht billing.prisma).

Proof: pnpm --filter @hivegrid/{worker,queue,db,web} typecheck gruen; fokussierte Suiten billing-domain.server.test.ts (13), billing-dunning-cron.test.ts + handlers.test.ts (123), packages/queue (127), index.test.ts/notify-rls.test.ts gruen; verify:i18n, verify:cross-cutting-models, verify:sidebar-routes gruen.

Fortschritt: AK-P20: 8/8 DoD = 100 % done (nach Nachzug; vor dem Nachzug real 7/8 = 87,5 %).

2026-07-12 · Bugfix-Nachtrag: EmptyState-Aktions-Buttons + Checklist-Reopen

Befund (Staging-Verifikation demo-pro-crm): Der „Demo-Daten erstellen"-Button war im DOM, aber unsichtbar. Root Cause außerhalb der AK-P20-Dateien: der ~/ui-EmptyState-Wrapper (apps/web/app/ui/components/EmptyState/index.tsx) mergte noch [&_button]:hidden (Alt-Workaround gegen den früheren hartkodierten Subframe-CTA) und versteckte damit jeden per action-Slot übergebenen Button (~10 Screens, u.a. Demo-Daten-Create und Retry-CTAs). Zusätzlich war das Checklisten-„Ausblenden" irreversibel (Dismissed-State ohne nächste Aktion, DoD-23-Lücke).

Umgesetzt:

  • Wrapper-Klasse entfernt + Regression-Guard-Test (EmptyState.wrapper.test.tsx).
  • Checklist-Reopen: Service-Action show (Session zurück auf active), „Wieder einblenden"-Button im Dismissed-State, i18n onboarding.firstSteps.dismissed.reopen (de/en), Tests nachgezogen.
  • Staging-Ops: versehentlich dismisste Session (john.doe @ demo-pro-crm) per SQL zurück auf active.

Proof: PR #86 (fix(ui): EmptyState action buttons visible again + checklist reopen, Commit 2ddff0ec0); pnpm typecheck, verify:i18n, verify:source-health grün; fokussierte Suites (Wrapper-Guard, OnboardingInterimScreens, akP20OnboardingService) 12/12 grün. Staging-E2E-Nachweis nach Merge/Deploy.

DoD-Stand unverändert: AK-P20: 8/8 DoD = 100 % done (Bugfix, kein Scope-Delta).

2026-07-12 · Interim-UI abgeschlossen

Umgesetzt:

  • Fünf kanonische Tenant-Screens fuer Subscription, Usage, Rechnungen/Zahlung, Demo-Daten und Erste Schritte als app-chrome-freie ~/ui-Komponenten mit reinen VM-/Action-Verträgen.
  • Subscription bleibt read-only ohne Pricing, Checkout, Upgrade/Downgrade oder Customer-Portal; Kontakt und berechtigte Kündigung bleiben verfügbar. Lago-Invoices und Mollie-Payment-State sind getrennt dargestellt.
  • Trial-/past_due-/frozen-Banner in der Tenant-Shell; Aktion nur mit View-Permission. Der Dark-Mode-Toggle bleibt deaktiviert und auch gespeicherte Tenant-Dark-Farben werden bei DARK_MODE_IN_APP=false nicht angewendet.
  • Demo-Daten-Settings und Erste-Schritte-Checkliste einschließlich Dashboard-Widget. Der Checklisten-GET ist strikt read-only; Provisionierung/Persistenz geschieht nur noch über explizite Mutationspfade.
  • Echter M016-Pixelvergleich fuer alle fünf Screens sowie schneller React-Markup- und ui-mock-Hot-Swap-Proof.

Proof:

  • Code-Commit 84f56966c (feat(ak-p20): add interim billing and onboarding UI), auf aktuellem origin/main (6d16e4da7) rebased und gepusht.
  • Plane-Kommentar 1dee227f-4726-4b7c-8ef1-7a15108f7e99, Titel auf den AD-27-Recut korrigiert und Label design-nachzug gesetzt; Ticket-State unverändert gelassen.
  • pnpm typecheck und pnpm lint grün; Pre-Push-Typecheck/i18n ebenfalls grün.
  • Fokussierte AK-P20-Suite: 22 Testdateien, 112 Tests grün.
  • pnpm run test:component:p20: 5/5 Chromium-Pixelvergleiche grün; PNGs visuell geprüft.
  • pnpm run verify:i18n, pnpm run verify:ui-visual, pnpm run test:hot-swap, pnpm run verify:billing-boundary-baseline, pnpm run verify:onboarding-flow, pnpm run verify:ci-baseline, pnpm run verify:source-health und pnpm exec prisma validate grün.
  • Sidebar-Reachability im Main-Workspace: 5 Testdateien, 29 Tests grün. Playwright-E2E-Discovery: 6 AK-P20-Smokes; ein vollständiger Live-Lauf benötigt die E2E-Tenant-Credentials.
  • Der breite Root-Wrapper pnpm test ist lokal kein belastbarer Gate-Lauf, weil er die benachbarten .codex/worktrees mit separaten React-Installationen einsammelt und dort bekannte Invalid-Hook-Fehler erzeugt. Die betroffenen Main-Workspace-Dateien und passenden Verify-Gates wurden deshalb explizit und grün ausgeführt.

Fortschritt: AK-P20: 8/8 DoD = 100 % done. Keine selbst machbare Dev-Arbeit offen; finales D-P20-Delta bleibt als nicht blockierender design-nachzug getrackt. Plane-Done bleibt bis zur separaten Freigabe ausstehend.

Hinweis 2026-07-04: Die folgenden Slice-Notizen dokumentieren historische Umsetzung vor AD-27. Wo sie Legacy-Provider nennen, ist das als Migrationsinventar/Vorarbeit zu lesen. Der aktive Zielpfad ist BILL-02 bis BILL-05.

2026-07-01 · AK-P20 Teilumsetzung

Umgesetzt:

  • Billing-Grundlage erweitert: SubscriptionFeature.code/quotaValue, Subscription-Statusfelder, metered Usage-Records mit Idempotenz, Webhook-Log, billing-Entitlement und tenantHasModule('billing')-Gate auf der Subscription-/Usage-Route.
  • In-App-AI-Credits entfernt bzw. auf Subscription umgeleitet; Subscription-UI bleibt read-only mit externem Hinweis, Portal/Kündigen bleiben erhalten.
  • Verbrauchsübersicht für Automation-Läufe/Speicher, Billing-Statusbanner-VM und Shell-Banner vorbereitet.
  • SHK-Onboarding-Grundlage: Signup ruft SHK-Defaults auf, Checkliste und Demo-Daten-Service/-Routes mit isDemoData-Tracking und löschbarer Provisionierung.
  • Hell/Dunkel-Toggle auf zwei Modi begrenzt, kein System-Fallback mehr.
  • Tenant-Isolation/RLS-Nachzug: OnboardingDemoProvisioning, Usage-Records und RLS-Artefakt registriert; Windows-kompatible Verify-Wrapper für die betroffenen Baseline-Gates repariert.

Proof:

  • pnpm prisma validate
  • pnpm typecheck
  • pnpm lint
  • pnpm run verify:i18n
  • pnpm run verify:sidebar-routes
  • pnpm run verify:tenant-isolation-report
  • pnpm run verify:billing-boundary-baseline
  • pnpm run verify:onboarding-flow
  • pnpm --filter @hivegrid/entitlements test
  • pnpm --filter @hivegrid/cli exec vitest run src/commands/tenant/models.test.ts
  • pnpm --filter @hivegrid/web exec vitest run app/application/sidebar/AppSidebar.test.tsx app/utils/theme/userThemePreference.server.test.ts 'app/routes/app.$tenant/settings/subscription.test.tsx' app/utils/services/.server/billingStatusService.test.ts

Fortschritt: AK-P20: 2/8 DoD = 25 % done.

Abgehakt: Hell/Dunkel ohne System-Modus; Billing-Konnektor/RLS.

Teilweise umgesetzt, aber noch nicht DoD-grün: Legacy-Provider-Abo-Baukasten-Grundschema, Trial/Frozen-Statusdaten + Banner, read-only Subscription-Oberfläche, Auto-SHK-Provisionierung, Demo-Daten-Knopf, Erste-Schritte-Checkliste.

Offen/blockiert: EXT-07 Legacy-Provider-Account/Produkte/Webhook, AK-P19 Admin-Abo-Baukasten/Trial-Freischaltung, D-P20 finale Screens/Subframe-Delta; außerdem selbst machbar offen sind vollständige Dunning-Sequenz Tag 1/3/7, Frozen-Read-Only-Middleware, Demo-ausblenden-Filter, Checklist-Auto-Erkennung und Dashboard-Widget.

2026-07-01 · AK-P20 Slice 1 Nachzug: Legacy-Provider-Webhooks + Dunning/Frozen

Umgesetzt:

  • Legacy-Provider-Webhook-Einstieg /webhooks/legacyProvider mit Signaturprüfung über MOLLIE_API_KEY und idempotentem Legacy-ProviderWebhookLog.
  • Legacy-Provider-Status-Sync für customer.subscription.updated/deleted, invoice.payment_failed, invoice.paid und invoice.payment_succeeded; Subscription-Periodenfelder werden aus Legacy-Provider übernommen.
  • Dunning-Entscheidung Tag 1/3/7 plus Freeze nach ausgeschöpfter Mahnstufe; pastDueSince bleibt bei wiederholten Legacy-Provider-Fehlerereignissen stabil.
  • Dunning-Email-Sequenz erzeugt Billing-Notifications über den bestehenden Notification-Delivery-Boundary (category=billing, channel=EMAIL).
  • Billing-Read-Only-State zentral auslesbar und erste Tenant-Shell-Schreibaktionen blockieren im Frozen/Read-only-Status mit 423.
  • Tests für Dunning-Entscheidung, Dunning-Cycle, Legacy-Provider-Webhook-Route, Legacy-Provider-Signaturkonstruktion, Status-Read-only-State und Tenant-Action-Block ergänzt.

Proof:

  • pnpm --filter @hivegrid/web exec vitest run app/utils/services/.server/billingStatusService.test.ts app/utils/services/.server/billingDunningService.test.ts app/routes/webhooks.legacyProvider.test.ts app/utils/legacyProvider.server.test.ts 'app/routes/app.$tenant.test.tsx'
  • pnpm prisma validate
  • pnpm typecheck
  • pnpm lint
  • pnpm run verify:i18n
  • pnpm run verify:sidebar-routes
  • pnpm run verify:billing-boundary-baseline

Fortschritt: AK-P20: 2/8 DoD = 25 % done.

Abgehakt bleibt: Hell/Dunkel ohne System-Modus; Billing-Konnektor/RLS.

Teilweise umgesetzt, aber noch nicht DoD-grün: Legacy-Provider-Abo-Baukasten-Grundschema; Trial/Dunning/Frozen mit Statusdaten, Webhook-Sync und erster Read-only-Blockade; read-only Subscription-Oberfläche; Auto-SHK-Provisionierung; Demo-Daten-Knopf; Erste-Schritte-Checkliste.

Selbst machbar offen: Frozen-Read-Only noch route-übergreifend härtbar, Verbrauchs-Drossel, Demo-ausblenden-Filter, Checklist-Auto-Erkennung und Dashboard-Widget.

Blockiert/offen durch externes Delta: finale Subframe-/Screen-Integration aus D-P20. EXT-07 ist laut Plane erledigt; AK-P19 ist formal auf On-Hold, die für AK-P20 genutzten Grundlagen liegen aber bereits auf main.

2026-07-01 · AK-P20 Slice 2 Nachzug: Usage-Drossel + First-Steps-Auto-Erkennung

Umgesetzt:

  • Verbrauchs-Drossel: recordBillingUsage() prueft Quotas vor dem Schreiben, wirft BillingUsageQuotaExceededError und behandelt idempotencyKey jetzt wirklich idempotent.
  • Usage-Summary liefert pro Metrik quota, remaining, exceeded und percentUsed; /settings/usage zeigt Limit, Restmenge und ausgeschöpfte Limits an.
  • Erste-Schritte-Checkliste erkennt Status automatisch aus echten Tenant-Daten: Profil, Kontakte, Projekte und aktives Trial/Abo. Erfüllte Schritte werden in OnboardingSessionStep.completedAt persistiert; vollständige Sessions werden auf completed gesetzt.
  • Dashboard-Widget für die Erste-Schritte-Checkliste ergänzt, inklusive Fortschritt und Link zur Checklist-Route.

Proof:

  • pnpm --filter @hivegrid/web exec vitest run app/utils/services/.server/billingStatusService.test.ts app/utils/services/.server/billingDunningService.test.ts app/routes/webhooks.legacyProvider.test.ts app/utils/legacyProvider.server.test.ts 'app/routes/app.$tenant.test.tsx'
  • pnpm typecheck
  • pnpm lint
  • pnpm run verify:i18n
  • pnpm run verify:billing-boundary-baseline

Hinweis Testabdeckung:

  • Der isolierte direkte Lauf von app/routes/app.$tenant/dashboard.test.tsx bleibt ein bestehender Mixed-Environment-Testfall: Loader-Imports sind server-only, Render-Assertions brauchen jsdom. Die Dashboard-Änderung ist via Typecheck abgedeckt; die fokussierten grünen Tests decken die Billing-/Webhook-Regressionen ab.

Fortschritt: AK-P20: 3/8 DoD = 37,5 % done.

Abgehakt: Hell/Dunkel ohne System-Modus; Billing-Konnektor/RLS; Erste-Schritte-Checkliste.

Teilweise umgesetzt, aber noch nicht DoD-grün: Legacy-Provider-Abo-Baukasten-Grundschema; Trial/Dunning/Frozen mit Webhook-Sync, Dunning-Notifications, Usage-Drossel und erster Read-only-Blockade; read-only Subscription-Oberfläche; Auto-SHK-Provisionierung; Demo-Daten-Knopf.

Selbst machbar offen: Frozen-Read-Only noch route-übergreifend härtbar und Demo-ausblenden-Filter.

2026-07-01 · AK-P20 Slice 3 Nachzug: Demo-Daten in Listen standardmäßig ausblenden

Umgesetzt:

  • Demo-Daten werden in Projektlisten, Projekt-Board, Aufgabenliste und Kontaktliste standardmäßig serverseitig ausgeblendet (isDemoData=false).
  • Explizites Anzeigen läuft einheitlich über demo=show; Projekte/Aufgaben bieten einen Toggle-Link, Kontakte nutzen den bestehenden Filter-Submit.
  • Kontaktlisten-Query serialisiert und parst den Demo-Filter stabil, inklusive Unit-Test.
  • i18n-Keys für „Demo-Daten anzeigen/ausblenden" in Deutsch und Englisch ergänzt.

Proof:

  • pnpm --filter @hivegrid/web exec vitest run app/utils/services/.server/billingStatusService.test.ts app/utils/services/.server/billingDunningService.test.ts app/routes/webhooks.legacyProvider.test.ts app/utils/legacyProvider.server.test.ts 'app/routes/app.$tenant.test.tsx' app/utils/integrations/crm/kontaktListQuery.test.ts
  • pnpm typecheck
  • pnpm lint
  • pnpm run verify:i18n
  • pnpm run verify:billing-boundary-baseline
  • pnpm run verify:onboarding-flow

Fortschritt: AK-P20: 4/8 DoD = 50 % done.

Abgehakt: Hell/Dunkel ohne System-Modus; Billing-Konnektor/RLS; Erste-Schritte-Checkliste; Demo-Daten-Knopf plus Demo-ausblenden-Filter.

Teilweise umgesetzt, aber noch nicht DoD-grün: Legacy-Provider-Abo-Baukasten-Grundschema; Trial/Dunning/Frozen mit Webhook-Sync, Dunning-Notifications, Usage-Drossel und erster Read-only-Blockade; read-only Subscription-Oberfläche; Auto-SHK-Provisionierung.

Selbst machbar offen: Frozen-Read-Only noch route-übergreifend härtbar. Der zentrale Guard existiert aktuell nicht als Request-/Action-Middleware; ein flächiger Route-Patch hätte hohen Blast-Radius und sollte als eigener, gezielter Nachzug umgesetzt werden.

Blockiert/offen durch externes Delta: finale Subframe-/Screen-Integration aus D-P20.

2026-07-02 · AK-P20 Slice 5 Nachzug: Frozen-ReadOnly zentral gehärtet

Umgesetzt:

  • Mutierende Tenant-Requests werden im zentralen Permission-Boundary verifyUserHasPermission() gegen den Billing-ReadOnly-State geprüft.
  • past_due, frozen und cancelled blockieren permission-gated Tenant-Schreibaktionen mit HTTP 423 und dem Klartext-Key billing:status.readOnly.
  • Billing-Recovery bleibt erlaubt: /settings/subscription ist als Ausnahme freigegeben, damit Customer-Portal/Zahlungs- und Kündigungsaktionen erreichbar bleiben.
  • Bestehende Tenant-Shell-Actions (Feedback/Support) bleiben zusätzlich durch den bisherigen ReadOnly-Check geschützt.

Proof:

  • pnpm --filter @hivegrid/web exec vitest run 'app/routes/app.$tenant.test.tsx' app/utils/helpers/.server/PermissionsService.billing-readonly.test.ts
  • pnpm typecheck
  • pnpm lint
  • pnpm run verify:i18n
  • pnpm run verify:billing-boundary-baseline

Fortschritt: AK-P20: 6/8 DoD = 75 % done.

Abgehakt: Hell/Dunkel ohne System-Modus; Billing-Konnektor/RLS; Erste-Schritte-Checkliste; Demo-Daten-Knopf plus Demo-ausblenden-Filter; Auto-SHK-Provisionierung; Trial/Dunning/Frozen/Usage-Drossel.

Teilweise umgesetzt, aber noch nicht DoD-grün: Legacy-Provider-Abo-Baukasten-Grundschema; read-only Subscription-Oberfläche ohne Pricing-/Upgrade-/Plan-Wechsel-UI.

Selbst machbar offen: AD-26-Cleanup von verbliebenen AI-Credits-/Credits-Entitlement-Resten prüfen und, falls scope-konform, bereinigen.

Blockiert/offen durch externes Delta: finale Subframe-/Screen-Integration aus D-P20.

2026-07-02 · AK-P20 Slice 4 Nachzug: Auto-SHK-Provisionierung vervollständigt

Umgesetzt:

  • provisionShkTenantDefaults() orchestriert jetzt alle vorhandenen SHK-Seed-Bausteine: Rollen, Default-Sales-Pipeline, Custom-Field-Template-Seed, Abnahmeformular-Template, Projekt-Template, Erste-Schritte-Checkliste.
  • Die bisher direkt in der Forms-Route liegenden SHK-Form-Templates wurden in modules/forms/services/shkFormTemplates.server.ts extrahiert und werden beim Signup automatisch mit lokalisierten Labels angelegt.
  • Der bestehende Forms-Admin-Button nutzt denselben Seed-Service weiter; kein zweiter Seed-Pfad.
  • Hinweis: Die Custom-Field-Template-Liste bleibt bewusst leer, weil der bestehende Code sie bis zum SHK-Domain-Workshop nicht mit erfundenen Feldern füllt. Der Provisioning-Hook ist verdrahtet.

Proof:

  • pnpm --filter @hivegrid/web exec vitest run app/modules/forms/services/shkFormTemplates.server.test.ts app/utils/services/shkRoles.server.test.ts app/utils/services/authService.transactional-email.test.ts
  • pnpm typecheck
  • pnpm lint
  • pnpm run verify:i18n
  • pnpm run verify:onboarding-flow

Fortschritt: AK-P20: 5/8 DoD = 62,5 % done.

Abgehakt: Hell/Dunkel ohne System-Modus; Billing-Konnektor/RLS; Erste-Schritte-Checkliste; Demo-Daten-Knopf plus Demo-ausblenden-Filter; Auto-SHK-Provisionierung.

Teilweise umgesetzt, aber noch nicht DoD-grün: Legacy-Provider-Abo-Baukasten-Grundschema; Trial/Dunning/Frozen mit Webhook-Sync, Dunning-Notifications, Usage-Drossel und erster Read-only-Blockade; read-only Subscription-Oberfläche.

Selbst machbar offen: Frozen-Read-Only noch route-übergreifend härtbar; AD-26-Cleanup von verbliebenen AI-Credits-/Credits-Entitlement-Resten.

Blockiert/offen durch externes Delta: finale Subframe-/Screen-Integration aus D-P20.

2026-07-02 · AK-P20 Slice 6 Nachzug: In-App-Planwechsel entfernt

Umgesetzt:

  • Die Legacy-Route /subscribe/:tenant rendert keine Pricing-/Planwechsel-UI mehr und startet keine Payment-Checkout-Session mehr; GET/POST fallen auf die read-only Subscription-Übersicht zurück.
  • Interne Subscription-required-Links zeigen direkt auf /settings/subscription?subscription_required=1 statt auf die alte Checkout-Seite.
  • Header-/ProFeature-Einstiege verlinken nur noch die Subscription-Übersicht; Customer-Portal, Zahlungsmethoden und Kündigen bleiben in /settings/subscription erhalten.
  • Billing-Boundary-Test ergänzt: Legacy-Subscribe muss frei von Checkout-Writes, PlansGrouped und direkten Billing-Imports bleiben.

Proof:

  • pnpm --filter @hivegrid/web exec vitest run 'app/routes/subscribe.$tenant.test.tsx' app/utils/app/SubscriptionUrlUtils.test.ts
  • pnpm typecheck
  • pnpm lint
  • pnpm run verify:i18n
  • pnpm exec vitest run packages/db/src/subscriptions.server.test.ts packages/db/src/subscriptions-boundary.test.ts apps/web/app/utils/services/.server/subscriptionService.test.ts
  • pnpm run verify:billing-boundary-baseline

Fortschritt: AK-P20: 7/8 DoD = 87,5 % done.

Abgehakt: Hell/Dunkel ohne System-Modus; Billing-Konnektor/RLS; Erste-Schritte-Checkliste; Demo-Daten-Knopf plus Demo-ausblenden-Filter; Auto-SHK-Provisionierung; Trial/Dunning/Frozen/Usage-Drossel; read-only Subscription-Oberfläche ohne Pricing-/Upgrade-/Plan-Wechsel-UI.

Offen nach Recut: Der alte Legacy-Provider-Abo-Baukasten-Abschluss wird nicht weitergebaut. Der saubere Abschluss laeuft ueber BILL-02 bis BILL-05: lokale Plan-/Seat-/Entitlement-Domain, Lago-Gateway, Mollie-Gateway und Billing-Sync.

Blockiert/offen durch externes Delta: finale Subframe-/Screen-Integration aus D-P20.

2026-07-02 · AK-P20 Slice 7 Nachzug: Seat-Typen im Admin-Pricing blockiert

Umgesetzt:

  • Die Standard-Plan-Seeds erzeugen keine PER_SEAT-Pläne mehr.
  • Die Plattform-Admin-Pricing-Auswahl nutzt eine zentrale HiveGrid-Pricing-Policy ohne PER_SEAT.
  • pricing.new, pricing.edit und create-all-plans lehnen manipulierte PER_SEAT-Formulare serverseitig mit shared.invalidForm ab.
  • Test ergänzt: Policy und File-Seeds bleiben frei von Seat-Type-Plänen.

Proof:

  • pnpm --filter @hivegrid/web exec vitest run app/application/pricing/pricingModelPolicy.test.ts
  • pnpm typecheck
  • pnpm lint
  • pnpm run verify:i18n
  • pnpm run verify:billing-boundary-baseline

Fortschritt: AK-P20: 7/8 DoD = 87,5 % done.

Weiterhin offen nach Recut: Der alte Legacy-Provider-Abo-Baukasten-DoD ist durch AD-27 ersetzt. Keine weitere Legacy-Provider-Admin-Positionen-Arbeit in AK-P20; neue Billing-Arbeit ueber BILL-02 bis BILL-05.