Oliver Wallisch 576ed74ad4 feat: adding h5p task integration, updated database schema and data

2026-09-14 22:45:02 +02:00

12 KiB

Raw Blame History

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 persistente Datenhaltung mit Redis als Caching-Layer für schnelle Zugriffszeiten.

Kinder können durch das Lösen von Lernaufgaben, beispielsweise Mathematikaufgaben, zusätzliche Bildschirmzeit erwerben. Gleichzeitig synchronisiert das System die verbrauchte Bildschirmzeit und sperrt das Gerät automatisch, sobald keine verfügbare Bildschirmzeit mehr vorhanden ist.

Features

Feature	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 in 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 verbrauchten Bildschirmzeit. Sinkt die verbleibende Zeit auf oder unter null, wird der Status automatisch auf `isBlocked = true` gesetzt.
Zwei-Ebenen-Speicher	PostgreSQL als persistente Datenbank, kombiniert mit Redis-Caching für schnelle Screentime-Abfragen.
Fallback-Mechanismus	Ist Redis nicht erreichbar, fällt das System automatisch und transparent auf PostgreSQL zurück.

Technologiestack

Framework: Ktor
Programmiersprache: Kotlin
Datenbank-ORM: JetBrains Exposed
Persistenz: PostgreSQL
Caching: Redis via Jedis
Authentifizierung: JWT via Java JWT (Auth0)
Serialisierung: Kotlinx Serialization
Code Quality / Linter: KtLint
Testing: Ktor Server Testing, JUnit
CI/CD: Forgejo Actions (Gitea / Act Runner)

API-Endpunkte

Alle API-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-Registrierung

Methode: POST

Pfad:

/api/v1/auth/register

Request-Body:

{
  "email": "test@family.de",
  "passwordPlain": "strengGeheim1",
  "familyName": "Familie Schmidt",
  "childAge": 8,
  "parentPin": "4321"
}

Antwort – 201 Created:

{
  "token": "eyJhbGciOiJIUzI1NiIsIn...",
  "familyName": "Familie Schmidt"
}

Methode: POST

Pfad:

/api/v1/auth/login

Request-Body:

{
  "email": "test@family.de",
  "passwordPlain": "strengGeheim1"
}

Antwort – 200 OK:

{
  "token": "eyJhbGciOiJIUzI1NiIsIn...",
  "familyName": "Familie Schmidt"
}

Geschützte Endpunkte

Die folgenden Endpunkte erfordern ein gültiges JWT im HTTP-Header:

Authorization: Bearer <Token>

4. Bildschirmzeit abrufen

Methode: GET

Pfad:

/api/v1/screentime

Beschreibung:

Liefert die aktuell verbleibende Bildschirmzeit sowie den aktuellen Sperrstatus.

Antwort:

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

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
}

6. 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
  }
]

7. Antwort überprüfen und Belohnung verbuchen

Methode: POST

Pfad:

/api/v1/tasks/verify

Request-Body:

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

Antwort – korrekte Lösung:

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

Antwort – falsche Lösung:

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

Projektkonfiguration und Umgebungsvariablen

Die Anwendung wird über folgende Konfigurationsdatei konfiguriert:

src/main/resources/application.yaml

Für eine flexible Konfiguration in lokalen Entwicklungsumgebungen, Docker-Containern oder Deployments können folgende Umgebungsvariablen gesetzt werden:

Variable	Beschreibung	Standardwert
`DB_HOST`	Hostname der PostgreSQL-Datenbank	`localhost`
`DB_PORT`	Port der PostgreSQL-Datenbank	`5432`
`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`

Hinweis: Die angegebenen Standardwerte sind für die lokale Entwicklung gedacht. Für produktive Umgebungen sollten insbesondere DB_PASSWORD und JWT_SECRET über sichere Secrets bzw. Umgebungsvariablen gesetzt werden.

Lokale Entwicklung

Voraussetzungen

Für die lokale Entwicklung werden benötigt:

JDK / Java
Kotlin bzw. Gradle Wrapper
PostgreSQL
Redis

Die konkreten Versionen richten sich nach der im Projekt konfigurierten Gradle- und Kotlin-Version.

Bauen und Ausführen

Das Projekt verwendet den Gradle Wrapper, sodass Gradle nicht global installiert sein muss.

Anwendung starten

./gradlew run

Der Ktor-Server ist anschließend standardmäßig unter folgender Adresse erreichbar:

http://localhost:8080

Projekt bauen

./gradlew build

Tests ausführen

./gradlew test

Code Quality

Für die Einhaltung der Kotlin-Coding-Standards wird KtLint verwendet.

Code automatisch formatieren

./gradlew ktlintFormat

Code Style prüfen

./gradlew ktlintCheck

Der KtLint-Check wird ebenfalls innerhalb der CI-Pipeline ausgeführt.

