Ninjaserver/wiki/FAQ.md

# ❓ FAQ - Häufige Fragen

Antworten auf häufig gestellte Fragen zum Ninja Cross Parkour System.

## 🚀 Installation und Setup

### Wie installiere ich das System?
Siehe [Schnellstart](Schnellstart) für eine detaillierte Anleitung. Kurz gesagt:
1. Repository klonen
2. `npm install` ausführen
3. `.env`-Datei konfigurieren
4. `npm run init-db` ausführen
5. `npm start` starten

### Welche Voraussetzungen benötige ich?
- Node.js v16 oder höher
- PostgreSQL 12 oder höher
- npm oder yarn
- Git für die Installation

### Wie konfiguriere ich die Datenbank?
Bearbeiten Sie die `.env`-Datei mit Ihren Datenbankdaten:
```env
DB_HOST=localhost
DB_PORT=5432
DB_NAME=ninjaserver
DB_USER=your_username
DB_PASSWORD=your_password
```

### Wie erstelle ich den ersten Admin-Benutzer?
```bash
npm run create-user
```
Standard-Anmeldedaten: `admin` / `admin123`

## 🔐 Authentifizierung

### Wie funktioniert die API-Authentifizierung?
Das System verwendet API-Keys für die Authentifizierung. Generieren Sie einen Key:
```bash
curl -X POST http://localhost:3000/api/v1/web/generate-api-key \
  -H "Content-Type: application/json" \
  -d '{"description": "Mein API Key"}'
```

### Wie verwende ich den API-Key?
Fügen Sie den Key in den Authorization Header ein:
```http
Authorization: Bearer YOUR_API_KEY_HERE
```

### Wie lange sind API-Keys gültig?
API-Keys sind standardmäßig unbegrenzt gültig, können aber mit einem Ablaufdatum versehen werden.

### Kann ich mehrere API-Keys haben?
Ja, Sie können beliebig viele API-Keys erstellen, z.B. für verschiedene Anwendungen oder Benutzer.

## 🏃‍♂️ Spieler und Zeiten

### Wie registriere ich einen neuen Spieler?
```bash
curl -X POST http://localhost:3000/api/v1/public/players \
  -H "Content-Type: application/json" \
  -d '{"firstname": "Max", "lastname": "Mustermann", "birthdate": "1990-01-01", "rfiduid": "AA:BB:CC:DD"}'
```

### Wie verknüpfe ich eine RFID-Karte mit einem Spieler?
```bash
curl -X POST http://localhost:3000/api/v1/public/link-by-rfid \
  -H "Content-Type: application/json" \
  -d '{"rfiduid": "AA:BB:CC:DD", "supabase_user_id": "uuid-here"}'
```

### Wie messe ich eine Zeit?
```bash
curl -X POST http://localhost:3000/api/v1/private/create-time \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"player_id": "AA:BB:CC:DD", "location_id": "Standort-Name", "recorded_time": "01:23.456"}'
```

### Welches Zeitformat wird verwendet?
Zeiten werden im Format `MM:SS.mmm` gespeichert:
- Minuten:Sekunden.Millisekunden
- Beispiel: `01:23.456` = 1 Minute, 23 Sekunden, 456 Millisekunden

### Was ist eine gültige Zeit?
- **Minimum:** 30 Sekunden
- **Maximum:** 10 Minuten
- **Schwelle:** Konfigurierbar pro Standort (Standard: 120 Sekunden)

## 🏆 Achievements

### Wie funktioniert das Achievement-System?
Das System überprüft automatisch täglich alle Spieler auf neue Achievements. Siehe [Achievement System](Achievement-System) für Details.

### Wann werden Achievements vergeben?
- **Automatisch:** Täglich um 23:59 Uhr
- **Manuell:** Über API-Endpoints
- **Sofort:** Bei bestimmten Aktionen

