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

27 KiB

VA-P26c · P26 Customer-Portal: Paket-Gates + Self-Service-Custom-Domain ⭐

Typ Dev (Code + Infra-Integration)
Owner Akeshan
Phase P26 — Customer-Portal · v2-P6 · AD-30/CR-001-Delta
Cycle/Fenster technischer Staging-Abschluss 2026-07-21 · keine Produktionsfreigabe
Status technisch vollständig · Plane Done · 8/8 DoD = 100 % done

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

Abhängigkeiten & Parallelität

  • Erfüllte Grundlagen: VA-P26a (separate hivegrid-portal-Runtime, Host-/Auth-/DB-Trust-Boundary) und VA-P26b (Admin-/Interaktionsschicht) sind seit 2026-07-21 technisch vollständig.
  • Erfüllte technische Voraussetzung: VA-P24a liefert den generischen Vertrag für pauschales Monats-Add-on und einmalige Einrichtungsposition mit 18dfd4825/355eead8e; die portalspezifischen Provider-/Live-Proofs sind auf Staging abgeschlossen.
  • Erfüllter Estate-Vertrag: Traefik, DNS, TLS, der schmal berechtigte Domain-Controller und der zentrale Prometheus-Scrape sind live geprüft. Es existiert kein eigener Server pro Tenant.
  • Erfüllter Downstream-Vertrag: Preis-, Entitlement-, Domain- und Lifecycle-Flow für VJ-3 sind vollständig geprüft.
  • Design bedient durch: VD-P26; kein harter Dev-Blocker wegen AD-28. VD-P24 liefert die generischen Checkout-/Payment-Zustände.
  • Läuft fachlich nach: VA-P26a; kann technisch parallel zu den Interaktions-Slices aus VA-P26b vorbereitet werden. Zeitlich erst nach a/b einplanen, damit der feste Portal-Slot nicht still wächst.
  • Produktentscheidung 2026-07-16: Starter/Team buchen das Portal als Add-on, Business/Enterprise enthalten es. Die Domain kostet Starter/Team/Business einmalig 299,99 EUR, Enterprise enthält eine. business und Enterprise bleiben technisch getrennte Entitlement-Pfade.

Entscheidungs-Notiz

2026-07-16 · Raffael: Produkt- und Betriebsvertrag sind bestätigt. Öffentliche Buchung/Freischaltung erfolgt erst nach VA-P26b. Ein Domain-Wechsel ist eine neue 299,99-EUR-Einrichtung, sofern kein individueller Enterprise-Vertrag abweicht; entfernte/gewechselte Hosts erhalten 30 Tage Reclaim-Cooldown. Erlaubt ist genau eine Subdomain, kein Apex, Wildcard oder Mehrfachhost; der Standardhost bleibt Fallback. Das ist kein vollständiges App-White-Label.

Umsetzungs-Notiz

2026-07-16 · Raffael · Repository-Proof: 18dfd4825 (Domain-/Ledger-Persistenz und RLS), 355eead8e (Billing/Entitlements), f5604db81 (privater Controller-Runtime-Vertrag), bd2d69f2d (Claim, Host-Auflösung und Orchestrierung), cd1193756 (Admin-Self-Service) und 5dc3b01d7 (Interim-Visual-, Hot-Swap- und Smoke-Verträge). Der lokale Domain-Core besitzt einen global eindeutigen, IDNA-/PSL-normalisierten Hostname-Claim mit ausschließlich gehasht gespeichertem TXT- Proof, CNAME-Prüfung, Generation, Concurrency-Schutz und 30-Tage-Reclaim-Cooldown. Apex, Wildcards, IP-Adressen, reservierte Hosts und Mehrfachzuordnungen werden fail-closed abgelehnt. Der Custom-Host wird vor Assets, Router, Auth und Session tenantgebunden aufgelöst; unbekannte, unbestätigte oder deaktivierte Hosts liefern 404. __Host-*-Session und absolute Mail-/Magic-Link-Origin verwenden den gespeicherten aktiven Origin statt eines ungeprüften Request-Hosts. Idempotente Initial-Claim-Replays liefern denselben kurzlebigen TXT-Proof auch nach bereits persistierter Domain-Bindung; manuelle und DNS-getriebene Provisioning-Retries erhöhen Claim- und Domain-Generation vor dem neuen Command. Die einzige pre-active Host-Ausnahme ist der schmale Controller-Probe auf /healthz: Er verlangt verifizierten DNS-/Entitlement-/Payment-State, einen persistierten Controller-Command und den Zustand provisioning, active oder degraded; Disable, Kill-Switch und Deprovisioning bleiben 404. Diese Capability schaltet kein öffentliches Portal-Routing frei.

