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

201 lines
16 KiB
Markdown

# 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`](https://git.tool-ctrl.de/toolctrl-labs/HiveGrid-Cloud/actions/runs/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`](../../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
- [x] **Upload** (mobile-Kamera, Multi-File, Limits aus Basispaket/Fair-Use) → Files + **Activity** + **PL-Notification**; Reklamation melden
- [x] **Subunternehmer-Zugang** (M144) + **Skalierungs-Sicht/Service-Inbox** (M145)
- [x] **Tenant-Admin-Konfig** (Phasen-Sichtbarkeit / Doc-Auto-Freigabe / Integration des in `VA-P26a` bereits gelieferten Mail-Template-Editors; kein zweiter Editor)
- [x] **DSGVO-Lösch/Export für PortalUser** + Lebensdauer-/Konfig-Verwaltung (M146)
- [x] Wiederverwendung v1: Files/FileEntityLink, Form-Builder (`portal_form`), Automation (`portal.*`), `notify()`, DSGVO-Lösch-Workflow
- [x] **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
- [x] 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
- [x] 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.