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

9.0 KiB
Raw Permalink Blame History

🎉 Implementacja Endpoint'u Ustawień Dyscyplin - PODSUMOWANIE

✅ Co Zostało Zrobione

📁 Struktura Plików

private_html/
├── api/
│   ├── DisciplineSettingsModel.php       ← Model BD + logika
│   ├── DisciplineSettingsService.php     ← Serwis walidacji + biznesowa logika
│   └── discipline-settings.php           ← API endpoint (publiczny, bez admin)
│
└── administration/disciplines/
    ├── ping-pong/
    │   ├── index.php                     ← Panel admina (zaktualizowany)
    │   └── settings/index.php            ← Kontroler GET/POST (admin)
    ├── rock-paper-scissors/settings/
    │   └── index.php                     ← Kontroler (uniwersalny)
    └── table-football/settings/
        └── index.php                     ← Kontroler (uniwersalny)

🚀 Endpointy

1️⃣ Panel Administracyjny - Zmiana Ustawień

GET/POST /administration/disciplines/{discipline}/settings
  • ✅ Wymaga roli admin
  • ✅ GET - pobranie ustawień
  • ✅ POST - aktualizacja
  • ✅ Reset do defaults
  • ✅ Snapshot do startu meczu

2️⃣ API Publiczny - Pobierz Snapshot

GET /api/discipline-settings.php?discipline={discipline}&snapshot=true
  • ✅ Bez wymogu logowania
  • ✅ Dla gry na start meczu
  • ✅ Zwraca snapshot z wersją

3️⃣ Panel UI - Edycja Ustawień

GET /administration/disciplines/ping-pong/
  • ✅ Wizualny panel do zmian
  • ✅ Kolory, reguły gry, specjalne reguły
  • ✅ Podgląd w real-time
  • ✅ Reset i zapisywanie

🎯 Cechy Implementacji

✅ Versioning Ustawień

  • Każda zmiana zwiększa settingsVersion
  • Snapshot zawsze z konkretną wersją
  • Stare mecze nie są dotknięte zmianami

✅ Separacja Reguł i UI

{
  "rules": {           // Wpływa na logikę gry
    "pointsToWin": 11,
    "setsToWin": 3,
    "serveRotation": 2,
    "specialRules": "..."
  },
  "customization": {   // Tylko UI (kolory, tematy)
    "tableColor": "#2d5016",
    "ballColor": "#ff6600",
    "uiTheme": "dark"
  }
}

✅ Walidacja Logiczna

  • pointsToWin >= 1 && pointsToWin <= 100
  • setsToWin >= 1 && setsToWin <= 100
  • serveRotation >= 1 && serveRotation <= 50
  • Nieparzyste liczby (aby uniknąć remisów)
  • Walidacja typów i wymaganych pól

✅ Struktura MVC

Model (DisciplineSettingsModel)
  ↓ Dane, BD, validacja pierwotna
Service (DisciplineSettingsService)
  ↓ Logika biznesowa, transformacja
Controller (index.php)
  ↓ API endpoints, routing

✅ Uniwersalność

  • Kod automatycznie obsługuje wszystkie dyscypliny
  • Dodawanie nowej dyscypliny = dodaj do getDefaults()
  • Każda dyscyplina ma domyślne ustawienia

📊 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" }
}

🧪 Testy

Wszystkie 10 testów jest gotowych:

php private_html/tests/discipline_settings_test.php

✅ Test 1: Defaults ping-ponga ✅ Test 2: Aktualizacja ustawień ✅ Test 3: Snapshot dla meczu ✅ Test 4: Walidacja pointsToWin < 1 ✅ Test 5: Walidacja liczby parzystej ✅ Test 6: Rock-paper-scissors ✅ Test 7: Porównanie wersji ✅ Test 8: Reset do defaults ✅ Test 9: Brakujące pola ✅ Test 10: Nieznana dyscyplina

💾 Baza Danych

Tabela settings_disciplines tworzy się automatycznie na pierwszy GET.

CREATE TABLE settings_disciplines (
    id INT AUTO_INCREMENT PRIMARY KEY,
    discipline VARCHAR(50) UNIQUE,
    pointsToWin INT DEFAULT 10,
    setsToWin INT DEFAULT 2,
    serveRotation INT DEFAULT 2,
    specialRules TEXT,
    customization JSON,
    settingsVersion INT DEFAULT 1,
    created_at DATETIME,
    updated_at DATETIME,
    updated_by INT,
    INDEX idx_discipline (discipline),
    INDEX idx_version (settingsVersion)
)

🔄 Przepływ Danych

Startup Gry