Der Workspace-Admin-Self-Service ist als reine VM plus Action-Callbacks mit Interim-UI aus ~/ui umgesetzt: Kauf-/Eligibility-Zustände, DNS-Anleitung und Copy-Aktionen, Verify, Timeline, Retry, Fehler, Standardhost-Fallback, Entfernen, Kill-Switch und kostenpflichtiger Wechsel. Permission-404, CSRF, Rate-Limits, Klartext-, Loading-/Empty-/Read-only-Zustände sowie a11y-, Hot-Swap- und Interim-Visual-Verträge sind lokal geprüft. Die AD-28-Matrix umfasst 22/22 Prüfungen und eine Component-Reise; zwei Browser-E2E-Reisen sind für Staging registriert, aber nicht als Live-Lauf gewertet. VD-P26 bleibt als finaler Design-Nachzug offen.

Der generische Billing-Unterbau und der private Domain-Controller sind im Repository vorbereitet: idempotentes Add-on-/One-off-/Contract-Ledger, Claim-Bindung und isolierte Produktfehler sowie signierte Command-/Result-Queues, atomarer Traefik-Renderer, Health/Metrics, Retry/Revalidation, Deprovisioning und Rollback. Diese lokalen Verträge ersetzen weder echte Lago-/Mollie-Replay- und Refund-Proofs noch SNI/Let's-Encrypt/Ingress-, Controller-Ressourcen-, Merge-Migrations- oder Staging-Nachweise.

Stand 2026-07-16: VA-P26c: 3/8 DoD = 37,5 % done. Gezählt sind ausschließlich Domain-Claim, Host-/Session-Sicherheit und Workspace-Admin-Self-Service. Offen bleiben 5 Punkte mit realen externen Gates: Billing-Provider, Standardhost-Staging, TLS/Ingress/Controller-Ack, Lifecycle-/Alert-Betrieb und Querschnitt samt Merge-Migration/Staging-E2E. Das Ticket wird nicht auf Done gesetzt; es gab keine Deployment-, DNS-, TLS-, Coolify- oder Produktionsmutation.

Teilnachweis aus dem P26-Basis-Deploy

2026-07-16 · Raffael: Deploy #10300 hat die gemeinsame P26-Migration, die getrennten Core-/Portal-Rollen über PgBouncer, denselben Web-Digest für beide Surfaces sowie Health/Readiness der Standardhost-Portal-Runtime erfolgreich ausgerollt. Der Staging-Standardhost ist technisch erreichbar und die Basis-RLS-Grenze ist aktiv.

Der Standardhost-DoD bleibt dennoch offen, bis Slug-/Tenant-Auflösung, reservierte und inaktive Slugs sowie die 404-Pfade mit einer echten UAT-Fixture geprüft sind. Billing-Provider, privater Domain-Controller, Custom-Domain-TLS/Ingress, Lifecycle/Alerts und Custom-Host-E2E waren nicht Teil dieses Basis-Deploys. Der Stand bleibt daher 3/8 DoD = 37,5 % done · 5 Punkte offen, davon 5 extern/UAT-abhängig und 0 zusätzliche bereits abgeschlossene Punkte.

M006-Abhängigkeits-Nachtrag

2026-07-18 · Raffael: Der globale customer-portal-Betriebsschalter aus VA-P26a ist ausdrücklich nicht das Paket-Entitlement customer_portal, nicht customer_portal_custom_domain und nicht der hostbezogene killSwitchEnabled. Bei Disable schließen Standard- und Custom-Host-Inhalt/Auth sowie die Workspace-Admin-Self-Service-Routes fail-closed. Der schmale hivegrid_portal_resolve_custom_hostname_health-//healthz-Pfad bleibt absichtlich erreichbar; Claims, Entitlements und Domain-Zustand werden durch den Toggle nicht deprovisioniert.

