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 <token>` 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.

