353 lines
27 KiB
Markdown
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.
|