DÜSK - Electron Desktop App (Vollständige README.md)

DÜSK ist eine professionelle Desktop-Anwendung für Windows, macOS und Linux zur Erfassung und Auswertung von Selbst- und Fremdeinschätzungen von Schülerkompetenzen. Die App wurde mit Electron entwickelt und bietet eine native Benutzeroberfläche auf allen Plattformen.

---

📋 Inhaltsverzeichnis

- Überblick
- Features
- Technologie-Stack
- Screenshots
- API-Dokumentation
- Datenbankstruktur
- Installation
- Projektstruktur
- Berechnungslogik
- Konfiguration
- Build & Deployment
- Entwicklung
- Fehlerbehandlung

---

🎯 Überblick

DÜSK (Düsseldorfer Schülerinventar) ist ein diagnostisches Instrument zur Erfassung von Schülerkompetenzen in sechs Bereichen:

| Bereich | Beschreibung |
|---------|--------------|
| 1. Arbeitsverhalten | Zuverlässigkeit, Arbeitstempo, Planung, Organisation |
| 2. Lernverhalten | Selbstständigkeit, Belastbarkeit, Konzentration, Merkfähigkeit |
| 3. Sozialverhalten | Teamfähigkeit, Hilfsbereitschaft, Kommunikation, Konfliktfähigkeit |
| 4. Fachkompetenz | Schreiben, Lesen, Mathematik, Naturwissenschaften, Fremdsprachen |
| 5. Personale Kompetenz | Kreativität, Problemlösung, Abstraktion, Reflexion |
| 6. Methodenkompetenz | Präsentation, PC-Kenntnisse, fächerübergreifendes Denken |

Die Anwendung ermöglicht den Vergleich von Selbsteinschätzung (SE) und Fremdeinschätzung (FE) mit Normtabellen für Hauptschulen (HS) und Förderschulen (FS).

---

✨ Features

Kernfunktionen

- ✅ Login/Logout mit Session-Verwaltung und persistenter Authentifizierung
- ✅ CRUD-Operationen für Schülerprofile (Erstellen, Lesen, Aktualisieren, Löschen)
- ✅ 36 Items pro Einschätzung (4-stufige Likert-Skala: 1-4)
- ✅ Automatische Kompetenzberechnung aus 72 Items
- ✅ Normwertvergleich (HS/FS Normtabellen)
- ✅ Profilansicht mit Tabellen, interaktiven Diagrammen und Textinterpretation

Erweiterte Funktionen

- 📊 Zeitreihenanalyse für Gruppenentwicklung über Zeit
- 📈 Vergleichsdiagramme (SE vs. FE mit Pearson-Korrelation)
- 📐 Korrelationsberechnung mit statistischer Interpretation
- 📑 Exportfunktion (CSV, PDF in Entwicklung)
- 🔍 Such- und Filterfunktionen (nach Namen und Gruppen)
- 📁 Gruppenverwaltung (CRUD mit Umbenennung)
- 🌙 Dark Mode Support (systemabhängig)
- 💾 Persistente Speicherung (electron-store für Fensterposition, Session)
- 🖥️ Native Desktop Integration (Menüs, Dialoge, Shortcuts)
- 🔄 Auto-Updater für automatische Updates
- ⌨️ Tastatur-Shortcuts (Cmd+N, F11, Cmd+Q, etc.)

---

🛠 Technologie-Stack

Electron App

| Komponente | Technologie | Version |
|------------|-------------|---------|
| Framework | Electron | 28.0 |
| Sprache | JavaScript (ES6) | - |
| HTTP-Client | Axios | 1.6.5 |
| Charts | Chart.js | 4.4.0 |
| Persistenz | electron-store | 8.1.0 |
| Updater | electron-updater | 6.1.7 |
| PDF Export | pdfmake | 0.2.9 |
| Build-Tool | electron-builder | 24.9.1 |

Server (PHP API)

| Komponente | Technologie |
|------------|-------------|
| Backend | PHP 7.4+ |
| Datenbank | MySQL 5.7+ |
| Webserver | Apache/Nginx |
| Format | JSON |

---

📡 API-Dokumentation

Die REST-API ist unter https://paul-koop.org/api/ verfügbar.

Authentifizierung

#### POST /api_login.php

`json
// Request
{
"username": "gast",
"password": "gast"
}

// Response (Success)
{
"success": true,
"userID": "12345",
"session": "abc123def456789"
}

// Response (Error)
{
"success": false,
"error": "Invalid credentials"
}
`

Profile-Endpunkte

> Wichtig: Alle Profile-Endpunkte benötigen die Header:
> - X-User-ID: Benutzer-ID aus Login
> - X-Session: Session-Token aus Login

