LernApp/README.md

Kidio Backend

Das Kidio-Backend ist eine gamifizierte Lösung zur Verwaltung von Bildschirmzeit für Kinder. Die Anwendung basiert auf dem Ktor-Framework in Kotlin und kombiniert PostgreSQL für die Persistenz mit Redis als Caching-Layer für schnelle Zugriffszeiten.

Kinder können durch das Lösen von Lernaufgaben (z. B. Mathe-Aufgaben) zusätzliche Bildschirmzeit erwerben, während das System ihre verbrauchte Bildschirmzeit synchronisiert und bei Ablauf sperrt.

---

Features

Hier ist eine Übersicht der implementierten Kernfunktionen des Kidio-Backends:

Name	Beschreibung
JWT Authentifizierung	Sichere API-Endpunkte für authentifizierte Benutzer über JSON Web Tokens (JWT).
Lernaufgaben (Tasks)	Abrufen von interaktiven Lernaufgaben mit vordefinierten Antwortmöglichkeiten und Belohnungen (z. B. Minuten).
Antwort-Verifizierung	Überprüfung der vom Kind ausgewählten Antworten. Bei korrekter Antwort wird die Belohnung direkt auf die verbleibende Bildschirmzeit aufgerechnet.
Bildschirmzeit-Synchronisation	Laufender Datenabgleich der genutzten Bildschirmzeit. Sinkt die Zeit auf oder unter Null, wird der Status automatisch auf isBlocked = true gesetzt.
Zwei-Ebenen-Speicher	Datenhaltung in PostgreSQL (via JetBrains Exposed ORM) kombiniert mit Redis-Caching (via Jedis) für optimale Performance bei der Screentime-Abfrage.
Fallback-Mechanismus	Ist die Redis-Instanz nicht erreichbar, fällt das System automatisch und transparent auf PostgreSQL zurück.

---

Technologiestack

• Framework: Ktor (Kotlin-basiertes asynchrones Web-Framework)
• Datenbank-ORM: JetBrains Exposed
• Persistenz: PostgreSQL
• Caching: Redis (via Jedis Client)
• Sicherheit & Auth: JWT (Java JWT von auth0)
• Serialization: Kotlinx Serialization (JSON)
• Testing: Ktor Server Testing, JUnit

---

API-Endpunkte

Alle Endpunkte befinden sich unter dem Präfix /api/v1.

Öffentliche Endpunkte

1. Health-Check

• Methode: GET
• Pfad: /api/v1/health
• Beschreibung: Prüft, ob der Backend-Server ordnungsgemäß läuft.
• Antwort:

  {
    "status": "OK",
    "message": "Kidio Backend läuft!"
  }
  

2. Benutzer-Login (Auth-Token abholen)

• Methode: POST
• Pfad: /api/v1/auth/login
• Request-Body:

  {
    "userId": "default_user"
  }
  

• Antwort:

  {
    "token": "eyJhbGciOiJIUzI1NiIsIn..."
  }
  

Geschützte Endpunkte (Erfordern JWT im Authorization: Bearer <Token> Header)

3. Alle verfügbaren Aufgaben abrufen

• Methode: GET
• Pfad: /api/v1/tasks
• Beschreibung: Liefert eine Liste aller verfügbaren Lernaufgaben.
• Antwort:

  [
    {
      "id": "t1",
      "question": "Was ist 12 + 15?",
      "options": ["25", "27", "30", "22"],
      "rewardMinutes": 10
    }
  ]
  

4. Antwort überprüfen & Belohnung verbuchen

• Methode: POST
• Pfad: /api/v1/tasks/verify
• Request-Body:

  {
    "taskId": "t1",
    "selectedAnswer": "27"
  }
  

• Antwort (Erfolg):

  {
    "isCorrect": true,
    "earnedMinutes": 10,
    "message": "Super gemacht! Du hast 10 Minuten gewonnen."
  }
  

• Antwort (Fehler):

  {
    "isCorrect": false,
    "earnedMinutes": 0,
    "message": "Schade, das war leider falsch. Versuche es nochmal!"
  }
  

5. Bildschirmzeit synchronisieren

• Methode: POST
• Pfad: /api/v1/screentime/sync
• Beschreibung: Zieht die seit dem letzten Abgleich verbrauchten Sekunden von der verfügbaren Bildschirmzeit ab.
• Request-Body:

  {
    "userId": "default_user",
    "usedSecondsSinceLastSync": 200
  }
  

• Antwort:

  {
    "remainingSeconds": 1600,
    "isBlocked": false
  }
  

---

Projektkonfiguration und Umgebungsvariablen

Das Projekt wird über die Datei src/main/resources/application.yaml konfiguriert. Folgende Umgebungsvariablen können zur flexiblen Docker- oder Deployment-Konfiguration übergeben werden:

Variable	Beschreibung	Standardwert
DB_HOST	Hostname der PostgreSQL-Datenbank	localhost / aus application.yaml
DB_PORT	Port der PostgreSQL-Datenbank	5432 / aus application.yaml
DB_NAME	Name der PostgreSQL-Datenbank	kidio_db
DB_USER	PostgreSQL-Benutzername	kidio_admin
DB_PASSWORD	PostgreSQL-Passwort	learning
REDIS_HOST	Hostname der Redis-Instanz	localhost
REDIS_PORT	Port der Redis-Instanz	6379
JWT_SECRET	Geheimer Schlüssel zur Signierung der JWTs	super-geheimes-secret-fuer-dev

---

Lokale Entwicklung, Bauen & Testen

Zur Ausführung des Projekts werden die folgenden Gradle-Tasks bereitgestellt:

Task	Beschreibung
./gradlew test	Führt alle automatisierten Unit- und Integrationstests aus (nutzt die InMemory-Repository-Implementierung).
./gradlew build	Kompiliert das Projekt und baut das Artefakt.
./gradlew run	Startet den Ktor-Entwicklungsserver lokal auf Port 8080.

# Tests ausführen
./gradlew test

# Server starten
./gradlew run

Sobald der Server erfolgreich gestartet ist, ist er unter http://localhost:8080 erreichbar.