SkillMate – Detaillierte Anwendungsbeschreibung ================================================ 1) Überblick ------------- SkillMate ist eine interne Anwendung zur Erfassung, Suche und Verwaltung von Kompetenzen (Skills) von Mitarbeitenden. Sie besteht aus drei Hauptteilen: - Frontend (Endanwender): React/TypeScript App (Vite) im Ordner `frontend`. - Admin-Panel: Separates React/TypeScript Frontend im Ordner `admin-panel` für Administratoren/Superuser. - Backend: Express/TypeScript API mit SQLite (verschlüsselte Speicherung) im Ordner `backend`. - Gemeinsame Typen/Konstanten im Paket `shared`. Ziel ist es, Kompetenzen hierarchisch zu pflegen (Kategorie → Unterkategorie → Skill), Mitarbeitende zu verwalten und anhand freier Suche oder Skills passende Personen zu finden. 2) Hauptfunktionen ------------------- - Mitarbeitendenverwaltung (Lesen/Detailansicht im Frontend, Erstellen/Bearbeiten im Admin-Panel) - Skill-Suche nach Freitext und/oder spezifischen Skills (Frontend) - Mein Profil: Eigenes Profil einsehen und Kompetenz-Level pflegen (Frontend) - Skill-Verwaltung: Kategorien, Unterkategorien und Skills pflegen (Admin-Panel) - Benutzerverwaltung: Benutzer anlegen, Rollen verwalten, Status ändern (Admin-Panel) - Uploads: Mitarbeiterfotos (vom Backend ausgeliefert) 3) Architektur und Code-Struktur --------------------------------- Repository-Wurzel: - `frontend/` – Endanwender-App - `admin-panel/` – Admin-Frontend - `backend/` – Express API - `shared/` – Gemeinsame Typen/Konstanten (z. B. `User`, `Employee`) - `main.py`, Skripte und Hilfsdateien Frontend (Ordner `frontend`): - `src/App.tsx`: Routing (Login, Dashboard, Mitarbeiterliste/-detail, Skill-Suche, Mein Profil, Einstellungen) - `src/views/`: Seiten wie `Dashboard.tsx`, `EmployeeList.tsx`, `EmployeeDetail.tsx`, `EmployeeForm.tsx`, `SkillSearch.tsx`, `MyProfile.tsx`, `Settings.tsx` - `src/components/`: UI-Komponenten (Layout, Sidebar, EmployeeCard, SkillLevelBar etc.) - `src/services/api.ts`: Axios-Client, Endpunkte `auth`, `employees`, `skills` - Zustandsspeicher: `stores` (z. B. `authStore`, `themeStore`) Admin-Panel (Ordner `admin-panel`): - `src/App.tsx`: Routen (Dashboard, Benutzerverwaltung, Skill-Verwaltung, Sync-/E-Mail-Einstellungen) - `src/views/`: `UserManagement.tsx`, `SkillManagement.tsx`, `CreateEmployee.tsx` u. a. - `src/services/api.ts`: Axios-Client mit Token-Interceptor Backend (Ordner `backend`): - `src/index.ts`: Express-App, Routing-Registrierung - `src/config/secureDatabase.ts`: SQLite-Initialisierung (verschlüsselte Felder, Hash-Spalten für Suche), Tabellen-Definitionen - `src/routes/`: - `auth.ts` – Login über Benutzername/E-Mail (JWT) - `employeesSecure.ts` – Mitarbeitenden-Routen (verschlüsselte Felder, Join-Tabellen) - `skills.ts` – Skills und Hierarchien (Kontrolliertes Vokabular) - `users.ts`, `usersAdmin.ts` – Benutzer-Endpoints (Admin) - weitere (upload, settings, workspaces …) - `src/middleware/`: Authentifizierung, Rollen-/Berechtigungsprüfungen - `src/services/`: Verschlüsselung, E-Mail, Sync Shared (Ordner `shared`): - `index.d.ts` TypeScript-Typen (User, Employee, Skill, usw.) - `index.js`, `skills.js` Konstanten (z. B. `ROLE_PERMISSIONS`, `SKILL_HIERARCHY`) 4) Datenmodell (vereinfacht) ----------------------------- - `users`: Benutzer (username, email verschlüsselt + Hash, password (bcrypt), role, employee_id, is_active, …) - `employees`: Mitarbeitende (first_name, last_name, employee_number, photo, position, department, email/phone verschlüsselt+Hash, availability, …) - `skills`: Skills (id, name, category = `catId.subId`, description, expires_after) - `employee_skills`: Zuordnung Mitarbeitende↔Skills mit Level/Verifikation - `language_skills`: Sprachkenntnisse (Kompatibilitäts- und Suchzwecke) - `specializations`: Freitext-Spezialisierungen je Mitarbeitendem - `controlled_vocabulary`: Kontrolliertes Vokabular (z. B. `skill_category` und `skill_subcategory`) - Diverse weitere Tabellen für optionale Module (Workspaces, Bookings etc.) 5) Sicherheit & Authentifizierung ---------------------------------- - Login via `/api/auth/login` (JWT), Token wird im Frontend gespeichert und als `Authorization: Bearer ` gesendet. - Berechtigungen über Rollen (`admin`, `superuser`, `user`) und `ROLE_PERMISSIONS` in `shared/index.js`. - Sensible Felder (z. B. E-Mail, Telefonnummern) in `employees` verschlüsselt gespeichert; Hash-Spalten dienen der Suche. - Admin-Panel-Endpunkte prüfen zusätzliche Berechtigungen (`users:read/update/create`, `skills:update`, `admin:panel:access`). 6) Frontend-Routen (Auszug) ---------------------------- - `/login`: Anmeldung - `/`: Dashboard - `/employees`: Mitarbeiterliste (Filter, Suche) - `/employees/:id`: Mitarbeiter-Detail (Kontakt, allgemeine Infos, Kompetenzen) - `/employees/new`: Neuanlage (sofern Rolle berechtigt) - `/search`: Skill-Suche (Freitext + Skillfilter mit Hierarchieauswahl) - `/profile`: Mein Profil (eigene Daten, Kompetenzen pflegen) - `/settings`: Einstellungen Admin-Panel-Routen (Auszug): - `/`: Dashboard (Statistiken) - `/users`: Benutzerverwaltung (Rollen, Aktivierung, Passwort zurücksetzen) - `/skills`: Skill-Verwaltung (Kategorien, Unterkategorien, Skills pflegen) - weitere: Sync-/E-Mail-/Systemeinstellungen 7) API-Endpunkte (Auszug) ------------------------- Authentifizierung - `POST /api/auth/login` – Login via Benutzername oder E-Mail + Passwort → JWT Mitarbeitende - `GET /api/employees` – Liste (für Admin-Panel, erfordert Berechtigung) - `GET /api/employees/public` – Gefilterte Liste für Frontend (nur verknüpfte, aktive Nutzer) - `GET /api/employees/:id` – Detailansicht - `POST /api/employees` – Anlegen (berechtigungsbasiert) - `PUT /api/employees/:id` – Aktualisieren (eigene oder Admin/Superuser) - `DELETE /api/employees/:id` – Löschen (Admin) Skills - `GET /api/skills` – Liste aller Skills - `GET /api/skills/hierarchy` – Hierarchische Struktur (Kategorien → Unterkategorien → Skills) - `POST /api/skills` – Skill anlegen (Admin/Superuser), benötigt vorhandene Unterkategorie - `PUT /api/skills/:id` – Skill ändern (Admin) - `DELETE /api/skills/:id` – Skill löschen (Admin) - Kategorien/Unterkategorien: `POST/PUT/DELETE /api/skills/categories…` (Admin) Benutzer (Admin) - `GET /api/admin/users` – Liste aller Benutzer - `PUT /api/admin/users/:id/role` – Rolle setzen - `PUT /api/admin/users/:id/status` – Aktiv/Inaktiv - `POST /api/admin/users/:id/reset-password` – Passwort zurücksetzen (Temp-Passwort) - `POST /api/admin/users/bulk-create-from-employees` – Benutzer aus Mitarbeitenden anlegen 8) Datenfluss (Beispiele) -------------------------- - Login: Frontend → `POST /api/auth/login` → Token speichern → künftige Requests mit `Authorization`-Header. - Mitarbeiterliste (Frontend): `GET /api/employees/public` → Kartenansicht mit `EmployeeCard`. - Skill-Suche: Frontend lädt per `GET /api/skills/hierarchy` Kategorien/Unterkategorien/Skills, filtert lokal; Trefferanzeige über `employeeApi.getAll()` / Filterung nach ausgewählten Skill-IDs. - Mein Profil: `GET /api/employees/:id` → Anzeige + lokale Bearbeitung → `PUT /api/employees/:id` zum Speichern. - Admin: Skill-Verwaltung liest `GET /api/skills/hierarchy`; Kategorien/Unterkategorien/Skills werden via `POST/PUT/DELETE` gepflegt. 9) Konfiguration & Umgebungsvariablen -------------------------------------- Frontend/Admin-Panel (`.env`): - `VITE_API_URL` – Basis-URL der API (z. B. `http://localhost:3004/api`) Backend (`.env`): - `PORT` – Port der API (Standard 3004) - `JWT_SECRET` – Geheimnis für Tokens - `DATABASE_ENCRYPTION_KEY` – Schlüssel für DB-Dateiverschlüsselung - `FIELD_ENCRYPTION_KEY` – Schlüssel für Feldverschlüsselung (E-Mail/Telefon …) - optional: `DATABASE_PATH` (Ablageort der verschlüsselten DB-Datei) 10) Sicherheitshinweise ------------------------ - In Produktion müssen `JWT_SECRET`, `DATABASE_ENCRYPTION_KEY` und `FIELD_ENCRYPTION_KEY` gesetzt sein. - Passwörter werden mittels bcrypt gespeichert, sensible Felder per AES verschlüsselt. - CORS, Helmet und Token-Validierung sind aktiv; Admin-Panel-Endpunkte prüfen Rollen/Permissions. 11) Typische Probleme & Hinweise --------------------------------- - Bei „keine Daten“ in Frontends: Prüfen, ob Token gültig und Backend erreichbar (Netzwerk/Port, 401/403/5xx in Browser-Konsole). - Skill-Hierarchie leer: Kontrolliertes Vokabular wurde ggf. noch nicht gepflegt; Skills erscheinen erst bei gültiger Kategorie/Unterkategorie. - E-Mail im Profil ist im Frontend schreibgeschützt (kommt aus dem Login/Benutzerkonto). Änderungen über Admin-Panel/Benutzerverwaltung. 12) Weiterentwicklung ---------------------- - Team-Zusammenstellung: Platzhalter-Ansicht vorhanden; Logik kann um Matching nach Rollen/Skills erweitert werden. - Erweiterte Suche: Gewichtung nach Skill-Level, Verfügbarkeit, Sprache o. Ä. - Audit-/Sync-Funktionen ausbauen; E-Mail-Benachrichtigungen bei Änderungen. Ansprechperson & Lizenz ----------------------- Interner Einsatz. Für Fragen zur Architektur und Erweiterung bitte an das Entwicklungsteam wenden.