wiktor/togethere.cloud
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
master
togethere.cloud/mds/DISCIPLINE_SETTINGS_DOCUMENTATION.md

11 KiB
Raw Permalink Blame History

📋 Dokumentacja Endpoint'u Ustawień Dyscyplin

🎯 Przegląd

Endpoint do zarządzania ustawieniami dyscyplin (Ping-Pong, Papier-Kamień-Nożyce, Piłkarzyki). Obsługuje:

  • GET: pobranie aktualnych ustawień
  • POST: aktualizacja ustawień (admin only)

Kluczowe cechy

✅ Versioning ustawień (snapshot do startu meczu) ✅ Separacja reguł gry od UI customization ✅ Walidacja logiczna (min/max wartości, typy) ✅ Domyślne ustawienia dla każdej dyscypliny ✅ Przygotowanie do rozbudowy na inne dyscypliny

📍 Endpointy

1. Pobierz aktualne ustawienia (GET)

GET /administration/disciplines/{discipline}/settings

URL parametry:

  • {discipline}: ping-pong, rock-paper-scissors, table-football

Query parametry:

  • snapshot=true (opcjonalne): zwróć snapshot do startu meczu
  • version=N (opcjonalne): pobierz ustawienia z konkretnej wersji

Authoryzacja: Admin role

Przykład:

curl -X GET \
  "http://localhost/administration/disciplines/ping-pong/settings" \
  -H "Cookie: PHPSESSID=abc123..."

Odpowiedź (200 OK):

{
  "success": true,
  "data": {
    "discipline": "ping-pong",
    "settingsVersion": 1,
    "rules": {
      "pointsToWin": 11,
      "setsToWin": 3,
      "serveRotation": 2,
      "specialRules": "Deuce at 10-10 (play until 2 points ahead)"
    },
    "customization": {
      "tableColor": "#2d5016",
      "ballColor": "#ff6600",
      "paddleColor": "#000000",
      "uiTheme": "dark"
    },
    "metadata": {
      "created_at": "2026-01-28 12:30:45",
      "updated_at": "2026-01-28 12:30:45",
      "updated_by": 1
    },
    "status": "custom"
  }
}

Snapshot (query: ?snapshot=true):

{
  "success": true,
  "snapshot": {
    "discipline": "ping-pong",
    "settingsVersion": 1,
    "rules": {
      "pointsToWin": 11,
      "setsToWin": 3,
      "serveRotation": 2,
      "specialRules": "Deuce at 10-10..."
    },
    "snapshotTimestamp": "2026-01-28 12:30:45"
  }
}

2. Aktualizuj ustawienia (POST)

POST /administration/disciplines/{discipline}/settings

Authoryzacja: Admin role

Body (JSON):

{
  "rules": {
    "pointsToWin": 11,
    "setsToWin": 3,
    "serveRotation": 2,
    "specialRules": "Deuce at 10-10 (play until 2 points ahead)"
  },
  "customization": {
    "tableColor": "#2d5016",
    "ballColor": "#ff6600",
    "paddleColor": "#000000",
    "uiTheme": "dark"
  }
}

Przykład:

curl -X POST \
  "http://localhost/administration/disciplines/ping-pong/settings" \
  -H "Content-Type: application/json" \
  -H "Cookie: PHPSESSID=abc123..." \
  -d '{
    "rules": {
      "pointsToWin": 11,
      "setsToWin": 3,
      "serveRotation": 2,
      "specialRules": "Custom rules"
    },
    "customization": {
      "tableColor": "#000000"
    }
  }'

Odpowiedź (200 OK):

{
  "success": true,
  "message": "Settings for ping-pong have been updated successfully",
  "data": {
    "discipline": "ping-pong",
    "settingsVersion": 2,
    "rules": { ... },
    "customization": { ... },
    "metadata": {
      "created_at": "2026-01-28 12:30:45",
      "updated_at": "2026-01-28 12:35:10",
      "updated_by": 1
    }
  }
}