#### GET /api_profiles.php

Response: Array aller Profile des Benutzers

`json
[
{
"profilID": "1",
"name": "Max Mustermann",
"gruppename": "Klasse 8a",
"gruppeID": "5",
"created_at": "2024-01-15 10:30:00",
"item1": 4, "item2": 3, ..., "item36": 2,
"feitem1": 3, "feitem2": 4, ..., "feitem36": 3
}
]
`

#### GET /api_profiles.php?id={profileId}

Response: Einzelnes Profil

#### POST /api_profiles.php

Request Body: Vollständiges Profil-Objekt (alle 72 Items)
Response: 200 OK bei Erfolg

#### PUT /api_profiles.php

Request Body: Aktualisiertes Profil-Objekt
Response: 200 OK bei Erfolg

#### DELETE /api_profiles.php?id={profileId}

Response: 200 OK bei Erfolg

Gruppen-Endpunkte

#### GET /api_groups.php

Response:
`json
[
{"gruppeID": 1, "name": "Klasse 8a"},
{"gruppeID": 2, "name": "Klasse 8b"},
{"gruppeID": 3, "name": "Klasse 9a"}
]
`

#### POST /api_groups.php

Request Body: {"name": "Neue Gruppe"}
Response: 200 OK bei Erfolg

#### DELETE /api_groups.php?id={groupId}

Response: 200 OK bei Erfolg

---

🗄 Datenbankstruktur

ER-Diagramm

`
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ users │ │ groups │ │ profiles │
├─────────────┤ ├─────────────┤ ├─────────────┤
│ userID (PK) │────<│ userID (FK) │ │ profilID(PK)│
│ username │ │ gruppeID(PK)│<────│ userID (FK) │
│ password │ │ name │ │ gruppeID(FK)│
│ session │ │ created_at │ │ name │
│ created_at │ └─────────────┘ │ item1-36 │
└─────────────┘ │ feitem1-36 │
│ created_at │
│ updated_at │
└─────────────┘
`

SQL-Schema

`sql
-- Users Tabelle
CREATE TABLE users (
userID INT AUTO_INCREMENT PRIMARY KEY,
username VARCHAR(50) UNIQUE NOT NULL,
password_hash VARCHAR(255) NOT NULL,
session_token VARCHAR(255),
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- Groups Tabelle
CREATE TABLE groups (
gruppeID INT AUTO_INCREMENT PRIMARY KEY,
userID INT NOT NULL,
name VARCHAR(255) NOT NULL,
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
FOREIGN KEY (userID) REFERENCES users(userID) ON DELETE CASCADE,
UNIQUE KEY unique_group_per_user (userID, name)
);

-- Profiles Tabelle
CREATE TABLE profiles (
profilID INT AUTO_INCREMENT PRIMARY KEY,
userID INT NOT NULL,
name VARCHAR(255) NOT NULL,
gruppeID INT,
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
-- 36 SE-Items (Werte 1-4)
item1 TINYINT DEFAULT 2, item2 TINYINT DEFAULT 2, ..., item36 TINYINT DEFAULT 2,
-- 36 FE-Items (Werte 1-4)
feitem1 TINYINT DEFAULT 2, feitem2 TINYINT DEFAULT 2, ..., feitem36 TINYINT DEFAULT 2,
FOREIGN KEY (userID) REFERENCES users(userID) ON DELETE CASCADE,
FOREIGN KEY (gruppeID) REFERENCES groups(gruppeID) ON DELETE SET NULL
);
`

---

💻 Installation

Voraussetzungen

- Node.js 18+ (Download)
- npm oder yarn
- Für Windows: Visual Studio 2022 Build Tools mit C++ Desktop-Entwicklung
- Für macOS: Xcode Command Line Tools
- Für Linux: build-essential (sudo apt install build-essential)

Plattformspezifische Builds

`bash

Windows Installer (NSIS)

npm run build:win

macOS App (DMG)

npm run build:mac

Linux (AppImage + DEB)

npm run build:linux

Alle Plattformen

npm run dist
`

---

📁 Projektstruktur

