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

353 lines
27 KiB
Markdown

# 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`](https://git.tool-ctrl.de/toolctrl-labs/HiveGrid-Cloud/actions/runs/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`](https://git.tool-ctrl.de/toolctrl-labs/HiveGrid-Cloud/actions/runs/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`](../../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
- [x] **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.
- [x] **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.
- [x] **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.
- [x] **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.
- [x] **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`.
- [x] **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.
- [x] **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.
- [x] **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
- [x] 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
- [x] Ticket-Abschluss-Audit gegen alle 8 DoD-Punkte durchgeführt
- [x] 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
- [x] 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
- [x] 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.