# 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.