`
duesk-electron/
├── package.json # Abhängigkeiten & Skripte
├── electron-builder.json # Build-Konfiguration
├── main.js # Hauptprozess (Electron)
├── preload.js # Preload-Skript (IPC Bridge)
├── src/
│ ├── index.html # Haupt-HTML (Template)
│ ├── renderer.js # Renderer-Prozess (Hauptlogik)
│ ├── styles.css # Globale Styles
│ ├── js/
│ │ ├── api.js # API-Kommunikation (Axios)
│ │ ├── session.js # Session-Management
│ │ ├── calculator.js # Berechnungslogik (Normen, Korrelation)
│ │ └── utils.js # Hilfsfunktionen (escapeHtml, formatDate)
│ └── pages/
│ ├── splash.html # Splash Screen beim Start
│ ├── login.html # Login-Seite
│ ├── main.html # Hauptansicht mit Sidebar
│ ├── profile-detail.html # Profildetails mit Charts
│ ├── profile-edit.html # Profil bearbeiten/erstellen
│ ├── group-manager.html # Gruppenverwaltung
│ └── time-series.html # Zeitreihenanalyse
├── assets/
│ ├── icons/
│ │ ├── icon.png # App-Icon (512x512)
│ │ ├── icon.ico # Windows-Icon
│ │ └── icon.icns # macOS-Icon
│ └── build/ # Build-Ausgabe (dist)
└── README.md # Dokumentation
`

---

🧮 Berechnungslogik

Item-zu-Kompetenz-Zuordnung

`javascript
// Kompetenz 1: Arbeitsverhalten (Items 1-10)
for (let i = 0; i < 10; i++) sums[1] += items[i];

// Kompetenz 2: Lernverhalten (Items 11-20)
for (let i = 10; i < 20; i++) sums[2] += items[i];

// Kompetenz 3: Sozialverhalten (Items 21-28 + Items 9-10)
for (let i = 20; i < 28; i++) sums[3] += items[i];
sums[3] += items[8] + items[9];

// Kompetenz 4: Fachkompetenz (Items 29-36)
for (let i = 28; i < 36; i++) sums[4] += items[i];

// Kompetenz 5: Personale Kompetenz (spezifische Items)
sums[5] = items[0] + items[1] + items[5] + items[6] + items[7] +
items[8] + items[9] + items[11] + items[12] + items[13] + items[14];

// Kompetenz 6: Methodenkompetenz (spezifische Items)
sums[6] = items[2] + items[3] + items[4] + items[8] + items[9] +
items[10] + items[16] + items[17];
`

Profilwertberechnung

`javascript
function calculateProfileValue(rawSum, normTable) {
// 1 = weit unterdurchschnittlich
// 2 = unterdurchschnittlich
// 3 = durchschnittlich
// 4 = überdurchschnittlich
// 5 = weit überdurchschnittlich

for (let i = 0; i < normTable.length; i++) {
if (rawSum < normTable[i]) {
return i + 1;
}
}
return 5;
}
`

Korrelationsberechnung (Pearson)

`javascript
function calculateCorrelation(seValues, feValues) {
const n = seValues.length;
let sumSE = 0, sumFE = 0, sumSEFE = 0, sumSE2 = 0, sumFE2 = 0;

for (let i = 0; i < n; i++) {
sumSE += seValues[i];
sumFE += feValues[i];
sumSEFE += seValues[i] * feValues[i];
sumSE2 += seValues[i] * seValues[i];
sumFE2 += feValues[i] * feValues[i];
}

const numerator = n sumSEFE - sumSE sumFE;
const denominator = Math.sqrt((n sumSE2 - sumSE sumSE) *
(n sumFE2 - sumFE sumFE));

return denominator === 0 ? 0 : numerator / denominator;
}
`

Normtabellen (Vollständig)

| Kompetenz | HS SE Grenzwerte | HS FE Grenzwerte |
|-----------|------------------|------------------|
| Arbeitsverhalten | 21.33, 25.33, 29.33, 33.32, 37.32 | 12.66, 18.16, 23.66, 29.16, 34.66 |
| Lernverhalten | 20.87, 24.95, 29.03, 33.13, 37.18 | 13.33, 18.42, 23.51, 28.60, 33.69 |
| Sozialverhalten | 17.93, 21.37, 24.80, 28.23, 31.67 | 10.75, 15.41, 20.07, 24.73, 29.39 |
| Fachkompetenz | 13.98, 17.71, 21.44, 25.17, 28.90 | 14.22, 15.30, 16.38, 17.46, 18.54 |
| Personale Kompetenz | 24.60, 28.55, 33.04, 37.53, 42.01 | 14.12, 20.21, 26.30, 32.39, 38.48 |
| Methodenkompetenz | 15.53, 18.97, 22.40, 25.83, 29.27 | 10.53, 14.51, 18.49, 22.47, 26.45 |

Für FS (Förderschule) existieren separate Normtabellen.

---

⚙️ Konfiguration

API Base URL ändern

`javascript
// main.js oder js/api.js
const API_BASE_URL = 'https://your-server.com/api/';
`

Umgebungsvariablen

`bash

.env Datei (für Entwicklung)

API_URL=https://paul-koop.org/api/
DEBUG_MODE=true
`

App-Icons und Build-Konfiguration

