Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/.planning/ticket-docs/VA-P26b.md
T

16 KiB

VA-P26b · P26 Customer-Portal: Upload/Reklamation + Subunternehmer/Skalierung/DSGVO ⭐

Typ Dev (Code)
Owner Akeshan
Phase P26 — Customer-Portal · v2-P6 (ex-P18)
Cycle/Fenster lokale Vorarbeit seit 2026-07-16 · technischer Handoff am 2026-07-21 erfüllt
Status technisch vollständig · Plane Done · 6/6 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 Grundlage: VA-P26a (Portal-Auth-Schicht + PortalUser + Projekt-Sicht) wurde am 2026-07-21 mit 8/8 DoD technisch abgenommen.
  • Blocks: keine offene Abhängigkeit; der Portal-Funktionsvertrag für VJ-3 ist erfüllt.
  • Läuft parallel zu: dann laufender Arbeit in disjunkten Domänen. Das Ticket erweitert das von VA-P26a recuttete prisma/schema/portals.prisma additiv und nutzt dessen separat deployte hivegrid-portal-Runtime; keine eigene zweite Runtime in diesem Ticket.
  • Konflikt-Risiko: gering — additiv auf der bereits getrennten Portal-Auth-Schicht aus VA-P26a.

Termin-Auswirkung 2026-07-15: VA-P26a wurde wegen des neuen Runtime-/Deploy-/Live-RLS-Slices bis 05.08.2026 retimiert. Die lokale, nicht aktivierende Vorarbeit läuft seit 16.07. auf dem gemeinsamen Branch; Plane-Start und formaler Handoff bleiben auf frühestens 06.08. terminiert und werden nach dem stabilen Auth-/RLS-Handoff neu festgelegt. Scope und Owner bleiben unverändert.

Produktfreigabe 2026-07-16: Die VA-P26a-Grundlage darf vorher auf Staging laufen. Das Customer-Portal wird aber erst nach vollständigem Abschluss dieses Tickets öffentlich buchbar/freigeschaltet, damit Workspace-Admin-Verwaltung, Upload/Reklamation und DSGVO-Flows beim Produktstart vorhanden sind.

Umsetzungs-Notiz

2026-07-16 · Raffael · Repository-Proof: 18dfd4825 (Persistenz/RLS), 1b80b7d42 (Aktor-/Permission-/Automation-/VM-Verträge), 40cb27b8d (Upload, Forms und Portal-Routen), 76ad10bfe (Admin-Konfiguration und Service-Inbox), 84ac38a90 (DSGVO/Lifecycle) und 5dc3b01d7 (Interim-Visual-, Hot-Swap- und Smoke-Verträge). Der lokal und im Repository umsetzbare Interaktions-Slice ist vollständig aufgebaut. Upload und Reklamation erzwingen bis zu zehn Dateien, 50 MB Standard-/100 MB Absolutgrenze je Datei, erlaubte Bild-/PDF-/Office-/Audio-Typen, Quota-Reservation und ClamAV fail-closed. Die Browser-Stapelverarbeitung sendet bis zu zehn Dateien sequenziell mit stabilen Idempotenzschlüsseln; die DB-Reservation bindet Metadaten und SHA-256-Inhalt, damit ein Retry mit anderen Bytes fail-closed kollidiert. Erst nach sauberem Abschluss entstehen File-/Upload-/Link-Aktorattribution, Activity mit explizitem portalUserId-Metadatum, Service-Inbox und notify(). portal_form ist ausschließlich authentifiziert; der anonyme Embed-Pfad liefert dafür 404.

Subunternehmer-Zugänge sind projektgenau und von Endkunden sowie anderen Subunternehmern isoliert. Die persistente Sieben-Tage-Service-Inbox enthält Priorität, Routing, Owner/Status und 30-Minuten-Bündelung. Die Workspace-Admin-Konfiguration umfasst User/Access, Phasen-/Projekt-Typ-Sichtbarkeit, Auto-Freigabe, Rechtslink-Aktivierungsgate und den bestehenden Template-Editor. Export, 24-Stunden-Lösch-Widerruf, anschließende Anonymisierung, Session-/Token-/Access-Revoke sowie 12-/24- Monats-Lifecycle-Jobs verwenden die gemeinsamen Storage-, Queue-, Audit-, Activity-, Automation- und Notification-Verträge.