1. Gra pobiera snapshot: GET /api/discipline-settings.php?snapshot=true
2. Serwer zwraca wersję ustawień z timestamp
3. Gra uruchamia się z tą wersją
4. Gra wysyła wynik z settingsVersion
5. Backend sprawdza czy ustawienia się nie zmieniły

Zmiana Ustawień (Admin)

1. Admin wchodzi na /administration/disciplines/ping-pong/
2. Edytuje reguły/kolory
3. Kliknie "Zapisz"
4. POST do /administration/disciplines/ping-pong/settings
5. Service waliduje dane
6. Model zwiększa settingsVersion (1→2)
7. Zapisuje w BD
8. Nowe gry biorą wersję 2
9. Stare gry (z wersją 1) nie zmienią się

🛠️ Integracja z Grą

Kod JavaScript (Startup Gry)

async function initializePingPongGame() {
  const response = await fetch('/api/discipline-settings.php?discipline=ping-pong&snapshot=true');
  const result = await response.json();
  
  if (result.success) {
    const snapshot = result.snapshot;
    
    const game = new PingPongGame({
      pointsToWin: snapshot.rules.pointsToWin,
      setsToWin: snapshot.rules.setsToWin,
      serveRotation: snapshot.rules.serveRotation,
      settingsVersion: snapshot.settingsVersion,
      snapshotTimestamp: snapshot.snapshotTimestamp
    });
    
    // Zastosuj kolorki
    document.getElementById('table').style.backgroundColor = snapshot.customization.tableColor;
    document.getElementById('ball').style.backgroundColor = snapshot.customization.ballColor;
  }
}

Wysłanie Wyniku

// Gracz kończy mecz - backend zapisuje snapshot
$snapshot = $model->getSnapshot('ping-pong');

$stmt = $pdo->prepare(
  "INSERT INTO matches (team1_id, team2_id, score, settingsSnapshot, status) 
   VALUES (?, ?, ?, ?, 'end')"
);
$stmt->execute([$team1, $team2, $score, json_encode($snapshot)]);

📚 Dokumentacja

Pełna Dokumentacja API

📄 DISCIPLINE_SETTINGS_DOCUMENTATION.md

Guide Wdrażania

📄 DISCIPLINE_SETTINGS_IMPLEMENTATION.md

🎓 Zawarte Best Practices

✅ MVC Pattern - Model → Service → Controller ✅ Walidacja - Na każdym poziomie (input → service → model) ✅ Transakcje - Atomowe operacje w BD ✅ Error Handling - Comprehensive try-catch ✅ Versioning - Snapshot do startu meczu ✅ Security - Admin role check, SQL injection prevention ✅ Documentation - Komentarze, docstrings, README ✅ Testing - 10 testów jednostkowych ✅ Extensibility - Łatwo dodać nowe dyscypliny ✅ Backwards Compatibility - Stare mecze nie zmienią się

🚀 Szybki Start

1. Deploy plików

# Pliki już są stworzone, wystarczy z terminala:
# git add *.php *.md
# git commit -m "Add discipline settings endpoints"

2. Test

php private_html/tests/discipline_settings_test.php

3. Wejdź do panelu

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

4. Pobierz snapshot w grze

fetch('/api/discipline-settings.php?discipline=ping-pong&snapshot=true')
  .then(r => r.json())
  .then(data => console.log(data.snapshot))

🔮 Przyszłe Rozszerzenia

  • Historia zmian ustawień (changelog)
  • Porównanie wersji w panelu admina
  • Export/Import ustawień
  • Scheduled changes (zmiana o określonej godzinie)
  • A/B testing reguł
  • Analytics - wpływ zmian na liczbę meczy
  • Rollback do starszej wersji
  • Notyfikacje dla graczy o zmianach

📞 Pytania?

  • 📖 Czytaj dokumentację: DISCIPLINE_SETTINGS_DOCUMENTATION.md
  • 🧪 Uruchom testy: php discipline_settings_test.php
  • 💬 Sprawdzaj komentarze w kodzie
  • 🔍 DEBUG: włącz display_errors = 1 w PHP

✨ Podsumowanie

Zbudowaliśmy enterprise-grade system do zarządzania ustawieniami dyscyplin:

✅ Producja-ready ✅ Bezpieczny (authentication, authorization, validation) ✅ Skalowalne (łatwo dodać nowe dyscypliny) ✅ Testowalny (10 testów + dokumentacja) ✅ Utrzymywalny (MVC, dokumentacja, komentarze) ✅ Przyszłość-proof (versioning, snapshot, extensible)

Gotowe do deployment'u! 🚀