Das erfüllt keinen zusätzlichen VA-P26c-DoD. Der Stand bleibt 3/8 DoD = 37,5 % done mit fünf externen/UAT-abhängigen Punkten.

Abhängigkeits-Nachtrag 2026-07-18: Der Standard-/Custom-Host-Handoff aus VA-P26a umfasst nach der Scope-Präzisierung auch den vollständigen Einladungs- und Erst-Setup-Pfad. VA-P26c bleibt bei 3/8 DoD = 37,5 % done; es übernimmt weder Einladung noch PortalUser-Setup und darf seine Host-/Session-Proofs erst gegen den korrigierten Auth-Vertrag abschließen.

RLS-Overlay-Korrektur 2026-07-18: Run #10519 hat im gemeinsamen Standalone-Overlay einen ungültigen token-Alias im E-Mail-Resolver aus VA-P26a gefunden. Die Korrektur stellt ausschließlich den bereits migrationsgebundenen invited-/active-Statusvertrag wieder her und ändert weder Standard-/Custom-Host-Auflösung noch Session-, Entitlement- oder Domain-Controller-Verträge. VA-P26c bleibt 3/8 DoD = 37,5 % done mit fünf externen/UAT-abhängigen Punkten.

Technischer Staging-Teilabschluss

2026-07-21 · Raffael: Katalog und kommerzielle Portal-Fixture liefen jeweils über Plan, Apply und Verify. Der Starter-Checkout über 19,99 EUR, das enthaltene Business-Entitlement und der getrennte Enterprise-Override wurden ohne Null-Euro-Checkout belegt. Genau eine erfolgreiche Lago-One-off- Rechnung ist operatorseitig audit-verknüpft; ihr Replay erzeugte kein Duplikat. Mollie-/Lago- Zustände, Refund-/Failure-Isolation und die lokalen Entitlements blieben konsistent.

Für p26-uat.saas-ctrl.com sind TXT- und CNAME-Nachweis, Controller-Ack, Let's Encrypt und der Custom-Host grün; der einmalige TXT-Wert wird nicht dokumentiert. Standardhost-Fallback, Domain-Entfernung, Reclaim-Cooldown und Deprovisionierung wurden live auf Staging geprüft. Der Firing→Resolved-Alert inklusive zugestellter Alarmmail ist belegt. Core, Portal und Controller akzeptieren die Merge-Revision a747e9c655b2be4bd9ba52e59f56d5f0e9d145b0; Core und Portal verwenden denselben Registry-Digest. Der erste Deploy-Versuch scheiterte vor Kandidatenstart an einem transienten Registry-Layer-Commit, der exakt einmal wiederholte Lauf war grün und löste keinen Controller-Rollback aus. Produktion blieb übersprungen.

Der zentrale Prometheus besaß bereits den exakt gelabelten Staging-Scrape für den Portal-Domain-Controller. Der am 2026-07-21 ausdrücklich freigegebene, rein lesende Zugriff auf control bestätigte Ziel up=1, Controller-Readiness 1, die exakte Merge-Revision und die Command-Metriken über die kanonische Grafana-Datenquelle. Es war keine Observability-Mutation nötig. Weder Hetzner-Account-Zugang noch Schlüssel- oder Passwortrotation wurden verwendet; vorhandene Schlüssel und Passwörter blieben unverändert.

Der Operator-Kill-Switch wurde danach exakt einmal über die bestehende Admin-Oberfläche angenommen und nicht wiederholt. Der read-only Nachaudit bestätigt genau eine Deprovision-Generation, den 30-tägigen Cooldown, einen Command mit Attempt 1, drei Audit-Ereignisse, zwei Activities, eine nach dem nullable-Creator-Vertrag erwartete Notification und einen um eins erhöhten Controller-Zähler deprovisioned; Retries und Failures blieben jeweils null. Tenant- und Plattform-Audit-Ketten sind bis zu ihren authentifizierten Heads verifiziert. Der Standardhost blieb gesund. Die exakte Custom-Host-Route wurde entfernt. HTTPS antwortet danach jedoch mit dem gemeinsamen Staging-Edge-Fallback 503 no available server statt mit dem in AD-30 und diesem Ticket festgelegten 404. Zwei nie konfigurierte Kontrollhosts am selben Edge liefern exakt denselben fail-closed Zustand. Der Kill-Switch darf dafür weder wiederholt noch zurückgeschaltet werden; nach einer engen 404-Korrektur ist nur ein read-only HTTP-Nachweis zulässig.

