201 lines
16 KiB
Markdown
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.
|