### Wie viele Achievements gibt es?
Das System hat 32 verschiedene Achievements in 4 Kategorien:
- Konsistenz-basierte (8)
- Verbesserungs-basierte (4)
- Saisonale (4)
- Monatliche (12)
- Jahreszeiten (4)

### Wie rufe ich Achievements ab?
```bash
# Alle Achievements
curl http://localhost:3000/api/achievements

# Spieler-Achievements
curl http://localhost:3000/api/achievements/player/{playerId}

# Spieler-Statistiken
curl http://localhost:3000/api/achievements/player/{playerId}/stats
```

## 📍 Standorte

### Wie erstelle ich einen neuen Standort?
```bash
curl -X POST http://localhost:3000/api/v1/private/create-location \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "München", "latitude": 48.1351, "longitude": 11.5820}'
```

### Wie ändere ich die Zeit-Schwelle eines Standorts?
```bash
curl -X PUT http://localhost:3000/api/v1/private/locations/{id}/threshold \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"threshold_seconds": 120}'
```

### Wie viele Standorte kann ich haben?
Es gibt keine Begrenzung der Anzahl der Standorte.

## 🔧 Technische Fragen

### Wie starte ich den Server?
```bash
# Entwicklung
npm run dev

# Produktion
npm start
```

### Wie überwache ich den Server?
```bash
# Logs anzeigen
tail -f logs/server.log

# Achievement-Logs
tail -f /var/log/ninjaserver_achievements.log

# Datenbank-Status
psql -d ninjaserver -c "SELECT NOW();"
```

### Wie teste ich die API?
```bash
# Test-Skript ausführen
node test-api.js

# Einzelne Endpoints testen
curl http://localhost:3000/api/v1/public/locations
```

### Wie sichere ich die Datenbank?
```bash
# Vollständiges Backup
pg_dump -h localhost -U username -d ninjaserver > backup.sql

# Wiederherstellung
psql -h localhost -U username -d ninjaserver < backup.sql
```

## 🐛 Fehlerbehebung

### "Port 3000 bereits belegt"
```bash
# Port freigeben
sudo lsof -ti:3000 | xargs kill -9

# Oder anderen Port verwenden
PORT=3001 npm start
```

### "Datenbank-Verbindung fehlgeschlagen"
1. PostgreSQL-Service prüfen: `sudo systemctl status postgresql`
2. Datenbank-Credentials in `.env` prüfen
3. Firewall-Einstellungen prüfen

### "API-Key funktioniert nicht"
1. API-Key neu generieren
2. Authorization Header prüfen: `Bearer YOUR_API_KEY`
3. Token-Ablaufzeit prüfen

### "Zeit wird nicht gespeichert"
1. Gültige Zeit prüfen (innerhalb der Schwelle)
2. Standort korrekt ausgewählt
3. Internetverbindung prüfen
4. Seite neu laden

### "Achievements werden nicht vergeben"
1. Tägliche Prüfung abwarten
2. Bedingungen erfüllt prüfen
3. System-Status prüfen
4. Administrator kontaktieren

## 📊 Statistiken und Monitoring

### Wie rufe ich Statistiken ab?
```bash
# Admin-Statistiken
curl -H "Authorization: Bearer ADMIN_TOKEN" http://localhost:3000/api/v1/admin/stats

# Seiten-Statistiken
curl -H "Authorization: Bearer ADMIN_TOKEN" http://localhost:3000/api/v1/admin/page-stats
```

### Wie überwache ich die Performance?
```sql
-- Langsamste Queries
SELECT query, calls, total_time, mean_time
FROM pg_stat_statements 
ORDER BY mean_time DESC LIMIT 10;

-- Index-Nutzung
SELECT schemaname, tablename, indexname, idx_scan
FROM pg_stat_user_indexes 
ORDER BY idx_scan DESC;
```