Lokaler Proof: Die Actor-Invarianten für File, FileUpload, FileEntityLink und FormSubmission sind in vier validierten Checks grün. 22/22 Portal-Live-Postgres-Tests (P26a-Basis 14/14, P26b-Slice 7/7, schmaler Custom-Host-Resolver 1/1) mit hivegrid_portal beweisen PortalUser A/B, Tenant A/B, Customer/Subunternehmer, active/revoked, Frozen read/write sowie schmale Upload-/Reklamations-Capabilities ohne synthetischen TenantUser. Der gesamte frische PG16- Feature-Overlay-Lauf ist mit 68/68 Tests grün; er ersetzt weiterhin keine Merge-Migration. Die vollständige portal.*-Automation-Registry mit sechs Aktionen, DB-autoritativem Auto-Release, Lineage-/5-in-60-Sekunden-Grenze, inneren Frozen-/Permission-Rechecks und dauerhaften Fehlerdiagnosen ist im fokussierten 104/104-Lauf grün. VM-/Route-/Lifecycle-/Worker-/UI-, a11y-, Hot-Swap- und Interim-Visual-Verträge sind lokal grün; die AD-28-Matrix umfasst 57/57 Prüfungen und vier Component-Reisen. Vier Browser-E2E-Reisen sind für Staging registriert, aber nicht als Live-Lauf gewertet. Admin-Loader serialisieren User-/Access-/Inbox-Daten nur mit der jeweils schmalen Permission; Membership-/Permission-404 wird vor CSRF- und Payload-Validierung geprüft. Der Design-Nachzug VD-P26 bleibt offen.

Stand 2026-07-16: VA-P26b: 5/6 DoD = ~83 % done · offen: der strikte sechste Portal-RLS- Abschluss über die echte P26-Merge-Migration, migration-only Parität und eingeschränkten Staging-Proof. Das Ticket bleibt formal durch VA-P26a blockiert und wird nicht auf Done gesetzt. Es wurde kein Migrationsfile angelegt, kein Staging- oder Produktionssystem verwendet und keine öffentliche Produktfreigabe vorgenommen.

Live-Deploy-Proof

2026-07-16 · Raffael: Die gemeinsame P26-Migration prisma/migrations/20260716123000_va_p26_customer_portal/migration.sql wurde mit PR #125 gemergt. Nach den Deploy-Hotfixes #130 und #132 lief Deploy #10300 für Revision f54b04162b2823b1d2f6db0318baf1a7431c5b66 vollständig grün. Migration-Chain-Parität, Tenant-Policy-Vertrag, RLS-Release-Readiness, Live-RLS-Isolation sowie Portal-Health und -Readiness bestanden mit der eingeschränkten hivegrid_portal-Rolle über PgBouncer.

Damit ist auch der geerbte Portal-RLS-Punkt technisch erfüllt: 6/6 DoD = 100 % done. Das Ticket bleibt dennoch im Plane-Backlog und formal durch den noch offenen VA-P26a-Staging-Klickpfad/UAT blockiert; es wurde keine öffentliche Produktfreigabe erklärt. Die vier registrierten Browser-E2E- Reisen gegen eine echte UAT-Fixture und der User-Sign-off bleiben der formale Handoff, nicht ein erneut offenes Repository- oder RLS-Gate.

M006-Abhängigkeits-Nachtrag

2026-07-18 · Raffael: VA-P26b erbt mit Commit 6d96b7928 den globalen customer-portal-Schalter aus VA-P26a; es entsteht keine zweite Flag. Bei Disable liefern öffentliche Upload-/Reklamations-/ Account-Flows 404. Workspace-Admin-Konfiguration, Inbox und Template-Editor werden verborgen beziehungsweise direkt mit 404 abgewiesen. portal.*-Automation, Action-Writes, Auto-Release sowie bereits eingereihte Portal-Auth-/Status-Mails werden fail-closed unterdrückt. Separate DSGVO-/ Retention-Maintenance wird durch diesen Diff nicht als abgeschaltet behauptet.

