Gitea läuft seit 2026-11-11 auf hivegrid-control (git.hg-int.dev); git.tool-ctrl.de wird abgeschaltet. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
7.8 KiB
Customer-Portal: aktueller Produkt- und UX-Stand
- Stand: 2026-07-22
- Technische Tickets:
VA-P26a,VA-P26b,VA-P26cjeweils 100 % - Design-Nachzug:
VD-P26bleibt offen - Staging:
https://staging-portal.hivegrid.de - Tenant-Administration:
https://staging-app.hivegrid.de/<tenant>/settings/customer-portal
Dieses Dokument beschreibt das aktuell ausgelieferte Customer-Portal aus Sicht von Workspace-Admins
und externen PortalUsern. Der Betriebs-, Secret- und Rollout-Vertrag steht separat in
docs/deploy/customer-portal.md.
1. Produktgrenze
Das Customer-Portal ist eine eigene, extern sichtbare Oberfläche. PortalUser sind strikt von internen HiveGrid-Nutzern getrennt und erhalten nur Zugriff auf ausdrücklich zugewiesene Projekte, sichtbare Projektphasen und freigegebene Dokumente. Fehlende Berechtigungen, fremde Projekte und unbekannte Hosts liefern 404, damit keine Existenz fremder Daten offengelegt wird.
Core und Portal laufen als getrennte Runtime-Ressourcen aus demselben unveränderlichen Web-Image. Das Portal besitzt eigene Sessions, eine minimal berechtigte Datenbankrolle und keine internen Admin-, OAuth-, Billing- oder Ingress-Zugangsdaten.
2. Endkunden-Navigation und Hauptreisen
Die Portaloberfläche verwendet dieselbe HiveGrid-Shell wie die SaaS: gleich große Wortmarke, einklappbare Sidebar, Sidebar-Inset, Breadcrumbs, Seitenkopf, Avatar und mobile Navigation. Die Hauptnavigation ist vollständig klickbar und bewusst auf wenige Ziele reduziert:
- Übersicht: eigene Projekte, aktueller Status und sinnvolle nächste Aktionen.
- Projekte: Liste der freigegebenen Projekte mit Fortschritt und letztem Update.
- Projekt: kompakte Detailansicht mit den Bereichen Übersicht, Dateien und Anliegen.
- Upload: projektbezogener Multi-Datei-Upload mit den konfigurierten Anzahl- und Größenlimits.
- Einstellungen: Benachrichtigungen, Profildaten, DSGVO-Export und Kontolöschung; der Einstieg liegt getrennt von den Arbeitszielen unten in der Sidebar.
Projektstatus wird als verständliche Abfolge sichtbarer Phasen dargestellt. Freigegebene Dateien können heruntergeladen werden. PortalUser können Dateien hochladen und Anliegen beziehungsweise Reklamationen melden, sofern ihr Projektzugang dies erlaubt. Ein eingefrorener Workspace bleibt lesbar, verhindert aber Schreibaktionen mit einem Klartext-Hinweis.
3. Zugang und Einladungen
Ein berechtigter Workspace-Admin kann PortalUser aus drei fachlichen Einstiegen einladen:
- aus der Customer-Portal-Verwaltung,
- aus einem Kontakt,
- aus einem Projekt; dabei wird der Projektzugang atomar vergeben.
Die Einladung verwendet einen einmaligen, gehashten Setup-Token mit sieben Tagen Laufzeit. Nach Datenschutzannahme und optionaler Passwortvergabe entsteht eine eigene Portal-Session. Magic-Link ist der primäre Login-Pfad, Passwort der sekundäre. Replays, fremde Tenant-/Projektzuordnungen und doppelte Einladungszustände werden fail-closed abgewiesen.
4. Tenant-Administration
Die zentrale Verwaltung liegt unter /<tenant>/settings/customer-portal. Sichtbarkeit und Aktionen werden
über portal.read, portal.manage_users, portal.manage_access, portal.activity.*,
portal.delete_user und portal.admin begrenzt.
Je nach Berechtigung kann der Workspace-Admin:
- Portal veröffentlichen oder einfrieren und den Lifecycle konfigurieren,
- erlaubte Projekttypen, sichtbare Phasen und kundenseitige Phasenbezeichnungen festlegen,
- Dokument-Auto-Freigaben und Upload-Limits verwalten,
- Statusmails sowie Impressum-, Datenschutz- und AGB-Links konfigurieren,
- Kunden und Subunternehmer einladen, erneut einladen oder deaktivieren,
- projektbezogene Zugriffe, Upload-Rechte, Laufzeiten und sichtbare Inhalte festlegen,
- Portalaktivitäten in der Service-Inbox bearbeiten,
- Portal-Paket und optional eine Custom-Domain verwalten.
5. Tenant-Logo und Fallback
Ein Workspace-Admin mit portal.admin kann in den Portal-Einstellungen ein eigenes Portal-Logo
hochladen, direkt als Vorschau prüfen und wieder entfernen.
- akzeptierte Formate: PNG, JPEG und WebP,
- maximale Größe: 5 MB,
- Prüfung: restriktive Bildsignatur und verpflichtender ClamAV-Scan vor Speicherung,
- Speicherung: privates, tenant-isoliertes Objekt mit deterministischem Schlüssel,
- Auslieferung: kurzlebige, serverseitig signierte URL; kein öffentlicher Bucket,
- Cache-/Leak-Schutz:
private, no-store,no-referrerundnosniff, - Fallback: fehlt das Tenant-Logo oder kann es nicht geladen werden, erscheint automatisch die normale HiveGrid-Wortmarke; in der eingeklappten Sidebar erscheint das HiveGrid-Signet.
Dasselbe Branding gilt auf dem Standardhost und auf einer aktivierten Custom-Domain. Es gibt aktuell kein frei konfigurierbares Theme, keine eigenen Fonts und kein vollständiges White-Labeling.
6. Hosts und Custom-Domain
Der Standardhost ist immer der Fallback:
- Staging:
https://staging-portal.hivegrid.de/<tenant>/... - Produktion:
https://portal.hivegrid.de/<tenant>/...
Auf einer verifizierten Custom-Domain entfallen Tenant-Slug und HiveGrid-Standardhost aus der sichtbaren URL; die fachlichen Seiten und das Tenant-Branding bleiben identisch. Workspace-Admins erhalten TXT-/CNAME- Anleitung, Status und Fehlerhilfe. Der Domain-Controller provisioniert ausschließlich exakte, verifizierte Hosts inklusive TLS. Entfernung, Entitlement-Verlust und Kill-Switch deaktivieren den Host; ein 30-tägiger Reclaim-Cooldown verhindert eine schnelle Fremdübernahme.
7. Bewusste UX-Entscheidungen des Rescue-Stands
Der UI-Nachzug aus PR #212 reduziert visuelle Konkurrenz und richtet das Portal an der bestehenden
HiveGrid-SaaS aus:
- keine doppelte Kopf- und Hauptnavigation,
- Einstellungen getrennt von den täglichen Arbeitszielen,
- weniger Dashboard-Karten und Wiederholungen,
- Projektfortschritt und Tabs ohne Überlagerungen oder übergroße Leerflächen,
- kompakter Datei-Upload mit klarer Auswahl, Aktion und Upload-Historie,
- konsistente Abstände, Typografie, Status-Badges, Empty-/Loading-/Fehlerzustände und mobile Breakpoints.
Die lokale Demo-Route dient ausschließlich der visuellen Entwicklung und ist im Production-Build nicht
registriert. Der aktuelle Screen bleibt formal die verbesserte AD-28-Interim-UI. VD-P26 bleibt deshalb als
finaler Subframe-/Design-Polish offen; der technische Funktionsumfang von VA-P26a/b/c bleibt abgeschlossen.
8. Release-Nachweis
- UI-/Branding-PR:
#212 - Main-Revision:
090e2558a6965e1c5804eb24d3eab5da8c8611a8 - Staging-Deploy:
#11018 - CI: 13/13 PR-Jobs grün; Typecheck, Lint, Core-Tests, Visual-, A11y-, i18n-, Hot-Swap-, Bundle- und Docker-Gates grün.
- Core und Portal verwenden denselben Web-Digest
sha256:064bd20e3e1694a1162198f772406b1aea10e3f7f7b73f877b6e4f0246c041e1. staging-app.hivegrid.deundstaging-portal.hivegrid.delieferten nach dem Rollout auf/healthzund/readyzHTTP 200 mit der exakten Main-Revision. Der Domain-Controller akzeptierte den Release; der Recovery-Pfad führte keinen Rollback aus.- Produktion, Plane-Tickets, DNS-Zustände, Schlüssel und Passwörter wurden durch diesen UI-Release nicht verändert.
9. Maßgebliche Codepfade
- Portal-Shell und Screens:
apps/web/app/components/screens/customer-portal/ - Portal-Routen:
apps/web/app/routes/customer-portal/ - Tenant-Verwaltung:
apps/web/app/routes/app.$tenant/settings/customer-portal.tsx - Branding-Service:
apps/web/app/services/customer-portal/portal-branding.server.ts - Portal-Domain-Controller:
apps/portal-domain-controller/ - View-Models:
packages/view-models/src/customer-portal/ - Visual-Baselines:
packages/ui-mock/visual-baseline/va-p26*-customer-portal-*