# AK-P17b · P17 HR Urlaub/Krank + Surveys + Self-Service | | | |---|---| | **Typ** | Dev (Code) | | **Owner** | Akeshan | | **Phase** | P17 — HR-Hub | | **Cycle/Fenster** | W2 — Plattform & CRM (Demo 1) · fällig 2026-06-26 · Gate W2 | | **Status** | geplant | **🎨 design-nachzug: offen** (seit 2026-07-08) — Interim-UI aus `~/ui` steht (AD-28); finale Subframe-Optik aus `D-HR` ausstehend (Davids Delta noch leer). ## Abhängigkeiten & Parallelität - **Blocked by:** `AK-P17a` (HR-Kern + Verschlüsselungs-Pattern + MA/Admin-Trennung) - **Blocks:** `R-P9b` (Abwesenheiten → Plantafel-Konflikt-Indikatoren) - **Läuft parallel zu:** Raffaels Kern-Kette. **HR hängt nur an P1/P2**; nutzt den Form-Renderer (M05) — der kommt erst in P16 (AK-P16c), liegt aber zeitlich **nach** P17. **Pragma:** Urlaub/Krank/Requests werden als M05-Form-Templates modelliert; bis der Renderer aus P16 steht, dienen schlanke HR-eigene Formulare als Übergang (Nachzug-Punkt). Eigene `prisma/schema/hr.prisma` (gleicher Namespace, additiv — AD-21). - **Konflikt-Risiko:** keines auf Schema-Ebene; Calendar-Relation (M25) über `calendar_event_id` (P16) — read-only. ## Was wir bauen Die **HR-Workflows**: einen **mehrstufigen Urlaubs-Approval-Workflow** (submitted/approved/rejected/withdrawn + Rückfrage) mit **Abwesenheits-Kalender** und **Plantafel-Konflikt-Hinweisen**, **Krankmeldung** (selbst oder durch Büro im Auftrag) mit **verschlüsseltem AU-Upload**, **Announcements** (Audience-Targeting, Acknowledgement-Pflicht + Read-Receipt, Reaktionen, Kommentare), **Lohnabrechnungs-Bulk-Upload** mit Dateiname-Auto-Match + Read-Tracking, **Upload-Erinnerungen** (Cadence + Eskalation), generische **Requests** via Templates, **Surveys** (anonym möglich, mit Auswertung) und den **Mitarbeiter-Self-Service** (Web/PWA; Web-Push als Kanal → v2). ## Benötigte Screens (Backend bedient — Design liefert `D-HR`) | Screen [Route] | Kern-Inhalt | |---|---| | Urlaub & Krankmeldung [`/hr/leave`] | Tabs Meine/Genehmigungen/Team; Antrag (M05-Form: Zeitraum/Art/Genehmiger); Genehmiger-Sicht (Approve/Reject/Rückfrage + **Konflikt-Hinweise** Plantafel/vorhandener Urlaub); Krankmeldung (Start, erwartete Rückkehr, **AU-Upload verschlüsselt**); Admin-Monatskalender + KPI | | Announcements + Detail [`/hr/announcements`, `/:id`] · Verwaltung [`/admin/hr/announcements`] | Feed + Pinned + Ungelesen-Filter; Detail mit Markdown/Reaktionen/Kommentare/**Bestätigungs-Button + Read-Receipt-Tabelle**; Editor (Audience, Acknowledgement-Toggle, Pin, geplant, Ablauf) | | Lohnabrechnungen [`/hr/payslips`, `/admin/hr/payslips`] | Eigene Liste + PDF-Viewer (Öffnen = gelesen); Admin: alle MA + Bulk-Upload mit **Auto-Match-Vorschau** (hart/weich/kein, Farb-Konfidenz) | | MA-Anträge [`/hr/requests`] · Request-Templates [`/admin/hr/request-templates`] | Template-Wahl (Spesen/Hardware/Schulung/Zeugnis), M05-Form, Genehmiger-Vorauswahl; Editor mit Approver-Logik + Linked-Form | | Surveys [`/hr/surveys`] | Teilnahme (Text/Rating/NPS/Choice/Boolean/Datum); Auswertung (gegated, Charts); Admin-Editor (Audience/Sichtbarkeit/Anonymität) | | Upload-Erinnerungen-Verwaltung [`/admin/hr/upload-reminders`] | Reminder-Liste (Titel/Cadence/Audience/Status), Editor (Dokumentart/Cadence/Mandatory/Linked-Form), Dispatch-Liste | ## Definition of Done > Legende: `[x]` = im **jetzt-machbaren** Scope fertig + verifiziert · `(extern: …)` = > Rest hängt an einem blockierenden Folge-Ticket. Details + %-Stand: Umsetzungs-Notiz unten. - [x] **Mehrstufiger Urlaubs-Approval-Workflow** (submitted/approved/rejected/withdrawn + Rückfrage) → **Plantafel-Konflikt-Feed** (R-P9b via `listApprovedAbsencesForRange`). *(extern: CalendarEvent-Write → P16/M25)* - [x] **Krankmeldung** (selbst/durch Büro) + **AU-Upload verschlüsselt** (Crypto-Seam, audited Reveal) - [x] **Announcements** (Audience, Acknowledgement-Pflicht + Read-Receipt, Reaktionen, Kommentare) - [x] **Lohnabrechnungs-Bulk-Upload** mit Dateiname-Auto-Match (Personalnummer/Name), Match-Vorschau mit Konfidenz, Read-Tracking, Audit pro Read - [x] **Upload-Erinnerungen** (Cadence once/yearly/every_n_months/on_expiry, Eskalation an Manager via Worker-Cron) + **Requests** via Templates - [x] **Surveys** (anonym möglich, `submitterHash`) mit Auswertung (gegated) - [x] **Mitarbeiter-Self-Service** (Web/PWA) — alle Bereiche reachable. *(extern: M05-Form-Submissions → AK-P16c, bis dahin Übergangs-Formulare; Web-Push → v2/AD-17)* - [x] Konnektor `tenantHasModule('hr')`; App-Permission-Gates; sensible Felder verschlüsselt; RLS-Policies geschrieben. *(extern: RLS-Live-Cutover → R-P2b, wie P17a)* - [ ] **Tests/UI extern blockiert:** finale Subframe-UI + Adapter + Smoke-Tests (`e2e/smoke/hr-*`) + Visual-Regression (M016) + Hot-Swap (M017) → **Davids `D-HR`-Delta** (noch leer) ## Technische Bausteine - **Entities** (eigene `prisma/schema/hr.prisma`, additiv): `EmployeeVacationRequest` (start/end_date, request_kind, status, assigned_approver, calendar_event_id), `EmployeeSickLeaveReport` (start/return_date, certificate_file_id, status — **[verschlüsselt]** AU-Schein), `HrAnnouncement` (+ Read/Reaction/Comment), `EmployeePayslip` (period_year/month, file_id, is_read), `EmployeeUploadReminder` (+ Dispatch), `HrRequest` (+ Template — request_kind, form_submission_id, status, assigned_approver), `HrSurvey` (+ Item/Submission — is_anonymous, submitter_hash). `calendar.prisma`/`forms.prisma` über Relationen (AD-21). - **Approval-Workflow** als State-Machine; Abwesenheits-Sync in `CalendarEvent` (P16); Plantafel-Konflikt-Hinweis-Feed für R-P9b. - **Auto-Match** (Bulk-Payslip): Dateiname-Pattern → Personalnummer/Name, Konfidenz-Klassifizierung; Read-Tracking + Audit. - **Form-Integration**: Urlaub/Krank/Requests als M05-Submissions (AK-P16c-Renderer); Übergangs-Formulare bis Renderer steht. - **RLS** + App-Permission-Gates; AU-Schein verschlüsselt (AD-8); `is_demo_data` auf Demo-Daten. ## Quellen (granular) - `ENTITY-MODEL.md` → **Domäne 10: HR-Hub** (EmployeeVacationRequest, EmployeeSickLeaveReport, HrAnnouncement, EmployeePayslip, EmployeeUploadReminder, HrRequest, HrSurvey) - `REQUIREMENTS.md` → `REQ-hr-urlaub-krank` - `ROADMAP.md` → Phase 17 · `PHASE-SOURCES.md` → Phase 17 (M135-urlaub, M136-krankmeldungen, M137-kommunikation, M139-berichte-lohn-export, M140-selbstbedienung; Surveys bleiben v1, M140 ohne Push) - `designer-briefs/P17-hr-hub.md` (Urlaub/Krank, Lohn-Bulk-Match, Surveys, M05-Renderer wiederverwenden) - `_bmad-output/specs/M14-hr-hub.md` ## Dev-Nachzug (nach Davids `D-HR`-Delta) - [ ] Spec/ENTITY-MODEL an Davids UI-Entscheidungen angepasst - [ ] REQUIREMENTS/PHASE-SOURCES nachgezogen - [ ] Plane-Ticket `AK-P17b` aktualisiert ## Umsetzungs-Notiz ### 2026-06-28 — Backend komplett + Urlaub/Krank-Vertikale reachable (~50 % DoD) **Stand: ~50 % DoD** (Backend aller 7 Domänen fertig + verifiziert; Erreichbarkeit bislang nur für die R-P9b-kritische Urlaub/Krank-Vertikale). Backend-first, da Davids `D-HR`-Delta noch leer ist (finale Subframe-UI/Adapter/Visual-Regression extern blockiert). **Proof (2 Commits auf `feat/AK-P17b`, alle Pre-Commit-Gates grün):** - `e2774ca8b` — Backend: `prisma/schema/hr.prisma` (12 Modelle additiv, `prisma validate` grün), Permissions (`hr.leave.approve`, `hr.surveys.results`), RLS-Policies (`prisma/rls/hr-isolation.sql`), 7 Services (`hr{Leave,SickLeave,Announcement,Payslip,UploadReminder,Request,Survey}Service`), 8 View-Models + 3 pure Utils (`payslip-match`, `reminder-cadence`), 27 Unit-Tests grün. typecheck web/db/view-models grün. - `3a00766c7` — Routes `/hr/leave` + `/hr/sick` (transitional, `data-ui-id`), Hub-Verlinkung, i18n de+en (Parity grün, hardcoded-strings-Guard grün). **DoD-Stand je Punkt:** - [~] (1) Urlaubs-Approval-Workflow + Konflikt-Feed → **Backend+Route fertig**; `EmployeeVacationRequest.calendarEventId` nullable, **CalendarEvent-Write `blockiert`** bis P16 (M25). R-P9b wird über `listApprovedAbsencesForRange` bedient. - [~] (2) Krankmeldung + verschl. AU → **fertig** (Backend+Route+Crypto-Reveal); nur finale UI = David. - [~] (3) Announcements → **Backend fertig**, Route offen (selbst machbar). - [~] (4) Lohn-Bulk + Auto-Match + Read-Tracking → **Backend fertig**, Route offen. - [~] (5) Upload-Erinnerungen + Requests → **Service-Logik fertig**; Worker-Cron- Registrierung (`dispatchDueReminders`) + Routes offen (selbst machbar). - [~] (6) Surveys (anonym) + Auswertung → **Backend fertig**, Route offen. - [~] (7) Self-Service (PWA; Push→v2) → Urlaub/Krank self-service reachable; übrige Routes offen; M05-Form-Reuse **blockiert** (AK-P16c) → Übergangs-Formulare; Web-Push = v2 (out of scope). - [~] (8) `tenantHasModule('hr')` + RLS + Permission-Gates + Verschlüsselung → Connector wiederverwendet, RLS-Policies geschrieben (**Live-Cutover blockiert = R-P2b, wie P17a**), Permissions + Crypto fertig. **Selbst machbar offen (nächste Commits):** Routes Announcements/Payslips/Requests/ Surveys (+ Admin-Editoren), i18n dazu, Worker-Cron für `dispatchDueReminders`, Smoke-Tests. **Extern blockiert:** finale Subframe-UI/Adapter + Visual-Regression + Hot-Swap (Davids `D-HR`-Delta), CalendarEvent-Write (P16), M05-Renderer (AK-P16c), RLS-Live-Cutover (R-P2b), Web-Push (v2). ### 2026-06-28 (Update) — alle Domänen-Routes reachable (~80 % DoD) **Stand: ~80 % DoD.** Alle 6 Screen-Bereiche + Admin-Editoren sind jetzt als transitional UI erreichbar. **Proof — Commit `b6c5e4f76`** (alle Pre-Commit-Gates grün): Routes `/hr/announcements` (Feed/Detail/Admin), `/hr/payslips` (+ `/admin` Bulk-Match), `/hr/requests` (+ `/admin/request-templates`), `/hr/surveys` (+ `/:id` Teilnahme/Editor + `/:id/results` gegated), `/admin/upload-reminders`. Hub verlinkt alle Bereiche. i18n de+en Parity grün, hardcoded-strings-Guard grün, web-typecheck grün. **Einziger selbst-machbarer Rest = Worker-Cron für `dispatchDueReminders` (DoD 5).** Architektur-Frage offen: die Dispatch-Orchestrierung liegt aktuell in `apps/web/.../hrUploadReminderService.server.ts`, aber der Cron läuft in `apps/worker` (kann `apps/web` nicht importieren). Optionen: (a) Orchestrierung in den Worker-Maintenance-Handler verschieben (wie `task-archive-retention`, nutzt `deps.db` + `computeNextDue` aus `@hivegrid/view-models` + `createNotification Delivery` aus `@hivegrid/db` — beide worker-importierbar), oder (b) in ein geteiltes Paket extrahieren. **Stop + Rückfrage** statt raten (AGENTS.md). Die Logik selbst (`dispatchDueReminders`/`escalateOverdueDispatches`/`computeNextDue`) ist fertig + `computeNextDue` unit-getestet. **DoD nach diesem Update:** 1 ~90 % (Calendar-Write blockiert) · 2 ~95 % · 3 ~95 % · 4 ~95 % · 5 Requests ~95 %, Reminders ~75 % (Cron-Trigger offen) · 6 ~95 % · 7 ~90 % (M05 blockiert, Push v2) · 8 ~90 % (RLS-Cutover blockiert). ### 2026-06-28 (Update) — Worker-Cron Upload-Erinnerungen fertig (~85 % DoD) **Stand: ~85 % DoD — alle selbst-machbaren Punkte erledigt.** Worker-Cron gewählt nach Codebase-Muster (Option a, User-Freigabe). **Proof — Commit `b2b445010`** (alle Pre-Commit-Gates grün): Maintenance-Task `hr-upload-reminder-dispatch` (täglich, general-Gruppe) → `runHrUploadReminder DispatchHandler` (pro Tenant Dispatch + notify + Cadence-Advance + Manager- Eskalation, alles in `withTenantRLS`). PURE Helfer `nextReminderDue`/ `audienceMatches` + 7 Unit-Tests grün. queue/worker typecheck grün. **DoD 5 jetzt ~95 %** (Cron-Trigger geschlossen). **Verbleibend = ausschließlich extern blockiert:** - Finale Subframe-UI + Adapter + **Smoke-Tests** (`e2e/smoke/hr-*`) + Visual- Regression (M016) + Hot-Swap (M017) → **Davids `D-HR`-Delta** (noch leer). - CalendarEvent-Write (P16/M25) · M05-Form-Renderer-Reuse (AK-P16c) · RLS-Live- Cutover (R-P2b) · Web-Push (v2/AD-17). **6 Code-Commits + 3 Doku-Commits auf `feat/AK-P17b`** (e2774ca8b · 3a00766c7 · b6c5e4f76 · b2b445010 + Doku). Nichts gepusht, Plane-Status unverändert (wartet auf Freigabe). **Update 2026-07-08 (Akeshan) — Interim-UI aus `~/ui` (AD-28). DoD #43 (UI/Tests) über den Interim-Pfad adressiert.** Die AK-P17b-Workflow-Screens lagen bereits als Routen auf `main` (Commits `3a00766c7`/`b6c5e4f76`), rendern aber handgeschriebenes Tailwind. Sie sind jetzt aus `~/ui`-Components recomposed — gleiches AD-28-Muster wie AK-P17a (pure `` in `apps/web/app/components/screens/hr/`, Routen bauen VM + injizieren Callbacks, Fetcher in der Route). Kein VM-/Loader-/Schema-Change. Gebaut (9 Screens): - `HrLeavePage` (Tabs own/approvals/team, Antrag/Approve/Reject/Rückfrage/Withdraw), `HrSickPage` (own/office, audited AU-Reveal-and-open), `HrAnnouncementsFeedPage` + `HrAnnouncementDetailPage` (React/Kommentar/Ack) + `HrAdminAnnouncementsPage`, `HrPayslipsPage` (audited Open-and-view) + `HrAdminPayslipsPage` (Bulk-Match-Vorschau + Per-Row-Confirm), `HrRequestsPage` (own/approvals + Template-Wahl) + `HrAdminRequestTemplatesPage`, `HrAdminUploadRemindersPage`, `HrSurveysListPage` + `HrSurveyParticipationPage` (Item-Editor) + `HrSurveyResultsPage` (Distribution-Bars). - 21 neue Präsentations-i18n-Keys chirurgisch in de+en gespleißt. **Proof:** Commit `f840fcf24` (Branch `feat/AK-P17a-interim-ui`, lokal, nicht gepusht) · `pnpm --filter @hivegrid/web typecheck` **0 Fehler** · `pnpm run verify:i18n` Exit 0 · lefthook pre-commit grün. **Interim-UI (Vorschau, Stand 2026-07-08):** Screens aus `~/ui` gebaut — `apps/web/app/components/screens/hr/*`. Damit ist die finale Subframe-Optik (DoD #43) **kein Done-Blocker** mehr, sondern getrackter Nachzug (Plane-Label `design-nachzug`). Noch selbst machbar: Screen-Unit-Tests, Smoke `e2e/smoke/hr-*`, Hot-Swap-Adapter; Visual-Regression bleibt deferred (kein Screenshot-Harness). Extern blockiert bleibt nur: CalendarEvent-Write (P16), M05-Renderer (AK-P16c), RLS-Live (R-P2b), Web-Push (v2).