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
@@ -5,50 +5,476 @@
|
||||
| **Typ** | Dev (Code) |
|
||||
| **Owner** | Akeshan |
|
||||
| **Phase** | P26 — Customer-Portal · v2-P6 *(ex-P18)* |
|
||||
| **Cycle/Fenster** | v2-W2 — KWP/Portal/Mobile-Start · fällig 2026-07-21 |
|
||||
| **Status** | geplant |
|
||||
| **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
|
||||
- **Blocked by:** `AK-P4a` (FileEntityLink — Doc-Freigabe + Portal-Uploads), `R-P6` (CRM), `R-P9a` (Projekt — Project-Stages/Stage-Trigger)
|
||||
- **Blocks:** `VA-P26b` (Upload/Reklamation/Skalierung baut auf der Portal-Auth-Schicht auf)
|
||||
- **Läuft parallel zu:** Raffaels `VR-P5/KWP` im selben Fenster v2-W2 — disjunkte Domänen. Eigene `prisma/schema/customer-portal.prisma` (AD-21); `crm.prisma`/`project.prisma`/`files.prisma` nur über FK.
|
||||
- **Konflikt-Risiko:** mittel — **eigene Auth-Schicht** parallel zum TenantUser-Auth (NICHT geteilt); strikte Cookie-/Route-Trennung erforderlich.
|
||||
- **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 Auth-Schicht** des Customer-Portals (⭐ einzige extern sichtbare Endkunden-Oberfläche, höchster Polish): eine strikt von `TenantUser` getrennte **`PortalUser`-Klasse** (eigene Cookies, eigene Routes unter `/portal/<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).
|
||||
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 `D-P26`, externer Polish)
|
||||
## Benötigte Screens (Backend bedient — Design liefert `VD-P26`, externer Polish)
|
||||
| Screen [Route] | Kern-Inhalt |
|
||||
|---|---|
|
||||
| Endkunde · Login [`/portal/{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/{tenant}/setup/{token}` · `/verify-email/{token}` · `/forgot-password` · `/reset-password/{token}`] | Erstzugang-Setup, E-Mail-Verifizierung, Passwort-Vergessen/-Reset |
|
||||
| Endkunde · Portal-Dashboard [`/portal/{tenant}`] | Übersicht eigene Projekte + Status, freigegebene Dokumente, Schnellaktionen |
|
||||
| Endkunde · Projekte-Liste [`/portal/{tenant}/projects`] | Liste eigener Projekte (Name, Stage/Fortschritt, letztes Update) |
|
||||
| Endkunde · Project-Detail [`/portal/{tenant}/projects/:id`] | Fortschritt (**nur sichtbare Stages**), freigegebene Dokumente (Download) |
|
||||
| Tenant-Admin · Mail-Template-Editor [`/admin/portal/email-templates`] | Auto-Status-Mail-Vorlagen je Stage-Event, Variablen, Vorschau |
|
||||
| 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
|
||||
- [ ] Eigene **`PortalUser`-Klasse strikt getrennt** von TenantUser (eigene Cookies/Routes, keine Permission-Vermischung); **Magic-Link primär**
|
||||
- [ ] Endkunde sieht **nur eigene Projekte / konfigurierte Stages / freigegebene Dokumente**; fehlender Zugang → **404** (keine Existenz-Offenlegung)
|
||||
- [ ] **Auto-Status-Mails** bei `project.stage_changed` (Debounce; Bedingungen: sichtbare Stage / aktiver Access / Pref / nicht frozen)
|
||||
- [ ] **Härtung:** Rate-Limits, Captcha, **kein User-Enumeration**, wasserdichte Cookie-Trennung
|
||||
- [ ] Wiederverwendung v1: Auth-Pattern (**parallel, NICHT geteilt**), Sende-Domain (Auto-Mails), `notify()`, Tenant-Lifecycle (`frozen`→read-only)
|
||||
- [ ] **RLS** auf allen Portal-Tabellen (über Tenant); Access-Filter serverseitig
|
||||
- [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
|
||||
- **Entities** (eigene `prisma/schema/customer-portal.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 Cookies, eigene Middleware-Kette unter `/portal/<tenant>/…`; Auth-Pattern aus v1 **kopiert, nicht geteilt** (kein Cross-Routing, keine Permission-Vermischung). Fehlender Zugang → 404 statt 403 (keine Enumeration).
|
||||
- **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; **RLS** auf Tenant-Tabellen; `is_demo_data` auf seedbaren Portal-Demos.
|
||||
- **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 · `PHASE-SOURCES.md` → Phase 26 (M141 Auth/Magic-Link, M142 Projekt-Sicht + Status-Mails)
|
||||
- `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)
|
||||
- `_bmad-output/specs/M15-customer-portal.md` (Portal)
|
||||
- `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.
|
||||
|
||||
## Dev-Nachzug (nach Davids `D-P26`-Delta)
|
||||
- [ ] Spec/ENTITY-MODEL an Davids UI-Entscheidungen angepasst
|
||||
- [ ] REQUIREMENTS/PHASE-SOURCES nachgezogen
|
||||
- [ ] Plane-Ticket `VA-P26a` aktualisiert
|
||||
- [ ] 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.**
|
||||
Reference in new issue
Block a user