3. Reset do domyślnych (POST)

POST /administration/disciplines/{discipline}/settings

Body:

{
  "reset": true
}

Przykład:

curl -X POST \
  "http://localhost/administration/disciplines/ping-pong/settings" \
  -H "Content-Type: application/json" \
  -H "Cookie: PHPSESSID=abc123..." \
  -d '{"reset": true}'

🔐 API Endpoint dla Gry (bez admin wymogu)

GET /api/discipline-settings.php?discipline=ping-pong&snapshot=true

Parametry:

  • discipline: nazwa dyscypliny
  • version (opcjonalne): konkretna wersja

Nie wymaga logowania - gra pobiera snapshot do startu meczu

Przykład:

curl -X GET \
  "http://localhost/api/discipline-settings.php?discipline=ping-pong&snapshot=true"

Odpowiedź:

{
  "success": true,
  "snapshot": {
    "discipline": "ping-pong",
    "settingsVersion": 1,
    "rules": {
      "pointsToWin": 11,
      "setsToWin": 3,
      "serveRotation": 2,
      "specialRules": "Deuce at 10-10..."
    },
    "customization": { ... },
    "snapshotTimestamp": "2026-01-28 12:35:10"
  }
}

✅ Walidacja Danych

Reguły gry (Logika)

Pole Typ Min Max Default Opis
pointsToWin INT 1 100 11 Punkty do wygrania seta
setsToWin INT 1 100 3 Sety do wygrania meczu
serveRotation INT 1 50 2 Punkty do zmiany serwisu
specialRules TEXT - - null Dodatkowe reguły (np. brak przerw, tie-break)

Logika Biznesowa

✅ pointsToWin >= 1 ✅ setsToWin >= 1 ✅ pointsToWin i setsToWin powinny być nieparzyste (aby uniknąć remisów)

Przy remisie wymagany jest override reguł (specjalne logika w grze).

Personalizacja (UI)

{
  "customization": {
    "tableColor": "#2d5016",
    "ballColor": "#ff6600",
    "paddleColor": "#000000",
    "uiTheme": "dark"
  }
}

Customization to JSON, może zawierać dowolne pola - nie wpływa na logiką gry.

🔄 Versioning Ustawień

Każda aktualizacja automatycznie zwiększa settingsVersion:

Wersja 1 → 2 → 3 → ...

Przydatne do:

  • Startu meczu ze snapshot'em (ustawienia z momentu startu)
  • Auditowania zmian
  • Przywracania starych wersji (w przyszłości)

🚀 Integracja z Grą

Startup gry (pobierz snapshot)

// JavaScript - pobierz ustawienia na start meczu
async function initializeGame(discipline) {
  const response = await fetch(
    `/api/discipline-settings.php?discipline=${discipline}&snapshot=true`
  );
  const result = await response.json();
  
  if (result.success) {
    const settings = result.snapshot;
    // Ustaw reguły gry
    const game = new PingPongGame({
      pointsToWin: settings.rules.pointsToWin,
      setsToWin: settings.rules.setsToWin,
      serveRotation: settings.rules.serveRotation,
      settingsVersion: settings.settingsVersion // Zapisz wersję dla logów
    });
    
    // Ustaw UI
    applyCustomization(settings.customization);
    
    return game;
  }
}

Wysyłanie wyniku meczu

// PHP - backend zapisuje mecz z snapshot'em ustawień
$snapshot = $service->getMatchSnapshot('ping-pong');

$match = [
  'team1_id' => 1,
  'team2_id' => 2,
  'score' => '3:2',
  'status' => 'end',
  'settingsSnapshot' => json_encode($snapshot), // Zapisz snapshot
  'startTime' => date('Y-m-d H:i:s')
];

🧪 Testowanie

Test 1: Pobierz domyślne ustawienia

curl http://localhost/administration/disciplines/ping-pong/settings \
  -H "Cookie: PHPSESSID=admin_session"