Zwischenstand: VA-P26c: 7/8 DoD = 87,5 % done · offen: Lifecycle/Betrieb, ausschließlich weil der deprovisionierte HTTPS-Host am gemeinsamen Staging-Fallback 503 statt des vertraglichen 404 liefert. VD-P26 bleibt 0/11 und offen; Produktion ist nicht freigegeben.

Finaler 404- und Betriebsabschluss

2026-07-21 · Raffael: PR #202 wurde nach grüner CI (11/11 Jobs) und Coverage (1/1 Job) als normaler Merge-Commit 61dcc2ba1d5410e492a27ea47aa9b4d0b93903d6 übernommen, ausdrücklich ohne Squash. Die zwei getrennten Code-Commits b2ea1d890 und eb139fdff halten nach Deprovisionierung einen exakten TLS-404-Tombstone, reconciliieren persistierte Routen vor dem Queue-Start und verlangen vor jedem Rollout einen revisionsgebundenen Controller-Drain. Die globale Config-Fence serialisiert Reconciliation und Runtime-Commands; Shutdown entfernt Health erst nach Queue- und Lock-Drainage.

Lokal bestanden Controller-Typecheck/-Build, 71 Tests bei einem plattformbedingten Skip, 50 Deploy-/Verifier-Tests, der statische Deploy-Vertrag 34/34, Root-Typecheck, Lint und 7.048 Core-Tests bei 55 vorgesehenen Integrations-Skips. Docker-Baseline 398/398, Non-root 4/4, der revisionsgebundene Controller-Image-Smoke und ein echter traefik:v3.6.16-Routing-Smoke waren grün. Der Traefik-Smoke belegte Tombstone 404, Legacy-Reclaim 200, neuen Reclaim 200 und unbekannten Fallback 503. Der read-only Live-Inventar-Nachweis auf control belegte zuvor die Prioritätsordnung -1000 < 28 < 29 < 1000001 für gemeinsamen Fallback, Tombstone, Legacy-Exact-Host und neuen aktiven Router.

Der automatische Staging-Deploy #10925 war auf der Merge-Revision vollständig grün. Build/Signatur, Migration, RLS, Core-/Portal-Health, abhängige Dienste und der neue 31-Sekunden-Drain bestanden. Der Controller akzeptierte den neuen Release; der Recovery-Pfad erkannte dies und rollte nicht zurück. Alle Produktionspfade meldeten explizit „skipped for staging".

Der anschließende Nachweis war ausschließlich lesend. Standardhost blieb 200; der deprovisionierte Custom-Host liefert über gültiges HTTPS auf /healthz und /login jetzt exakt 404. Die bereits ausgeführte Einmal-Aktion blieb unverändert bei einem Command/Attempt, drei Audits, zwei Activities und einer erwarteten Notification; 30-Tage-Cooldown, authentifizierte Tenant-/ Plattform-Audit-Ketten, Content-Hash-Verknüpfung sowie null Retries und null Failures blieben grün. Controller-Health und Prometheus waren revisionsgebunden ready/up; der neue Controller-Prozess hatte 0 Commands verarbeitet und löste damit keinen Replay aus. Der Kill-Switch wurde nicht wiederholt oder zurückgeschaltet. Es wurden keine Schlüssel oder Passwörter rotiert und keine Produktion verändert. Tokens, Empfänger, Mailinhalte, TXT-Wert und private Proof-IDs bleiben redigiert.

Abschlussstand: VA-P26c: 8/8 DoD = 100 % done. Der technische P26-Handoff an VJ-3 ist erfüllt. VD-P26 bleibt 0/11 als separater Design-Nachzug offen; eine Produktionsfreigabe ist nicht Teil dieses Abschlusses.

