Ninjaserver/ACHIEVEMENTS.md

🏆 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

- 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

- 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

# 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

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

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

# 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

-- 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

UPDATE achievements SET is_active = false WHERE name = 'Achievement-Name';

Daten zurücksetzen

-- 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