Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/.planning/ticket-docs/AK-P17b.md
T

214 lines
17 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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.
- [x] **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 setzt `calendarEventId` — Commit `7a64dd477`, live im Browser bewiesen (Kalender September zeigt „Urlaub").*
- [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. *M05-Form-Reuse seit Audit-Restwork 2026-07-19 verdrahtet (AK-P16c ist Done): Request-Templates können publizierte `hr_request`-Formulare verlinken, `submitRequest` persistiert dann eine echte `FormSubmission` und setzt `formSubmissionId` (Commit `8247d399c`). Urlaub/Krank tragen laut ENTITY-MODEL bewusst kein `form_submission_id` und bleiben beim schlanken Formular. Web-Push → v2/AD-17.*
- [x] Konnektor `tenantHasModule('hr')`; App-Permission-Gates; sensible Felder verschlüsselt; RLS-Policies geschrieben. *RLS ist seit Cutover `20260713190000_appwide_rls_cutover` (14.07.) auf allen HR-Tabellen LIVE; der HR-Worker-Cron nutzt `notifyWithTenantRlsContext` (R-P1b-Regression trifft HR nicht).*
- [x] **Tests/UI:** Interim-UI aus `~/ui` (PR #54) + Smoke-Test `tests/e2e/hr-workflows-smoke.spec.ts` (Commit `f309ecbce`) + Hot-Swap-Drill/ui-mock (Commit `b216848c4`) + Screen-/VM-Unit-Tests (Commit `7c3867039`). *Nur Visual-Regression (M016) bleibt deferred (kein Screenshot-Harness, R-P5-Präzedenz) — Baseline beim `design-nachzug` gegen die finale D-HR-Optik · `blockiert`. Die finale Subframe-Optik selbst = getrackter `design-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_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 · 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-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 `<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).
- 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):** `approveRequest` erzeugt im selben RLS-Kontext ein internes All-Day-Event
(Titel = i18n-aufgelöste Kind-Bezeichnung aus der Route, Booking-Präzedenz) und setzt `calendarEventId`;
Approve ist im Statemachine terminal, daher kein Cleanup-Pfad nötig. Commit `7a64dd477` + Service-Tests.
- **M05-Form-Reuse (DoD 7):** Template-Editor mit Linked-Form-Auswahl (publizierte `hr_request`-Formulare),
`submitRequest` schreibt `FormSubmission` (`linkedEntityType: hr_request`) + `formSubmissionId`. Fallback
bleibt das Übergangs-Formular, Submission bricht nie an einem fehlenden Formular. Commit `8247d399c` + 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-Nachzug `UI_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.