### Wie prüfe ich die Datenbank-Größe?
```sql
-- Gesamtgröße
SELECT pg_size_pretty(pg_database_size('ninjaserver'));

-- Tabellen-Größen
SELECT tablename, pg_size_pretty(pg_total_relation_size(tablename)) as size
FROM pg_tables WHERE schemaname = 'public'
ORDER BY pg_total_relation_size(tablename) DESC;
```

## 🔒 Sicherheit

### Wie sichere ich das System?
- Standardpasswörter ändern
- HTTPS in der Produktion verwenden
- Regelmäßige Backups
- API-Keys regelmäßig rotieren
- Firewall konfigurieren

### Wie ändere ich das Admin-Passwort?
```bash
# Neuen Admin-Benutzer erstellen
npm run create-user

# Oder direkt in der Datenbank
UPDATE adminusers SET password_hash = '$2b$10$...' WHERE username = 'admin';
```

### Wie deaktiviere ich einen API-Key?
```sql
UPDATE api_tokens SET is_active = false WHERE token = 'YOUR_TOKEN';
```

## 🌐 Deployment

### Wie deploye ich in die Produktion?
1. Server vorbereiten (Node.js, PostgreSQL)
2. Code deployen
3. Umgebungsvariablen setzen
4. Datenbank initialisieren
5. Nginx konfigurieren
6. SSL-Zertifikat einrichten

### Wie konfiguriere ich Nginx?
```nginx
server {
    listen 80;
    server_name ninja.reptilfpv.de;
    
    location / {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
    }
}
```

### Wie richte ich SSL ein?
```bash
# Let's Encrypt
certbot --nginx -d ninja.reptilfpv.de
```

## 📱 Frontend

### Wie integriere ich das System in meine Website?
Verwenden Sie die REST API oder das Web-Interface. Siehe [API Referenz](API-Referenz) für Details.

### Gibt es eine mobile App?
Eine native mobile App ist geplant, aber noch nicht verfügbar. Das Web-Interface ist responsive und funktioniert auf allen Geräten.

### Wie passe ich das Design an?
Bearbeiten Sie die CSS-Dateien im `public/css/` Verzeichnis oder erstellen Sie ein eigenes Frontend mit der API.

## 🔄 Updates und Wartung

### Wie aktualisiere ich das System?
```bash
# Code aktualisieren
git pull origin main

# Abhängigkeiten aktualisieren
npm install

# Datenbank-Migrationen (falls vorhanden)
npm run migrate

# Server neu starten
npm restart
```

### Wie führe ich Wartungsaufgaben durch?
```sql
-- Tabellen analysieren
ANALYZE;

-- Indizes neu aufbauen
REINDEX DATABASE ninjaserver;

-- Vakuum durchführen
VACUUM ANALYZE;
```

### Wie lösche ich alte Daten?
```sql
-- Alte Zeiten löschen (älter als 1 Jahr)
DELETE FROM times WHERE created_at < NOW() - INTERVAL '1 year';

-- Alte Seitenaufrufe löschen (älter als 6 Monate)
DELETE FROM page_views WHERE created_at < NOW() - INTERVAL '6 months';
```

## 📞 Support

### Wo bekomme ich Hilfe?
- 📖 Konsultieren Sie diese Dokumentation
- 🔍 Schauen Sie in [Troubleshooting](Troubleshooting)
- 📧 Kontaktieren Sie den Systemadministrator
- 🐛 Melden Sie Bugs über das Issue-System

### Wie melde ich einen Bug?
1. Beschreiben Sie das Problem
2. Fügen Sie Logs hinzu
3. Geben Sie Schritte zur Reproduktion an
4. Erwähnen Sie Ihre Systemkonfiguration

### Wie schlage ich eine Verbesserung vor?
1. Beschreiben Sie die gewünschte Funktion
2. Erklären Sie den Nutzen
3. Geben Sie Beispiele an
4. Erwähnen Sie mögliche Implementierung

---

**Hinweis:** Diese FAQ wird regelmäßig aktualisiert. Bei Fragen, die hier nicht beantwortet werden, wenden Sie sich an den Support.