Test 2: Zaktualizuj ustawienia

curl -X POST http://localhost/administration/disciplines/ping-pong/settings \
  -H "Content-Type: application/json" \
  -H "Cookie: PHPSESSID=admin_session" \
  -d '{
    "rules": {
      "pointsToWin": 21,
      "setsToWin": 2,
      "serveRotation": 3
    }
  }'

Test 3: Pobierz snapshot

curl http://localhost/administration/disciplines/ping-pong/settings?snapshot=true \
  -H "Cookie: PHPSESSID=admin_session"

Test 4: Pobierz snapshot z API (bez admin)

curl http://localhost/api/discipline-settings.php?discipline=ping-pong&snapshot=true

Test 5: Reset do defaults

curl -X POST http://localhost/administration/disciplines/ping-pong/settings \
  -H "Content-Type: application/json" \
  -H "Cookie: PHPSESSID=admin_session" \
  -d '{"reset": true}'

📊 Domyślne Ustawienia

Ping-Pong (🏓)

{
  "pointsToWin": 11,
  "setsToWin": 3,
  "serveRotation": 2,
  "specialRules": "Deuce at 10-10 (play until 2 points ahead)",
  "customization": {
    "tableColor": "#2d5016",
    "ballColor": "#ff6600",
    "paddleColor": "#000000",
    "uiTheme": "dark"
  }
}

Papier-Kamień-Nożyce (✊)

{
  "pointsToWin": 5,
  "setsToWin": 1,
  "serveRotation": 1,
  "specialRules": "Best of 1, instant rounds",
  "customization": {
    "animationSpeed": "fast",
    "uiTheme": "light"
  }
}

Piłkarzyki (⚽)

{
  "pointsToWin": 5,
  "setsToWin": 1,
  "serveRotation": 3,
  "specialRules": "Standard foosball rules, auto-restart after goal",
  "customization": {
    "tableColor": "#000000",
    "figureColor": "#ffffff",
    "uiTheme": "dark"
  }
}

📁 Struktura Plików

private_html/
├── api/
│   ├── DisciplineSettingsModel.php       # Model BD
│   ├── DisciplineSettingsService.php     # Serwis logiki
│   └── discipline-settings.php           # API endpoint (publiczny)
└── administration/
    └── disciplines/
        ├── ping-pong/settings/
        │   └── index.php                 # Kontroler settings
        ├── rock-paper-scissors/settings/
        │   └── index.php                 # Kontroler settings
        └── table-football/settings/
            └── index.php                 # Kontroler settings

🔧 Rozbudowa na Nowe Dyscypliny

  1. Dodaj dyscyplinę do DisciplineSettingsModel::getDefaults()
  2. Utwórz folder administration/disciplines/{discipline}/settings/
  3. Skopiuj index.php z ping-ponga
  4. Kod automatycznie rozpozna nową dyscyplinę z URL

⚠️ Kody Błędów

Kod Błąd Opis
200 OK Sukces
400 Bad Request Zła walidacja danych lub JSON
401 Unauthorized Brak logowania
403 Forbidden Brak roli admin
405 Method Not Allowed Tylko GET i POST
500 Server Error Błąd bazy danych

📝 Wdrażanie

  1. Załaduj pliki:

    • private_html/api/DisciplineSettingsModel.php
    • private_html/api/DisciplineSettingsService.php
    • private_html/api/discipline-settings.php
    • private_html/administration/disciplines/*/settings/index.php

  2. Tabela BD:

    • Automatycznie tworzy się na pierwszy GET

  3. Testuj:

    curl http://localhost/administration/disciplines/ping-pong/settings

🎯 Przyszłe Rozszerzenia

  • Historia zmian (tabela settings_disciplines_history)
  • Porównanie wersji w panelu admina
  • Export/Import ustawień
  • Scheduled changes (zmiana ustawień w określonym czasie)
  • A/B testing reguł
  • Analytics - jak zmiana ustawień wpłyneła na liczbę meczy