Pilot-UAT-Nachtrag: Tenant-Scaffold

2026-08-01 · Der vollständige Registrierungs-/Billing-UAT hat einen fehlenden Integrationsschritt außerhalb des abgeschlossenen Domain-Vertrags gezeigt: Der normale Tenant-Bootstrap erzeugte keinen unveröffentlichten Portal-Scaffold, während die Portal-Admin-Routen diesen vor dem Add-on-Kauf voraussetzen. Der eng begrenzte Nachzug läuft in BILL-15 / CR-010 und ergänzt Bootstrap plus Bestands-Backfill. Entitlement-, Preis-, Domain-, RLS- und Veröffentlichungsverträge dieses Tickets bleiben unverändert.

VA-P26c bleibt 8/8 = 100 % done; BILL-15 blockiert ausschließlich den Pilot-UAT für frisch registrierte Tenants.

Branding- und Staging-Nachtrag

2026-07-22 · Raffael: PR #212 ergänzt die bestehende Portalverwaltung um ein echtes Tenant-Logo. Ein Admin mit portal.admin kann PNG, JPEG oder WebP bis 5 MB hochladen, ansehen und entfernen. Vor der privaten tenant-isolierten Speicherung greifen Magic-Byte-Allowlist und fail-closed ClamAV-Scan; die Auslieferung nutzt kurzlebige signierte URLs. Das Branding gilt identisch auf Standard- und aktivem Custom-Host. Bei fehlendem oder nicht ladbarem Tenant-Logo erscheint automatisch das HiveGrid-Logo.

Staging-Deploy #11018 lief auf Main-Revision 090e2558a6965e1c5804eb24d3eab5da8c8611a8 vollständig grün. Core und Portal verwendeten denselben Web-Digest; alle abhängigen Dienste und der revisionsgebundene Domain-Controller waren gesund, der akzeptierte Kandidat wurde nicht zurückgerollt. Produktion, DNS-/Domain-Zustände, Schlüssel und Passwörter blieben unverändert. Details stehen in docs/features/customer-portal.md.

Der Nachtrag verändert keinen kommerziellen oder Domain-Lifecycle-Vertrag: VA-P26c bleibt 8/8 = 100 % done; VD-P26 bleibt offen.

Pilot-Readiness-Nachtrag: Coolify-Hard-Caps

2026-07-29 · Raffael: Der bestehende rein lesende Coolify-Runtime-Preflight prüft positive limits_cpus und ein positives, mit b/k/m/g suffigiertes limits_memory jetzt nicht nur für Core, Admin und Portal, sondern zusätzlich für API, MCP, Hocuspocus, alle fünf Worker-Gruppen und den privaten hivegrid-portal-domain-controller. Der Controller wird über seine bereits festgelegte exakte Coolify-Identität innerhalb der Resource-Allowlist gebunden; fehlende, mehrdeutige oder nicht allowlistete Controller sowie fehlende oder ungültige Hard-Caps brechen den Preflight vor Migration und Deploy fail-closed ab.

Proof ohne Live-Aufruf oder Deployment: pnpm exec vitest run scripts/coolify-deploy.test.mjs 83/83 Tests grün, darunter positive Zwölf-Runtime-Inventur und gruppierte Negativfälle für API/MCP/Hocuspocus, jeden Worker und den Domain-Controller; pnpm exec eslint scripts/coolify-deploy.mjs scripts/coolify-deploy.test.mjs --max-warnings=0 sowie git diff --check grün. Der Nachtrag verändert keinen Produkt-, Domain- oder Betriebs-DoD: VA-P26c bleibt 8/8 = 100 % done · 0 Punkte offen, 0 selbst machbar.

Was wir bauen

