218 lines
6.5 KiB
Markdown
218 lines
6.5 KiB
Markdown
# 🏆 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
|