# 🏆 Ninja Cross Parkour Achievement System

Ein umfassendes Achievement-System für das Ninja Cross Parkour im Schwimmbad.

## 📊 System-Übersicht

Das Achievement-System besteht aus:
- **32 verschiedene Achievements** in 4 Kategorien
- **Automatische tägliche Vergabe** am Ende des Tages
- **REST API Endpoints** für Frontend-Integration
- **PostgreSQL Funktionen** für effiziente Verarbeitung

## 🎯 Achievement-Kategorien

### 1. Konsistenz-basierte Achievements
- **Erste Schritte** 👶 - Erste Zeit aufgezeichnet (5 Punkte)
- **Durchhalter** 💪 - 3 Versuche an einem Tag (10 Punkte)
- **Fleißig** 🔥 - 5 Versuche an einem Tag (15 Punkte)
- **Besessen** 😤 - 10 Versuche an einem Tag (25 Punkte)
- **Regelmäßig** 📅 - 5 verschiedene Tage gespielt (20 Punkte)
- **Stammgast** ⭐ - 10 verschiedene Tage gespielt (30 Punkte)
- **Treue** 💎 - 20 verschiedene Tage gespielt (50 Punkte)
- **Veteran** 🏆 - 50 verschiedene Tage gespielt (100 Punkte)

### 2. Verbesserungs-basierte Achievements
- **Fortschritt** 📈 - Persönliche Bestzeit um 5 Sekunden verbessert (15 Punkte)
- **Durchbruch** ⚡ - Persönliche Bestzeit um 10 Sekunden verbessert (25 Punkte)
- **Transformation** 🔄 - Persönliche Bestzeit um 15 Sekunden verbessert (40 Punkte)
- **Perfektionist** ✨ - Persönliche Bestzeit um 20 Sekunden verbessert (60 Punkte)

### 3. Saisonale Achievements
- **Wochenend-Krieger** 🏁 - Am Wochenende gespielt (10 Punkte)
- **Nachmittags-Sportler** ☀️ - Zwischen 14-18 Uhr gespielt (10 Punkte)
- **Frühaufsteher** 🌅 - Vor 10 Uhr gespielt (15 Punkte)
- **Abend-Sportler** 🌙 - Nach 18 Uhr gespielt (10 Punkte)

### 4. Monatliche Achievements
- **Januar-Krieger** ❄️ bis **Dezember-Dynamo** 🎄 (je 20 Punkte)

### 5. Jahreszeiten-Achievements
- **Frühjahrs-Fighter** 🌱 - Im Frühling gespielt (30 Punkte)
- **Sommer-Sportler** ☀️ - Im Sommer gespielt (30 Punkte)
- **Herbst-Held** 🍂 - Im Herbst gespielt (30 Punkte)
- **Winter-Warrior** ❄️ - Im Winter gespielt (30 Punkte)

## 🗄️ Datenbank-Schema

### Tabelle: `achievements`
```sql
- id (uuid, PK)
- name (varchar) - Achievement-Name
- description (text) - Beschreibung
- category (varchar) - Kategorie
- condition_type (varchar) - Bedingungstyp
- condition_value (integer) - Bedingungswert
- icon (varchar) - Emoji-Icon
- points (integer) - Punkte
- is_active (boolean) - Aktiv
- created_at (timestamp)
```

### Tabelle: `player_achievements`
```sql
- id (uuid, PK)
- player_id (uuid, FK) - Verweis auf players.id
- achievement_id (uuid, FK) - Verweis auf achievements.id
- earned_at (timestamp) - Wann erreicht
- progress (integer) - Fortschritt
- is_completed (boolean) - Abgeschlossen
- created_at (timestamp)
```

## 🔧 PostgreSQL Funktionen

### `check_consistency_achievements(player_uuid)`
Überprüft alle Konsistenz-basierten Achievements für einen Spieler.

### `check_improvement_achievements(player_uuid)`
Überprüft alle Verbesserungs-basierten Achievements für einen Spieler.

### `check_seasonal_achievements(player_uuid)`
Überprüft alle saisonalen und monatlichen Achievements für einen Spieler.