Der technische Stand bleibt 6/6 DoD = 100 % done; Plane-Backlog und formaler VA-P26a-UAT-/Handoff-Block bleiben unverändert.

Abhängigkeits-Nachtrag 2026-07-18: VA-P26a wurde nach dem Produktvertrags-Abgleich um den expliziten Einladungs-Lifecycle erweitert. Der technische VA-P26b-Stand bleibt 6/6 DoD = 100 % done; der formale Handoff wartet nun zusätzlich auf die einlösbare Setup-Mail, Datenschutzannahme und die drei fachlichen Einladungseinstiege aus VA-P26a. Es entsteht kein zweiter Invite-Service in diesem Ticket.

RLS-Overlay-Korrektur 2026-07-18: Run #10519 hat im gemeinsamen Standalone-Overlay einen ungültigen token-Alias im E-Mail-Resolver aus VA-P26a gefunden. Die Korrektur stellt ausschließlich den bereits migrationsgebundenen invited-/active-Statusvertrag wieder her. Upload-, Reklamations-, Lifecycle- und Actor-Verträge dieses Tickets ändern sich nicht; VA-P26b bleibt 6/6 DoD = 100 % done und formal bis zum VA-P26a-UAT blockiert.

Staging-UAT-Abschluss

2026-07-21 · Raffael: Der formale VA-P26a-Handoff ist erfüllt. Die fünf Staging-Reisen für Upload, Reklamation, Subunternehmer-Zugang, Service-Inbox und DSGVO-Export/-Löschung liefen ohne Skip. Der eingeschränkte Portal-RLS-Vertrag wies fremde PortalUser, fremde Tenants und unzulässige Rollen weiterhin fail-closed ab. Core und Portal liefen dabei auf Merge-Revision a747e9c655b2be4bd9ba52e59f56d5f0e9d145b0 und demselben Registry-Digest; Produktion blieb unangetastet.

Abschlussstand: VA-P26b: 6/6 DoD = 100 % done. Der Funktions-Handoff an VJ-3 ist erfüllt. VD-P26 bleibt als Design-Nachzug offen und ist kein technischer Done-Blocker.

UI-/UX-Nachtrag

2026-07-22 · Raffael: PR #212 hat die ausgelieferten P26b-Reisen innerhalb der gemeinsamen HiveGrid-Portal-Shell neu geordnet. Projekt-Tabs überlagern keine Inhalte mehr; Fortschritt, Dateien und Anliegen besitzen eine klare Hierarchie. Der Upload zeigt Dateiauswahl, primäre Aktion, Limits und bisherige Uploads kompakt statt als großflächige Formularstrecke. Settings, DSGVO-Export und Kontolöschung bleiben fachlich unverändert, sind aber visuell entzerrt.

Die neuen Interaction-, Visual-, A11y-, i18n- und Hot-Swap-Verträge waren zusammen mit 13/13 PR-CI-Jobs grün. Staging-Deploy #11018 rollte die Main-Revision 090e2558a6965e1c5804eb24d3eab5da8c8611a8 erfolgreich aus. Details stehen in docs/features/customer-portal.md.

Der Nachtrag erweitert keinen Ticket-Scope: VA-P26b bleibt 6/6 = 100 % done; VD-P26 bleibt offen.

Was wir bauen

Den Skalierungs- und Endkunden-Interaktions-Teil des Customer-Portals (⭐ externer Polish): Endkunden laden Dateien hoch (mobile Kamera, Multi-File) → Files + Activity + Projektleiter-Notification, und melden Reklamationen. Subunternehmer erhalten Zugang (M144), eine Skalierungs-Sicht/Service-Inbox (M145) bündelt eingehende Portal-Aktivität. Der Workspace-Admin konfiguriert Phasen-Sichtbarkeit und Dokument-Auto-Freigabe; der in VA-P26a bereits gelieferte Mail-Template-Editor wird in diese vollständige Portal-Konfiguration integriert, nicht erneut gebaut. DSGVO-Lösch/Export für PortalUser ist vorhanden (M146). PortalUser/Projekte sind nicht limitiert, aber Upload-/Speicher-/Mail-Limits des Basispakets bleiben serverseitig wirksam. Paket-Gates und Custom-Domain gehören separat zu VA-P26c.

