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](https://ktor.io/) (Kotlin-basiertes asynchrones Web-Framework)
- **Datenbank-ORM**: [JetBrains Exposed](https://github.com/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**:
  ```json
  {
    "status": "OK",
    "message": "Kidio Backend läuft!"
  }
  ```

#### 2. Benutzer-Login (Auth-Token abholen)
- **Methode**: `POST`
- **Pfad**: `/api/v1/auth/login`
- **Request-Body**:
  ```json
  {
    "userId": "default_user"
  }
  ```
- **Antwort**:
  ```json
  {
    "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**:
  ```json
  [
    {
      "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**:
  ```json
  {
    "taskId": "t1",
    "selectedAnswer": "27"
  }
  ```
- **Antwort (Erfolg)**:
  ```json
  {
    "isCorrect": true,
    "earnedMinutes": 10,
    "message": "Super gemacht! Du hast 10 Minuten gewonnen."
  }
  ```
- **Antwort (Fehler)**:
  ```json
  {
    "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**:
  ```json
  {
    "userId": "default_user",
    "usedSecondsSinceLastSync": 200
  }
  ```
- **Antwort**:
  ```json
  {
    "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`. |

```bash
# Tests ausführen
./gradlew test

# Server starten
./gradlew run
```

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