Den kommerziellen und hostseitigen Abschluss des Customer-Portals:

  1. Standardhost: https://portal.hivegrid.de/<tenant>/... (Staging: https://staging-portal.hivegrid.de/<tenant>/...).
  2. Portal-Entitlement: Starter/Team 19,99 EUR netto/Monat je Workspace, Business/Enterprise inklusive. PortalUser und zugeordnete Projekte sind unbegrenzt; Speicher, Uploads, Mailvolumen und weitere Ressourcen bleiben unter den Kontingenten/Fair-Use-Regeln des Basispakets.
  3. Custom-Domain-Entitlement: Starter/Team/Business 299,99 EUR netto einmalig pro Hostname/Einrichtung, Enterprise eine Domain inklusive. Aktive HiveGrid-Subscription und aktives Portal-Entitlement sind Voraussetzung.
  4. Self-Service: Workspace-Admin trägt z. B. portal.geerkens.de ein, weist die Domain per TXT nach, setzt einen CNAME auf domains.portal.hivegrid.de und sieht Verifikation, Provisioning und TLS-Status.
  5. Sicherer Betrieb: ein separater, minimal berechtigter Provisioner konfiguriert Traefik/Let's Encrypt und routet ausschließlich auf den von VA-P26a gelieferten hivegrid-portal-Service; Host-Tenant-Auflösung, Cookies, absolute Links, Monitoring, Fallback und Deprovisionierung sind gehärtet.

Der Custom-Host zeigt dieselben Endkundenpfade ohne Tenant-Slug, z. B. https://portal.geerkens.de/projects/42. Der Standardhost bleibt als Fallback erreichbar. Ein Domain-Wechsel ist eine neue 299,99-EUR-Einrichtung, sofern keine individuelle Enterprise-Vertragsregel greift. Nach Entfernung oder Wechsel bleibt der Host 30 Tage gegen die Zuordnung zu einem anderen Workspace gesperrt.

Benötigte Screens

Screen [Route] Kern-Inhalt
Workspace-Admin · Portal-Paket [app.hivegrid.de/{tenant}/settings/customer-portal] aktuelles Portal-Entitlement, inkludiert vs. 19,99-EUR-Add-on, Aktivieren/Kündigen, Payment-/Read-only-/Fehlerzustände, Hinweis auf unveränderte Ressourcenlimits
Workspace-Admin · Custom-Domain [app.hivegrid.de/{tenant}/settings/customer-portal/domain] Eligibility/299,99-EUR-Setup bzw. „inklusive", Hostname-Eingabe, TXT-/CNAME-Anleitung, DNS-Prüfung, Status-Timeline, aktiver Primärhost, Standardhost-Fallback, Entfernen/Wechseln
Endkunde · alle Portal-Screens [portal.hivegrid.de/{tenant}/... bzw. <verified-host>/...] identische Inhalte auf Standard- und Custom-Host; auf Custom-Host kein Tenant-Slug
Betreiber · bestehende Diagnoseflächen Portal-Domain-Events, DNS/TLS-Fehler, Jobs und Kill-Switch über bestehende Audit/Jobs/Health-Flächen; keine PortalUser-Impersonation und keine neue globale Support-Konsole

