19 KiB
AK-P17a · P17 HR-Kern (Stammdaten, Doku, Passwort-Safe)
| Typ | Dev (Code) |
| Owner | Akeshan |
| Phase | P17 — HR-Hub |
| Cycle/Fenster | W2 — Plattform & CRM (Demo 1) · fällig 2026-06-25 · 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-P4b(Files/Tasks + EntityLink — HR-Dokumente hängen an Files) - Blocks:
AK-P17b(Urlaub/Krank/Surveys) - Läuft parallel zu: Raffaels Kern-Kette (P6/P7). HR hängt nur an P1/P2 (User/RLS/Verschlüsselungs-Fundament) — KEINE Abhängigkeit von R-P5/R-P6, daher früh in W2 baubar. Eigene
prisma/schema/hr.prisma(AD-21);core.prismanur für User-Relation berührt. - Konflikt-Risiko: keines auf Schema-Ebene — disjunkte HR-Domäne.
Was wir bauen
Den verschlüsselten HR-Kern (Quiply-Ablösung): MA-Stammdaten (HrEmployeeProfile, Standorte), Personaldokumente und den verschlüsselten Team-Passwort-Safe. Sensible Daten liegen AES-256-GCM mit KMS-backed Envelope-Encryption (AD-8) vor; sensible Tabellen haben zusätzlich zum RLS einen App-Permission-Layer — Werte werden nie automatisch angezeigt (Reveal on-demand + Audit-Eintrag). Strikte Trennung MA-Sicht (eigener Bereich, eigene Daten) vs. HR-Admin-Sicht (/admin/hr/...). Passwort-Safe: Werte nie in der Liste, Reveal/Copy entschlüsselt on-demand mit Permission-Check, Copy mit 30s-Auto-Clear, DSGVO-Export.
Benötigte Screens (Backend bedient — Design liefert D-HR)
| Screen [Route] | Kern-Inhalt |
|---|---|
HR-Hub-Start [/hr] |
Angepinnte Announcements, offene Pflichten, eigene Anträge, Team heute (gegated), Geburtstage, Quick-Links, prominente Aktionen |
MA-Verzeichnis + Detail [/hr/directory, /:userId] |
Karten/Tabelle (Avatar/Name/Position/Team/Standort), Click-to-Call/Mail/Chat; Detail: Stammdaten, Notfallkontakt (nur self/HR), Inline-Edit selbst-pflegbarer Felder, eigene Dokumente |
Standorte + Detail [/hr/locations, /:id] |
Karten/Tabelle (Name/Adresse/Map/MA-Anzahl/Bild); Admin: anlegen/bearbeiten/Default/Bulk-Reassign |
Eigene Dokumente [/hr/my-documents] |
Liste (Titel/Art/Datum/Gültigkeit) + Filter, Upload eigener Dokumente, File-Viewer; vom Büro hochgeladene = read-only |
Passwort-Safe [/hr/password-safe] |
Vault-Liste → Eintrags-Liste (Titel/Tags, keine Werte!) → Detail mit Reveal je Wert (audit-geloggt), Copy mit 30s-Auto-Clear, Access-Verwaltung, Audit-Log |
Passwort-Safe-Verwaltung [/admin/hr/password-safe] |
Tenant-weite Vault-Sicht (ohne Inhalts-Access), Vault-Anlage/Archiv/Delete, Access-Verwaltung, Audit-Log-Übersicht |
Definition of Done
- HR-Profile/Dokumente AES-256-GCM (KMS-Envelope-Encryption, AD-8) — per-Tenant-DEK-Envelope aus R-P5 (
getTenantFieldCrypto) jetzt in den Seam gebunden; Notfallkontakt verschlüsselt. Finale UI-Optik = Davids D-HR. - MA-Bereich vs. HR-Admin-Bereich strikt getrennt; sensible Tabellen zusätzlich App-Permission-gegated
- Verschlüsselter Passwort-Safe mit Audit-Trail: Reveal/Copy entschlüsselt on-demand + Permission-Check + Audit-Eintrag; Werte nie in Liste; Copy mit 30s-Auto-Clear; DSGVO-Export — Backend komplett: Ver-/Entschlüsselung jetzt scharf (R-P5-Envelope); Audit/Permission/Never-List/Export gebaut. 30s-Clear = UI (David).
- MA-Verzeichnis + Standorte (Admin-CRUD) + eigene Dokumente (Upload + read-only Büro-Uploads) — Backend + funktionale Routen; finale Optik wartet auf Davids D-HR-Delta.
- Konnektor
tenantHasModule('hr'); RLS auf allen Tenant-Tabellen; sensible Felder verschlüsselt — Konnektor (Feature/Blueprint/Plan) + RLS-SQL (deferred-Aktivierung wie P4b) + sensible Felder verschlüsselt (R-P5-Envelope) stehen.
Technische Bausteine
- Entities (eigene
prisma/schema/hr.prisma):HrEmployeeProfile(user_id 1:1, personal_number, hire_date, position, team, location_id, manager_user_id, emergency_contact_),HrLocation(name, address_, geo, image_file_id),HrEmployeeDocument(employee_user_id, document_kind, file_id, visibility),HrResource/HrQuickLink,EmployeePasswordSafeVault(+Entry/Access— username/password/notes AES-256-GCM, permission_level read/write/admin).core.prismanur für User-Relation (AD-21). - Verschlüsselung: KMS-backed Envelope (per-Tenant-DEK, AD-8); Reveal entschlüsselt on-demand mit Permission-Check +
AuditEntry. - App-Permission-Layer oben auf RLS für sensible Tabellen (Werte nie in Listen, Reveal-gated).
- Konnektor
tenantHasModule('hr');is_demo_dataauf Demo-Profilen/-Standorten. - Dokumente via Files/FileEntityLink (AK-P4a/b).
Quellen (granular)
ENTITY-MODEL.md→ Domäne 10: HR-Hub (HrEmployeeProfile, HrLocation, HrEmployeeDocument, HrResource/QuickLink, EmployeePasswordSafeVault — viel Verschlüsselung)REQUIREMENTS.md→REQ-hr-datenmodell,REQ-hr-passwort-safeROADMAP.md→ Phase 17 ·PHASE-SOURCES.md→ Phase 17 (M133-stammdaten, M134-dokumente; M138 Drittanbieter-Onboarding → v2)designer-briefs/P17-hr-hub.md(MA- vs. HR-Admin-Trennung, Passwort-Safe-Reveal, sensible Daten)_bmad-output/specs/M14-hr-hub.md
Umsetzungs-Notiz
✅ Stand 2026-06-28 — auf
maingemergt.feat/AK-P17a(inkl. der eingemergten R-P5-Commits) ging mit PR #5 (squash, Merge-Commitb0fae1af8, Basemain, 2026-06-28 17:50, merged_by raffael) aufmain; Docker-Nachzugpackages/integrations/package.jsonvia PR #8 (0b9d2e46, 18:05). Alle HR-Artefakte (hr.prisma,hrFieldCrypto.server.ts,hrService/hrPasswordSafeService, RLS-SQL, Routen-Hülle, Sidebar) + das R-P5-Crypto-Fundament liegen immain-Tree. Die „Branch lokal, nicht gepusht"-Notizen unten sind damit überholt. Backend 5/5 DoD grün. Extern offen bleibt nur: DavidsD-HR-Optik + echter 30s-Clipboard-Wipe, RLS-Live/Crypto-Round-trip/Visual-Regression gegen Staging-DB, Plane-Ticket auf Done. Weiterarbeit am HR-Hub läuft über AK-P17b (neuer Branch).
2026-06-27 (Akeshan) — Backend-Kern + funktionale Routen, ~70% gebaut (2/5 DoD voll grün).
Branch feat/AK-P17a (lokal, nicht gepusht). Blocker AK-P4b ist in main gemergt (Commit 2e7b935b9), Files/EntityLink-Fundament steht. Strikt im AK-P17a-Scope geblieben (Entscheidung „strikt nach Ticket-Doc"): nur Stammdaten/Directory/Locations/Documents/Passwort-Safe; Announcements/Leave/Payslips/Surveys/Requests bleiben bei AK-P17b/Folge.
Gebaut:
- Schema
prisma/schema/hr.prisma(AD-21, bare Scalars,core.prismaunberührt): HrEmployeeProfile, HrLocation, HrEmployeeDocument, HrResource/HrQuickLink, EmployeePasswordSafeVault/Entry/Access. Sensible Werte als*Ciphertext-Spalten.prisma validate+generategrün.db pushlokal noch offen (kein lokales Postgres/Docker), env-gegatet wie bei AK-P4b. - RLS
prisma/rls/hr-isolation.sql(deferred-Aktivierung wie task-isolation.sql, P5-Cutover mit R-P2b) + env-gegateter Gate-Testrls-hr-isolation.integration.test.ts(skippt ohneRLS_TEST_DATABASE_URL). - Crypto-Seam
hrFieldCrypto.server.ts(Entscheidung c): Interface + injizierbar; Produktiv-Binding wirft Klartext-Fehler (M002) bis zum separaten AD-8-Crypto-Ticket. Services nehmen den Provider injiziert → voll testbar. - Services
hrService.server.ts(Profile/Directory/Locations/Documents, MA-self vs HR-admin) +hrPasswordSafeService.server.ts(Vault/Entry/Access,withTenantRLS, 404-statt-403, Reveal audit-geloggt + Permission-Check, Werte nie in Listen, DSGVO-Export).hrAccess.server.ts(Konnektor-Gate + Bundle-Permissions). - Permissions
hr.*-Set + Rollen-Grants inpermissions-seed.server.ts. Konnektor:hrals Feature-Key + Blueprint + alle 3 Pläne (entitlements),tenantHasModule({moduleKey:'hr'})in jedem Loader. - View-Models
packages/view-models/src/hr/*(pure, Never-List-Values-Contract per Test gesichert) + Search-Schemashr-directory/hr-locations(Vault-Werte nie indexiert). - Routen
app.$tenant/hr.*(Hub, Directory+Detail, Locations, My-Documents, Passwort-Safe-Liste+Vault-Detail+Reveal+Export, Admin-Vault-Sicht) + Sidebar-Eintrag (Feature- + Permission-gegated) + i18n de+en. Finale Optik = Hot-Swap-Hülle, wartet auf Davids D-HR-Delta (Delta leer).
Verifiziert (lokal grün): pnpm typecheck (alle Pakete + web), pnpm run verify:i18n (Exit 0), eslint-staged/baseline/test-density-Gates, entitlements/search/view-models/sidebar-Tests, neue HR-VM- + Crypto-Seam-Tests (15), RLS-Gate-Test skippt sauber. (Pre-existing Windows-Only-Flake permissions-seed isPermissionsSeedDirectExecution unverändert, environmental.)
Stand: 2/5 DoD voll grün (#2, #4) = 40% strikt; #3/#5 zu ~90% (alles außer per-Tenant-Verschlüsselung), #1 schemaseitig vorbereitet. Gesamt ~70% gebaut. Offen/blockiert: (a) AD-8-Crypto-Ticket (Entscheidung c) → schaltet #1/#3/#5-Verschlüsselung scharf; (b) Davids D-HR-Delta → finale UI/Visual-Regression; (c) db push + RLS-Live-Verifikation (Staging/DB); (d) Merge-Migration entsteht erst beim main-Merge (AD-21). 0 weitere selbst machbar ohne Crypto-Ticket/David/DB.
Proof: Commit aa848dca7 (Branch feat/AK-P17a, lokal, nicht gepusht). Plane-Kommentar gesetzt (2026-06-27, akeshan). Ticket bleibt offen.
Noch im Ticket selbst machbar (ohne externe Blocker), als Folge-Schritte:
- Nebenbei-Validierung sobald lokal/Staging-Postgres da ist:
prisma db push+ RLS-Gate-Test (RLS_TEST_DATABASE_URL) live grün ziehen. - Demo-Seed (
is_demo_data) für Profile/Standorte/Vault, damit die Routen mit Daten zeigbar sind (sofern P17a-Scope; sonst AK-DEMO1). - Smoke-Test
tests/e2e/hr.spec.ts(Login → /hr → Hauptaktion) sobald die UI nicht mehr reine Hülle ist (nach Davids Delta). - Mobile-Tab-Bar-Eintrag (DoD B#11) für die Monteur-relevanten HR-Screens, falls vorgezogen erwünscht.
Update 2026-06-28 (Akeshan) — R-P5 in feat/AK-P17a gemergt + Crypto-Seam scharfgeschaltet. DoD jetzt 5/5 backend grün.
Co-Dev-Abstimmung: R-P5 von Raffael übernommen und auf feat/R-P5 fertig gebaut (per-Tenant-DEK-Envelope, AD-8). Entscheidung: feat/R-P5 voll in feat/AK-P17a mergen, damit das Crypto-Fundament hier verfügbar ist, dann den HR-Seam umbinden. 2 Commits:
efcf44a9Mergefeat/R-P5— bringtgetTenantFieldCrypto(@hivegrid/db) +crypto.prisma/TenantEncryptionKey. Konflikte alle „beide behalten": entitlements (hr + integrations,integrationsdefaultOrder 12→13 wegen unique+ascending-Test), permissions-seed/DefaultPermissions/AppSidebar, translations.json de+en (chirurgisch, kein Round-trip),packages/db/generated/**viaprisma generateaus dem Union-Schema neu.84fcf1e0Seam-Rebind —getHrFieldCrypto()liefert jetztgetTenantFieldCrypto()(strukturell identisch). Schaltet #1 (Notfallkontakt AES-256-GCM), #3 (Passwort-Safe Reveal/Export), #5 (sensible Felder verschlüsselt) scharf. Deferred-Fail-Closed-Gerüst (HrCryptoNotProvisionedError) bleibt. Seam-Test angepasst (liefert echten Provider, nicht das Gerüst) + neuer env-gegateter Round-trip-Integrationstest (HR_CRYPTO_TEST_DATABASE_URL): treibt die echten Services, prüft Ciphertext≠Klartext, Reveal-Round-trip, List versteckt Werte, fremder Tenant kann nicht entschlüsseln (skippt ohne DB).
Verifiziert: pnpm typecheck (alle Pakete + web, direkt-tsc, 0 Fehler — Turbo-Cache umgangen), verify:i18n Exit 0, Zieltests grün (Seam 5, HR-VMs 10, foundation+db-Crypto 16, entitlements 13), Round-trip-Test skippt sauber, beide Commits lefthook-grün.
Stand: 5/5 DoD backend grün. Nur noch extern blockiert: (a) Davids D-HR-Delta → finale Optik + echter 30s-Clipboard-Wipe + Visual-Regression/Smoke; (b) db push + RLS-Live + Crypto-Round-trip gegen echtes Postgres (kein lokales PG); (c) Merge-Migration beim main-Merge (AD-21). 0 selbst machbar offen. Kopplung (bewusst): feat/AK-P17a trägt jetzt R-P5s Commits; R-P5 muss vor/mit P17a auf main, bei R-P5-Review-Änderung hier nachziehen. Branch lokal, nicht gepusht, Plane-Status unverändert (In Progress).
Nachtrag 2026-06-28 — aktuellen origin/main reingemergt (5a30e950, Branch war 1 Commit hinter main: e7a888e3 WF-P2 Auth-Screens + du/Sie-Anrede-Toggle). Konflikt nur in prisma/schema/accounts.prisma: main fügte Tenant.anrede direkt neben den alten apps/dataConnections/appSyncRuns-Back-Relations ein, die R-P5 bewusst entfernt hat (App global, bare Scalars, AD-21) → anrede behalten, Back-Relations draußen gelassen. Generierter Prisma-Client aus dem Union-Schema neu erzeugt, translations.json auto-gemergt (hr + integrations + main-Keys, JSON valide). Verifiziert: pnpm typecheck direkt-tsc 0 Fehler, verify:i18n Exit 0, Zieltests grün (44). Branch jetzt 18 Commits ahead, lokal, nicht gepusht.
Soll/Ist-Verifikation 2026-06-28 (Akeshan) — unabhängiger Nach-Merge-Check, alle CI-Gates grün, DoD bleibt 5/5 backend.
Anforderungen (DoD #1–#5) gegen den Ist-Stand im Repo geprüft und nachgewiesen, dass durch die beiden Merges (R-P5 + origin/main) nichts gebrochen ist:
- CI-Gates (= was Gitea-CI + lefthook real fahren):
prisma generateaus Union-Schema sauber;pnpm typecheck(web) 0 Fehler;@hivegrid/api+@hivegrid/workertypecheck 0 Fehler;verify:i18nExit 0; Zieltests 44 passed / 3 skipped (HR-VMs 10, Seam 5, foundation+db-Crypto 16, entitlements 13; Round-trip skippt sauber ohne DB). - DoD-Ist im Code bestätigt: Crypto-Seam (
hrFieldCrypto.server.ts) liefertgetTenantFieldCrypto(Seam-Test grün) → #1/#3/#5 scharf;crypto.prisma/hr.prisma/appsEngine.prismaalle im Schema-Ordner,prisma generatevalidiert das Union-Schema;accounts.prisma-Konflikt korrekt (Tenant.anrededa, keine entfernten Back-Relations zurückgekrochen). - Befund (vorbestehend, KEIN Merge-Schaden): Der volle
pnpm -r typecheck(nicht von CI gefahren — CI = nur web/api/worker) zeigte 3 latenteTS2352-Fehler in den HR-VM-Tests (hr-directory.vm.test.ts,hr-password-safe.vm.test.ts): direkter Cast eines benannten Row-Interfaces aufRecord<string, unknown>. Die Tests liefen grün (vitest/esbuild typecheckt nicht), nur der Paket-tscstolperte — und der@hivegrid/view-models-tschängt in keinem Gate. Schon im Ursprungs-Commitaa848dca7vorhanden (tsconfig im Merge-Range unberührt), also nicht durch den Merge entstanden. Behoben mit dem von TS vorgeschlagenenas unknown as Record<…>-Cast in den 3 Stellen →@hivegrid/view-modelstypecheckt jetzt sauber, VM-Tests bleiben grün. Damit stimmt die frühere „direkt-tsc 0 Fehler"-Aussage jetzt auch paketweit. - Ebenfalls vorbestehend + außerhalb Scope (nicht angefasst):
packages/exports-tscwirftTS2688 Cannot find type definition file for 'node'— lokales@types/node-Resolution-Thema ("types":["node"]), im Merge-Range nicht berührt, in keinem CI-Gate, nicht HR/R-P5-bezogen. Notiert, nicht repariert (Fremd-Scope).
Stand unverändert: 5/5 DoD backend grün. Extern blockiert bleibt: (a) Davids D-HR-Delta → finale Optik + echter 30s-Clipboard-Wipe + Visual-Regression/Smoke; (b) db push + RLS-Live + Crypto-Round-trip gegen echtes Postgres; (c) Merge-Migration beim main-Merge (AD-21). 0 selbst machbar offen. Branch lokal (mehrere Commits ahead von origin/main, 0 behind), nicht gepusht, Plane-Status unverändert (In Progress).
Nachtrag 2026-06-28 — PR-Pipeline Build-Fix (Client/Server-Split). Der PR-Build (pnpm --filter @hivegrid/web build) fiel im Client-Environment mit „Server-only module referenced by client" auf app.$tenant/hr._index.tsx → ~/utils/integrations/hrAccess.server. Ursache: export const handle = { moduleKey: HR_MODULE_KEY } — handle ist kein server-gestrippter Export (RR strippt nur loader/action/middleware/headers), und HR_MODULE_KEY lag im .server-Guard → der ganze Server-Graph (Prisma/db) wurde in den Client-Bundle gezogen. Typecheck fängt das nicht (kein Client/Server-Split), nur der Build. Identisches Latenz-Muster im R-P5-Pendant integrations._index.tsx (INTEGRATIONS_MODULE_KEY aus integrationsAccess.server) — der Build bricht nur zuerst bei HR ab. Fix nach dem Walking-Skeleton-Präzedenzfall (modules/walkingSkeleton/constants.ts): den Modul-Key in das client-sichere Companion-Modul (hrRoutePaths.ts / integrationsRoutePaths.ts) verschoben, aus dem .server-Guard für Back-Compat re-exportiert, und den Route-Import auf das client-sichere Modul umgezogen. Verifiziert: lokaler pnpm --filter @hivegrid/web build → Client-Environment ✓ (8079 Module, no server-only error); web-typecheck 0 Fehler. (Lokaler Server-Build-Step bricht danach am bekannten Windows-/dev/null-Footgun in packages/mail ab — environmental, Linux-CI nicht betroffen.) 6 Dateien, beide Routen (HR + integrations).
Update 2026-07-08 (Akeshan) — Interim-UI aus ~/ui (AD-28). UI-DoD über den Interim-Pfad erfüllt.
Die HR-Screens rendern nicht mehr handgeschriebenes Tailwind (das war das Playbook-Negativbeispiel), sondern
sind aus ~/ui-Components recomposed — pure <XPage vm={} actions={} /> in apps/web/app/components/screens/hr/,
die Routen bauen nur das VM und injizieren Action-Callbacks (Fetcher bleiben in der Route). Kein VM-/Loader-/
Schema-Change. Gebaut (AK-P17a-Scope, 6 Screens + 4 Detail-/Sub-Screens):
HrHubPage,HrDirectoryPage+HrDirectoryDetailPage(Notfallkontakt-Reveal on-demand, Inline-Self-Edit),HrLocationsPage(+ Create-Dialog),HrMyDocumentsPage(Kind-Filter, read-only Büro-Uploads),HrPasswordSafeListPage+HrVaultDetailPage(Werte nie in der Liste, Reveal je Feld, echter 30-s-Clipboard-Wipe nach Copy viaCopyToClipboardButton+vm.copyAutoClearMs, DoD #3),HrAdminPasswordSafePage.- 57 neue Präsentations-i18n-Keys chirurgisch in de+en gespleißt (kein JSON-Round-trip).
Proof: Commit e0f8affd2 (Branch feat/AK-P17a-interim-ui, lokal, nicht gepusht) · pnpm --filter @hivegrid/web typecheck 0 Fehler · pnpm run verify:i18n Exit 0 (Parität ok, 0 missing-source) ·
lefthook pre-commit grün (lint-staged/eslint-baseline/secrets/test-density).
Interim-UI (Vorschau, Stand 2026-07-08): Screens aus ~/ui gebaut — apps/web/app/components/screens/hr/*.
Refactor-Nachzug offen: finale Subframe-Optik aus D-HR (Plane-Label design-nachzug). Noch selbst machbar
(nicht David-blockiert): Screen-Unit-Tests je <XPage>.test.tsx, Smoke e2e/smoke/hr-*, Hot-Swap-Adapter-Triplet;
Visual-Regression bleibt deferred (kein Screenshot-Harness im Repo, R-P5-Präzedenz). Demo-Seed (is_demo_data)
für Profile/Standorte/Vault als Folge-Task.
Dev-Nachzug (nach Davids D-HR-Delta)
- Spec/ENTITY-MODEL an Davids UI-Entscheidungen angepasst
- REQUIREMENTS/PHASE-SOURCES nachgezogen
- Plane-Ticket
AK-P17aaktualisiert - Finale
D-HR-Optik in<XPage>-Internals getauscht (VM/Loader/Route unverändert), Visual-Baseline gezogen,design-nachzug-Tag auf erledigt