Alle Endkunden-Routes dieses Tickets laufen ausschließlich in hivegrid-portal; Workspace-Admin-Konfiguration, Access-Matrix und Service-Inbox bleiben in hivegrid-web. Beide verwenden gemeinsame VM-/UI-/Domain-Verträge, aber keine geteilte Portal-/TenantUser-Session.

Benötigte Screens (Backend bedient — Design liefert VD-P26, externer Polish)

Screen [Route] Kern-Inhalt
Endkunde · Upload [portal.hivegrid.de/{tenant}/upload] Datei-Upload (mobile-Kamera, Multi-File, Basispaket-Limits) → Files + Activity + PL-Notification
Endkunde · Reklamation [portal.hivegrid.de/{tenant}/projects/:id] Reklamations-Formular (portal_form-Renderer)
Endkunde · Settings [portal.hivegrid.de/{tenant}/settings · /notifications · /account-delete] Profil, Benachrichtigungs-Präferenzen, DSGVO-Account-Löschung/Export
Workspace-Admin · Portal-Konfig, User und Access [app.hivegrid.de/{tenant}/settings/customer-portal] Phasen-/Projekt-Typ-Sichtbarkeit, Auto-Freigabe, Rechtslinks, PortalUser und Subunternehmer-Zugang
Workspace-Admin · Mail-Template-Editor [app.hivegrid.de/{tenant}/settings/customer-portal/email-templates] bestehender Editor für Status-Mail-Vorlagen und Testmail
Workspace-Admin · Skalierungs-Sicht/Service-Inbox [app.hivegrid.de/{tenant}/customer-portal/inbox] Eingehende Portal-Aktivität (Uploads/Reklamationen) gebündelt; separate interne Route

Definition of Done

  • Upload (mobile-Kamera, Multi-File, Limits aus Basispaket/Fair-Use) → Files + Activity + PL-Notification; Reklamation melden
  • Subunternehmer-Zugang (M144) + Skalierungs-Sicht/Service-Inbox (M145)
  • Tenant-Admin-Konfig (Phasen-Sichtbarkeit / Doc-Auto-Freigabe / Integration des in VA-P26a bereits gelieferten Mail-Template-Editors; kein zweiter Editor)
  • DSGVO-Lösch/Export für PortalUser + Lebensdauer-/Konfig-Verwaltung (M146)
  • Wiederverwendung v1: Files/FileEntityLink, Form-Builder (portal_form), Automation (portal.*), notify(), DSGVO-Lösch-Workflow
  • Portal-RLS geerbt: Alle Endkunden-Aktionen laufen als hivegrid_portal mit gebundenem app.portal_user_id + app.tenant_id und tabellenweiser Access-/Upload-/Form-Policy. Kein Fallback auf hivegrid_app, TenantUser oder synthetische interne User-ID; Frozen → Read-Only. Live-Postgres-Tests beweisen Cross-PortalUser-, Cross-Tenant- und Cross-Role-Denial. Abgehakt wird erst nach der reviewten forward-only P26-Merge-Migration, grüner migration-only Parität und dem eingeschränkten Staging-RLS-Proof; der 68/68-Feature-Overlay-Lauf, der Recut-Helper und prisma db push zählen ausdrücklich nicht als Abschluss.

