togethere.cloud/mds/DISCIPLINE_SETTINGS_DOCUMENTATION.md

# 📋 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:**
```bash
curl -X GET \
  "http://localhost/administration/disciplines/ping-pong/settings" \
  -H "Cookie: PHPSESSID=abc123..."
```

**Odpowiedź (200 OK):**
```json
{
  "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):**
```json
{
  "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):**
```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:**
```bash
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):**
```json
{
  "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:**
```json
{
  "reset": true
}
```

**Przykład:**
```bash
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:**
```bash
curl -X GET \
  "http://localhost/api/discipline-settings.php?discipline=ping-pong&snapshot=true"
```

**Odpowiedź:**
```json
{
  "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)

```json
{
  "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
// 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
// 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
```bash
curl http://localhost/administration/disciplines/ping-pong/settings \
  -H "Cookie: PHPSESSID=admin_session"
```

### Test 2: Zaktualizuj ustawienia
```bash
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
```bash
curl http://localhost/administration/disciplines/ping-pong/settings?snapshot=true \
  -H "Cookie: PHPSESSID=admin_session"
```

### Test 4: Pobierz snapshot z API (bez admin)
```bash
curl http://localhost/api/discipline-settings.php?discipline=ping-pong&snapshot=true
```

### Test 5: Reset do defaults
```bash
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 (🏓)
```json
{
  "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 (✊)
```json
{
  "pointsToWin": 5,
  "setsToWin": 1,
  "serveRotation": 1,
  "specialRules": "Best of 1, instant rounds",
  "customization": {
    "animationSpeed": "fast",
    "uiTheme": "light"
  }
}
```

### Piłkarzyki (⚽)
```json
{
  "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:**
   ```bash
   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