`json
// electron-builder.json
{
"appId": "com.duesk.app",
"productName": "DÜSK",
"directories": {
"output": "dist"
},
"win": {
"target": "nsis",
"icon": "assets/icons/icon.ico"
},
"mac": {
"target": "dmg",
"icon": "assets/icons/icon.icns",
"category": "public.app-category.education"
},
"linux": {
"target": ["AppImage", "deb"],
"icon": "assets/icons/icon.png",
"category": "Education"
}
}
`

---

🚀 Build & Deployment

Entwicklung

`bash

Entwicklung starten

npm start

Mit Debug-Entwicklertools

npm run dev

Tests ausführen

npm test
`

Produktions-Build

`bash

Windows (NSIS Installer)

npm run build:win

macOS (DMG)

npm run build:mac

Linux (AppImage + DEB)

npm run build:linux

Alle Plattformen

npm run dist
`

Build-Ausgabe

| Plattform | Ausgabeort | Datei |
|-----------|------------|-------|
| Windows | dist/win-unpacked/ | DÜSK Setup.exe |
| macOS | dist/mac/ | DÜSK.dmg |
| Linux | dist/linux-unpacked/ | DÜSK.AppImage |

---

⌨️ Tastatur-Shortcuts

| Shortcut | Aktion |
|----------|--------|
| Cmd/Ctrl + N | Neues Profil |
| Cmd/Ctrl + Q | Beenden |
| Cmd/Ctrl + Z | Rückgängig |
| Cmd/Ctrl + Y | Wiederherstellen |
| Cmd/Ctrl + C | Kopieren |
| Cmd/Ctrl + V | Einfügen |
| Cmd/Ctrl + A | Alles auswählen |
| F11 | Vollbild |
| F12 | Entwicklertools |

---

🐛 Fehlerbehandlung

HTTP-Statuscodes

| Code | Bedeutung | Behandlung |
|------|-----------|------------|
| 200 | Erfolg | Daten verarbeiten |
| 400 | Bad Request | Validierungsfehler prüfen |
| 401 | Unauthorized | Neu anmelden |
| 403 | Forbidden | Berechtigung prüfen |
| 404 | Not Found | Ressource existiert nicht |
| 500 | Server Error | Erneut versuchen, Support kontaktieren |

Typische Fehler und Lösungen

`javascript
try {
const result = await apiCall('api_profiles.php', 'GET');
if (!result.success) {
if (result.status === 401) {
// Session abgelaufen - erneut anmelden
await logout();
} else {
showError(result.error || 'Unbekannter Fehler');
}
}
} catch (error) {
if (error.code === 'ECONNABORTED') {
showError('Verbindung zeitüberschritten');
} else if (error.message.includes('Network Error')) {
showError('Keine Internetverbindung');
} else {
showError(Fehler: ${error.message});
}
}
`

---

🔄 Vergleich der Implementierungen

| Feature | Electron | Flutter | React Native | Swift (iOS) |
|---------|----------|---------|--------------|-------------|
| Plattformen | 3 (Win/Mac/Linux) | 6 | 2 | 1 |
| Code-Wiederverwendung | 100% | 95% | 70% | - |
| Performance | Mittel | Sehr gut | Gut | Exzellent |
| Installationsgröße | ~80 MB | ~25 MB | ~30 MB | ~15 MB |
| Lernkurve | Gering | Mittel | Gering | Hoch |
| Charts | Chart.js | FL Chart | React Native Chart Kit | Swift Charts |
| Desktop-Integration | Exzellent | Gut | Eingeschränkt | Exzellent |
| Auto-Updater | ✅ Ja | ❌ Nein | ❌ Nein | ✅ Ja (App Store) |

- Normtabellen: Bildungsforschung Düsseldorf
- API-Entwicklung: Paul Koop
- Electron Framework: OpenJS Foundation
- Chart.js: Chart.js Contributors
- Testing & Feedback: Alle Beta-Tester

---

Letzte Aktualisierung: Januar 2026

---

🎯 Nächste Schritte

Die Electron-Version ist vollständig implementiert und unterstützt Windows, macOS und Linux.

Alle DÜSK-Implementierungen sind nun abgeschlossen:

| Version | Plattformen | Status |
|---------|-------------|--------|
| Java/Swing | Windows, macOS, Linux | ✅ Vollständig |
| Swift/SwiftUI | iOS, macOS | ✅ Vollständig |
| React Native | iOS, Android | ✅ Vollständig |
| Flutter | iOS, Android, Web, Windows, macOS, Linux | ✅ Vollständig |
| Electron | Windows, macOS, Linux | ✅ Vollständig |

Alle Versionen sind funktional identisch und teilen dieselbe API!