Technische Bausteine

  • Entities (Delta auf prisma/schema/portals.prisma aus VA-P26a, AD-21): PortalUpload/-Verknüpfung über FileEntityLink, PortalComplaint (Reklamation, via portal_form-FormSubmission), PortalSubcontractorAccess (M144), Portal-Konfig (PortalStageVisibility erweitert, Doc-Auto-Freigabe-Regeln), DSGVO-Lösch-/Export-Record je PortalUser (M146). files.prisma/formWidget.prisma nur über FK.
  • Upload-Pipeline: mobile-Kamera-Capture + sequenzieller Multi-File-Stapel → @hivegrid/storage + FileEntityLink; File, FileUpload und FileEntityLink tragen den expliziten PortalUser-Aktor. Der gemeinsame Activity-Vertrag bleibt bei actor_kind=system und führt portalUserId im Metadatum; notify() geht an den Projektleiter.
  • Reklamation + Forms: v1-Form-Builder mit Subtype portal_form (FormSubmission + FormAction); Service-Inbox aggregiert Portal-Activity.
  • DSGVO: Lösch-/Export-Workflow für PortalUser über v1-DSGVO-Lösch-Workflow; Lebensdauer-/Konfig-Verwaltung (M146).
  • Härtung & RLS: Die Policy-Matrix und der PortalUser-/Tenant-Kontext aus VA-P26a werden für Upload, FormSubmission, Subunternehmerzugang und Portal-Lifecycle erweitert; generischer Tenant-Scope oder nur gemockte DB-Tests zählen nicht. Frozen→Read-Only respektieren; is_demo_data auf seedbaren Demos.
  • Runtime-Grenze: Portal-Upload/Reklamation akzeptiert ausschließlich den von VA-P26a gebundenen PortalUser-/Tenant-Kontext. Kein Fallback auf hivegrid_app, TenantUser oder synthetische interne User-ID; fremde App-/Admin-Hosts und interne Routen bleiben 404.

Quellen (granular)

  • ROADMAP-V2.md → §v2-P6 (Upload/Reklamation/Subunternehmer/Skalierung/DSGVO = Hauptquelle)
  • ENTITY-MODEL.md → Domäne 4 Files/FileEntityLink + Domäne 9 Forms (portal_form) + Domäne 13 DSGVO-Lösch-Workflow
  • ROADMAP.md → Phase 26 · Milestones: (M143 Upload/Reklamation, M144 Subunternehmer, M145 Skalierung/Service-Inbox, M146 Lebensdauer/DSGVO/Konfig)
  • designer-briefs/P26-customer-portal.md (⭐ externer Polish, Access-Matrix, DSGVO-Flow)
  • Querverweis: ticket-docs/VA-P26a.md (Portal-Auth-Schicht, auf der dies aufbaut)
  • docs/ARCHITECTURE-DECISIONS.md → AD-30 (unbegrenzte PortalUser/Projekte, Ressourcenlimits bleiben) · Querverweis ticket-docs/VA-P26c.md

Dev-Nachzug (nach Davids VD-P26-Delta)

Interim-UI (Vorschau, Stand 2026-07-16): Admin-, Interaktions-, Inbox- und Lifecycle-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-p26b-customer-portal-interim.snapshot.json. Proof: 57/57 lokale AD-28-Prüfungen und vier Component-Reisen; vier Browser-E2E-Reisen sind für Staging registriert, nicht live ausgeführt. Refactor-Nachzug: finale Subframe-Optik aus VD-P26 und Re-Baseline.

  • Spec/ENTITY-MODEL an Davids UI-Entscheidungen angepasst
  • REQUIREMENTS/ROADMAP nachgezogen
  • Plane-Ticket VA-P26b mit 5/6-Stand und dem offenen Merge-/Staging-RLS-Gate aktualisiert (031ff6ea-d040-4350-9226-71e652c1df63, 2026-07-16); Status bleibt Backlog
  • Plane-Ticket nach grünem Merge-/RLS-Gate auf technisch 6/6 und den formalen UAT-/Handoff-Block nachgezogen (2b9f81b1-ba45-423a-b254-ea7cbec7a0ca, 2026-07-16); Status bleibt Backlog

Abhängigkeitsnachzug · CR-007 · 2026-07-27

Portal-Interaktionen, Automationen und Status-Mails fragen kein globales customer-portal-Flag mehr ab. Fachliche Permission-, Frozen-, Zugriffs- und Idempotenzprüfungen bleiben unverändert.