Files
HiveGrid-Wireframes/hivegrid-cloud/docs/boilerplate-mapping/M14-hr-hub.md
T

178 lines
23 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.
# Boilerplate-Mapping: M14 — HR-Hub / Mitarbeiterplattform
> Abgleich-Report. Stellt fest, was fuer M14 aus der Boilerplate
> (`/Users/raffaelsheikh/Documents/GitHub/boilerplate`) uebernommen werden kann,
> was angepasst werden muss und was komplett fehlt.
> Boilerplate wurde NUR gelesen. Alle Pfade absolut.
## Kopf
| Feld | Wert |
| --- | --- |
| Modul-ID | M14 |
| Name | HR-Hub / Mitarbeiterplattform |
| Spec | `/Users/raffaelsheikh/Documents/GitHub/HiveGrid-Cloud/_bmad-output/specs/M14-hr-hub.md` |
| Milestones | M133 (Stammdaten+Standorte), M134 (Dokumente), M135 (Urlaub), M136 (Krankmeldungen), M137 (Kommunikation/Announcements/Quick-Links/Resources/Password-Safe), M138 (Onboarding-Drittanbieter), M139 (Anträge+Surveys+Lohn-Export+DSGVO), M140 (MA-Selbstbedienung/Hub) |
| Pflichtenheft-Block | Block 6, Modul 14 (`_bmad-output/pflichtenheft/blocks/block6.md` Abschnitte 14.1–14.17) |
| Size | XL |
| **Reuse-Level** | **low** (kein einziges HR-Domänen-Modell vorhanden; aber sehr starke Querschnitt-/Infrastruktur-Basis) |
### Begründung Reuse-Level = low
Die HR-Fachdomäne ist in der Boilerplate **vollständig abwesend**: es gibt **keine** der 21 in der Spec genannten Entitäten als Prisma-Modell und **kein** HR-Modul in `apps/web`. Verifiziert per Grep gegen `prisma/schema/*.prisma` (keine Treffer auf `Hr*`, `Employee*`, `Vacation*`, `Sick*`, `Payslip*`, `PasswordSafe*`, `Announcement*`, `Survey*`, `Leave*`) und gegen `apps/web/app/**` (kein `hr/`, `employee/`, `payslip/`, `vacation/`, `announcement/`, `directory/`-Verzeichnis).
Trotzdem ist der Wiederverwendungs-Hebel auf der **Querschnitt-/Infrastruktur-Ebene hoch**: Verschlüsselung (AES-256-GCM-Helper), Storage+Signed-URLs, Audit-Hash-Kette, Notifications (In-App/E-Mail/Push), Permissions/Owner-Check, Export (CSV/DSGVO/Audit-PDF), Import (Bulk/Dedupe — für Payslip-Bulk-Upload), Form-Widget, Worker/Cron (Reminder-Engine), Feature-Flags und das View-Model-/Sidebar-Registry-Fundament sind alle vorhanden. M14 baut sein Datenmodell + Service-Layer + UI neu, klinkt sich aber durchgängig in fertige Querschnitte ein.
---
## Übernehmbar aus Boilerplate
| Boilerplate-Pfad | Was | Wie nutzbar |
| --- | --- | --- |
| `/Users/raffaelsheikh/Documents/GitHub/boilerplate/apps/web/app/utils/api/.server/CryptoApi.ts` | AES-256-GCM Encrypt/Decrypt (`aes-256-gcm`, 12-Byte-IV, AuthTag, versioniertes `v1:iv:tag:ct`-Format, Key = SHA-256 von `CRYPTO_SECRET`) | **als-vorlage** — direkt für Password-Safe-Werte (`username`/`password`/`notes_encrypted`) und Sick-Cert-Encryption. ACHTUNG: nutzt **einen** Env-Key, **nicht** Per-Tenant-KMS/per-Eintrag-DEK wie die Spec (Block J) fordert → Architektur-Lücke (s.u.) |
| `/Users/raffaelsheikh/Documents/GitHub/boilerplate/apps/web/app/utils/leads/marketingIntegrations.db.server.ts` | Muster „selektive Feld-Verschlüsselung at-rest in JSON + nie Re-Display im UI" (`encryptSensitive`/`decryptSensitive` mit `CRYPTO_TAG`-Prefix, Merge+Re-Encrypt bei Patch) | **als-vorlage** — exakt das Reveal/Edit-Verhalten für Password-Safe-Einträge (UI zeigt entschlüsselten Wert nie automatisch) |
| `/Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/storage/src/index.ts` + `/Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/storage/src/signed/` | `putObject`, Signed-Upload/-Download, S3/Scaleway-Provider | **1:1** — für alle Datei-Anhänge (Payslips, Employee-Docs, Sick-Certs, Announcement-/Request-Attachments). Tenant-isolierte Pfade (`tenants/{tenantId}/payslips/{userId}/…`) als Key-Konvention selbst setzen |
| `prisma/schema/core.prisma` → `model FileObject` (`/Users/raffaelsheikh/.../boilerplate/prisma/schema/core.prisma`) | Storage-Metadaten-Modell (`provider`/`bucket`/`key`/`contentType`/`byteSize`/`checksumSha256`, signed-Timestamps) | **1:1** — File-Referenzen aller HR-Dokumente (Spec verweist auf „File M23"; M23 = dieses FileObject) |
| `/Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/foundation/src/notifications.ts` | `notify`/`notifyMany`/`bundleNotifications`, Preference-Check, `sourceKey`-Upsert, `assertI18nKey` | **1:1** — alle M14-Notifications (Approver/Antragsteller/HR-Admin/Reminder/Announcement-Push). INTEGRATION-CONTRACTS §6 verlangt `notify()` statt Direkt-Versand |
| `prisma/schema/notifications.prisma` → `NotificationDelivery`, `UserNotificationPreference`, `DeviceToken` | In-App + E-Mail + Push-Token-Modelle (APNs/FCM/WebPush) | **1:1** — Push für Krankmeldung/Urlaub/Payslip/Reminder (Spec Block N M22); Mobile-Push bereits modelliert |
| `/Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/foundation/src/permissions.ts` | `withTenantScope`, `withPermission`, `withOwnerCheck`, `requirePermission`; Fehlschlag = `CatalogError(notFound)` (404, nicht 403) | **1:1** — deckt Block O exakt: Owner-Check (`read_own`), 404-statt-403 (LP-9 Information-Hiding), Tenant-Scope. HR-Permission-IDs selbst registrieren |
| `prisma/schema/permissions.prisma` → `Role`, `Permission`, `RolePermission`, `UserRole`, `Group`, `GroupUser` | RBAC-Fundament; `Group`/`GroupUser` für Audience-Auflösung (`audience_group_ids`) | **1:1** — HR-Permission-Bundles (`hr.employee`…`hr.admin`) als `Permission`-Sätze + Default-Rollen-Zuweisung. Audience „groups" nutzt `Group` |
| `/Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/foundation/src/audit.ts` + `/Users/raffaelsheikh/.../packages/db/src/audit-hash.ts` | `auditEvent`/`withAuditMiddleware`; tamper-evidente Hash-Kette (`previousHash`/`eventHash`), `dataSensitivity`, `regulatoryScope[]` | **1:1** — Block P „Audit": Pflicht-Audit für sensible Reads (Payslip-Download, Sick-Cert-Einsicht, **Password-Safe-Reveal**), `regulatoryScope=gdpr`, `dataSensitivity=pii` |
| `prisma/schema/core.prisma` → `AuditEvent` | Audit-Trail-Tabelle (actor, target, outcome, Hash-Chain) | **1:1** — alle schreibenden HR-Aktionen + sensible Reads |
| `/Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/foundation/src/idempotency.ts` + `core.prisma:IdempotencyKey` | `withIdempotency` (scope+key, In-Process-Lock, 409 bei Konflikt) | **1:1** — Antrags-Submit, Payslip-Bulk-Upload, Reveal-Endpoint (Replay-Schutz) |
| `/Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/exports/` (`./csv`, `./json`, `./pdf`, `./audit-pdf`, `./s3-multipart`, `./limits`) | Streaming-Export CSV/JSON/PDF + Audit-Compliance-PDF + Plan-Row-Caps | **1:1** — M139 Lohn-Export-CSV (Steuerberater), Survey-CSV-Export, DSGVO-MA-Datenexport, Audit-Reports |
| `/Users/raffaelsheikh/Documents/GitHub/boilerplate/apps/worker/src/jobs/dsgvo-export.ts` + `/Users/raffaelsheikh/.../packages/db/src/dsgvo/user-fk-map.ts` | DSGVO-Personal-Data-Export-Job (aggregiert alle User-FK-Rows, JSON-Bundle → S3 → Signed-URL → AuditEvent) | **anpassen** — neue HR-Modelle in `USER_FK_MAP` eintragen (Pflicht, sonst CI-Bruch), dann deckt der Job M14 Block P „DSGVO-Auskunftsrecht" + M139 14.16.5 ab |
| `/Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/imports/` (`createImportDryRunPreview`, `dedupe`, Diagnose-Redaction) | Bulk-Import-Framework mit Dry-Run-Preview + Dedupe + PII-Redaction | **als-vorlage** — Payslip-Bulk-Upload (Block F): Match-Vorschau (Hard/Soft/No-Match), Doppel-Upload-Erkennung. Dateiname-Pattern-Match (`{personal_number}-{yyyy-mm}.pdf`) ist HR-spezifisch und neu |
| `prisma/schema/imports.prisma` → `ImportJob` | Job-Tracking (accepted/rejected rows, error-report) | **anpassen** — Bulk-Upload-Status + Aktivitäts-Bericht (Block F Schritt 7) |
| `/Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/form-widget/` + `prisma/schema/formWidget.prisma` (`Form`, `FormSubmission`) + `apps/web/app/modules/formWidget/builder/` | Form-Definition (Zod), Submission-Routing, Field-Mapping, Form-Builder-UI | **anpassen** — Urlaubsantrag/Krankmeldung/Request laufen laut Spec (Block E/H, Block N M5) als M5-Forms; `form_submission_id`-FKs zeigen darauf. Neue Form-Action-Typen (`create_hr_vacation_request`…) sind HR-spezifisch zu ergänzen |
| `/Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/db/src/outbox.ts` + `apps/worker/src/outbox/event-router.ts` | Transaktionaler Outbox-Publisher + Event-Routing (Prefix→Queue) | **1:1** — alle HR-Side-Effects (Activity, Notification, Automation-Trigger `hr.*`) atomar mit DB-Write. Block M Activity-Typen als Outbox-Events |
| `/Users/raffaelsheikh/Documents/GitHub/boilerplate/apps/worker/` (Cron-Scheduler, BullMQ-Gruppen, `HandlerDependencies`) | Worker-Runtime mit single-instance Cron + Queue-Consumer | **anpassen** — Reminder-Engine (Block G: täglicher Cron `once`/`yearly`/`every_n_months`/`on_expiry`), Überfälligkeits-Eskalation, Aufbewahrungs-Hard-Delete-Cron (Block P) als neue Jobs nach Muster von `dsgvo-grace-cron.ts`/`audit-retention.ts` |
| `/Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/feature-flags/` + `packages/foundation/src/flags.ts` | Feature-Flag-Engine v2 (Targeting) + leichtgewichtige Gates | **1:1** — AV #7 „Feature-Flag-Hülle" (`hr.feature_resturlaub_tracking`), Modul ohne Deploy abschaltbar (DoD) |
| `/Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/view-models/src/index.ts` | `VMState`, `ActionCallbacks`, `RegistryGate`, `I18nLabel`, `SidebarRegistryItem`, `assertI18nLabel` | **1:1** — Loader-baut-VM-Disziplin (DoD „Code-Layer-Disziplin"), Sidebar-Gating per Permission/Flag |
| `/Users/raffaelsheikh/Documents/GitHub/boilerplate/apps/web/app/components/layouts/sidebars/shadcn/` + `app/application/sidebar/AppSidebar.tsx`, `SidebarItem.ts` | App-Shell (App/Admin/Docs), datengetriebene Sidebar mit Permission-/Feature-Gate, Breadcrumb-Header, Mobile-Sidebar | **als-vorlage** — HR-Hub-Hauptpunkt + kontextabhängige Sub-Punkte (Block B); HiveGrid registriert real in `packages/ui-hivegrid/src/app-shell/sidebar.config.ts` (INTEGRATION-CONTRACTS §1) |
| `/Users/raffaelsheikh/Documents/GitHub/boilerplate/apps/web/app/components/ui/` (table, tabs, dialog, sheet, form, calendar, chart, multi-select, pagination, command, badge, card, drawer, stepper, modals, emptyState, loaders, pdf-viewer, editors) | shadcn/Radix-Primitives + Tabellen/Forms/Modale/Empty-/Loading-States/PDF-Viewer/Markdown-Editoren | **als-vorlage** — Feed-Listen, Detail-Views, Reveal-Dialoge, Payslip-PDF-Viewer, Leave-Kalendersicht (`calendar.tsx`/`chart.tsx`), Survey-Auswertung (`chart.tsx` für Bar/NPS) |
| `/Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/i18n/` + `apps/web/app/locale/` | i18n (de/en), Intl-Formatter (Datum/Zahl), ICU-Plurale, `useTranslate` | **1:1** — alle Klartext-Hinweise (Block Q) als i18n-Keys (DoD + INTEGRATION-CONTRACTS §10). Locale-File neu: `packages/i18n/src/locales/de/hr.json` |
| `/Users/raffaelsheikh/Documents/GitHub/boilerplate/apps/web/app/components/entities/` (Entity-Builder: Properties, Views, RowComment/RowCommentReaction, RowTask, RowTag) | No-Code-Entity-Engine inkl. Kommentare+Reaktionen+Tags-Muster | **als-vorlage** — Announcement-Comments/-Reactions und Request-Comments können das `RowComment`/`RowCommentReaction`-Muster adaptieren; Phase-2-Custom-Felder pro `HrEmployeeProfile` (Block R) per Entity-Builder |
| `/Users/raffaelsheikh/Documents/GitHub/boilerplate/prisma/schema/appsEngine.prisma` (`App`, `DataConnection`, `AppSyncRun`, `AppSyncRunLog`, `AppSyncItem`) + `apps/web/app/modules/onboarding/` | Integrations-/Sync-Engine (verschlüsselte Credentials, Rollback-fähige Sync-Runs) + Onboarding-Flow-Modelle | **anpassen** — M138 Onboarding-Drittanbieter (Memberspot/Boobora) via Apps-Engine: Read-Sync Modul-Abschlüsse/Zertifikate/Quiz/Fortschritt = `AppSyncRun`/`AppSyncItem`-Muster |
| `/Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/db/src/client.server.ts` + `transactions.server.ts` | `getDbClient`/`getReadDbClient`/`getExtendedDbClient`, `runDbTransaction` | **1:1** — DB-Boundary für alle HR-Repositories; Read-Replica für Hub-/Verzeichnis-Dashboards |
| `prisma/schema/app.prisma` (`// custom database models`) | Leerer Platzhalter für projekt-eigene Modelle | **1:1** — vorgesehener Ort für ALLE 21 HR-Modelle (alternativ HiveGrid-eigene Schema-Datei `hr.prisma`) |
| `/Users/raffaelsheikh/Documents/GitHub/boilerplate/packages/db/src/search/indexed-entities.ts` (per INTEGRATION-CONTRACTS §7) | Such-Index-Registry | **anpassen** — MA-Verzeichnis-Suche, Announcement-Volltextsuche registrieren |
---
## Vorhandene Daten-Modelle (konkrete Prisma-Modelle, die M14 nutzt/erweitert)
**Wichtig: KEIN HR-Domänen-Modell existiert. Folgende Boilerplate-Modelle sind Anbindungs-/Querschnitt-Modelle, auf die M14 verweist:**
| Modell | Pfad | M14-Bezug |
| --- | --- | --- |
| `TenantUser`, `User`, `Tenant` | `prisma/schema/accounts.prisma` | `HrEmployeeProfile.user_id` (1:1 mit TenantUser), `manager_user_id`; Auto-Seed leeres Profil bei Tenant-User-Anlage (Spec A „Sonderfall", 14.1.5). `User.totpSecretEncrypted` zeigt das Encrypted-Suffix-Muster für 2FA (Block P 2FA-Empfehlung) |
| `Role`, `Permission`, `RolePermission`, `UserRole`, `Group`, `GroupUser` | `prisma/schema/permissions.prisma` | Permission-Bundles Block O; Audience-Auflösung `groups` |
| `FileObject` | `prisma/schema/core.prisma` | Datei-Backing für `file_id`/`attached_file_ids[]`/`certificate_file_id`/`avatar_file_id` |
| `AuditEvent`, `IdempotencyKey`, `Event` | `prisma/schema/core.prisma` | Audit-Trail; Idempotenz; generischer `Event` (kein Calendar-Event!) |
| `NotificationDelivery`, `UserNotificationPreference`, `DeviceToken` | `prisma/schema/notifications.prisma` | Notifications/Push |
| `OutboxEvent` | `prisma/schema/outbox.prisma` | Activity-/Automation-/Notification-Fanout (`hr.*`-Events) |
| `Form`, `FormSubmission` | `prisma/schema/formWidget.prisma` | `form_submission_id` für Urlaub/Krank/Request |
| `ImportJob` | `prisma/schema/imports.prisma` | Payslip-Bulk-Upload-Tracking |
| `ExportJob` | `prisma/schema/queue.prisma` | Lohn-/Survey-/DSGVO-Export |
| `App`, `DataConnection`, `AppSyncRun`, `AppSyncItem` | `prisma/schema/appsEngine.prisma` | M138 Drittanbieter-Onboarding-Sync |
| `FeatureFlag`, `FeatureFlagFilter`, `FeatureFlagAudit` | `prisma/schema/featureFlags.prisma` | AV #7 Feature-Flags |
| `Onboarding*` (7 Modelle) | `prisma/schema/onboarding.prisma` | Produkt-Onboarding-Tour (NICHT MA-Onboarding) — nur als Muster für M138 |
---
## Lücken / komplett neu zu bauen
### A. Alle 21 HR-Domänen-Modelle (komplett neu, in `app.prisma` / `hr.prisma`)
`HrEmployeeProfile`, `HrAnnouncement`, `HrAnnouncementRead`, `HrAnnouncementReaction`, `HrAnnouncementComment`, `HrLocation`, `HrEmployeeDocument`, `HrResource`, `HrQuickLink`, `HrSurvey`, `HrSurveyItem`, `HrSurveySubmission`, `HrSurveySubmissionAnswer`, `HrRequest`, `HrRequestTemplate`, `HrRequestComment`, `EmployeePayslip`, `EmployeeUploadReminder`, `EmployeeUploadReminderDispatch`, `EmployeeVacationRequest`, `EmployeeSickLeaveReport`, `EmployeePasswordSafeVault`, `EmployeePasswordSafeEntry`, `EmployeePasswordSafeAccess` — **kein einziges existiert**. Inkl. aller Indizes (Spec A „Indizes") und der zusätzlichen App-Code-Permission-Layer über RLS hinaus (Spec A „RLS / Datenisolation").
> Pflicht beim Bau: jedes Modell mit User-FK in `packages/db/src/dsgvo/user-fk-map.ts` eintragen (Cascade-Strategie `hard-delete`/`pseudonymize`/`retain-tombstone` + `includeInExport`) — der CI-Test bricht sonst. HR hat gesetzliche Aufbewahrungsfristen (Block P: 10/4 Jahre) → meist `retain-tombstone`/anonymisieren statt hard-delete.
### B. Per-Tenant-KMS / Per-Eintrag-DEK für Password-Safe (Architektur-Lücke)
Die Spec (Block J „Verschlüsselung") fordert **Per-Tenant-Master-Key im KMS (Scaleway-KMS) + Per-Eintrag-DEK gewrappt mit Master-Key**. Die Boilerplate liefert nur `CryptoApi.ts` mit **einem** Env-abgeleiteten Key (`CRYPTO_SECRET`) und **keine** KMS-Integration, **kein** DEK-Wrapping, **keine** Key-Rotation. → Das KMS-/DEK-Wrapping-Layer ist komplett neu zu bauen (Master-Key-Rotation explizit Phase 2). CryptoApi taugt nur als AES-256-GCM-Primitive darunter.
### C. Leave-/Approval-Workflow-Engine (komplett neu)
Genehmigungs-Workflow (submitted→approved/rejected/withdrawn), Default-Approver-Auflösung (`manager`/`fixed_user`/`role`/`group`), Approver-Rückfrage, `working_days_count`-Berechnung. Es gibt KEINE generische Approval-Engine in der Boilerplate. Der `workflows.prisma`-Builder ist node-basierte Automation, kein menschlicher Genehmigungs-Workflow.
### D. DE-Feiertagskalender / Bundesland-genaue Arbeitstage-Berechnung (komplett neu)
`working_days_count` netto ohne Wochenende + Bundesland-Feiertage (aus `HrLocation`). Keine Feiertags-Library/-Logik in der Boilerplate (offener Detail-Punkt in der Spec).
### E. Calendar-Integration (Modell fehlt)
Spec Block N M25: genehmigter Urlaub → Calendar-Event. Es gibt **kein** Calendar-/CalendarEvent-Modell in der Boilerplate (nur generischer `Event` in `core.prisma` = Webhook-Event, kein Kalendereintrag). `calendar_event_id`-FK zeigt auf ein erst zu bauendes M25.
### F. Plantafel-Konflikt-Detection (Modul-übergreifend, neu)
Spec Block N M4: genehmigte Urlaube + aktive Krankmeldungen als Konflikt-Indikatoren in Plantafel/ScheduleEntries. Kein ScheduleEntry-Modell vorhanden — gehört zu M4, ist hier nur Integrationspunkt.
### G. Automation-Trigger/-Actions `hr.*` (neu)
Spec Block N M17: `hr.vacation_requested`, `hr.sick_leave_reported`, Actions `hr.send_announcement` etc. Die Outbox/Workflow-Infra existiert, aber die HR-spezifischen Trigger/Action-Definitionen + Block-Verträge sind neu.
### H. Reminder-Engine-Cron-Logik (neu, Muster vorhanden)
Block G: Dispatch-Erzeugung pro Cadence, Überfälligkeits-Eskalation, `reminder_count`-Wiederholung. Worker-Cron-Muster vorhanden (s.o.), aber die konkrete Reminder-Logik + `on_expiry`-Lookahead auf `valid_until` ist neu.
### I. SHK-Default-Seeding (neu)
Block H/LP-3: Default Request-Templates (Spesen/Hardware/Schulung/Zeugnis/Sonstiges), Default-Reminder, Default-Announcements. Seeding-Infra vorhanden (`packages/db/src/seed`), HR-Inhalte neu.
### J. HR-spezifische UI-Surfaces (neu, in `packages/ui-hivegrid`)
Announcement-Feed + Detail (Reaction-Picker, Read-Receipt-Tabelle), Leave-Übersicht (Tabs + Kalendersicht), Password-Safe Reveal-UI (Copy-mit-Auto-Clear-30s), Survey-Editor + Auswertung, MA-Verzeichnis (Karten/Liste + Click-to-Call/Mail/Chat), Bulk-Upload-Match-Vorschau, Hub-Startseite mit Widgets. Primitives vorhanden (Tabelle/Tabs/Chart/Calendar/Dialog), HR-Komposition neu. Subframe-Adapter-Layer ist Boilerplate-seitig leer (`@toolctrl/ui-subframe` = Stub) — HiveGrid muss diese Grenze selbst füllen (MEMORY: Subframe für alle Routes Pflicht).
### K. Permission-IDs `hr.*` (neu registrieren)
Alle 18 atomaren Permissions + 5 Bundles (Block O) als TypeScript-Konst in `packages/entitlements/src/permissions.ts` (INTEGRATION-CONTRACTS §8) + Default-Rollen-Zuweisung (SHK-Template).
### L. `@hivegrid/activity` `logActivity` (HiveGrid-Querschnitt, kein BP-1:1)
INTEGRATION-CONTRACTS §5 verlangt `logActivity` aus `@hivegrid/activity` (M045) — das ist ein HiveGrid-eigenes Paket, nicht die Boilerplate-Foundation. Block M Activity-Typen `hr.*` dort registrieren.
---
## Empfohlenes Vorgehen (Reihenfolge)
**Phase 1 — Fundament aus BP einklinken (vor jedem Feature):**
1. HR-Permission-IDs + Bundles in `packages/entitlements/src/permissions.ts` registrieren (Block O). Voraussetzung für jede Route.
2. Datenmodelle in `prisma/schema/app.prisma` (oder neue `hr.prisma`) anlegen — **gestaffelt pro Milestone**, nicht alle 21 auf einmal. M133 zuerst: `HrEmployeeProfile`, `HrLocation`. Jeweils sofort `USER_FK_MAP` ergänzen (CI-Gate).
3. DB-Repositories über `@toolctrl/db/client.server` + `runDbTransaction`; Side-Effects ausschließlich via `publishOutboxEvent` (INTEGRATION-CONTRACTS §6/Outbox).
4. Sidebar-Eintrag in `packages/ui-hivegrid/src/app-shell/sidebar.config.ts` + Routes unter `app.$tenant/hr/*` und `admin/hr/*` (Block B), gegated via `withTenantScope`+`withPermission` (404-statt-403).
**Phase 2 — Stammdaten/Verzeichnis/Dokumente (M133, M134):**
5. `HrEmployeeProfile`/`HrLocation` + Verzeichnis-UI (Click-to-Call M12/Mail/Chat M13). i18n-Keys `hr.*`.
6. `HrEmployeeDocument` + Upload über `@toolctrl/storage` (`putObject`+signed-download) auf `FileObject`; tenant-isolierte Key-Konvention. Visibility-Gating + Audit auf sensible Reads (`withAuditMiddleware`).
**Phase 3 — Leave + Payslips (M135, M136, M139-Teil):**
7. Form-Templates Urlaub/Krank über `@toolctrl/form-widget` + `FormSubmission`; neue Form-Actions `create_hr_vacation_request`/`create_hr_sick_leave`.
8. **Neu bauen:** Approval-Workflow-Engine, `working_days_count`+DE-Feiertage, Calendar-Event-Hook (sobald M25 da).
9. Payslip-Bulk-Upload: `@toolctrl/imports` Dry-Run/Dedupe als Vorlage + HR-Dateiname-Pattern-Match; `ImportJob`-Tracking; Lohn-Export-CSV via `@toolctrl/exports/csv`.
**Phase 4 — Kommunikation + Password-Safe (M137):**
10. Announcements (Feed/Detail/Reactions/Comments) — `RowComment`/`RowCommentReaction`-Muster adaptieren; Read-Receipts neu. Push via `notify()`.
11. **Password-Safe: KMS/DEK-Layer komplett neu** (Scaleway-KMS + per-Eintrag-DEK über AES-256-GCM-Primitive aus `CryptoApi.ts`); Reveal-Endpoint mit Audit + Idempotenz; Copy-Auto-Clear-UI. Quick-Links/Resources (Audience-Gating).
**Phase 5 — Reminder-Engine + Surveys + Onboarding-Drittanbieter (M138, M139, M140):**
12. Reminder-Cron als neuer Worker-Job nach Muster `dsgvo-grace-cron.ts`/`audit-retention.ts`.
13. Surveys (Items als Form-Renderer-Wiederverwendung) + Auswertung (`chart.tsx`) + CSV-Export.
14. M138 Drittanbieter-Onboarding via `App`/`AppSyncRun`/`AppSyncItem` (Apps-Engine).
15. Hub-Startseite (M140) — aggregiert vorhandene Widgets; DSGVO-Export via `dsgvo-export.ts` (USER_FK_MAP muss vollständig sein).
16. AV #7 Feature-Flag-Hülle + SHK-Default-Seeding.
**Querschnitt durchgängig (DoD/INTEGRATION-CONTRACTS):** Loader-baut-VM (`@toolctrl/view-models`), keine Prisma-Imports in `packages/ui-hivegrid/**`, i18n-Keys (`hr.json`), `logActivity` (M045) + auto-Audit (M001), Smoke-Test + Hot-Swap-Drill + Visual-Snapshot.
---
## Anti-Erfindungs-Hinweise (faktische Grenzen)
- **Es gibt KEIN HR-Datenmodell und KEIN HR-Modul in der Boilerplate.** Verifiziert per Grep gegen `prisma/schema/*.prisma` und `apps/web/app/**`.
- **CryptoApi nutzt EINEN Env-Key, KEIN KMS/DEK.** Die Per-Tenant-KMS-Architektur der Spec ist neu.
- **Kein Calendar-/CalendarEvent-Modell.** `Event` in `core.prisma` ist ein Webhook-/Domain-Event, kein Kalendereintrag.
- **`@toolctrl/ui-subframe` ist ein leerer Stub** — kein gebauter Subframe-Adapter-Layer.
- **Keine generische Human-Approval-Workflow-Engine** (nur node-basierte `workflows.prisma`-Automation).
- **`packages/ui-hivegrid`, `@hivegrid/activity`, `packages/entitlements/src/permissions.ts` (HiveGrid-Variante)** sind HiveGrid-Repo-Konventionen aus INTEGRATION-CONTRACTS — in der Boilerplate so nicht vorhanden (Boilerplate hat `@toolctrl/*`).