Refresh HiveGrid Cloud reference snapshot

This commit is contained in:
david committed 2026-08-03 15:31:14 +02:00
1 parent 5e99e14772
commit 7f88026f79
5955 files changed
+1177325 -188362

No files matched your search

@@ -0,0 +1,243 @@
# R-UX3 · Personal: Rollenbasierten Mitarbeiter- und Verwaltungs-Hub überarbeiten
| | |
|---|---|
| **Typ** | Dev (UX-/Produkt-Nachzug) |
| **Owner** | Raffael |
| **Phase** | Querschnitt · Tenant UX |
| **Cycle/Fenster** | noch nicht eingeplant |
| **Status** | umgesetzt · wartet auf lokale Gesamtabnahme |
| **Plane** | [HIVEGRID-202](https://project.tool-ctrl.de/toolctrl/projects/35d0d968-8ab3-40cc-97b8-b81d917dc5df/issues/51b1808b-6018-4e91-98d7-b62ec565549e) · Parent `HIVEGRID-199` |
🎨 **design-nachzug: offen** · AD-28-Interim-UI ist die verifizierte Abnahmebaseline.
## Abhängigkeiten & Parallelität
- **Baut auf:** `AK-P17a` (Stammdaten, Dokumente, Standorte) und `AK-P17b`
(Urlaub/Krank, Announcements, Lohn, Anträge, Surveys).
- **Design-Bezug:** `D-HR`; finales Delta ist nach AD-28 kein Hard-Blocker.
- **Verträge zu schützen:** `AK-P16c`/M05-Form-Renderer, `AK-P4b`/Files,
Rollen-/Permission-Verträge aus P2 sowie P9-/P15-Integrationen.
- **Passwörter:** werden aus der Personal-Navigation herausgelöst und ausschließlich in `R-UX4`
fachlich weiterentwickelt.
- **Hard-Block vor Umsetzung:** aktuelle Objektberechtigungen, Teamzuordnung und RLS-Policies aus
beiden P17-Tickets erneut gegen Code und Plane prüfen.
## Zielnutzer und Hauptaufgaben
| Nutzer | Hauptaufgabe |
|---|---|
| Mitarbeitende | eigene Anträge, Meldungen, Dokumente und Mitteilungen erledigen |
| Teamleitung | nur das eigene Team sehen und definierte Genehmigungen bearbeiten |
| Personalverwaltung | Mitarbeitende, Dokumente, Vorlagen und Prozesse administrieren |
| Tenant-Admin | Rollen und Module verwalten, ohne automatisch sensible HR-Daten zu erhalten |
## Belegter Ist-Flow
1. Bis zu elf gleichrangige Navigationseinträge konkurrieren miteinander; der Hub ist vor allem
eine Linksammlung.
2. Es fehlt eine klare Teamleitungsfläche zwischen „meine Daten“ und tenantweiter Verwaltung.
3. `canViewAdmin` und ähnliche Fähigkeiten werden nicht durchgängig in die UI-Struktur übersetzt.
4. Auswahl-/Detail-Flows zeigen rohe IDs oder tote Links.
5. Krankmeldung, Urlaub, Announcement-/Survey-Audience und Teamansichten haben
Objektberechtigungsrisiken bei direkt übergebenen IDs oder URLs.
6. Team-Abwesenheiten können tenantweit statt teambegrenzt erscheinen.
7. Personaldokumente können ohne atomare `FileEntityLink`-Zuordnung entstehen.
8. Tenant-Administration wird zu leicht mit HR-Vollzugriff gleichgesetzt.
## Freigegebener Ziel-Flow
1. Einstieg **Personal** zeigt zuerst offene Aufgaben und drei rollenabhängige Bereiche:
**Für mich / Mein Team / Verwaltung**.
2. „Für mich“ bündelt eigene Anträge, Krankmeldung, Dokumente, Lohnabrechnungen,
Announcements und Surveys.
3. „Mein Team“ zeigt nur direkte/zugewiesene Teammitglieder, offene Genehmigungen und erlaubte
Abwesenheitsinformationen.
4. „Verwaltung“ enthält Stammdaten, Standorte, Dokumente, Uploads, Vorlagen und Auswertungen nur
bei einzelnen HR-Rechten.
5. Urlaub, Krankmeldung und Anträge verwenden den bestehenden M05-Renderer statt paralleler
Formularlogik.
6. Auswahlfelder zeigen Namen, Team und Rolle; Detail-/Historienseiten haben echte Ziele.
7. Passwörter erscheinen als eigener Hauptbereich und nicht mehr in Personal.
## Vorher/Nachher
| Vorher | Nachher |
|---|---|
| viele gleichrangige HR-Links | Aufgabenhub plus Für mich / Mein Team / Verwaltung |
| Tenant-Admin impliziert HR-Nähe | einzelne HR-Rechte, sensible Daten separat |
| tenantweite Teamlisten | serverseitig begrenzte Team-Sicht |
| rohe User-/File-IDs | Comboboxen, Namen, atomare Verknüpfungen |
| parallele Übergangsformulare | Wiederverwendung des M05-Renderers |
| Passwort-Safe unter HR | eigenständiger Bereich `R-UX4` |
## Screen- und Komponentenmatrix
| Screen | Kernaufgabe | Vorhandene Bausteine |
|---|---|---|
| Personal-Hub `/hr` | offene Aufgaben und richtige Einstiege | `PageShell`, Header, Tabs, Task-Cards, Status-Badges |
| Für mich | eigene Prozesse | Cards/Listen, M05-Renderer, Upload, Detail/Activity |
| Mein Team | Genehmigungen und erlaubte Teamübersicht | Filter, `Table`, mobile Cards, Status, Dialog |
| Verwaltung | Mitarbeitende und HR-Konfiguration | Tabellen, Search, Combobox, Drawer/Dialog, Upload |
| Mitarbeitenden-Detail | öffentliche vs. sensible Daten | Tabs, Cards, Files, Activity, permission-aware Sections |
Die `/forms`-Richtung gilt für Header, klare Tabs, Filter/Search, responsive Tabellen/Karten,
Editor-/Save-Zustände und vollständige States. Kein Screen rendert eine zweite App-Sidebar.
## Actions und erwartete Ergebnisse
| Action | Serverprüfung | Sichtbares Ergebnis |
|---|---|---|
| `submitLeave` / `submitSick` | self oder explizites Büro-Recht, Zielperson erlaubt, M05-Validierung | Antrag/Meldung mit Status und nächstem Schritt |
| `decideRequest` | zugewiesene Genehmigung oder HR-Recht | Entscheidung, Begründung, Activity/Notification |
| `publishAnnouncement` | HR-Kommunikationsrecht und erlaubte Audience | sichtbare Zielgruppe in Klartext |
| `publishSurvey` | Survey-Recht und erlaubte Audience | Teilnahmeziel und Anonymitätsstatus |
| `uploadEmployeeFile` | Dateirecht, Zielperson im Scope, atomare File-Verknüpfung | Dokument direkt im richtigen Profil |
| `updateEmployee` | Feldrecht und Objektzugriff | geänderte, auditierte Daten |
## Rollen und Berechtigungen
| Bereich | Mitarbeitende | Teamleitung | Personalverwaltung | Tenant-Admin |
|---|---|---|---|---|
| Für mich | eigene Daten | eigene Daten | eigene Daten | eigene Daten |
| Mein Team | nein | nur zugewiesenes Team | laut Team-/HR-Recht | nicht automatisch |
| Verwaltung | nein | nein, außer Einzelrecht | nach granularen HR-Rechten | nicht automatisch |
| AU/Lohn/Notfallkontakt | nur eigene erlaubte Daten | keine Details ohne Sonderrecht | nach sensiblem Einzelrecht | nicht automatisch |
Objektprüfung gilt zusätzlich zur App-Permission: Zielperson, Team, Audience, Genehmiger,
Dokumentverknüpfung und Direkt-URL werden serverseitig geprüft. Nicht sichtbare Objekte liefern 404.
## Mobile-Verhalten
- Personal-Hub priorisiert „Krank melden“, „Urlaub beantragen“ und offene Aufgaben.
- Tabs bleiben als kurze Segmente oder mobile Unterseiten verständlich.
- Team- und Mitarbeitendenlisten werden zu Karten; sensible Werte erscheinen nie in der Vorschau.
- Genehmigen/Ablehnen/Rückfrage bleibt mit Tastatur und Touch erreichbar und verlangt bei
irreversiblen Folgen eine Bestätigung.
- Uploads zeigen Fortschritt, Scanstatus und klare Wiederholen-Aktion.
## Loading-, Empty-, Fehler- und Erfolgszustände
- **Für mich leer:** keine offenen Aufgaben, nächste sinnvolle Aktion.
- **Mein Team leer:** kein zugeordnetes Team oder keine offenen Genehmigungen, klar unterschieden.
- **Verwaltung gesperrt:** Navigation fehlt; Direktaufruf 404.
- **Upload:** ausgewählt, lädt, geprüft, fehlgeschlagen, verknüpft.
- **Konflikt:** Antrag wurde bereits entschieden; aktueller Status mit Reload.
- **Sensible Daten:** gesperrte Sektion wird nicht mit Platzhaltern geleakt.
- **Erfolg:** Status, nächste Instanz und direkter Detail-/Historienlink.
## View-Models und Actions
- Hub-VM gruppiert sichtbare Bereiche und offene Aufgaben in `forMe`, `myTeam`, `administration`.
- Jede Section erhält serverseitig `visible`, `count`, `items`, `allowedActions`; UI leitet
Permission nicht aus Rollenbezeichnungen ab.
- Employee-Detail-VM trennt öffentliche Profildaten, Self-Felder und sensible HR-Sektionen.
- Team-VM wird serverseitig aus tatsächlicher Team-/Genehmigerzuordnung gebaut.
- M05-Submission-VM und Actions werden wiederverwendet; keine zweite Leave-/Sick-/Request-
Formularengine.
- Routes injizieren VMs und Callbacks; Screens enthalten keine DB-, Permission- oder
Audience-Logik.
## Daten, RLS und Querschnitt
- Bestehendes `hr.prisma` und File-Modelle nutzen; neue Fachmodelle nur typisiert.
- File-Upload und `FileEntityLink` entstehen atomar bzw. mit sauberem Compensating Cleanup.
- Forced-RLS-Tests decken Self, Teamleitung, HR-Einzelrecht, Tenant-Admin ohne HR-Recht,
Cross-Tenant-ID und direkte Audience-URL ab.
- Alle Änderungen an Personal-, Antrag-, Dokument-, Audience- und Genehmigungsdaten werden
auditiert; relevante Vorgänge erzeugen Activity/Notification.
- Mitarbeitenden- und Dokumentensuche nutzt die zentrale Search-Registry mit Permission-Filter.
- Sensible Dateien folgen AV fail-closed und vorhandener Verschlüsselung/Audit-Logik.
## Priorisierung
| Priorität | Inhalt |
|---|---|
| P0 | Objektberechtigungen, Audience-Gates, Team-Scope, atomare File-Verknüpfung, Tenant-Admin≠HR |
| P1 | Für mich/Mein Team/Verwaltung, Aufgabenhub, M05-Reuse, benannte Picker, Detail/History, Mobile/States |
| P2 | Komfortauswertungen nur aus beauftragten P17-Daten und Rechten |
## Definition of Done
| Status | Fertigkeitskriterium | Proof | Zählt nicht als fertig |
|---|---|---|---|
| [x] | Personal nutzt die rollenabhängige IA Für mich / Mein Team / Verwaltung. | VM-/Visual-/Navigationstest | drei Tabs für jeden User sichtbar |
| [x] | Passwörter sind aus Personal entfernt und auf `R-UX4` verlinkt/umgeleitet. | Sidebar-/Route-Test | zusätzlicher Link bei weiter bestehendem HR-Safe |
| [x] | Tenant-Admin erhält ohne Einzelrecht keinen HR-Vollzugriff. | Permission-/Forced-RLS-Test | UI-Sektion nur verborgen |
| [x] | Self-, Büro- und Genehmiger-Actions prüfen Zielperson und Objektzugriff. | Action-/IDOR-Tests | nur Formularfeld read-only |
| [x] | Teamansichten enthalten ausschließlich das erlaubte Team. | Forced-RLS-/VM-Test | tenantweite Query mit Clientfilter |
| [x] | Announcement-/Survey-Audiences sind bei Loader und Action serverseitig geschützt. | Direkt-URL-/Action-Test | nur Editor-Dropdown gegated |
| [x] | Personaldokumente werden atomar zur richtigen Person verknüpft. | Integration-/Rollback-Test | File ohne `FileEntityLink` |
| [x] | Urlaub, Krankmeldung und Anträge verwenden den M05-Vertrag. | Contract-/E2E-Test | optisch ähnliches Parallelformular |
| [x] | Picker und Links zeigen Namen/Kontext und keine IDs oder toten Ziele. | UI-Text-/Link-Test | UUID als versteckter Hilfetext |
| [x] | Audit, Activity, Notification und Search sind permission-aware verdrahtet. | Integrationstest | nur Audit-Middleware ohne Fachereignis |
| [x] | Loading-, Empty-, Fehler-, Konflikt-, Upload- und Erfolgszustände sind vollständig. | Component-/Visual-Test | leerer Spinner |
| [x] | Desktop/Mobile, Tastatur, Accessibility und deutsche i18n sind verifiziert. | Visual + a11y + i18n | Desktop-only Happy Path |
| [x] | VM-, Action-, Permission- und Forced-RLS-Tests sind grün. | Testprotokoll | DB-Mock ohne Policy-Semantik |
| [x] | Playwright-Hauptflows, Interim-Visuals und Hot-Swap sind grün. | CI-Artefakte | Hub öffnet nur ohne Hauptaktion |
## Rollout und Rollback
- P0-Rechte zuerst hinter internen Testrollen verifizieren.
- Neue IA tenantweise aktivieren; bestehende Deep Links erhalten Redirects oder stabile Ziele.
- Metriken: Zeit bis Antrag, Abbruchquote, Genehmigungsdauer, 404/Permission-Fehler,
unzugeordnete Dokumente und Supportfälle je Bereich.
- Rollback schaltet neue Hub-Komposition ab; bestehende P17-Daten und Aktionen bleiben erhalten.
File-/Permission-Schemaänderungen sind forward-only und dokumentieren Inverse-SQL.
## Abgrenzung
Keine neue Plantafel, kein Chat/Call-System, kein Onboarding-Drittanbieter, kein Web-Push,
keine allgemeine Dokumentenplattform. Passwörter werden ausschließlich in `R-UX4` ausgebaut.
## Quellen
- [`R-UX0`](R-UX0.md)
- `AK-P17a`, `AK-P17b`, `D-HR`, `AK-P16c`, `AK-P4b`
- `.planning/ENTITY-MODEL.md` · HR-Domäne
- `.planning/INTERIM-UI-PLAYBOOK.md`
- `/forms`: Header, Tabs, Filter/Search, responsive States und Save-Muster
- bestehende HR-Routes, Services, View-Models, Actions und Tests
## Planungsnotiz
**2026-07-25:** Umsetzungsreife UX-Spec nach Freigabe angelegt.
**2026-07-25 · Umsetzungs-Proof:** Der rollenabhängige Personal-Hub wurde mit den Commits
`339262115`, `dd6cf7aeb`, `be27a8c4f` und `39297fb01` umgesetzt. PR
[#249](https://git.tool-ctrl.de/toolctrl-labs/HiveGrid-Cloud/pulls/249) bleibt bis zur lokalen
Gesamtabnahme offen.
- Permission-/RLS-Proof: Self-, Direktbericht-, Genehmiger-, Audience- und granulare HR-Rechte
werden serverseitig auf Objekt und Tenant geprüft; ein Tenant-Admin erhält ohne HR-Einzelrecht
keinen Personalvollzugriff. Direkt-URLs und fremde Zielpersonen liefern 404.
- Workflow-/Daten-Proof: Für mich, Mein Team und Verwaltung entstehen aus einem serverseitigen
Hub-VM. Urlaub, Krankmeldung und Anträge nutzen den vorhandenen M05-Vertrag. Upload und
`FileEntityLink` werden atomar bzw. mit Compensating Cleanup gespeichert; Lohnabrechnungen
durchlaufen AV-Scan, Mitarbeiterprüfung, Activity, Notification und Audit.
- UX-Proof: benannte Mitarbeiter-Picker, auflösbare Detailziele, mobile Hub-/Team-/
Verwaltungsansichten und vollständige Empty-, Loading-, Fehler-, Upload- und Erfolgszustände.
Passwörter sind vollständig aus Personal entfernt und über den eigenständigen R-UX4-Bereich
erreichbar.
- Search-/Querschnitt-Proof: Mitarbeitende sind ohne sensible Felder in der zentralen
Search-Registry registriert. Tenantweite Ergebnisse verlangen `hr.read_all`; `hr.read_own`
beschränkt SQL-Fallback und Revalidierung auf die eigene Person und direkte Berichte.
- Test-Proof: `pnpm typecheck`, `pnpm lint`, `pnpm test` (1.057 Testdateien / 7.531 Tests),
`verify:i18n`, `verify:sidebar-routes`, `verify:tenant-policy-contract` (301/301),
`verify:permissions-audit-baseline`, `verify:ui-visual`, `test:hot-swap`,
`verify:a11y-coverage`, 42 gezielte Payslip-/Search-/Visual-/Accessibility-Tests sowie beide
kompilierten Playwright-Smokes sind lokal grün. Der vollständige
[PR-CI-Lauf 11185](https://git.tool-ctrl.de/toolctrl-labs/HiveGrid-Cloud/actions/runs/11185)
ist mit allen elf Jobs einschließlich Docker-Smoke, Database Checks und Typecheck/Tests grün.
- Interim-Baseline:
`apps/web/app/components/screens/hr/__snapshots__/personnel-interim.visual.test.tsx.snap`;
die finale Subframe-Optik bleibt als `design-nachzug` offen und blockiert Done nach AD-28
nicht.
- Bekannte Main-Baseline: `pnpm run verify:permission-matrix` referenziert weiterhin drei vor
diesem Ticket nach `settings/compliance/` verschobene Testpfade unter `settings/logs/`.
Die verifier-eigenen Permission-Audit-Tests und alle ticketbezogenen Permission-, IDOR- und
Forced-RLS-Tests sind grün. Dieser scope-fremde Baseline-Nachzug wird auf R-UX3 nicht still
geändert.
**Stand: 14/14 DoD = 100 % done.** Keine selbst machbaren Punkte offen; Ticket und Plane bleiben
bis zur lokalen Gesamtabnahme auf In Progress.