# Organigramm & Vertretungsmanagement - Implementierung

## Übersicht
Vollständige Implementierung eines interaktiven Organigramm-Systems mit dynamischer Vertretungsverwaltung für das LKA NRW.

## Datum: 2025-01-22

## Neue Features

### 1. Organigramm-Verwaltung
- **Hierarchische Darstellung** der Behördenstruktur (Direktion → Abteilung → Dezernat → Sachgebiet)
- **Sondereinheiten** wie Personalrat und Schwerbehindertenvertretung
- **Führungsstellen (FüSt)** für Abteilungen 1-6
- **Interaktive Visualisierung** mit Zoom/Pan und Suche

### 2. Dynamisches Vertretungssystem
- **Selbstverwaltung**: Mitarbeiter können eigene Vertretungen festlegen
- **Unbegrenzte Delegationskette**: Vertretungen können weitergegeben werden
- **Zeitliche Begrenzung**: Von-Bis Zeiträume für Vertretungen
- **Ebenengleiche Vertretung**: Automatische Vorschläge für passende Vertreter

### 3. Admin-Panel Features
- **React Flow Editor** für Drag & Drop Organigramm-Bearbeitung
- **Einheiten-Verwaltung**: Hinzufügen, Bearbeiten, Löschen von Organisationseinheiten
- **Visuelle Differenzierung** durch Gradient-Farbschema nach Abteilungen
- **PDF-Import ready** für zukünftige OCR-Integration

### 4. Frontend Features
- **Organigramm-Modal**: Fullscreen-Popup mit 3-Bereich-Layout
- **Mitarbeiter-Details**: Anzeige von Mitarbeitern pro Einheit
- **Vertretungs-Tab** in "Mein Profil"
- **Quick-Access**: 🏢 Button im Header für schnellen Zugriff

## Technische Änderungen

### Backend

#### Neue Dateien:
- `backend/src/routes/organization.ts` - API-Routes für Organigramm und Vertretungen

#### Geänderte Dateien:
- `backend/src/config/secureDatabase.ts` - Neue Datenbank-Tabellen:
  - `organizational_units` - Organisationseinheiten
  - `employee_unit_assignments` - Mitarbeiter-Zuordnungen
  - `special_positions` - Sonderpositionen (Beauftragte, Räte)
  - `deputy_assignments` - Vertretungszuweisungen
  - `deputy_delegations` - Vertretungs-Weitergaben

- `backend/src/index.ts` - Neue Route `/api/organization` registriert

- `backend/src/routes/employeesSecure.ts` - Neue Route `/employees/public` für öffentliche Mitarbeiterliste

#### API Endpoints:
```
GET  /api/organization/units          - Alle Einheiten abrufen
GET  /api/organization/hierarchy      - Hierarchie-Baum abrufen
GET  /api/organization/units/:id      - Einzelne Einheit mit Mitarbeitern
POST /api/organization/units          - Neue Einheit anlegen
PUT  /api/organization/units/:id      - Einheit bearbeiten

POST /api/organization/assignments    - Mitarbeiter zuordnen
GET  /api/organization/my-units       - Eigene Einheiten abrufen

GET  /api/organization/deputies/my    - Eigene Vertretungen abrufen
POST /api/organization/deputies/my    - Vertretung anlegen
POST /api/organization/deputies/delegate - Vertretung weitergeben
GET  /api/organization/deputies/chain/:id - Vertretungskette abrufen

GET  /api/organization/special-positions - Sonderpositionen abrufen
```

### Shared Types

#### Geänderte Dateien:
- `shared/index.d.ts` - Neue TypeScript-Definitionen:
  - `OrganizationalUnit` - Organisationseinheit
  - `OrganizationalUnitType` - Einheiten-Typen
  - `EmployeeUnitAssignment` - Mitarbeiter-Zuordnung
  - `EmployeeUnitRole` - Rollen (leiter, stellvertreter, mitarbeiter, beauftragter)
  - `SpecialPosition` - Sonderpositionen
  - `DeputyAssignment` - Vertretungszuweisung
  - `DeputyDelegation` - Vertretungs-Delegation

### Admin-Panel

#### Neue Dateien:
- `admin-panel/src/views/OrganizationEditor.tsx` - React Flow basierter Organigramm-Editor

#### Geänderte Dateien:
- `admin-panel/src/App.tsx` - Route `/organization` hinzugefügt
- `admin-panel/src/components/Layout.tsx` - Navigation für Organigramm hinzugefügt