Empfohlener Workflow vor Commits / Pull Requests

Vor einem Commit oder Pull Request sollte der folgende Workflow ausgeführt werden:

# 1. Kotlin-Code automatisch formatieren
./gradlew ktlintFormat

# 2. Code Style überprüfen
./gradlew ktlintCheck

# 3. Tests ausführen
./gradlew test

# 4. Projekt bauen
./gradlew build

# 5. Server lokal starten
./gradlew run

Der Server ist anschließend unter:

http://localhost:8080

erreichbar.

CI/CD Pipeline

Das Repository verwendet Forgejo Actions für Continuous Integration.

Bei jedem Push oder Pull Request auf den main-Branch wird automatisch ein Workflow ausgeführt.

Die Pipeline führt unter anderem folgende Prüfungen durch:

Code Style
```
./gradlew ktlintCheck
```
Automatisierte Tests
```
./gradlew test
```

Dadurch wird sichergestellt, dass Änderungen den bestehenden Code-Style einhalten und die automatisierten Tests weiterhin erfolgreich ausgeführt werden können.

Architektur

Das Backend besteht im Wesentlichen aus folgenden Komponenten:

                    ┌───────────────────┐
                    │      Client       │
                    │  Web / Mobile /   │
                    │      Device       │
                    └─────────┬─────────┘
                              │
                              │ HTTP / JSON
                              ▼
                    ┌───────────────────┐
                    │       Ktor        │
                    │    REST API       │
                    └─────────┬─────────┘
                              │
                 ┌────────────┴────────────┐
                 │                         │
                 ▼                         ▼
        ┌─────────────────┐       ┌─────────────────┐
        │      Redis      │       │   PostgreSQL    │
        │      Cache      │       │   Persistence   │
        └────────┬────────┘       └────────┬────────┘
                 │                         │
                 └────────────┬────────────┘
                              │
                              ▼
                    ┌───────────────────┐
                    │   Exposed ORM     │
                    └───────────────────┘

Redis-Fallback

Redis wird für schnelle Zugriffe auf häufig benötigte Daten, insbesondere die verbleibende Bildschirmzeit, verwendet.

Sollte Redis nicht erreichbar sein, greift das Backend automatisch auf PostgreSQL zurück.

Dadurch bleibt die Anwendung auch bei einem Ausfall des Caches funktionsfähig.

Bildschirmzeit-Logik

Die Bildschirmzeit wird intern in Sekunden verwaltet.

Beispielsweise:

Start:
1800 Sekunden
= 30 Minuten

Verbrauch:
200 Sekunden

Verbleibend:
1600 Sekunden
= 26 Minuten 40 Sekunden

Sobald die verbleibende Bildschirmzeit auf 0 oder darunter fällt, wird der Benutzer automatisch gesperrt:

{
  "remainingSeconds": 0,
  "isBlocked": true
}

Durch das Lösen einer Aufgabe kann zusätzliche Bildschirmzeit erworben werden.

Beispiel:

Verbleibend:       0 Sekunden
Aufgaben-Belohnung: 10 Minuten
                     ↓
Neue Bildschirmzeit: 600 Sekunden

Lizenz

Falls für das Projekt eine bestimmte Lizenz verwendet wird, sollte diese hier ergänzt werden, beispielsweise:

MIT License

Eine entsprechende LICENSE-Datei sollte sich im Root-Verzeichnis des Repositorys befinden.

Kidio Ökosystem

Für Kinder (Der spielerische Teil - "Kid"):

Kidio Learn: Interaktive Lernspiele (Mathe, Sprachen, Logik), die sich dem Alter und Lernfortschritt des Kindes anpassen.
Kidio Create: Tools und Plattformen, um eigene Ideen, Kunstwerke oder kleine Projekte zu entwickeln und zu teilen.
Kidio Media: Ein sicherer Bereich mit kindgerechten Videos, Hörspielen und Büchern (ähnlich wie YouTube Kids).

12 KiB Raw Blame History Unescape Escape

Kidio Backend

Features

Technologiestack

API-Endpunkte

Öffentliche Endpunkte

1. Health-Check

2. Benutzer-Registrierung

3. Benutzer-Login

Geschützte Endpunkte

4. Bildschirmzeit abrufen

5. Bildschirmzeit synchronisieren

6. Alle verfügbaren Aufgaben abrufen

7. Antwort überprüfen und Belohnung verbuchen

Projektkonfiguration und Umgebungsvariablen

Lokale Entwicklung

Voraussetzungen

Bauen und Ausführen

Anwendung starten

Projekt bauen

Tests ausführen

Code Quality

Code automatisch formatieren

Code Style prüfen

Empfohlener Workflow vor Commits / Pull Requests

CI/CD Pipeline

Architektur

Redis-Fallback

Bildschirmzeit-Logik

Lizenz

Kidio Ökosystem

12 KiB

Raw Blame History