Refresh HiveGrid Cloud reference snapshot
This commit is contained in:
1 parent
5e99e14772
commit
7f88026f79
5955 files changed
+1177325
-188362
No files matched your search
@@ -4,7 +4,7 @@
|
||||
|
||||
Diese Datei ist Quelle der Wahrheit für: Sidebar-Gruppen, Route-Patterns, Breadcrumbs, Permissions, Search-Index, Activity-Stream, Audit, i18n.
|
||||
|
||||
> **Naming-/Pfad-Realität (Stand 2026-06-04, siehe `docs/ARCHITECTURE-DECISIONS.md` AD-10):**
|
||||
> **Naming-/Pfad-Realität (siehe `AGENTS.md` §Naming-Konvention; Entscheidungs-ID AD-10):**
|
||||
> Das HiveGrid-UI-Paket heißt real **`packages/ui-app`** (nicht `packages/ui-hivegrid`). Die
|
||||
> Sidebar-Konfiguration liegt in **`apps/web/app/application/sidebar/`** (nicht `sidebar.config.ts`).
|
||||
> Der Such-Index / `indexedEntities` gehört nach **`packages/search/`** (nicht
|
||||
@@ -103,7 +103,8 @@ Verbindliche URL-Schemata. Abweichungen erfordern Change-Request.
|
||||
| Mandanten-App | `app.hivegrid.de/<modul>/...` | `app.hivegrid.de/sales/D-2026-0042` |
|
||||
| Mandant-Settings | `app.hivegrid.de/settings/<modul>/...` | `app.hivegrid.de/settings/integrationen/kwp` |
|
||||
| Plattform-Admin | `admin.hivegrid.de/<bereich>/...` | `admin.hivegrid.de/mandanten/123` |
|
||||
| Customer-Portal | `app.hivegrid.de/portal/<tenant>/...` | `app.hivegrid.de/portal/geerkens/projekte/42` |
|
||||
| Customer-Portal (Standard) | `portal.hivegrid.de/<tenant>/...` | `portal.hivegrid.de/geerkens/projekte/42` |
|
||||
| Customer-Portal (verifizierte Custom-Domain) | `<portal-host>/...` | `portal.geerkens.de/projekte/42` |
|
||||
| Public-Forms | `app.hivegrid.de/f/<tenant>/<slug>` | `app.hivegrid.de/f/geerkens/kontaktformular` |
|
||||
| Public-Booking | `app.hivegrid.de/b/<tenant>/<slug>` | `app.hivegrid.de/b/geerkens/wartungstermin` |
|
||||
| Public-Help | `app.hivegrid.de/help/<lang>/<kategorie>/<slug>` | `app.hivegrid.de/help/de/integrationen/kwp-setup` |
|
||||
@@ -113,14 +114,21 @@ Verbindliche URL-Schemata. Abweichungen erfordern Change-Request.
|
||||
|
||||
Die Tenant-Slug ist **nicht** im Pfad bei der Mandanten-App — Tenant kommt aus Subdomain oder Session.
|
||||
|
||||
**Customer-Portal (AD-30):** Auf dem Standardhost bleibt der Tenant-Slug Pflicht. Auf einer verifizierten
|
||||
Custom-Domain steht er nicht im Pfad; der Tenant kommt dort ausschließlich aus der global eindeutigen,
|
||||
aktiven Host-Zuordnung. Unbekannte, noch nicht verifizierte oder deaktivierte Portal-Hosts liefern 404.
|
||||
Staging verwendet `staging-portal.hivegrid.de/<tenant>/...`. Eine interne Route darf weiter auf einen
|
||||
normalisierten Portal-Namespace abbilden, aber die öffentliche kanonische URL folgt immer dieser Tabelle.
|
||||
|
||||
**Public API und MCP:** Public API läuft ausschließlich auf `api.hivegrid.de` (staging: `staging-api.hivegrid.de`)
|
||||
und nutzt das Versionspraefix `/v1/...`. Es gibt keine Public-API-Routen unter `app.hivegrid.de/api`.
|
||||
Der MCP-Server läuft ausschließlich auf `mcp.hivegrid.de` (staging: `staging-mcp.hivegrid.de`) als separater
|
||||
Service/Container (`hivegrid-mcp`), ohne zusätzlichen `/mcp`-Pfad und nicht im Web- oder Public-API-Service.
|
||||
|
||||
**Externe OAuth-Connectors (Google-Kalender, KWP, später AirCall/Microsoft/…):** Der Redirect-/Callback-Endpoint
|
||||
liegt **immer** auf `app.` (nicht `api.`) unter `/integrations/<provider>/oauth/callback` — konsistent zu den
|
||||
Connector-Settings-Screens (`/settings/integrations/<modul>`, `/integrations/<provider>/…`). Begründung: Der
|
||||
liegt **immer** auf `app.` (nicht `api.`) unter `/integrations/<provider>/oauth/callback`. Die verwaltenden
|
||||
Connector-Screens liegen davon getrennt unter `/settings/integrations/<modul>` bzw. der generische Katalog unter
|
||||
`/settings/integrations`. Begründung: Der
|
||||
OAuth-Rückweg ist browser-basiert und braucht die an `app.` gebundene Nutzer-Session, um den Token dem richtigen
|
||||
Nutzer/Tenant zuzuordnen; `api.hivegrid.de` (token-basiert, ohne Session) ist dafür nicht geeignet. Tenant wird
|
||||
im OAuth-`state` mitgeführt (eine feste Callback-URL je Umgebung, kein Tenant im Pfad). Pro Umgebung registriert:
|
||||
@@ -243,4 +251,57 @@ Neue Funktionen, die in der Mobile-App relevant sind, müssen in `packages/ui-hi
|
||||
|
||||
## 14. Customer-Portal-Wiring (M142, M143)
|
||||
|
||||
Funktionen, die Endkunden sehen sollen, müssen explizit in `packages/ui-hivegrid/src/customer-portal/portal-shell.config.ts` registriert sein. Default-Sichtbarkeit: **NICHT sichtbar**. Tenant-Admin gibt explizit frei (M142.5).
|
||||
Funktionen, die Endkunden sehen sollen, müssen explizit in
|
||||
`packages/ui-app/src/customer-portal/portal-shell.config.ts` registriert sein. Default-Sichtbarkeit:
|
||||
**NICHT sichtbar**. Tenant-Admin gibt Projekte, Stages und Dokumente explizit frei (M142.5).
|
||||
|
||||
**Runtime-/Trust-Boundary (AD-30):** Öffentliche Portalrequests laufen über einen eigenen Coolify-Service
|
||||
und Container `hivegrid-portal`. Im ersten Schnitt verwenden `hivegrid-web` und `hivegrid-portal` dasselbe
|
||||
immutable `hivegrid/web:<sha>`-Image, aber getrennte Runtime-Modi, Secrets, Sessions, Ressourcenlimits und
|
||||
DB-Logins. `WEB_RUNTIME_SURFACE=core|portal` ist in Produktion Pflicht und bei fehlender, ungültiger oder
|
||||
zur Resource unpassender Konfiguration ein Boot-Fehler. Die Trennung erfolgt vor Static-Asset-Serving und
|
||||
React Router und ist fail-closed:
|
||||
|
||||
| Resource | Erlaubt | Muss 404 liefern |
|
||||
|---|---|---|
|
||||
| `hivegrid-web` | App-/Admin-/Root-Hosts sowie Workspace-Admin-Konfiguration unter `app.hivegrid.de/settings/customer-portal/...` | Standard- und Custom-Portalhosts |
|
||||
| `hivegrid-portal` | `portal.hivegrid.de`, Staging-Portalhost, aktive verifizierte Custom-Hosts, Portalroutes, Assets und Health | App-, Admin-, API-, Root- und interne Routen |
|
||||
|
||||
`hivegrid-portal` verwendet den dedizierten DB-Login `hivegrid_portal` mit minimalen Grants und
|
||||
PortalUser-/Projektzugriffs-RLS. Ein zweiter Container mit dem breiten `hivegrid_app`-Login erfüllt diesen
|
||||
Trust-Boundary-Vertrag nicht. Ein eigenes `apps/portal`, ein eigenes Portal-Image, eine eigene VM oder ein
|
||||
Deployment pro Tenant sind im ersten Schnitt nicht vorgesehen.
|
||||
|
||||
Vor dem React-Router-Dispatch normalisiert die Portal-Runtime beide öffentlichen URL-Formen auf einen
|
||||
reservierten, nur intern dispatchbaren Portal-Namespace (Arbeitsvertrag
|
||||
`/__portal/<resolved-tenant>/...`). Beim Standardhost stammt der Tenant aus dem validierten ersten
|
||||
Pfadsegment, beim Custom-Host ausschließlich aus der aktiven Host-Zuordnung. Direkte öffentliche Requests
|
||||
auf den internen Namespace sowie Portalpfade auf `hivegrid-web` liefern 404; dadurch kann keine bestehende
|
||||
TenantUser-/Admin-Route versehentlich einen Portalrequest übernehmen.
|
||||
|
||||
### 14.1 Host- und Tenant-Auflösung (AD-30)
|
||||
|
||||
- `portal.hivegrid.de/<tenant>/...` und `staging-portal.hivegrid.de/<tenant>/...` lösen den Tenant aus dem
|
||||
ersten Pfadsegment auf; Reserved-Words und Tenant-Existenz werden vor Auth geprüft.
|
||||
- Ein Custom-Host löst den Tenant ausschließlich über eine aktive, verifizierte Domain-Zuordnung auf. Ein
|
||||
Tenant-Slug im Pfad ist dort weder nötig noch als Override zulässig.
|
||||
- Bei Konflikt zwischen Pfad, Session und Host wird geschlossen abgebrochen. Ein Request darf niemals über
|
||||
einen vom Client gelieferten Hostnamen den Tenant wechseln.
|
||||
- Jede Portal-Session nutzt ein hostgebundenes `__Host-*`-Cookie. Auf dem geteilten Standardhost bleibt die
|
||||
Session zusätzlich unveränderlich an den Tenant gebunden; ein anderes Pfadsegment darf sie nicht umhängen.
|
||||
App-, Admin- und Portal-Cookies werden nicht geteilt; Sitzungen auf Standard- und Custom-Host sind ebenfalls
|
||||
hostgetrennt.
|
||||
|
||||
### 14.2 Custom-Domain-Lifecycle (VA-P26c)
|
||||
|
||||
1. Nur ein Workspace-Admin mit Portal- und Domain-Entitlement kann einen exakten Subdomain-Host anlegen.
|
||||
2. Der Host durchläuft `pending_dns → verified → provisioning → active`; Fehler und Deaktivierung sind
|
||||
explizite Zustände. Global eindeutige Hostnamen und idempotente Übergänge sind Pflicht.
|
||||
3. Ownership-Proof erfolgt per zufälligem TXT-Token; der Traffic-CNAME zeigt auf
|
||||
`domains.portal.hivegrid.de`. Erst danach provisioniert der getrennte Controller Traefik + TLS und
|
||||
routet den exakten Host ausschließlich auf `hivegrid-portal`.
|
||||
4. Absolute Links in Einladungen, Magic-Links und Status-Mails stammen aus der gespeicherten aktiven
|
||||
Portal-Origin. Der Standardhost bleibt als sichere Fallback-Origin verfügbar.
|
||||
5. DNS/TLS-Monitoring, Revalidierung, Deprovisionierung, ein 30-tägiger Reclaim-Cooldown und
|
||||
Operator-Kill-Switch gehören zum Lifecycle. Apex-Domains, Wildcards und mehrere parallele Domains sind
|
||||
nicht Teil des ersten Vertrags.
|
||||
Reference in new issue
Block a user