Initial commit

2025-09-20 21:31:04 +02:00
Commit 6b9b6d4f20
--- a/VOLLSTAENDIGE_DOKUMENTATION.txt
+++ b/VOLLSTAENDIGE_DOKUMENTATION.txt
@ -0,0 +1,689 @@
+================================================================================
+                     SKILLMATE - VOLLSTÄNDIGE ANWENDUNGSDOKUMENTATION
+================================================================================
+
+PROJEKTÜBERSICHT
+================================================================================
+SkillMate ist ein Mitarbeiter-Skills-Management-System für Sicherheitsbehörden.
+Die Anwendung besteht aus drei Hauptmodulen:
+- Frontend (React-basierte Benutzeroberfläche)
+- Admin-Panel (React-basierte Administrationsoberfläche)  
+- Backend (Node.js/Express API-Server mit verschlüsselter SQLite-Datenbank)
+
+================================================================================
+1. PROJEKTSTRUKTUR
+================================================================================
+
+SkillMate/
+├── backend/                    # Node.js/Express API-Server
+│   ├── src/
+│   │   ├── config/            # Datenbank- und Sicherheitskonfiguration
+│   │   ├── middleware/        # Auth, Error-Handler, Role-Auth
+│   │   ├── routes/            # 14 API-Route-Module
+│   │   ├── services/          # Email, Encryption, Sync-Services
+│   │   └── utils/             # Logger und Hilfsfunktionen
+│   ├── package.json
+│   └── tsconfig.json
+│
+├── frontend/                   # React Benutzeroberfläche
+│   ├── src/
+│   │   ├── components/        # Wiederverwendbare UI-Komponenten
+│   │   ├── views/             # Hauptansichten/Seiten
+│   │   ├── stores/            # Zustand-Management (Zustand)
+│   │   ├── services/          # API-Client
+│   │   └── data/              # Statische Daten
+│   ├── package.json
+│   ├── tailwind.config.js
+│   └── tsconfig.json
+│
+├── admin-panel/               # React Admin-Oberfläche
+│   ├── src/
+│   │   ├── components/
+│   │   ├── views/
+│   │   ├── services/
+│   │   └── stores/
+│   ├── package.json
+│   └── tailwind.config.js
+│
+├── shared/                    # Gemeinsame TypeScript-Typen (referenziert)
+└── main.py                    # Python-Anwendungsstarter
+
+================================================================================
+2. TECHNOLOGIE-STACK
+================================================================================
+
+FRONTEND & ADMIN-PANEL:
+- React 18.2.0 mit TypeScript 5.3.0
+- Vite als Build-Tool
+- React Router 6.20.0 für Routing
+- Zustand 4.4.7 für State Management
+- Axios 1.6.2 für HTTP-Requests
+- Tailwind CSS 3.3.6 für Styling
+- Lucide React für Icons
+
+BACKEND:
+- Node.js mit Express 4.18.2
+- TypeScript 5.3.0
+- better-sqlite3-multiple-ciphers 12.2.0 (verschlüsselte Datenbank)
+- jsonwebtoken 9.0.2 für JWT-Authentifizierung
+- bcrypt 6.0.0 für Passwort-Hashing
+- crypto-js 4.2.0 für Feld-Verschlüsselung
+- winston 3.11.0 für Logging
+- nodemailer 7.0.6 für E-Mail-Versand
+- multer 2.0.1 für Datei-Uploads
+- helmet 7.1.0 für Sicherheits-Header
+- cors 2.8.5 für Cross-Origin Requests
+
+================================================================================
+3. DATENBANK-SCHEMA (SQLite mit AES-256 Verschlüsselung)
+================================================================================
+
+TABELLE: employees
+------------------
+id                    TEXT PRIMARY KEY      # UUID
+first_name           TEXT NOT NULL
+last_name            TEXT NOT NULL
+employee_number      TEXT UNIQUE NOT NULL
+photo                TEXT                  # Base64 oder Pfad
+position             TEXT NOT NULL
+department           TEXT NOT NULL
+email                TEXT NOT NULL         # VERSCHLÜSSELT
+email_hash           TEXT                  # Für Suche
+phone                TEXT NOT NULL         # VERSCHLÜSSELT
+phone_hash           TEXT                  # Für Suche
+mobile               TEXT                  # VERSCHLÜSSELT
+office               TEXT
+availability         TEXT NOT NULL         # 'available', 'busy', 'offline'
+clearance_level      TEXT                  # VERSCHLÜSSELT
+clearance_valid_until TEXT                 # VERSCHLÜSSELT
+clearance_issued_date TEXT
+created_at           TEXT NOT NULL
+updated_at           TEXT NOT NULL
+created_by           TEXT NOT NULL
+updated_by           TEXT
+
+TABELLE: users
+--------------
+id                   TEXT PRIMARY KEY
+username             TEXT UNIQUE NOT NULL
+email                TEXT NOT NULL         # VERSCHLÜSSELT
+email_hash           TEXT                  # Für Suche
+password             TEXT NOT NULL         # Bcrypt gehashed
+role                 TEXT NOT NULL         # 'admin', 'superuser', 'user'
+employee_id          TEXT                  # FK zu employees
+last_login           TEXT
+is_active            INTEGER DEFAULT 1
+created_at           TEXT NOT NULL
+updated_at           TEXT NOT NULL
+
+TABELLE: skills
+---------------
+id                   TEXT PRIMARY KEY
+name                 TEXT NOT NULL
+category             TEXT NOT NULL
+description          TEXT
+requires_certification INTEGER DEFAULT 0
+expires_after        INTEGER              # Tage bis Ablauf
+
+TABELLE: employee_skills (Verknüpfungstabelle)
+-----------------------------------------------
+employee_id          TEXT NOT NULL
+skill_id             TEXT NOT NULL
+level                TEXT                  # 'basic', 'intermediate', 'advanced', 'expert'
+verified             INTEGER DEFAULT 0
+verified_by          TEXT
+verified_date        TEXT
+PRIMARY KEY (employee_id, skill_id)
+
+TABELLE: language_skills
+------------------------
+id                   TEXT PRIMARY KEY
+employee_id          TEXT NOT NULL
+language             TEXT NOT NULL
+proficiency          TEXT NOT NULL         # A1-C2, Muttersprachler
+certified            INTEGER DEFAULT 0
+certificate_type     TEXT
+is_native            INTEGER DEFAULT 0
+can_interpret        INTEGER DEFAULT 0
+
+TABELLE: specializations
+------------------------
+id                   TEXT PRIMARY KEY
+employee_id          TEXT NOT NULL
+name                 TEXT NOT NULL
+
+TABELLE: security_audit_log
+---------------------------
+id                   TEXT PRIMARY KEY
+entity_type          TEXT NOT NULL
+entity_id            TEXT NOT NULL
+action               TEXT NOT NULL         # CRUD, login, logout, failed_login
+user_id              TEXT
+changes              TEXT                  # JSON der Änderungen
+timestamp            TEXT NOT NULL
+ip_address           TEXT
+user_agent           TEXT
+risk_level           TEXT                  # low, medium, high, critical
+
+TABELLE: system_settings
+------------------------
+key                  TEXT PRIMARY KEY
+value                TEXT NOT NULL
+description          TEXT
+updated_at           TEXT NOT NULL
+updated_by           TEXT
+
+================================================================================
+4. API-ENDPUNKTE
+================================================================================
+
+AUTHENTIFIZIERUNG (/api/auth)
+-----------------------------
+POST /login          - Benutzeranmeldung (username/email + password)
+                      Returns: { user, token }
+POST /logout         - Benutzerabmeldung
+
+MITARBEITER (/api/employees)
+----------------------------
+GET /                - Alle Mitarbeiter mit Skills abrufen
+GET /:id             - Einzelnen Mitarbeiter abrufen
+POST /               - Neuen Mitarbeiter anlegen (admin/poweruser)
+PUT /:id             - Mitarbeiter aktualisieren
+DELETE /:id          - Mitarbeiter löschen (admin)
+POST /search         - Mitarbeiter nach Skills suchen
+                      Body: { skills: string[], category?: string }
+
+BENUTZER (/api/users, /api/admin/users)
+---------------------------------------
+GET /                - Alle Benutzer abrufen (admin)
+GET /:id             - Benutzer abrufen
+POST /               - Neuen Benutzer anlegen (admin)
+PUT /:id             - Benutzer aktualisieren (admin)
+DELETE /:id          - Benutzer löschen (admin)
+
+SKILLS (/api/skills)
+-------------------
+GET /                - Alle verfügbaren Skills abrufen
+POST /initialize     - Standard-Skills initialisieren (admin)
+
+DATEI-UPLOAD (/api/upload)
+--------------------------
+POST /photo          - Mitarbeiterfoto hochladen
+                      FormData: file (multipart)
+
+NETZWERK & SYNC (/api/network, /api/sync)
+-----------------------------------------
+GET /network/discover     - Andere Instanzen im Netzwerk finden
+POST /sync/push          - Daten an andere Instanz senden
+POST /sync/pull          - Daten von anderer Instanz holen
+GET /sync/status         - Synchronisationsstatus
+
+SYSTEM (/api/admin/settings)
+----------------------------
+GET /                - Alle Einstellungen abrufen
+PUT /:key            - Einstellung aktualisieren
+
+HEALTH CHECK
+-----------
+GET /api/health      - Server-Status prüfen
+
+================================================================================
+5. AUTHENTIFIZIERUNGS-FLOW
+================================================================================
+
+1. LOGIN-PROZESS:
+   - Benutzer sendet username/email + password an /api/auth/login
+   - Backend validiert Credentials gegen verschlüsselte Datenbank
+   - Passwort wird mit bcrypt verifiziert
+   - JWT-Token wird mit 24h Gültigkeit generiert
+   - User-Objekt und Token werden zurückgegeben
+
+2. AUTORISIERUNG:
+   - JWT-Token wird bei jedem Request im Authorization-Header gesendet
+   - Middleware verifiziert Token und extrahiert User-Daten
+   - Rollenbasierte Zugriffskontrolle (admin > superuser > user)
+   - Granulare Berechtigungen für spezifische Aktionen
+
+3. SICHERHEITS-FEATURES:
+   - Feld-Level-Verschlüsselung für sensible Daten
+   - Security Audit Logging aller kritischen Aktionen
+   - CSRF-Schutz durch Helmet
+   - Input-Validierung und Sanitization
+   - Rate-Limiting für Login-Versuche
+
+================================================================================
+6. GUI-AUFBAU UND STYLING
+================================================================================
+
+LAYOUT-STRUKTUR (Frontend & Admin-Panel)
+----------------------------------------
+┌─────────────────────────────────────────────────────────┐
+│                    HEADER (64px)                        │
+│  Logo | Navigation                    User | Theme      │
+├──────────┬──────────────────────────────────────────────┤
+│          │                                              │
+│          │              MAIN CONTENT                    │
+│ SIDEBAR  │                                              │
+│  (256px) │         (Responsive Grid/Flex)               │
+│          │                                              │
+│          │                                              │
+└──────────┴──────────────────────────────────────────────┘
+
+FARBSCHEMA
+----------
+LIGHT MODE:
+- Primär Blau:        #3182CE (hover: #2563EB)
+- Hintergrund:        #F8FAFC (main), #FFFFFF (cards)
+- Text Primär:        #1A365D
+- Text Sekundär:      #2D3748
+- Text Tertiär:       #4A5568
+- Text Quaternär:     #718096
+- Erfolg:             #059669
+- Warnung:            #D97706
+- Fehler:             #DC2626
+- Rahmen:             #E2E8F0
+
+DARK MODE:
+- Hintergrund:        #000000 (main), #1A1F3A (secondary)
+- Akzent Cyan:        #00D4FF
+- Text Primär:        #FFFFFF
+- Text Sekundär:      rgba(255,255,255,0.9)
+- Text Tertiär:       rgba(255,255,255,0.7)
+- Rahmen:             #2D3748
+
+TYPOGRAFIE
+----------
+- Schriftart:         Poppins (Primary), system-ui (Fallback)
+- Titel Groß:         32px, font-semibold
+- Titel Dialog:       24px, font-semibold
+- Titel Sektion:      20px, font-semibold
+- Body:               14px, font-normal
+- Small:              12px, font-normal
+- Caption:            10px, font-medium
+
+ABSTÄNDE
+--------
+- Container:          40px padding
+- Card:               32px padding
+- Element:            16px padding
+- Inline:             8px padding
+
+BORDER-RADIUS
+-------------
+- Card:               16px
+- Button:             24px
+- Input:              8px
+- Badge:              12px
+- Avatar:             50% (kreisförmig)
+
+KOMPONENTEN-STYLING
+-------------------
+BUTTONS:
+- Primär:             bg-blue-600, hover:bg-blue-700, text-white
+- Sekundär:           bg-gray-200, hover:bg-gray-300, text-gray-700
+- Gefahr:             bg-red-600, hover:bg-red-700, text-white
+- Höhe:               40px (standard), 32px (small), 48px (large)
+- Padding:            16px horizontal
+
+INPUTS:
+- Höhe:               40px
+- Padding:            12px
+- Border:             1px solid #E2E8F0
+- Focus:              ring-2 ring-blue-500
+- Dark Mode:          bg-gray-800, border-gray-600
+
+CARDS:
+- Background:         white (light), #1A1F3A (dark)
+- Shadow:             0 1px 3px rgba(0,0,0,0.1)
+- Hover Shadow:       0 4px 6px rgba(0,0,0,0.1)
+- Transition:         all 0.2s ease
+
+SIDEBAR:
+- Width:              256px (expanded), 64px (collapsed)
+- Background:         white (light), #1A1F3A (dark)
+- Items:              48px height, hover:bg-gray-100
+- Active Item:        bg-blue-50, border-left: 3px solid blue
+
+TABLES:
+- Header:             bg-gray-50, font-semibold
+- Row Height:         48px
+- Hover:              bg-gray-50
+- Border:             1px solid #E2E8F0
+
+RESPONSIVE BREAKPOINTS
+---------------------
+- Mobile:             < 640px
+- Tablet:             640px - 1024px
+- Desktop:            > 1024px
+
+ANIMATIONEN
+-----------
+- Transition Default: 200ms ease
+- Hover Scale:        scale(1.02)
+- Click Scale:        scale(0.98)
+- Fade In:            opacity 0 to 1, 300ms
+- Slide In:           translateX(-100%) to 0, 300ms
+
+================================================================================
+7. FRONTEND KOMPONENTEN-HIERARCHIE
+================================================================================
+
+APP.TSX (Router-Konfiguration)
+-------------------------------
+<BrowserRouter>
+  <Routes>
+    <Route path="/login" element={<Login />} />
+    <Route element={<Layout />}>
+      <Route path="/" element={<Dashboard />} />
+      <Route path="/employees" element={<EmployeeList />} />
+      <Route path="/employees/new" element={<EmployeeForm />} />
+      <Route path="/employees/:id" element={<EmployeeDetail />} />
+      <Route path="/employees/:id/edit" element={<EmployeeForm />} />
+      <Route path="/search" element={<SkillSearch />} />
+      <Route path="/settings" element={<Settings />} />
+      <Route path="/analytics" element={<WorkspaceAnalytics />} />
+      <Route path="/floor-plan" element={<FloorPlan />} />
+      <Route path="/desk-booking" element={<DeskBooking />} />
+    </Route>
+  </Routes>
+</BrowserRouter>
+
+LAYOUT-KOMPONENTE
+-----------------
+<div className="flex h-screen">
+  <Sidebar>
+    - Logo
+    - NavigationItems[]
+      - Dashboard
+      - Mitarbeiter
+      - Suche
+      - Analytics
+      - Einstellungen
+    - UserInfo
+  </Sidebar>
+  
+  <div className="flex-1 flex flex-col">
+    <Header>
+      - Breadcrumbs
+      - SearchBar
+      - NotificationBell
+      - UserMenu
+      - ThemeToggle
+    </Header>
+    
+    <main className="flex-1 overflow-auto">
+      <Outlet /> {/* Routed Content */}
+    </main>
+  </div>
+</div>
+
+WIEDERVERWENDBARE KOMPONENTEN
+-----------------------------
+EmployeeCard:
+  - Foto (Avatar)
+  - Name & Position
+  - Abteilung
+  - Verfügbarkeitsstatus
+  - Skills-Tags
+  - Kontakt-Icons
+
+PhotoUpload:
+  - Drag & Drop Zone
+  - File Input
+  - Preview
+  - Upload Progress
+  - Error Handling
+
+SkillBadge:
+  - Skill Name
+  - Level Indicator
+  - Verified Icon
+  - Category Color
+
+SearchFilter:
+  - Kategorie-Dropdown
+  - Skill-Multi-Select
+  - Level-Filter
+  - Verfügbarkeits-Filter
+  - Reset-Button
+
+DataTable:
+  - Sortierbare Header
+  - Pagination
+  - Row Selection
+  - Bulk Actions
+  - Export Funktion
+
+Modal:
+  - Overlay
+  - Content Container
+  - Close Button
+  - Title
+  - Footer Actions
+
+================================================================================
+8. STATE MANAGEMENT (ZUSTAND STORES)
+================================================================================
+
+AUTH STORE
+----------
+interface AuthState {
+  user: User | null
+  token: string | null
+  isAuthenticated: boolean
+  
+  // Actions
+  login: (user: User, token: string) => void
+  logout: () => void
+  updateUser: (updates: Partial<User>) => void
+  checkAuth: () => Promise<boolean>
+}
+
+THEME STORE
+-----------
+interface ThemeState {
+  theme: 'light' | 'dark'
+  sidebarCollapsed: boolean
+  
+  // Actions
+  toggleTheme: () => void
+  setTheme: (theme: 'light' | 'dark') => void
+  toggleSidebar: () => void
+  setSidebarCollapsed: (collapsed: boolean) => void
+}
+
+EMPLOYEE STORE (implizit)
+------------------------
+- Employees werden via React Query/SWR gecached
+- Optimistic Updates bei Änderungen
+- Background Refetching
+- Pagination State lokal
+
+================================================================================
+9. ENTWICKLUNGS- UND BUILD-PROZESS
+================================================================================
+
+ENTWICKLUNG
+-----------
+Frontend:
+  npm run dev              # Startet Vite Dev-Server auf Port 5173
+  
+Backend:
+  npm run dev              # Startet Nodemon mit ts-node
+  
+Admin-Panel:
+  npm run dev              # Startet Vite Dev-Server auf Port 5174
+
+PRODUCTION BUILD
+---------------
+Frontend:
+  npm run build            # Erstellt optimierten Build in dist/
+  
+Backend:
+  npm run build            # Kompiliert TypeScript zu JavaScript
+  npm start                # Startet Production Server
+  
+Admin-Panel:
+  npm run build            # Erstellt optimierten Build
+
+UMGEBUNGSVARIABLEN
+-----------------
+Backend (.env):
+  PORT=3000
+  DATABASE_PATH=./data/skillmate.db
+  DATABASE_KEY=your-encryption-key
+  JWT_SECRET=your-jwt-secret
+  FIELD_ENCRYPTION_KEY=your-field-key
+  SMTP_HOST=smtp.example.com
+  SMTP_PORT=587
+  SMTP_USER=user@example.com
+  SMTP_PASS=password
+
+Frontend (.env):
+  VITE_API_URL=http://localhost:3000/api
+  VITE_APP_TITLE=SkillMate
+
+================================================================================
+10. SICHERHEITS-FEATURES
+================================================================================
+
+1. DATENBANK-VERSCHLÜSSELUNG:
+   - AES-256 Verschlüsselung der gesamten Datenbank
+   - Zusätzliche Feld-Level-Verschlüsselung für PII
+
+2. AUTHENTIFIZIERUNG:
+   - JWT mit 24h Expiration
+   - Refresh Token Mechanismus
+   - Session Management
+
+3. AUTORISIERUNG:
+   - Rollenbasierte Zugriffskontrolle (RBAC)
+   - Granulare Berechtigungen
+   - API-Endpoint-Level Security
+
+4. AUDIT LOGGING:
+   - Alle CRUD-Operationen
+   - Login/Logout Events
+   - Failed Login Attempts
+   - Risk Level Assessment
+
+5. INPUT VALIDIERUNG:
+   - Express-Validator für alle Inputs
+   - SQL Injection Prevention
+   - XSS Protection
+   - CSRF Token Validation
+
+6. NETZWERK-SICHERHEIT:
+   - HTTPS in Production
+   - Helmet Security Headers
+   - CORS Configuration
+   - Rate Limiting
+
+================================================================================
+11. SPEZIELLE FEATURES
+================================================================================
+
+MULTI-INSTANZ-SYNCHRONISATION
+-----------------------------
+- Automatische Netzwerk-Discovery
+- Bidirektionale Daten-Synchronisation
+- Konfliktauflösung
+- Scheduled Sync Jobs
+- Sync History & Rollback
+
+SKILL-VERWALTUNG
+---------------
+- Hierarchische Skill-Kategorien
+- Skill-Level (Basic bis Expert)
+- Zertifizierungsverwaltung
+- Ablaufdaten-Tracking
+- Skill-Verifizierung
+
+SPRACHKENNTNISSE
+---------------
+- GER-Level (A1-C2)
+- Muttersprachler-Kennzeichnung
+- Dolmetscher-Fähigkeiten
+- Zertifikats-Verwaltung
+
+ARBEITSPLATZ-FUNKTIONEN
+----------------------
+- Büro-Zuweisung
+- Verfügbarkeitsstatus
+- Desk Booking System
+- Floor Plan Visualization
+
+E-MAIL-INTEGRATION
+-----------------
+- SMTP-Konfiguration
+- Benachrichtigungen
+- Passwort-Reset
+- Skill-Ablauf-Erinnerungen
+
+================================================================================
+12. INSTALLATION UND DEPLOYMENT
+================================================================================
+
+VORAUSSETZUNGEN
+--------------
+- Node.js 18+ mit npm
+- Python 3.8+ (für Launcher)
+- SQLite3
+- 4GB RAM minimum
+- Windows 10/11 oder Linux
+
+INSTALLATION
+-----------
+1. Repository klonen
+2. Dependencies installieren:
+   cd backend && npm install
+   cd ../frontend && npm install
+   cd ../admin-panel && npm install
+
+3. Datenbank initialisieren:
+   cd backend
+   npm run init-db
+
+4. Umgebungsvariablen konfigurieren
+
+5. Anwendung starten:
+   python main.py
+   oder
+   npm run dev (in jedem Ordner)
+
+DEPLOYMENT
+----------
+1. Production Builds erstellen
+2. Reverse Proxy konfigurieren (nginx/Apache)
+3. SSL-Zertifikate einrichten
+4. Systemd Service erstellen (Linux)
+5. Backup-Strategie implementieren
+
+================================================================================
+13. WARTUNG UND MONITORING
+================================================================================
+
+LOGGING
+-------
+- Winston Logger mit Rotation
+- Log-Level: error, warn, info, debug
+- Separate Logs für Security Events
+- Performance Metrics
+
+BACKUP
+------
+- Automatische Datenbank-Backups
+- Verschlüsselte Backup-Dateien
+- Retention Policy (30 Tage)
+- Restore-Funktionalität
+
+MONITORING
+----------
+- Health Check Endpoint
+- Performance Metrics
+- Error Tracking
+- User Activity Dashboard
+
+================================================================================
+ENDE DER DOKUMENTATION
+================================================================================