172 lines
5.3 KiB
Markdown
172 lines
5.3 KiB
Markdown
# 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.
|