Definition of Done

  • Produkt-/Entitlement-Vertrag: Starter/Team als 19,99-EUR-Add-on, Business/Enterprise inklusive und Domain-Setup für Starter/Team/Business einmalig 299,99 EUR sind exakt gemäß AD-30 abgebildet; Lago/Mollie können wiederkehrendes Portal-Add-on und einmaliges Domain-Setup idempotent kaufen/aktivieren, Business/Enterprise erhalten Portalrechte ohne Null-Euro-Checkout und bleiben getrennte Entitlement-Pfade.
  • Standardhost: portal.hivegrid.de/<tenant>/... (plus Staging) löst den Tenant vor Auth sicher auf; unbekannte/reservierte/inaktive Slugs und Konflikte liefern 404; alte öffentliche app.hivegrid.de/portal/...-Links werden nicht als paralleler Vertrag weitergeführt.
  • Domain-Claim: exakt eine global eindeutige Subdomain pro berechtigtem Workspace durchläuft eine idempotente State-Machine mit zufälligem TXT-Ownership-Proof und CNAME-Prüfung auf domains.portal.hivegrid.de; Apex/Wildcard/Mehrfach-Domains werden abgelehnt.
  • TLS/Ingress-Provisioning: ein schmal berechtigter, auditierter Controller provisioniert/deprovisioniert Traefik + Let's Encrypt automatisch und routet exakte verifizierte Hosts nur auf hivegrid-portal; weder hivegrid-web noch hivegrid-portal besitzen Coolify-/Root-/SSH-Credentials oder allgemeine Ingress-Schreibberechtigung.
  • Host-/Session-Sicherheit: verifizierter Host wird vor Session-Auflösung eindeutig einem Tenant zugeordnet, unbekannte/unbestätigte/deaktivierte Hosts liefern 404, __Host-*-Portal-Cookies sind hostgebunden und auf dem Standardhost zusätzlich tenantgebunden, absolute Mail-/Magic-Link-URLs kommen aus der gespeicherten aktiven Origin und nie blind aus Host.
  • Workspace-Admin-Self-Service: Entitlement-/Checkout-, DNS-, Provisioning-, Aktiv-/Fehler-, Fallback-, Entfernen- und Wechselzustände sind als VM + Action-Callbacks umgesetzt; Klartext erklärt exakt, was der Admin im DNS tun muss und wann eine neue Einrichtungsgebühr anfällt.
  • Lifecycle/Betrieb: Standardhost bleibt Fallback; Entitlement-Verlust, Domain-Entfernung oder Wechsel deaktivieren den Custom-Host sicher; DNS/TLS-Revalidierung, Monitoring/Alerts, Retry/Idempotenz, 30-tägiger Reclaim-Cooldown gegen Domain-Takeover und Operator-Kill-Switch sind vorhanden und auditiert.
  • Querschnitt + Tests: additive Claim-/Current-Domain-Modelle im von VA-P26a recutteten portals.prisma nach AD-21, RLS-Policy, Permissions, Audit/Activity/Notifications, i18n/Klartext, Unit-/Integration-/Security-Tests, E2E-Smoke für Standard- und Custom-Host gegen hivegrid-portal, Deploy-/Health-Proof beider Web-Ressourcen, Hot-Swap und Visual-Regression (Interim-Baseline bis VD-P26) sind grün.

Technische Bausteine

  • Entitlements/Katalog: zwei getrennte Feature-Gates (Arbeitsnamen customer_portal, customer_portal_custom_domain) in packages/entitlements; starter und pro/Team erhalten bezahlte Portal-Add-on-Freischaltung, business das Portal inklusive und die Domain als einmalige Position, Enterprise Portal plus eine Domain über einen eigenen vertraglichen Override.
  • Billing: portalspezifische Lago-Produkt-/Fee-Codes und Mollie-Zahlungsstart auf dem generischen VA-P24a-Vertrag. Kein Usage-Metering, keine zweite PortalSubscription-Billingwelt.
  • Datenmodell: zwei getrennte Modelle in prisma/schema/portals.prisma: der global eindeutige PortalDomainHostnameClaim mit Token-Hash, DNS-Status, Generation und 30-Tage-Cooldown sowie genau eine aktuelle PortalCustomDomain je Portal mit Zustand, aktiver Origin, TLS-/Provisioning-, Retry- und Revalidierungsdaten. Beide sind tenantgebunden und auf den in VA-P26a recutteten Portal-Kern ausgerichtet; ein freies Domain-Feld zählt nicht.
  • Host-Routing: Normalisierung/IDNA-Validierung, explizite Allow-/Deny-Regeln, Host→Tenant-Resolver mit RLS-sicherem Pre-Auth-Pfad; Standardhost und aktive Custom-Hosts werden intern auf dieselben Portal- Routes abgebildet. hivegrid_portal_resolve_custom_hostname_health ist eine getrennte, schmale /healthz-Capability für den Controller-Ack während provisioning; sie akzeptiert nur verifizierten DNS-/Entitlement-/Payment-State mit persistiertem Controller-Command und öffnet keine Inhaltsroute.
  • Provisioner: apps/portal-domain-controller als Queue-/Outbox-gesteuerter Domain-Controller mit eng begrenztem Schreibziel für Traefik Dynamic Config und ACME/TLS; atomare Config-Updates, exaktes Routing ausschließlich auf hivegrid-portal, Healthcheck vor active, Rollback auf Fallback. Der Controller bleibt ein dritter, nicht öffentlich erreichbarer Prozess und ist weder Teil von hivegrid-web noch hivegrid-portal.
  • Security: keine Host-Header-Vertrauensannahme, keine Domain-Übernahme nach CNAME-Dangling, keine Cross-Tenant-Cookies, kein offenes On-Demand-TLS für beliebige Hosts, Rate-Limits auf Verify/Retry.
  • UI-Layer: Route/Action baut VM; Screen in packages/ui-app erhält nur VM + Actions. Interim-UI aus ~/ui, finaler Adapter-Nachzug aus VD-P26; kein rekursiver App-Shell-/Sidebar-Import im Screen.

