481 lines
44 KiB
Markdown
481 lines
44 KiB
Markdown
# VA-P26a · P26 Customer-Portal: Auth/Magic-Link + Projekt-Sicht + Status-Mails ⭐
|
||
|
||
| | |
|
||
|---|---|
|
||
| **Typ** | Dev (Code) |
|
||
| **Owner** | Akeshan |
|
||
| **Phase** | P26 — Customer-Portal · v2-P6 *(ex-P18)* |
|
||
| **Cycle/Fenster** | retimiert: 2026-07-16 bis 2026-08-05 |
|
||
| **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:** `AK-P4a` (FileEntityLink — Doc-Freigabe + Portal-Uploads), `R-P6`
|
||
(CRM) und `R-P9a` (Projekt — Project-Stages/Stage-Trigger) wurden vollständig konsumiert; daraus
|
||
besteht kein offener Block mehr.
|
||
- **CI-Proof freigegeben durch:** `CI-05`; der ref-übergreifend parallel-sichere Docker-Smoke mit echten
|
||
SHA-Tags, wirksamen Timeouts und verwertbarer Fehlerdiagnostik ist in Gitea-Lauf `10574`, Job
|
||
`44135`, vollständig grün. Die fachlichen Staging-/UAT-Gates dieses Tickets bleiben davon
|
||
getrennt.
|
||
- **Erfüllte Handoffs:** `VA-P26b` (Upload/Reklamation/Skalierung) und `VA-P26c`
|
||
(Paket-Gates/Custom-Domain) bauen auf der am 2026-07-21 vollständig abgenommenen Portal-Auth-,
|
||
Host- und Projekt-Schicht auf; daraus besteht kein offener technischer Block mehr.
|
||
- **Läuft parallel zu:** anfangs Raffaels disjunktem KWP-Strang und danach weiterer disjunkter Carry-over-Arbeit. Das bestehende Modul-Schema `prisma/schema/portals.prisma` wird bewusst auf das Customer-Portal recuttet (AD-21); **kein zweites `Portal`-/`PortalUser`-Modell**. `crm.prisma`/`project.prisma`/`files.prisma` nur über minimale FK-Nachzüge.
|
||
- **Konflikt-Risiko:** hoch — **eigene Auth-Schicht** parallel zum TenantUser-Auth (NICHT geteilt) plus neuer Runtime-/DB-Trust-Boundary. Der zusätzliche Security-/Deploy-Slice ist deshalb auf den 16.07.–05.08.2026 retimiert; lokale P26b-Vorarbeit ist isoliert zulässig, formaler Handoff und Aktivierung beginnen erst nach diesem Gate.
|
||
|
||
## Übernahme- und Start-Notiz
|
||
|
||
2026-07-15 · Raffael: Die Umsetzung startet nach ausdrücklicher Freigabe im isolierten Worktree
|
||
`HiveGrid-Cloud-va-p26-customer-portal` auf Branch `feat/va-p26a-customer-portal`. Die Plane-Zuweisung an
|
||
Akeshan bleibt unverändert; der operative Branch wird von Raffael geführt. `AK-P4a`, `R-P6` und `R-P9a`
|
||
sind abgeschlossen. `VA-P26b` und `VA-P26c` wurden in beide Abhängigkeitsrichtungen geprüft. Ihre lokale
|
||
Vorarbeit läuft auf demselben Branch, der formale Handoff bleibt jedoch bis zum stabilen
|
||
Auth-/Runtime-/RLS-Vertrag blockiert.
|
||
|
||
**Reterminierung:** 16.07.2026 bis 05.08.2026. Der bisherige Zwei-Tage-Slot wurde wegen des durch AD-30
|
||
hinzugekommenen Runtime-, Deploy- und Live-RLS-Security-Slices ersetzt.
|
||
|
||
**Preflight:** Workspace-Struktur und EU-Import-Check grün; Node 24.18.0; `pnpm typecheck` grün;
|
||
`pnpm test` grün (803 Testdateien bestanden, 9 übersprungen; 5.444 Tests bestanden, 53 übersprungen).
|
||
|
||
**Startstand:** VA-P26a: 0/7 DoD = 0 % done · 7 Punkte selbst machbar; Live-Coolify-/Postgres-Proof ist
|
||
für den Abschluss extern auszuführen, aber kein lokaler Implementierungsblocker.
|
||
|
||
## Umsetzungs-Notiz
|
||
|
||
2026-07-15 · Raffael: Die lokale Implementierung liegt in Commit `82c41df34`
|
||
(`feat(customer-portal): add isolated portal runtime`). Umgesetzt sind die physisch getrennten
|
||
Core-/Portal-Builds aus demselben Web-Image, der fail-closed Host-/Surface-Dispatch vor Assets und
|
||
React Router, die eigene Portal-Identitäts-, Session-, Token- und RLS-Welt, Magic-Link/optionales
|
||
Passwort, Projekt-/Stage-/Dokumentsicht, der Status-Mail-Worker, der Admin-Template-Editor sowie die
|
||
AD-28-Interim-UI mit VM-, Hot-Swap-, Smoke- und Visual-Proof. Der fachfremde Legacy-Portal-Commerce-
|
||
Pfad wurde nach Konsumenten-Audit recuttet; auf dem Feature-Branch wurde gemäß AD-21 keine Migration
|
||
angelegt.
|
||
|
||
**Proof:** `pnpm typecheck`, DB-/Worker-Typecheck und `pnpm lint` grün. `pnpm test`: 829 Testdateien
|
||
bestanden, 9 übersprungen; 5.632 Tests bestanden, 53 übersprungen. Alle Package-Suiten grün; Worker:
|
||
98 Testdateien und 1.111 Tests bestanden, 5 übersprungen. Prisma valide; Tenant-Policy-Vertrag
|
||
266/266. Live-RLS: 39 Core-/App-Worker-, 14 Portal- und 7 Bootstrap-Tests grün. Dual-Build und
|
||
Surface-Verifier: 354 Core-Routen, exakt 11 Portal-Routen und keine gegenseitigen Route-, Server-,
|
||
Client- oder Public-Asset-Leaks; Runtime-Closure: 89 Imports/92 Dependencies. UI-Visual-Vertrag:
|
||
86 Prüfungen grün; Hot-Swap 1/1 und Playwright-Component-Pixeltest 1/1 grün. Gitea-CI-Vertrag
|
||
154/154, Deploy-Vertrag 189/189, Docker-Baseline 291/291, Non-Root 3/3, CI-Baseline 35/35,
|
||
Source-Health 17/17, Permission-Matrix 22/22 und Route-Inventar 5/5 grün. EU-Provider-Importcheck und
|
||
`git diff --check` grün. `verify:migrations-parity` endet erwartungsgemäß ausschließlich wegen der
|
||
nach AD-21 noch fehlenden Merge-Migration mit Exit 2.
|
||
|
||
**Stand:** VA-P26a: **5/7 DoD = ~71 % done**. Offen sind 2 Gates, beide außerhalb des jetzt lokal
|
||
abschließbaren Feature-Branch-Slices: (1) die realen Coolify-Ressourcen `hivegrid-web` und
|
||
`hivegrid-portal` samt identischem SHA/Digest, DNS/Ingress und Live-Health-Proof; (2) die einmalige
|
||
forward-only Merge-Migration samt grünem Parity-/Staging-RLS-Proof. Es wurde weder live deployt noch
|
||
DNS oder eine externe Ressource verändert. `VA-P26b` und `VA-P26c` bleiben bis zu diesen Gates
|
||
blockiert.
|
||
|
||
### Hardening- und Rollout-Nachzug
|
||
|
||
2026-07-15 · Raffael: Der lokale Rollout-Vertrag ist mit Hardening-Commit `a62945596` bis zur
|
||
Operator-Grenze fertiggestellt. Der
|
||
Deploy führt jetzt vor jeder Staging-/Production-Migration einen ausschließlich lesenden Preflight
|
||
über Core-Web, Portal-Web, API, MCP, Hocuspocus und alle fünf Worker aus. Geprüft werden unter
|
||
anderem Runtime-Rolle/RLS, verbotene Migrations-/Seed-Variablen, exakte Revision, explizite
|
||
DB-Pool-Limits, PgBouncer-Port, getrennte Sessions, kanonische HTTPS-Hosts, Web-Push sowie harte
|
||
CPU-/RAM-Grenzen beider Web-Ressourcen. Mutationen und Worker-Reconciliation bleiben hinter der
|
||
Migration. Veraltete Fly-Domain-Module und `PORTAL_SERVER_*`-Secrets wurden entfernt; Status-Mails
|
||
verwenden ausschließlich den kanonischen HTTPS-Portalhost. `/readyz` beweist Service, Surface und
|
||
Revision, ohne die DB-Rolle öffentlich auszugeben.
|
||
|
||
Der neue strikte Migration-Chain-Prüfer vergleicht für den damaligen P26a-Portal-Vertragsstand den
|
||
vollständigen App-/Worker-Zielzustand mit 29 Policies und 64 DML-Grants, inklusive ENABLE/FORCE RLS,
|
||
Policy-Ausdrücken, Rollen, PUBLIC-/vererbten Rechten und Column-ACLs. Im normalen lokalen
|
||
Feature-Branch-Modus sind der exakte Prüfer und alle 60 Live-RLS-Tests grün. Der migration-only
|
||
Strict-Modus stoppt erwartungsgemäß ausschließlich vor dem Overlay an der noch fehlenden
|
||
forward-only Merge-Migration.
|
||
|
||
**Hardening-Proof:** Node 24.18.0; Typecheck, Worker-Typecheck und Lint grün; Core-Suite 830
|
||
Testdateien bestanden, 9 übersprungen, 5.670 Tests bestanden, 53 übersprungen; Worker-Suite 98
|
||
Testdateien bestanden, 1 übersprungen, 1.114 Tests bestanden, 5 übersprungen. Core-/Portal-Build,
|
||
Web-/Worker-Runtime-Closures, Prisma-Validierung, Tenant-Policy-Vertrag 266/266, Gitea-CI-Vertrag
|
||
155/155, Deploy-Vertrag 195/195, Health 30/30, Docker-Baseline 291/291, Non-Root 3/3,
|
||
Production-/Release-Docs-Baselines, Env-Drift, Doku-Links, Secret-Scan und Removed-Module-Scan sind
|
||
grün. Das finale lokale Docker-Image lief erfolgreich gleichzeitig als getrennte Core- und
|
||
Portal-Runtime gegen den finalen gemeinsamen Policy-Zustand. `verify:migrations-parity` endet wie
|
||
vorgesehen mit Exit 2 und `verify:rls-release-readiness` ausschließlich wegen des noch nicht in einer
|
||
aktiven Merge-Migration enthaltenen Portal-Deltas. Der erweiterte P26b/P26c-Vertragsstand und sein
|
||
neuer Probe-Lauf sind im Nachweis vom 2026-07-16 unten getrennt dokumentiert.
|
||
|
||
**Stand nach Hardening:** VA-P26a: **5/7 DoD = ~71 % done**. Es wurde kein Coolify-, DNS-, TLS- oder
|
||
sonstiger Live-Zustand verändert. Offen bleiben exakt die bereits dokumentierten zwei Operator-Gates:
|
||
Merge-Migration plus strikter Staging-RLS-Proof sowie reale gleichartige Core-/Portal-Ressourcen mit
|
||
identischem SHA/Digest und Live-UAT.
|
||
|
||
### Produkt-/Betriebsentscheidungs-Nachtrag
|
||
|
||
2026-07-16 · Raffael: Die Betreiber-Startwerte sind bestätigt: Produktion startet für `hivegrid-web`
|
||
mit 2 vCPU/2 GB und `DATABASE_POOL_MAX=10`, für `hivegrid-portal` mit 1 vCPU/1 GB und
|
||
`DATABASE_POOL_MAX=5`, jeweils pro Prozess/Instanz. Die Werte bleiben anpassbare Betriebsbudgets, aber
|
||
explizite Hard-Caps sind Pflicht. VA-P26a darf die Runtime-/Auth-/RLS-Grundlage auf Staging bringen; die
|
||
öffentliche Buchung/Freischaltung wartet auf den vollständigen `VA-P26b`-Admin-/Interaktions-Slice.
|
||
Der DoD-Stand bleibt **5/7 = ~71 % done**, da weder Merge-Migration noch Live-Proof dadurch ersetzt werden.
|
||
|
||
**Rollback:** Vor der DB-Migration wird auf den vorherigen immutable Web-Digest zurückgerollt und die
|
||
Portal-Resource beziehungsweise ihr DNS-Eintrag deaktiviert. Nach der Merge-Migration gilt der im
|
||
Migration-File zu dokumentierende Inverse-SQL-Pfad parent-first für Struktur, Indizes, FKs und
|
||
Policies; gelöschte Legacy-Commerce-Zeilendaten sind nicht per DDL rückholbar und benötigen bei einem
|
||
echten Daten-Rollback das Datenbank-Backup.
|
||
|
||
### Lokaler Merge-Kandidaten-Proof
|
||
|
||
2026-07-16 · Raffael · **Bewusst ungetrackter lokaler Merge-Kandidaten-Proof.** Der reproduzierbare
|
||
Repository-Vertrag liegt in `18dfd4825`, die Main-Reconciliation in `1f8d9a04c`; der temporäre
|
||
Merge-Kandidat selbst wurde absichtlich nicht committed. Er wurde ohne Migrationsfile gegen zwei wegwerfbare
|
||
PostgreSQL-16-Datenbanken geprüft: einmal ab leerer Datenbank
|
||
über die vollständige bestehende Migration-Chain und einmal gegen einen Legacy-Datenklon. Beide Läufe
|
||
verwendeten den eingeschränkten `hivegrid_migrator`; der resultierende Zustand ist schema-paritätisch
|
||
zum aktuellen Prisma-Schema. Der Legacy-Klon belegt das freigegebene Mapping zu `active` beziehungsweise
|
||
`invited`, byte-identisch erhaltene Passwort-Hashes, zurückgesetzte nicht belastbar belegte
|
||
Verifikation/Tokens und den FK-sicheren child-first-Recut. Eine bewusst erzeugte normalisierte
|
||
E-Mail-Kollision bricht fail-closed vor der ersten Mutation ab.
|
||
|
||
Die nachgelagerten lokalen Policy-Proofs validieren vier Actor-Constraints für `File`, `FileUpload`,
|
||
`FileEntityLink` und `FormSubmission`. Der P26a-Anteil bleibt **14/14**; im aktuellen gemeinsamen
|
||
Vertragsstand sind **22/22** Portal- und zusammen mit App/Worker sowie Bootstrap **68/68** lokale
|
||
Feature-Overlay-Tests grün. Dieser Probe-Lauf ist Vorbereitung für die eine Merge-Migration, kein
|
||
Ersatz dafür: Es wurde kein Migrationsfile angelegt, kein Staging-System verwendet und keine Coolify-,
|
||
DNS-, TLS- oder
|
||
Produktionsressource verändert.
|
||
|
||
Finaler lokaler Gate-Proof: `pnpm typecheck`, `pnpm lint` und `pnpm test` grün (927 Testdateien
|
||
bestanden, 10 übersprungen; 6.166 Tests bestanden, 54 übersprungen), vollständiger Core-/Portal-Build,
|
||
Runtime-Closures, Controller-Container-Smoke, Prisma-Validierung und der reale Feature-Overlay-RLS-Lauf
|
||
mit eingeschränkten App-/Portal-Rollen grün. `verify:rls-release-readiness` bleibt ausschließlich wegen
|
||
der 19 noch nicht migrationsgebundenen P26-Definitionen erwartungsgemäß offen.
|
||
|
||
**Stand 2026-07-16:** VA-P26a bleibt **5/7 DoD = ~71 % done**. Offen sind weiterhin ausschließlich
|
||
die echte forward-only Merge-Migration samt migration-only Parity-/Staging-RLS-Proof und der reale
|
||
Core-/Portal-Ressourcen-, Digest-, Health- und UAT-Nachweis.
|
||
|
||
### Live-Deploy-Proof
|
||
|
||
2026-07-16 · Raffael: PR `#125` wurde nach grünem PR-Lauf per Squash gemergt. Die beiden aus dem
|
||
ersten Rollout sichtbar gewordenen Deploy-Vertragsfehler wurden in PR `#130` und PR `#132` jeweils
|
||
mit Regressionstests behoben. Der abschließende Deploy-Lauf
|
||
[`#10300`](https://git.tool-ctrl.de/toolctrl-labs/HiveGrid-Cloud/actions/runs/10300) hat die exakte
|
||
Revision `f54b04162b2823b1d2f6db0318baf1a7431c5b66` erfolgreich nach Staging und Produktion
|
||
promotet.
|
||
|
||
Die forward-only Migration
|
||
`prisma/migrations/20260716123000_va_p26_customer_portal/migration.sql` lief im einmaligen,
|
||
eingeschränkten Migrator-Container durch. Migration-Chain-Parität, exakter Tenant-Policy-Vertrag,
|
||
RLS-Release-Readiness und der Live-RLS-Isolationslauf waren grün. Core und Portal verwenden getrennte
|
||
App-/Portal-Rollen über PgBouncer; die Portal-Ressource läuft mit `hivegrid_portal`, erzwungenem RLS,
|
||
eigenem Pool-Limit und den vereinbarten Hard-Caps. Beide Web-Surfaces wurden aus demselben gepinnten
|
||
Image/Digest ausgerollt und bestanden `/healthz` sowie `/readyz` mit der erwarteten Revision.
|
||
|
||
Damit ist der Portal-RLS-Punkt erfüllt. Der Runtime-/Trust-Boundary-Punkt bleibt bis zum echten
|
||
Staging-UAT mit Tenant-Fixture, Host-/Surface-404-Pfaden und Endkunden-Klickpfad offen. **Aktueller
|
||
Stand: 6/7 DoD = ~86 % done · 1 Punkt offen, davon 1 UAT-/Sign-off-abhängig und 0 weitere
|
||
Repository-Gates.** Billing, Custom-Domain-Controller und Custom-Domain-TLS/Ingress sind Scope von
|
||
`VA-P26c` und werden durch diesen Deploy nicht als erledigt gewertet.
|
||
|
||
### Globales M006-Fail-Closed-Gate
|
||
|
||
2026-07-18 · Raffael · Commit `6d96b7928` · **Lokaler Repository-Proof, noch nicht deployt.** Die
|
||
forward-only Migration `20260717200000_va_p26_customer_portal_feature_gate` provisioniert genau die
|
||
kanonische globale Flag `customer-portal` (`feature_flag_customer_portal_global`) samt Create-Audit.
|
||
Die erstmalige Migration erhält die bestehende Verfügbarkeit mit `enabled=true`; danach entscheidet
|
||
ausschließlich der auditierte Feature-Flag-Engine-Toggle. Fehlende, doppelte, ersetzte, gescopte,
|
||
gefilterte, varianten-/regel-/parent-gebundene oder außerhalb ihres Zeitfensters liegende Zeilen
|
||
schließen das Portal fail-closed.
|
||
|
||
Der ungecachte Gate-Read greift auf Standardhost, Framework-/Asset-Requests, Standard-/Custom-Host-
|
||
Tenantauflösung, Workspace-Admin-Navigation und direkte Admin-Routes. Portal-Automation prüft am
|
||
Job-Einstieg, transaktionslokal vor Rule-Writes, vor jedem Action-Step und direkt vor Auto-Release.
|
||
Status- und Auth-Mails werden unmittelbar vor der finalen Provider-Zustellung erneut geprüft, sodass
|
||
auch bereits eingereihte Jobs nach einem Disable nicht versendet werden. Operative Health-Pfade,
|
||
insbesondere der schmale Custom-Host-`/healthz`-Controller-Probe, bleiben für Diagnose und sicheres
|
||
Re-enable erreichbar. Der globale Betriebsschalter ist orthogonal zu den `VA-P26c`-Entitlements und
|
||
zum hostbezogenen Domain-Kill-Switch.
|
||
|
||
**Proof:** Fokussierter Gate-Lauf 19/19 Testdateien und 429/429 Tests grün; vollständiger Root-Lauf
|
||
957 Testdateien bestanden, 10 übersprungen, 6.516 Tests bestanden, 55 übersprungen. Root-/Worker-
|
||
Typecheck, Lint, Prisma-Validate, Migration-Parität, i18n, Tenant-Policy-Vertrag 292/292,
|
||
CI-Baseline, Source-Health, Coverage und `git diff --check` sind grün. Der strikte lokale
|
||
Migration-Chain-/Live-RLS-Lauf gegen frisches PostgreSQL 16 ist grün. Es wurde weder deployt noch
|
||
Staging oder eine externe Ressource verändert.
|
||
|
||
**Rollback ab diesem M006-Nachzug:** Der normale sofortige Laufzeit-Rollback ist der auditierte
|
||
Toggle von `customer-portal` auf aus; die strukturelle Inverse-SQL ist kein normaler Kill-Switch. Ein
|
||
Image-Rollback auf eine Revision vor diesem Gate ist unvereinbar mit einem deaktivierten Portal:
|
||
gate-fähige Images müssen weiterlaufen oder alle älteren Portal-/Mail-/Automation-Consumer vorher
|
||
gestoppt und gedraint werden. Vor der strukturellen Inverse-SQL sind zusätzlich Portal-Runtime,
|
||
Ingress/DNS und Portal-Mail-Consumer zu stoppen/drainen, weil die wiederhergestellten Resolver
|
||
absichtlich ungegated sind. Nicht per DDL rückholbare Legacy-Commerce-Zeilendaten benötigen weiterhin
|
||
ein DB-Backup.
|
||
|
||
**Stand:** `VA-P26a` bleibt **6/7 DoD = ~86 % done**. Offen bleibt derselbe externe Runtime-/UAT-/
|
||
User-Sign-off-Punkt. Der UAT muss nach Deploy dieses Gate-Slices Enable, Disable→404/keine
|
||
Provider-Mail und Re-enable beweisen. Es wird kein zusätzlicher DoD-Punkt gezählt.
|
||
|
||
### Scope-Präzisierung: vollständiger Einladungs-Lifecycle
|
||
|
||
2026-07-18 · Raffael: Der Produktvertrags-Abgleich hat eine Lücke in
|
||
der bisherigen Ticket-DoD sichtbar gemacht. Die bestehende Portalverwaltung legt bei einer direkten
|
||
Einladung nur einen `PortalUser` an, stellt aber keinen einlösbaren 7-Tage-Setup-Token aus und
|
||
verschickt keine Setup-Mail. Der Automation-Pfad erzeugt zwar Token und Mail, sein systemseitig
|
||
ausgestellter Token erfüllt den aktuellen IP-Bindungsvertrag jedoch nicht. Datenschutzannahme,
|
||
erneutes Senden und die Einstiege aus Kontakt-, Projekt- und Sales-Projekt-Sicht sind ebenfalls nicht
|
||
als vollständige Produktkette nachgewiesen.
|
||
|
||
Nach ausdrücklicher Produktfreigabe wird deshalb ein achter DoD-Punkt ergänzt. Der Deal-Einstieg wird
|
||
gemäß AD-20 nicht als alte separate Deal-Entität wiederbelebt, sondern über dieselbe Projektdetail-
|
||
Einladung für Projekte in einer Sales-Pipeline erfüllt. `VA-P26b` und `VA-P26c` bleiben bis zu diesem
|
||
Auth-/Projekt-Handoff blockiert. **Aktueller Stand: 6/8 DoD = 75 % done · 2 Checkboxen offen.** Der
|
||
Einladungs-Punkt hat einen lokal selbst machbaren Repository-Anteil, verlangt in derselben Checkbox
|
||
aber zusätzlich Live-RLS- und Browser-E2E-Proof; er kann deshalb erst zusammen mit dem externen
|
||
Staging-UAT gezählt werden. Der zweite offene Punkt ist der Runtime-/Trust-Boundary-UAT samt
|
||
User-Sign-off. Plane steht noch auf dem älteren Nenner und wird erst nach lokal grünem Proof
|
||
nachgezogen.
|
||
|
||
### Einladungs-Lifecycle: lokaler Repository-Proof
|
||
|
||
2026-07-18 · Raffael · Commits `9a2c3403e`, `3d303bc43`, `41724c91f` und
|
||
`fb7072e63` · **Lokal vollständig umgesetzt, noch nicht deployt.** Portalverwaltung,
|
||
Kontakt-Detail und Projekt-Detail verwenden jetzt denselben permission-gegateten Invite-/Resend-
|
||
Service; die Projektaktion vergibt den Projektzugang in derselben Transaktion. Der Erstzugang nutzt
|
||
einen einmaligen gehashten 7-Tage-Setup-Token. Die eigentliche Capability bleibt bis zur finalen
|
||
Provider-Grenze tenantgebunden verschlüsselt, wird vor dem Provider-Aufruf aus dem Queue-Payload
|
||
redigiert und bei unsicherem Delivery-Ausgang terminalisiert. `worker-mail` startet und meldet sich
|
||
ohne denselben `CRYPTO_SECRET` wie `hivegrid-web` fail-closed.
|
||
|
||
Der Setup-Flow aktiviert den PortalUser erst nach expliziter Datenschutzannahme, unterstützt den
|
||
weiterhin optionalen Passwortweg und erstellt erst anschließend die Portal-Session. Re-Invite,
|
||
Resend, fremde Kontakt-/Projekt-IDs, Frozen-/Permission-Denial, Gate-Disable und konkurrierende
|
||
Replays sind getestet. Der Lifecycle-/Anonymisierungsweg entfernt die neue Datenschutzmetadaten und
|
||
erhält für Token-/IP-Hashfelder die Datenbankform `64hex`.
|
||
|
||
**Lokaler Proof:** Root-Testlauf 963 Testdateien bestanden, 10 übersprungen; 6.561 Tests bestanden,
|
||
55 übersprungen. Der fokussierte Setup-/Mail-Security-Lauf ist 13/13 Dateien und 365/365 Tests grün;
|
||
Config-/Health 70/70, Coolify-Provisionierung 139/139 und Customer-Portal-UAT-Vertrag 121/121 sind
|
||
grün. Root-, Worker-, DB-, View-Model- und CLI-Typecheck, vollständiger Lint, Produktionsbuild beider
|
||
Web-Surfaces, Web-/Worker-Runtime-Closures, Bundle-Budget, Coverage, i18n, Hot-Swap, Visual-Baseline,
|
||
Docs-Links, Secret-Scan, Source-Health, Env-Drift und CI-/Deploy-Verträge sind grün. Migration-Parität,
|
||
Tenant-Policy-Vertrag und der frische eingeschränkte Live-RLS-Lauf mit allen acht Phasen sind grün;
|
||
RLS-Release-Readiness klassifiziert 290/290 Modelle und deckt 245/245 erzwungene Modelle ab. Der
|
||
registrierte Browser-Smoke und der externe Delivered-Mail-Adapter wurden lokal verifiziert, aber
|
||
nicht als echter Staging-/Provider-Lauf ausgegeben.
|
||
|
||
**Rollback:** Portal-Mail-/Outbox-Consumer stoppen und drainen sowie noch lebende Setup-Tokens
|
||
widerrufen. Ein Image-Rollback verwendet den vorherigen immutable Digest; der Mail-Worker darf nur
|
||
mit dem zum Web-Image passenden Envelope-Key wieder starten. Ein struktureller DB-Rollback erfolgt ausschließlich
|
||
koordiniert über die im Migration-File dokumentierte Inverse-SQL, nachdem Portal-Runtime und Worker
|
||
gestoppt wurden.
|
||
|
||
**Stand:** `VA-P26a` bleibt **6/8 DoD = 75 % done**. Offen sind genau zwei Checkboxen: der echte
|
||
Runtime-/Trust-Boundary-UAT samt User-Sign-off sowie der Staging-Anteil des Einladungs-Lifecycle-
|
||
Punkts. Dafür fehlen noch Deploy der geprüften Revision, reale Mailjet-Zustellung, no-skip Browser-
|
||
Reise Einladung → Mail-Link → Datenschutz → Session → Projekt → Replay-Denial und die externe
|
||
Log-/Trust-Boundary-Prüfung. Im Repository ist für diese beiden Nachweise kein weiterer Codepunkt
|
||
offen.
|
||
|
||
### CI-Korrektur: RLS-Overlay-Drift
|
||
|
||
2026-07-18 · Raffael: Gitea-Run
|
||
[`#10519`](https://git.tool-ctrl.de/toolctrl-labs/HiveGrid-Cloud/actions/runs/10519) hat nach einem
|
||
erfolgreichen 20:48-Minuten-Docker-Build den Web-Runtime-Smoke beim erneuten Einspielen des
|
||
Standalone-RLS-Overlays abgebrochen. Der Overlay-Resolver
|
||
`hivegrid_portal_resolve_user_email` referenzierte durch eine fehlerhafte Predicate-Übernahme den
|
||
nicht vorhandenen Alias `token`; die kanonische Merge-Migration enthielt weiterhin den korrekten
|
||
Statusvertrag für `invited` und `active`.
|
||
|
||
Der Overlay-Resolver ist wieder bytegleich an die migrationsgebundene Funktion gekoppelt. Ein
|
||
Regressionstest vergleicht den vollständigen Funktionsblock und verbietet Token-Aliase in diesem
|
||
E-Mail-Resolver. Das ändert keinen Auth-, Token- oder RLS-Vertrag, sondern stellt den bereits
|
||
gemergten Zustand wieder her. `VA-P26b` und `VA-P26c` konsumieren denselben Pre-Auth-Resolver und
|
||
bleiben dadurch kompatibel; ihre DoD-Stände ändern sich nicht.
|
||
|
||
**Proof:** Der gezielte Policy-Contract-Test ist mit 37/37 Tests grün; die vollständige DB-Suite mit
|
||
91 bestandenen und 6 übersprungenen Testdateien (800 bestanden, 116 übersprungen). Eine frische
|
||
PostgreSQL-16-Instanz hat die komplette Migrationskette und danach das Standalone-Portal-RLS-Overlay
|
||
unter dem eingeschränkten Migrator erfolgreich angewendet. `verify:migrations-parity`,
|
||
`verify:tenant-policy-contract` (292/292) und `verify:rls-release-readiness` (290/290 klassifiziert,
|
||
245/245 RLS-Policies) sind grün. Der abschließende Pre-Push-Lauf aus Typecheck, Lint und Gesamttest
|
||
ist grün (964 bestandene und 10 übersprungene Testdateien; 6.597 bestanden, 55 übersprungen).
|
||
|
||
**Stand:** `VA-P26a` bleibt **6/8 DoD = 75 % done**. Offen bleiben dieselben zwei externen
|
||
Staging-/UAT-Punkte; die Korrektur zählt keinen neuen DoD-Punkt.
|
||
|
||
### CI-Korrektur: Mail-Worker-Runtime-Smoke
|
||
|
||
2026-07-19 · Raffael: Gitea-Run
|
||
[`#10605`](https://git.tool-ctrl.de/toolctrl-labs/HiveGrid-Cloud/actions/runs/10605) hat den neuen
|
||
fail-closed `CRYPTO_SECRET`-Vertrag des Mail-Workers korrekt erkannt. Der produktive
|
||
Coolify-/Worker-Vertrag war bereits vollständig nachgezogen; ausschließlich die isolierte
|
||
`worker:health-mail`-Probe startete noch ohne den nicht-produktiven Envelope-Key-Fixture und meldete
|
||
deshalb deterministisch `misconfigured`. Der Smoke setzt den klar erkennbaren Fixture jetzt nur für
|
||
die Mail-Probe. Disabled-, General- und Runtime-General-Worker erhalten ihn weiterhin nicht; ein
|
||
Regressionstest erzwingt genau ein mail-spezifisches Vorkommen. Der Outbox-Vertrag wird nicht
|
||
abgeschaltet oder aufgeweicht.
|
||
|
||
**Proof:** Der reproduzierte Worker-Docker-Smoke ist inklusive frischer 191-Migrations-Datenbank,
|
||
eingeschränkten RLS-Rollen, Mail-/General-Health und negativen Deploy-Health-Gates grün; der zuvor
|
||
fehlgeschlagene `worker:health-mail`-Schritt lief in 1,28 Sekunden, der Runtime-Teil in 20,5 Sekunden.
|
||
Der fokussierte Config-/Health-/Docker-Vertrag ist 128/128 Tests grün. Der abschließende Root-Lauf
|
||
ist mit 966 bestandenen und 10 übersprungenen Testdateien beziehungsweise 6.693 bestandenen und 55
|
||
übersprungenen Tests grün; Typecheck, Lint, Docker-Baseline 309/309, Non-Root 4/4,
|
||
Deploy-Readiness, CI-/Deploy-Verträge, Secret-Scan, Source-Health und `git diff --check` sind grün.
|
||
|
||
**Stand:** `VA-P26a` bleibt **6/8 DoD = 75 % done**. Offen bleiben ausschließlich die zwei
|
||
externen Staging-/UAT-Punkte; diese Smoke-Korrektur zählt keinen neuen DoD-Punkt.
|
||
|
||
### CI-Performance-Nachzug
|
||
|
||
2026-07-19 · Raffael: `CI-05` ersetzt die nachträglich eingeführte fünffache Docker-Serialisierung
|
||
durch einen einzigen gesperrten Production-Bundle-Schritt auf dem bereits warmen v2-Store. Fünf
|
||
parallele Offline-Deploys liegen in derselben atomaren RUN-Grenze; ein frozen Fetch mit vollständigem
|
||
Retry läuft nur nach einer fehlgeschlagenen Offline-Welle. Pruning und SBOM laufen danach targetweise ohne
|
||
Store-Mount. Getrennte parallele Build- und Runtime-Wellen bleiben erhalten. Die ungenutzte Buildx-
|
||
Setup-Action entfällt; erhöhte Docker-Kommando-Caps tolerieren Lastspitzen auf dem geteilten Runner,
|
||
ohne gesunde Pfade künstlich warten zu lassen.
|
||
Die für dieses Ticket relevanten Web-/Portal-/Worker-Images, Migrationen, RLS-Rollen, Health-Probes
|
||
und negativen Runtime-Gates bleiben unverändert vollständig enthalten. Run-spezifische Tags,
|
||
Container, Netze und Volumes verhindern weiterhin ref-übergreifende Kollisionen. Dieser reine
|
||
CI-Orchestrierungsnachzug ändert keinen Customer-Portal-Vertrag und keinen DoD-Zähler.
|
||
|
||
**Stand:** `VA-P26a` bleibt **6/8 DoD = 75 % done**. Offen bleiben ausschließlich die zwei externen
|
||
Staging-/UAT-Punkte.
|
||
|
||
### Technischer Staging-Abschluss
|
||
|
||
2026-07-21 · Raffael: PR `#201` wurde als normaler Merge-Commit
|
||
`a747e9c655b2be4bd9ba52e59f56d5f0e9d145b0` übernommen. Deploy `#10909` blieb auf Staging: Der
|
||
erste Versuch scheiterte vor dem Start eines Kandidaten-Containers an einem transienten Registry-
|
||
Layer-Commit; der bis dahin laufende Core-/Portal-Stand blieb gesund und der Controller-Recovery-
|
||
Pfad stellte die alte Revision sicher. Genau ein Wiederholungslauf rollte anschließend Core und
|
||
Portal aus demselben SHA und Registry-Digest aus. Health, Readiness, DB-Rollen und der
|
||
revisionsgebundene Controller-Proof waren grün; der Recovery-Schritt erkannte den gesunden
|
||
Kandidaten und führte keinen Rollback aus. Alle Produktionspfade blieben übersprungen.
|
||
|
||
Der Staging-UAT bewies die Core↔Portal-/Host-Matrix, interne und unbekannte Pfade sowie fremde
|
||
Sessions mit fail-closed 404. Der globale M006-Schalter lief Enable → Disable → Re-enable; während
|
||
Disable blieb auch die externe Mailzustellung aus. Katalog und Portal-Fixture liefen jeweils über
|
||
Plan, Apply und Verify.
|
||
|
||
Die vollständige Einladungsreise ist für genau drei fachliche Einstiege grün: direkte
|
||
Portalverwaltung, Kontakt-Detail und Projekt-Detail. Jede frische Reise belegte Provider-Zustellung,
|
||
Datenschutzannahme, Session, erlaubten Projektzugriff und Replay-Denial. Vor der Projektreise wurden
|
||
genau drei fehlende `projects.read_own`-Rollenbindungen gezielt ergänzt, transaktional verifiziert
|
||
und erst nach dem Cache-Fenster weiterverwendet; andere Benutzer-, Passwort-, Checkout-, Provider-
|
||
oder Portalzustände blieben unverändert.
|
||
|
||
Der temporäre Test-Mailadapter war ausschließlich an `127.0.0.1` gebunden. Logs und diese
|
||
Dokumentation enthalten weder Tokens noch Empfänger, Mailinhalte oder private Proof-Hashes. Es wurden
|
||
keine Schlüssel oder Passwörter rotiert; die vorhandenen Zugangsdaten blieben unverändert.
|
||
|
||
**Abschlussstand:** `VA-P26a`: **8/8 DoD = 100 % done**. Der technische Handoff an `VA-P26b` und
|
||
`VA-P26c` ist erfüllt. `VD-P26` bleibt als separater Design-Nachzug offen; Produktion wurde nicht
|
||
freigegeben.
|
||
|
||
### UI-/Branding-Nachtrag
|
||
|
||
2026-07-22 · Raffael: PR `#212` hat die Endkunden-Shell und die täglichen Portalreisen auf den
|
||
bestehenden HiveGrid-UI-Baukasten angeglichen: klickbare, einklappbare Navigation, Sidebar-Inset,
|
||
Breadcrumbs, konsistente Seitenköpfe sowie eine reduzierte Übersicht und Projektansicht. Einstellungen
|
||
liegen getrennt unten in der Sidebar. Ein Tenant-Logo wird über einen privaten, gescannten Upload
|
||
konfiguriert und auf Standard- sowie Custom-Host angezeigt; ohne Logo greift die HiveGrid-Wortmarke als
|
||
Fallback. Die lokale Vorschau bleibt aus Production-Builds ausgeschlossen.
|
||
|
||
Main-Revision `090e2558a6965e1c5804eb24d3eab5da8c8611a8` bestand 13/13 PR-CI-Jobs und den
|
||
Staging-Deploy `#11018`. Core und Portal meldeten auf Health und Readiness dieselbe Revision aus demselben
|
||
Web-Digest; der Controller akzeptierte den Release ohne Rollback. Der vollständige aktuelle Produktstand
|
||
steht in [`docs/features/customer-portal.md`](../../docs/features/customer-portal.md).
|
||
|
||
Der Nachtrag ändert weder Auth-/RLS-Vertrag noch DoD-Zähler: **VA-P26a bleibt 8/8 = 100 % done**.
|
||
`VD-P26` bleibt als finaler Subframe-/Design-Nachzug offen.
|
||
|
||
## Was wir bauen
|
||
Die **eigene Runtime- und Auth-Schicht** des Customer-Portals (⭐ einzige extern sichtbare Endkunden-Oberfläche, höchster Polish): ein separater Coolify-Service/Container `hivegrid-portal` aus demselben immutable Web-Image, aber mit fail-closed Portal-Surface, eigenem minimal berechtigtem DB-Login und einer strikt von `TenantUser` getrennten **`PortalUser`-Klasse**. Eigene Cookies, öffentliche Standard-Routes unter `https://portal.hivegrid.de/<tenant>/…`, **keine Permission-Vermischung**, **Magic-Link primär**. Endkunden sehen nur **eigene Projekte / konfigurierte Stages / freigegebene Dokumente**; fehlender Zugang → **404** (keine Existenz-Offenlegung). Bei `project.stage_changed` gehen **Auto-Status-Mails** raus (debounced, bedingungsgesteuert). Workspace-Admin-Screens bleiben in `hivegrid-web`. `VA-P26c` ergänzt darauf Paket-Gates und Custom-Hosts; diese gehören nicht in dieses Ticket.
|
||
|
||
## Benötigte Screens (Backend bedient — Design liefert `VD-P26`, externer Polish)
|
||
| Screen [Route] | Kern-Inhalt |
|
||
|---|---|
|
||
| Endkunde · Login [`portal.hivegrid.de/{tenant}/login` · `/login/magic-sent`] | Magic-Link primär, Passwort sekundär, „Magic-Link gesendet"-Bestätigung, **kein User-Enumeration** |
|
||
| Endkunde · Setup/Verify/Reset [`portal.hivegrid.de/{tenant}/setup/{token}` · `/verify-email/{token}` · `/forgot-password` · `/reset-password/{token}`] | Erstzugang-Setup, E-Mail-Verifizierung, Passwort-Vergessen/-Reset |
|
||
| Endkunde · Portal-Dashboard [`portal.hivegrid.de/{tenant}`] | Übersicht eigene Projekte + Status, freigegebene Dokumente, Schnellaktionen |
|
||
| Endkunde · Projekte-Liste [`portal.hivegrid.de/{tenant}/projects`] | Liste eigener Projekte (Name, Stage/Fortschritt, letztes Update) |
|
||
| Endkunde · Project-Detail [`portal.hivegrid.de/{tenant}/projects/:id`] | Fortschritt (**nur sichtbare Stages**), freigegebene Dokumente (Download) |
|
||
| Workspace-Admin · Mail-Template-Editor [`app.hivegrid.de/{tenant}/settings/customer-portal/email-templates`] | Auto-Status-Mail-Vorlagen je Stage-Event, Variablen, Vorschau |
|
||
|
||
## Definition of Done
|
||
- [x] **Runtime-/Trust-Boundary:** Pro Environment existieren genau zwei Web-Surface-Coolify-Ressourcen `hivegrid-web` und `hivegrid-portal` neben den übrigen API-/Worker-/Runtime-Ressourcen, beide aus demselben immutable `hivegrid/web:<sha>` und Registry-Digest. Der verpflichtende Production-Modus `WEB_RUNTIME_SURFACE=core|portal` bricht bei fehlendem, ungültigem oder zur Resource unpassendem Wert den Boot ab. Das fail-closed Gate läuft vor Static-Asset-Serving und React Router: Portal-Mode lässt nur konfigurierten Standardhost, Health, benötigte Assets/Data-Requests und Portal-Routes zu, löst den Tenant vor Auth auf und rewritet nur intern auf einen reservierten Portal-Namespace. App/Admin/API/Root/intern, unbekannte Hosts, direkte öffentliche Requests auf den internen Namespace sowie bis `VA-P26c` alle Custom-Hosts liefern 404. Core-Mode weist Standard-/Custom-Portalhosts und Portalpfade ebenfalls ab.
|
||
- [x] Eigene **`PortalUser`-/`PortalSession`-Welt strikt getrennt** von `User`/`TenantUser` und deren Sessions; Standardhost `portal.hivegrid.de/<tenant>`, **Magic-Link primär**. Das Portal verwendet ausschließlich `__Host-hivegrid_portal_session` und einen eigenen `PORTAL_SESSION_SECRET`; App-/Admin-Cookies werden nie gelesen oder akzeptiert und `SESSION_SECRET` ist in der Portal-Resource verboten. Serverseitige Session enthält unveränderlich `tenantId` + `portalUserId`; Pfad-, Session- und später Host-Tenant müssen exakt übereinstimmen.
|
||
- [x] Endkunde sieht **nur eigene Projekte / konfigurierte Stages / freigegebene Dokumente**; fehlender Zugang → **404** (keine Existenz-Offenlegung)
|
||
- [x] **Auto-Status-Mails** bei `project.stage_changed` (Debounce; Bedingungen: sichtbare Stage / aktiver Access / Pref / nicht frozen)
|
||
- [x] **Härtung:** Rate-Limits, Captcha, **kein User-Enumeration**, wasserdichte Cookie-Trennung
|
||
- [x] Wiederverwendung v1: Auth-Pattern (**parallel, NICHT geteilt**), Sende-Domain (Auto-Mails), `notify()`, Tenant-Lifecycle (`frozen`→read-only)
|
||
- [x] **Portal-RLS:** `hivegrid-portal` verbindet ausschließlich als `hivegrid_portal` (`LOGIN`, `NOINHERIT`, `NOBYPASSRLS`, keine Rollenmitgliedschaften) mit `RLS_RUNTIME_MODE=required`. Portalidentität wird über `app.portal_user_id` plus `app.tenant_id` gebunden, nie über `app.user_id`. Der Login erhält nur explizit geprüfte Portal-/ProjectAccess-/Stage-/Dokumentfreigabe-Policies und schmale Pre-Auth-`SECURITY DEFINER`-Resolver; keine Rechte auf `User`, `TenantUser`, `AdminUser`, Rollen/Permissions, Billing oder sonstige Tenantdaten. Live-Postgres-Tests beweisen PortalUser A/B, Tenant A/B, nicht freigegebene Projekte/Dokumente und Cross-Role-Denial. Der Punkt wird erst nach der reviewten forward-only P26-Merge-Migration, grüner migration-only Parität und dem eingeschränkten Staging-RLS-Proof abgehakt; Feature-Overlay, Recut-Helper und `prisma db push` zählen ausdrücklich nicht als Abschluss.
|
||
- [x] **Vollständiger Einladungs-Lifecycle:** Ein Workspace-Admin mit `portal.manage_users` kann Endkunden direkt aus der PortalUser-Verwaltung, vorausgefüllt aus dem Kontakt-Detail sowie aus dem Projekt-Detail einladen; die Projektdetail-Aktion vergibt den Projektzugang atomar und deckt nach AD-20 auch Sales-/Deal-Projekte ab. Jede neue oder erneut versendete Einladung erzeugt genau einen gehashten, einmaligen 7-Tage-Setup-Token, verschickt die Setup-Mail über den tenantgebundenen Mail-/Outbox-Vertrag und bleibt trotz systemseitiger Ausstellung sicher IP-gebunden. Der Setup-Flow aktiviert den User erst nach ausdrücklicher Datenschutzannahme, erlaubt weiterhin ein optionales Passwort und erzeugt erst danach die Portal-Session. Doppelte E-Mails, Re-Invite/Resend, fremde Kontakt-/Projekt-IDs, Frozen/Permission-Denial und Concurrent-Replays sind fail-closed, auditiert und RLS-geprüft. Unit-, Route-, Worker-, Live-RLS- und Browser-E2E-Proof decken Einladung → Mail-Link → Setup → Session → erlaubtes Projekt sowie Token-Replay ab.
|
||
|
||
## Technische Bausteine
|
||
- **Runtime-/Deploy-Slice:** kein neues `apps/portal` und kein neues Portal-Image im ersten Schnitt. `packages/config/src/types.ts`/`routing.ts`, `server/host-routing-runtime.ts` und `server/server.ts` erhalten einen fail-closed Portal-Runtime-Modus **vor Static-Asset-Serving und React Router**. Die Standard-URL wird nach sicherer Tenant-Auflösung intern auf einen reservierten Namespace (Arbeitsvertrag `/__portal/<tenant>/...`) rewritet; dieser Namespace ist von außen auf allen Hosts gesperrt, damit keine bestehende TenantUser-/Admin-Route matchen kann. `VA-P26a` liefert nur die sichere Erweiterungsnaht; Custom-Host-Auflösung und deren Rewrite gehören vollständig zu `VA-P26c`. Vom Client gelieferte interne Kontext-Header werden entfernt/überschrieben. `Dockerfile` bleibt beim Web-Target, bekommt aber einen surface-aware Healthcheck. Tenant-/Workspace-Admin-Routes bleiben ausschließlich im normalen Web-Service.
|
||
- **Root-/Loader-Grenze:** Portalrequests dürfen nicht durch Core-Root-Auth oder Core-Root-Data laufen. `apps/web/app/root.tsx` dispatcht anhand der vertrauenswürdigen Runtime-Surface auf getrennte Root-Middleware/-Loader/-Actions; im Portalpfad sind `getUserInfo`, `loadRootData`, Core-Session-Storage sowie `User`-/`TenantUser`-Queries verboten. Auch Locale-/CSRF-nahe Cookies verwenden die Portal-Konfiguration und nicht das Core-Session-Secret.
|
||
- **DB-/RLS-Grenze:** neuer Runtime-Login `hivegrid_portal` (`LOGIN`, `NOINHERIT`, `NOBYPASSRLS`, keine Rollenmitgliedschaften) mit minimalen Grants, `app.portal_user_id` + `app.tenant_id` und eigener tabellenweiser Portal-Policy-Matrix. Er wird nicht in den breiten App-/Worker-Tenant-Policy-Vertrag aufgenommen. Pre-Auth-Host-/Token-Auflösung erfolgt nur über eng begrenzte `SECURITY DEFINER`-Funktionen mit fixiertem `search_path`, entzogenem `PUBLIC EXECUTE` und exklusivem Execute-Recht für `hivegrid_portal`. Der bestehende `hivegrid_app`-Login oder nur tenantweite RLS zählt nicht als Proof.
|
||
- **Deploy-Identität:** `.gitea/workflows/deploy.yml`, Deploy-Verifier und Coolify-Helper adressieren Web und Portal über explizite Resource-Identitäten statt über das erste Image-Match, setzen denselben SHA/Digest, triggern beide separat und warten auf beide Deployments. `/healthz` unterscheidet Service/Surface und gebackene Revision; `/readyz` prüft die jeweilige DB-Rolle ohne sie öffentlich auszugeben. Bestehende Fly-/`PORTAL_SERVER_*`-Konsumenten werden auditiert und entfernt; keine Ingress-Credentials wandern in Web oder Portal.
|
||
- **Runtime-Secrets/Observability:** eigener Portal-Session-/Signing-Key, getrennte Rate-Limit-/Redis-Keys, CPU/RAM/PgBouncer-Limits und `service=hivegrid-portal`. Produktionsstartwerte: Core 2 vCPU/2 GB mit `DATABASE_POOL_MAX=10`, Portal 1 vCPU/1 GB mit `DATABASE_POOL_MAX=5` je Prozess/Instanz. Keine Authentik-JIT-, OAuth-, Billing-, Migrator-, Coolify-, SSH-, Traefik- oder Domain-Controller-Credentials. Dasselbe Sentry-Web-Projekt kann mit getrenntem Service-Tag verwendet werden.
|
||
- **Legacy-Recut vor neuen Entities:** `prisma/schema/portals.prisma` enthält bereits Boilerplate-Modelle `Portal`/`PortalUser` plus eine fachlich falsche Per-PortalUser-Commercewelt. Diese Modelle werden als einzige Portal-Domäne migriert: sichere/optionale Passwort-Identität, gehashte Auth-Tokens und Customer-Portal-Beziehungen ergänzen; nicht mehr benötigte `PortalSubscription*`-/Checkout-Modelle samt toten DB-Modulen nach Konsumenten-Audit entfernen. Kein paralleles zweites `PortalUser` anlegen.
|
||
- **Legacy-Recut DB-Push-/Merge-Vertrag:** Die historische RLS-Cutover-Migration bleibt unverändert. Vor einem ausschließlich lokalen/CI-seitigen Feature-Branch-`db push` läuft explizit `HIVEGRID_ALLOW_PORTAL_LEGACY_RECUT_DB_PUSH=1 pnpm run db:prepare:portal-legacy-commerce-recut`; der Helper ist auf Loopback-Datenbanken und die sieben geprüften `hg_Portal{Subscription*,UserSubscription*,CheckoutSessionStatus}_all`-Policies begrenzt, läuft atomar und bricht bei jeder weiteren Policy auf diesen Tabellen ab. Er ist **kein Migrationsersatz**: Beim Merge muss die eine forward-only P26-Migration für den ausgewählten gemeinsamen Portal-Vertragsstand nach einem fail-closed Bestandsdaten-Preflight die sieben Commerce-Policies sowie die Policy von `PortalUserRegistration` entfernen und insgesamt acht Tabellen FK-sicher child-first droppen (`PortalUserSubscriptionProductPrice` → `PortalUserSubscriptionProduct` → `PortalSubscriptionFeature`/`PortalSubscriptionPrice` → `PortalUserSubscription` → `PortalSubscriptionProduct` sowie `PortalCheckoutSessionStatus` und `PortalUserRegistration`). Vor `NOT NULL`/Unique/FK müssen `Portal.tenantId`, `PortalUser.tenantId`, `emailNormalized`, Tenant-Owner-Mismatches und normalisierte E-Mail-Kollisionen bewusst bereinigt werden. Alte `verifyToken`-/Registrierungs-Tokens werden nicht zu gültigen neuen Tokens umgedeutet; Status-/Verifikations-Mapping und Re-Invite sind eine dokumentierte Cutover-Entscheidung. Die Migration bettet App-/Worker-Tenant-Policies und die schmalen Portal-Policies unter genau einer äußeren Transaktion ein. Ihr Inverse-SQL-Kommentar beschreibt die strukturelle Wiederanlage parent-first inklusive Indizes, FKs, Grants und Policies und weist ausdrücklich darauf hin, dass gelöschte Zeilendaten nicht per DDL wiederherstellbar sind. `verify:migrations-parity` bleibt bis zu dieser Merge-Migration absichtlich rot; danach müssen `verify:migrations-parity` und der strikte, migration-only `HIVEGRID_RLS_REQUIRE_MIGRATION_CHAIN_PARITY=1 pnpm run verify:rls-live` beide grün sein. Operator-Ablauf: [`docs/deploy/customer-portal.md`](../../docs/deploy/customer-portal.md).
|
||
- **Entities** (in `prisma/schema/portals.prisma`, AD-21): `PortalUser` (eigene Identitäts-Klasse, **NICHT** `TenantUser`), Portal-Session/-Cookie-Modell (SameSite, getrennt), Magic-Link-Token + Setup/Verify/Reset-Token, `PortalProjectAccess` (welcher PortalUser sieht welches Projekt), `PortalStageVisibility`-Konfig, `PortalEmailTemplate` je Stage-Event. `project.prisma`/`crm.prisma`/`files.prisma` nur über FK (AD-21).
|
||
- **Auth-Trennung:** eigene hostgebundene Cookies, eigene Host-/Middleware-Kette für `portal.hivegrid.de/<tenant>/…`; Auth-Pattern aus v1 **kopiert, nicht geteilt** (kein Cross-Routing, keine Permission-Vermischung). Tenant-Auflösung erfolgt vor Auth; fehlender/ungültiger Zugang → 404 statt 403 (keine Enumeration).
|
||
- **Auto-Status-Mails:** Listener auf `project.stage_changed` (v1-Project-Stage-Trigger) → debounced Job; Bedingungs-Resolver (sichtbare Stage / aktiver Access / Pref / nicht frozen); Versand über v1-Sende-Domain; Templates aus `PortalEmailTemplate`.
|
||
- **Härtung:** Rate-Limits + Captcha auf allen Auth-Routes; die eigene tabellenweise PortalUser-/Access-Policy-Matrix aus der DB-/RLS-Grenze gilt verbindlich statt eines breiten tenantweiten RLS-Vertrags; `is_demo_data` auf seedbaren Portal-Demos.
|
||
|
||
## Quellen (granular)
|
||
- `ROADMAP-V2.md` → **§v2-P6 Customer-Portal** (Auth-Trennung/Magic-Link/Status-Mails = Hauptquelle; Depends-on/Success-Criteria/Recut)
|
||
- `ENTITY-MODEL.md` → **Domäne 5** (Project-Stages) + **Domäne 4** Files/FileEntityLink (Doc-Freigabe in P4 vorbereitet); PortalUser = parallele Auth-Klasse (kein geteiltes Auth-Modell)
|
||
- `ROADMAP.md` → Phase 26 · Milestones: (M141 Auth/Magic-Link, M142 Projekt-Sicht + Status-Mails)
|
||
- `designer-briefs/P26-customer-portal.md` (⭐ externer Polish, Auth-Trennung, 404-State, Mail-Template-Editor)
|
||
- `REQUIREMENTS.md` → `REQ-portal-runtime-isolation`
|
||
- `docs/ARCHITECTURE-DECISIONS.md` → AD-30 · `docs/INTEGRATION-CONTRACTS.md` §3/§14 · `docs/CHANGE-REQUESTS.md` CR-001
|
||
|
||
## Runtime-Slice: Fertig / Proof / zählt nicht
|
||
|
||
- **Fertigkeitskriterium:** Beide Coolify-Ressourcen laufen aus demselben SHA/Digest, booten nur mit passendem Surface-Modus, weisen die jeweils fremde Surface vor Assets und React Router mit 404 ab, benutzen getrennte Secrets und `hivegrid-portal` besteht Live-RLS mit minimalen Grants.
|
||
- **Proof:** Docker-/Deploy-Verifier, surface-aware Health-/Revision-Proof, Host-/Route-/Data-Request-Matrix und Live-Postgres-Test für PortalUser-/Tenant-/Cross-Role-Isolation auf Staging.
|
||
- **Zählt NICHT als fertig:** nur eine zusätzliche Domain am bestehenden Web-Container, ein zweiter Container mit `hivegrid_app`, ein Runtime-Flag erst innerhalb eines Route-Loaders oder ausschließlich gemockte RLS-Tests.
|
||
|
||
## Dev-Nachzug (nach Davids `VD-P26`-Delta)
|
||
|
||
**Interim-UI (Vorschau, Stand 2026-07-16):** Portal-Screens aus `~/ui` in
|
||
`apps/web/app/components/screens/customer-portal/CustomerPortalInterimPages.tsx`; die markierte
|
||
Interim-Baseline liegt unter
|
||
`packages/ui-mock/visual-baseline/va-p26a-customer-portal-interim.snapshot.json`. VM-, Hot-Swap-,
|
||
Visual- und Component-Proof sind lokal vorhanden; der Browser-Smoke ist registriert und wird nicht als
|
||
Staging-/Live-Lauf ausgegeben. Refactor-Nachzug: finale Subframe-Optik aus `VD-P26` und Re-Baseline.
|
||
|
||
- [ ] Spec/ENTITY-MODEL an Davids UI-Entscheidungen angepasst
|
||
- [ ] REQUIREMENTS/ROADMAP nachgezogen
|
||
- [x] Plane-Ticket `VA-P26a` mit 5/7-Stand und den zwei offenen externen Gates aktualisiert
|
||
(`c823b532-fd6f-46a5-aa19-0a331077f623`, 2026-07-16); Status bleibt In Progress
|
||
- [x] Plane-Ticket nach grünem Deploy auf 6/7-Stand und offenen Staging-UAT/User-Sign-off nachgezogen
|
||
(`8d1ab822-b8ee-4d2a-993c-e18c041bf745`, 2026-07-16); Status bleibt In Progress
|
||
|
||
## Abhängigkeitsnachzug · CR-007 · 2026-07-27
|
||
|
||
Das globale `customer-portal`-Rollout-Flag entfällt. Portal-Identität, Runtime-Trennung,
|
||
Tenant-/Subscription-Zustand, Veröffentlichung und RLS bleiben die fail-closed Grenzen.
|
||
|
||
## Pilot-Readiness-Nachzug · 2026-07-29
|
||
|
||
Der öffentliche Projekt-Upload begrenzt Multipart-Requests jetzt anhand der tatsächlich vom Parser
|
||
gelesenen Bytes. Fehlende oder absichtlich zu kleine `Content-Length`-Header umgehen das absolute
|
||
101-MB-Request-Limit nicht mehr; übergroße Streams enden stabil mit dem vorhandenen 413-/M002-Key,
|
||
bevor Dateien oder Storage-Zustand verarbeitet werden. Proof: fokussierte Helper- und Route-Tests,
|
||
ESLint und Web-Typecheck grün. **VA-P26a bleibt 8/8 DoD = 100 % done.**
|
||
|
||
Der Storage-Pfad übernimmt Portal-Dateien außerdem direkt als `Uint8Array`. Die bisherige
|
||
Base64-/Data-URI-Konvertierung mit anschließender erneuter Dekodierung und Blob-Kopie entfällt; Magic-
|
||
Bytes-Prüfung, fail-closed ClamAV-Scan und Provider-Fallback bleiben unverändert aktiv. Damit sinkt
|
||
der transiente Heap-Bedarf großer Uploads deutlich, ohne den Portal-/Storage-Vertrag zu erweitern.
|
||
Proof: 18 fokussierte Portal-/Storage-Tests, ESLint, Web-Typecheck und `git diff --check` grün.
|
||
**VA-P26a bleibt 8/8 DoD = 100 % done.**
|