17 KiB
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.
UX-Nachzug (2026-07-25): R-UX3 übernimmt den freigegebenen Personal-Hub mit
Für mich / Mein Team / Verwaltung. AK-P17b bleibt das Workflow-Fundament; M05-, P9- und
Permission-Verträge dürfen durch den Nachzug nicht gebrochen werden.
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.
- Mehrstufiger Urlaubs-Approval-Workflow (submitted/approved/rejected/withdrawn + Rückfrage) → Plantafel-Konflikt-Feed (R-P9b via
listApprovedAbsencesForRange). CalendarEvent-Write seit Audit-Restwork 2026-07-19 umgesetzt (P16/AK-P16a ist da): Approve erzeugt internes All-Day-Event (hivegrid_internal, busy,internalEntityLink: hr_vacation_request) und setztcalendarEventId— Commit7a64dd477, live im Browser bewiesen (Kalender September zeigt „Urlaub"). - Krankmeldung (selbst/durch Büro) + AU-Upload verschlüsselt (Crypto-Seam, audited Reveal)
- Announcements (Audience, Acknowledgement-Pflicht + Read-Receipt, Reaktionen, Kommentare)
- Lohnabrechnungs-Bulk-Upload mit Dateiname-Auto-Match (Personalnummer/Name), Match-Vorschau mit Konfidenz, Read-Tracking, Audit pro Read
- Upload-Erinnerungen (Cadence once/yearly/every_n_months/on_expiry, Eskalation an Manager via Worker-Cron) + Requests via Templates
- Surveys (anonym möglich,
submitterHash) mit Auswertung (gegated) - Mitarbeiter-Self-Service (Web/PWA) — alle Bereiche reachable. M05-Form-Reuse seit Audit-Restwork 2026-07-19 verdrahtet (AK-P16c ist Done): Request-Templates können publizierte
hr_request-Formulare verlinken,submitRequestpersistiert dann eine echteFormSubmissionund setztformSubmissionId(Commit8247d399c). Urlaub/Krank tragen laut ENTITY-MODEL bewusst keinform_submission_idund bleiben beim schlanken Formular. Web-Push → v2/AD-17. - Konnektor
tenantHasModule('hr'); App-Permission-Gates; sensible Felder verschlüsselt; RLS-Policies geschrieben. RLS ist seit Cutover20260713190000_appwide_rls_cutover(14.07.) auf allen HR-Tabellen LIVE; der HR-Worker-Cron nutztnotifyWithTenantRlsContext(R-P1b-Regression trifft HR nicht). - Tests/UI: Interim-UI aus
~/ui(PR #54) + Smoke-Testtests/e2e/hr-workflows-smoke.spec.ts(Commitf309ecbce) + Hot-Swap-Drill/ui-mock (Commitb216848c4) + Screen-/VM-Unit-Tests (Commit7c3867039). Nur Visual-Regression (M016) bleibt deferred (kein Screenshot-Harness, R-P5-Präzedenz) — Baseline beimdesign-nachzuggegen die finale D-HR-Optik ·blockiert. Die finale Subframe-Optik selbst = getrackterdesign-nachzug, nicht Done-blockierend (AD-28).
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_dataauf Demo-Daten.
Quellen (granular)
ENTITY-MODEL.md→ Domäne 10: HR-Hub (EmployeeVacationRequest, EmployeeSickLeaveReport, HrAnnouncement, EmployeePayslip, EmployeeUploadReminder, HrRequest, HrSurvey)REQUIREMENTS.md→REQ-hr-urlaub-krankROADMAP.md→ Phase 17 · Milestones: (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)
Dev-Nachzug (nach Davids D-HR-Delta)
- Spec/ENTITY-MODEL an Davids UI-Entscheidungen angepasst
- REQUIREMENTS/ROADMAP nachgezogen
- Plane-Ticket
AK-P17baktualisiert
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 validategrü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.calendarEventIdnullable, CalendarEvent-Writeblockiertbis P16 (M25). R-P9b wird überlistApprovedAbsencesForRangebedient. - [~] (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) → DavidsD-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 <XPage vm={} actions={} /> 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).
- Per-Row-Confirm),
- 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).
2026-07-19 — Stand-Audit + Restwork: alle vormals externen Blocker (außer D-HR) gefallen und abgearbeitet. 9/9 DoD (nur Visual-Baseline deferred)
Audit-Befund (Doc vs. Plane vs. Code): Die Interim-UI-Commits aus der 08.07.-Notiz (f840fcf24) existieren
nicht mehr — sie gingen umgeschrieben via PR #54 als 96e84d6bc/270f0df30 auf main. Drei als „extern
blockiert" geführte Punkte waren inzwischen frei: R-P2b/RLS (Cutover 14.07. deckt alle HR-Tabellen),
P16-Kalender (AK-P16a gemergt, calendar.prisma da) und AK-P16c/M05 (Form-Builder seit 11.07. Done).
Restwork umgesetzt (Branch fix/ak-p17-audit-restwork):
- CalendarEvent-Sync (DoD 1):
approveRequesterzeugt im selben RLS-Kontext ein internes All-Day-Event (Titel = i18n-aufgelöste Kind-Bezeichnung aus der Route, Booking-Präzedenz) und setztcalendarEventId; Approve ist im Statemachine terminal, daher kein Cleanup-Pfad nötig. Commit7a64dd477+ Service-Tests. - M05-Form-Reuse (DoD 7): Template-Editor mit Linked-Form-Auswahl (publizierte
hr_request-Formulare),submitRequestschreibtFormSubmission(linkedEntityType: hr_request) +formSubmissionId. Fallback bleibt das Übergangs-Formular, Submission bricht nie an einem fehlenden Formular. Commit8247d399c+ Tests. - Tests/Registry (DoD 9 + AGENTS.md-Pflicht): e2e-Smoke
hr-workflows-smoke.spec.ts(f309ecbce), ui-mock-Fixtures + Hot-Swap-Drill (b216848c4), VM-Unit-Tests für alle 8 ungetesteten HR-VMs (7c3867039), Registry-NachzugUI_NAV_IDS.appHr+ surfaces.json (bb230e6b6).
Proof: typecheck web/db/worker/view-models 0 Fehler · verify:i18n/verify:sidebar-routes/
verify:cross-cutting-models Exit 0 · pnpm run test:hot-swap grün · view-models-Suite 567 Tests grün ·
Live-Beweis im Browser (lokal, pnpm dev:local): Antrag gestellt → in Genehmigungen genehmigt →
DB zeigt status=approved + verlinktes CalendarEvent (hivegrid_internal, „Urlaub", all-day, busy) →
Kalender-Screen rendert „Urlaub" 01.–04.09. Kein Schema-Change → keine neue Migration (AD-21).
Sichtbar unter: http://app.localhost:3000/<tenant>/hr/leave (Workflow), /hr/requests +
/hr/admin/request-templates (M05-Verlinkung), /calendar (Absence-Event); Screens in
apps/web/app/components/screens/hr/*. Subframe: weiterhin keine D-HR-Pages (MCP-Check 19.07.) —
design-nachzug bleibt korrekt offen.