Nicht im Scope

  • Apex-Domain (geerkens.de), Wildcard (*.geerkens.de) oder mehrere aktive Domains pro Workspace
  • vollständiges App-White-Label (crm.geerkens.de), eigene Fonts, freies Theme/HTML-Mailtemplates, Entfernung sämtlicher HiveGrid-Hinweise
  • automatischer Schreibzugriff auf den DNS-Provider des Kunden
  • eigener Server/Deploy pro Tenant
  • eigenes apps/portal, eigenes Portal-Image oder eigene Portal-VM im ersten Schnitt
  • globale Portal-Support-Konsole oder PortalUser-Impersonation
  • PortalSubscription als eigenes Billing-System oder verbrauchsabhängiges Portal-/Domain-Metering

Quellen (granular)

  • docs/ARCHITECTURE-DECISIONS.md → AD-30
  • docs/CHANGE-REQUESTS.md → CR-001
  • docs/INTEGRATION-CONTRACTS.md → §3 und §14
  • docs/pricing-draft.md → Add-on Customer-Portal
  • .planning/ROADMAP-V2.md → v2-P3 und v2-P6
  • .planning/REQUIREMENTS.md → REQ-portal-runtime-isolation (geerbte Grundlage), REQ-portal-commercial-access, REQ-portal-custom-domain
  • .planning/designer-briefs/P26-customer-portal.md
  • Querverweise: VA-P26a, VA-P24a, VD-P26, VD-P24, VJ-3

Dev-Nachzug (nach Davids VD-P26-Delta)

Interim-UI (Vorschau, Stand 2026-07-16): Domain-Self-Service aus ~/ui in apps/web/app/components/screens/customer-portal/PortalDomainAdminInterimPage.tsx; die markierte Interim-Baseline liegt unter packages/ui-mock/visual-baseline/va-p26c-customer-portal-domain-interim.snapshot.json. Proof: 22/22 lokale AD-28-Prüfungen und eine Component-Reise; zwei Browser-E2E-Reisen sind für Staging registriert, nicht live ausgeführt. Refactor-Nachzug: finale Subframe-Optik aus VD-P26 und Re-Baseline.

  • Domain-/Paywall-Screen gegen Davids Delta integriert und Interim-Baseline neu gezogen
  • Bestätigtes Business-/Enterprise-Mapping in Entitlement-Code und interner Preis-/Ticket-Dokumentation synchronisiert (355eead8e)
  • Öffentliche Website-/Marketing-Veröffentlichung nach vollständigem P26b/P26c-Gate über VJ-3 nachgezogen
  • Ticket-Abschluss-Audit gegen alle 8 DoD-Punkte durchgeführt
  • Plane-Ticket VA-P26c mit 3/8-Stand und den fünf offenen externen Gates aktualisiert (b25d426d-83b8-40e8-85dc-f6ef6b50e7c5, 2026-07-16); Status bleibt Backlog
  • Plane-Ticket um den Standardhost-/Migration-/Health-Teilnachweis aus Deploy #10300 ergänzt (78ccb0ab-1780-4607-884c-952498bff35f, 2026-07-16); Stand bleibt 3/8 und Status Backlog
  • Abschlussdokumentation für PR #202, Deploy #10925 und den read-only 404-/Replay-Nachweis vorbereitet; finaler Stand 8/8 DoD = 100 % done, Plane-Handoff auf Done folgt in der vorgeschriebenen Reihenfolge nach Merge dieser Dokumentation

Abhängigkeitsnachzug · CR-007 · 2026-07-27

Das globale Portal-Rollout-Flag entfällt. Kommerzielle Portal-/Custom-Domain-Entitlements, der Domain-Kill-Switch und der verifizierte Host-/TLS-Lifecycle bleiben unverändert.