#### NPM Packages:
```json
{
  "reactflow": "^11.x",
  "@reactflow/controls": "^11.x",
  "@reactflow/minimap": "^11.x",
  "@reactflow/background": "^11.x"
}
```

### Frontend

#### Neue Dateien:
- `frontend/src/components/OrganizationChart.tsx` - Interaktives Organigramm-Modal
- `frontend/src/components/DeputyManagement.tsx` - Vertretungsverwaltung

#### Geänderte Dateien:
- `frontend/src/components/Header.tsx` - Organigramm-Button und Modal-Integration
- `frontend/src/views/MyProfile.tsx` - Tab für Vertretungsverwaltung hinzugefügt

## Datenmodell

### Organisationsstruktur
```sql
organizational_units:
- id (UUID)
- code (z.B. "ZA 1", "Dezernat 42")
- name (Vollständiger Name)
- type (direktion/abteilung/dezernat/sachgebiet/...)
- level (0=Direktor, 1=Abteilung, 2=Dezernat, 3=SG/TD)
- parent_id (Verweis auf übergeordnete Einheit)
- position_x/y (Visuelle Position)
- color (Farbcodierung)
- has_fuehrungsstelle (Boolean)
```

### Vertretungssystem
```sql
deputy_assignments:
- principal_id (Wer wird vertreten)
- deputy_id (Wer vertritt)
- valid_from/until (Zeitraum)
- reason (Urlaub/Dienstreise/etc.)
- can_delegate (Darf weitergeben)

deputy_delegations:
- original_assignment_id
- from_deputy_id
- to_deputy_id
- reason
```

## UI/UX Features

### Visuelle Gestaltung
- **Gradient-Farbschema** für Abteilungen 1-6
- **Icon-System** für verschiedene Einheiten-Typen
- **Hover-Effekte** mit Mitarbeiteranzahl und Details
- **Breadcrumb-Navigation** für Hierarchie-Pfad
- **Dark Mode Support** vollständig integriert

### Interaktionen
- **Zoom/Pan** für große Organigramme
- **Suche** nach Einheiten und Personen
- **Filter** nach Abteilungen
- **Drag & Drop** im Admin-Editor
- **Kontextmenüs** für schnelle Aktionen

## Sicherheit
- **Rollenbasierte Zugriffskontrolle** für Admin-Funktionen
- **Audit-Logging** für kritische Aktionen
- **Verschlüsselte Felder** für sensitive Daten
- **JWT-Authentication** für alle API-Calls

## Migration & Deployment

### Datenbank-Migration
Beim ersten Start werden automatisch alle neuen Tabellen angelegt.

### Rollback
Falls ein Rollback nötig ist, können die neuen Tabellen entfernt werden:
```sql
DROP TABLE IF EXISTS deputy_delegations;
DROP TABLE IF EXISTS deputy_assignments;
DROP TABLE IF EXISTS special_positions;
DROP TABLE IF EXISTS employee_unit_assignments;
DROP TABLE IF EXISTS organizational_units;
```

## Testing

### Smoke Tests
1. Backend neu starten für Datenbank-Schema
2. Admin-Panel: Organigramm → Einheit hinzufügen
3. Frontend: 🏢 Button → Organigramm anzeigen
4. Mein Profil → Vertretungen → Vertretung hinzufügen

### Bekannte Limitierungen
- PDF-Import noch nicht implementiert (Struktur vorbereitet)
- Skill-Aggregation pro Einheit noch nicht implementiert
- E-Mail-Benachrichtigungen für Vertretungen noch nicht aktiv

## Performance
- **Lazy Loading** für große Hierarchien
- **Virtualisierung** bei >500 Nodes
- **Caching** von Hierarchie-Daten
- **Progressive Disclosure** für Ebenen

## Zukünftige Erweiterungen
1. **PDF-OCR Import** für automatisches Einlesen von Organigrammen
2. **Skill-Matrix** pro Organisationseinheit
3. **Stellenplan-Integration** mit Soll/Ist-Vergleich
4. **Export-Funktionen** (PDF, PNG, Excel)
5. **Historien-Tracking** für Reorganisationen
6. **E-Mail-Notifications** bei Vertretungsänderungen

## Abhängigkeiten
- React Flow 11.x für Organigramm-Editor
- Better-SQLite3 für Datenbank
- TypeScript für Type-Safety
- Tailwind CSS für Styling

## Support & Dokumentation
Bei Fragen oder Problemen:
- Prüfen Sie die Browser-Konsole für Fehler
- Stellen Sie sicher, dass alle Services laufen
- Überprüfen Sie die Datenbank-Verbindung
- Logs befinden sich in `backend/logs/`