### `check_all_achievements(player_uuid)`
Führt alle Achievement-Überprüfungen für einen Spieler aus.

## 🚀 API Endpoints

### GET `/api/achievements`
Alle verfügbaren Achievements abrufen.

### GET `/api/achievements/player/:playerId`
Achievements eines bestimmten Spielers abrufen.

### GET `/api/achievements/player/:playerId/stats`
Achievement-Statistiken eines Spielers abrufen.

### POST `/api/achievements/check/:playerId`
Achievements für einen Spieler manuell überprüfen.

### POST `/api/achievements/daily-check`
Tägliche Achievement-Überprüfung für alle Spieler ausführen.

### GET `/api/achievements/leaderboard?limit=10`
Bestenliste der Spieler nach Achievement-Punkten.

## 📅 Automatisierung

### Tägliches Script
```bash
# Manuell ausführen
node scripts/daily_achievements.js

# Cron-Job einrichten
node scripts/setup_cron.js setup

# Cron-Job Status prüfen
node scripts/setup_cron.js status

# Cron-Job entfernen
node scripts/setup_cron.js remove
```

### Cron-Schedule
- **Zeit**: Täglich um 23:59 Uhr
- **Log**: `/var/log/ninjaserver_achievements.log`

## 🎮 Frontend-Integration

### Beispiel: Achievement-Liste laden
```javascript
fetch('/api/achievements/player/PLAYER_ID')
  .then(response => response.json())
  .then(data => {
    data.data.forEach(achievement => {
      console.log(`${achievement.icon} ${achievement.name}: ${achievement.is_completed ? '✅' : '❌'}`);
    });
  });
```

### Beispiel: Statistiken anzeigen
```javascript
fetch('/api/achievements/player/PLAYER_ID/stats')
  .then(response => response.json())
  .then(data => {
    console.log(`Punkte: ${data.data.total_points}`);
    console.log(`Abgeschlossen: ${data.data.completed_achievements}/${data.data.total_achievements}`);
  });
```

## 🔍 Monitoring

### Logs überwachen
```bash
# Live-Logs anzeigen
tail -f /var/log/ninjaserver_achievements.log

# Letzte Ausführung prüfen
grep "Daily achievement check completed" /var/log/ninjaserver_achievements.log | tail -1
```

### Datenbank-Status prüfen
```sql
-- Achievement-Statistiken
SELECT 
    COUNT(*) as total_achievements,
    COUNT(CASE WHEN is_active = true THEN 1 END) as active_achievements
FROM achievements;

-- Spieler-Statistiken
SELECT 
    COUNT(DISTINCT player_id) as players_with_achievements,
    COUNT(*) as total_earned_achievements
FROM player_achievements 
WHERE is_completed = true;
```

## 🛠️ Wartung

### Neue Achievements hinzufügen
1. Achievement in `achievements` Tabelle einfügen
2. Logik in entsprechenden PostgreSQL Funktionen erweitern
3. API Endpoints testen

### Achievement deaktivieren
```sql
UPDATE achievements SET is_active = false WHERE name = 'Achievement-Name';
```

### Daten zurücksetzen
```sql
-- Alle Spieler-Achievements löschen
DELETE FROM player_achievements;

-- Achievement-Statistiken zurücksetzen
UPDATE achievements SET created_at = NOW();
```

## 📈 Performance

- **Indizierung**: Automatische Indizes auf `player_id` und `achievement_id`
- **Batch-Processing**: Effiziente Verarbeitung aller Spieler
- **Caching**: Achievements werden nur bei Änderungen neu berechnet
- **Timezone**: Korrekte Zeitzone-Behandlung (Europe/Berlin)

## 🔒 Sicherheit

- **API-Schutz**: Alle Endpoints über bestehende Authentifizierung
- **SQL-Injection**: Parametrisierte Queries
- **Datenvalidierung**: Eingabe-Validierung in allen Funktionen
- **Fehlerbehandlung**: Umfassende Error-Handling

---

**Erstellt am**: $(date)  
**Version**: 1.0.0  
**Autor**: Ninja Cross Parkour System