Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/.planning/ticket-docs/AK-P17a.md
T
2026-07-08 16:15:37 +02:00

19 KiB
Raw Blame History

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.prisma nur 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.prisma nur 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_data auf 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-safe
  • ROADMAP.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 main gemergt. feat/AK-P17a (inkl. der eingemergten R-P5-Commits) ging mit PR #5 (squash, Merge-Commit b0fae1af8, Base main, 2026-06-28 17:50, merged_by raffael) auf main; Docker-Nachzug packages/integrations/package.json via 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 im main-Tree. Die „Branch lokal, nicht gepusht"-Notizen unten sind damit überholt. Backend 5/5 DoD grün. Extern offen bleibt nur: Davids D-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.prisma unberührt): HrEmployeeProfile, HrLocation, HrEmployeeDocument, HrResource/HrQuickLink, EmployeePasswordSafeVault/Entry/Access. Sensible Werte als *Ciphertext-Spalten. prisma validate + generate grün. db push lokal 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-Test rls-hr-isolation.integration.test.ts (skippt ohne RLS_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 in permissions-seed.server.ts. Konnektor: hr als 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-Schemas hr-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:

  • efcf44a9 Merge feat/R-P5 — bringt getTenantFieldCrypto (@hivegrid/db) + crypto.prisma/TenantEncryptionKey. Konflikte alle „beide behalten": entitlements (hr + integrations, integrations defaultOrder 12→13 wegen unique+ascending-Test), permissions-seed/DefaultPermissions/AppSidebar, translations.json de+en (chirurgisch, kein Round-trip), packages/db/generated/** via prisma generate aus dem Union-Schema neu.
  • 84fcf1e0 Seam-Rebind — getHrFieldCrypto() liefert jetzt getTenantFieldCrypto() (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 generate aus Union-Schema sauber; pnpm typecheck (web) 0 Fehler; @hivegrid/api + @hivegrid/worker typecheck 0 Fehler; verify:i18n Exit 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) liefert getTenantFieldCrypto (Seam-Test grün) → #1/#3/#5 scharf; crypto.prisma/hr.prisma/appsEngine.prisma alle im Schema-Ordner, prisma generate validiert das Union-Schema; accounts.prisma-Konflikt korrekt (Tenant.anrede da, 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 latente TS2352-Fehler in den HR-VM-Tests (hr-directory.vm.test.ts, hr-password-safe.vm.test.ts): direkter Cast eines benannten Row-Interfaces auf Record<string, unknown>. Die Tests liefen grün (vitest/esbuild typecheckt nicht), nur der Paket-tsc stolperte — und der @hivegrid/view-models-tsc hängt in keinem Gate. Schon im Ursprungs-Commit aa848dca7 vorhanden (tsconfig im Merge-Range unberührt), also nicht durch den Merge entstanden. Behoben mit dem von TS vorgeschlagenen as unknown as Record<…>-Cast in den 3 Stellen → @hivegrid/view-models typecheckt 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-tsc wirft TS2688 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 via CopyToClipboardButton + 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-P17a aktualisiert
  • Finale D-HR-Optik in <XPage>-Internals getauscht (VM/Loader/Route unverändert), Visual-Baseline gezogen, design-nachzug-Tag auf erledigt