# System Statystyk Głosowań - Dokumentacja

## Przegląd

System został rozbudowany o zaawansowane zbieranie statystyk głosowań. Teraz każdy pojedynek jest zapisywany, a zmiany rankingu są śledzone w czasie.

## Nowe funkcjonalności

### 1. **System hashowania plików (SHA-256)**
- Każdy mem ma unikalny identyfikator bazujący na hashu pliku
- Automatyczne wykrywanie duplikatów podczas uploadu
- Niemożliwe jest dodanie tego samego obrazka dwa razy

### 2. **Historia pojedynków (battles)**
- Każdy pojedynek jest zapisywany z pełnymi danymi:
  - Kto wygrał, kto przegrał
  - Rating przed i po pojedynku dla obu memów
  - Data i czas pojedynku

### 3. **Historia zmian ratingu (rating_history)**
- Śledzenie zmian ratingu w czasie
- Automatyczne zapisywanie po każdym głosowaniu
- Możliwość wizualizacji na wykresach

### 4. **Strona statystyk mema**
- Dostępna pod adresem: `meme_stats.php?id=X`
- Wyświetla:
  - Wykres zmian ratingu w czasie (Chart.js)
  - Szczegółowe statystyki (win rate, liczba gier, etc.)
  - Historia ostatnich 30 pojedynków
  - Wizualizacja przeciwników i wyników

## Struktura bazy danych

### Tabela: `memes` (zmodyfikowana)
```sql
CREATE TABLE memes (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    filename TEXT NOT NULL,
    file_hash TEXT,                -- NOWE: SHA-256 hash pliku
    rating INTEGER DEFAULT 1200,
    wins INTEGER DEFAULT 0,
    losses INTEGER DEFAULT 0,
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP
);
```

### Tabela: `battles` (nowa)
```sql
CREATE TABLE battles (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    winner_id INTEGER NOT NULL,
    loser_id INTEGER NOT NULL,
    winner_rating_before INTEGER NOT NULL,
    winner_rating_after INTEGER NOT NULL,
    loser_rating_before INTEGER NOT NULL,
    loser_rating_after INTEGER NOT NULL,
    battle_date DATETIME DEFAULT CURRENT_TIMESTAMP,
    FOREIGN KEY (winner_id) REFERENCES memes(id) ON DELETE CASCADE,
    FOREIGN KEY (loser_id) REFERENCES memes(id) ON DELETE CASCADE
);
```

### Tabela: `rating_history` (nowa)
```sql
CREATE TABLE rating_history (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    meme_id INTEGER NOT NULL,
    rating INTEGER NOT NULL,
    rank_position INTEGER,
    recorded_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    FOREIGN KEY (meme_id) REFERENCES memes(id) ON DELETE CASCADE
);
```

### Indeksy
- `idx_memes_hash` - szybkie wyszukiwanie po hashu
- `idx_battles_winner` - szybkie zapytania o wygrane
- `idx_battles_loser` - szybkie zapytania o przegrane
- `idx_battles_date` - sortowanie po dacie
- `idx_rating_history_meme` - historia dla konkretnego mema
- `idx_rating_history_date` - sortowanie chronologiczne

## Nowe pliki

### `meme_stats.php`
Strona ze statystykami pojedynczego mema. Zawiera:
- Wykres zmian ratingu (Chart.js)
- Karty ze statystykami
- Lista historii pojedynków z wizualizacją

### `update_existing_db.php`
Skrypt utrzymania bazy danych:
- Dodaje hashe do już istniejących memów
- Inicjalizuje rating_history dla starych rekordów
- **Uruchom po aktualizacji systemu!**

### `db_migrate.php`
Skrypt migracji (opcjonalny - tabele są tworzone automatycznie przez `db.php`)

## Nowe funkcje w `functions.php`

```php
calculateFileHash($filepath)              // Oblicza SHA-256 hash pliku
checkDuplicateByHash($db, $hash)         // Sprawdza duplikaty
recordBattle($db, ...)                   // Zapisuje pojedynek
updateRatingHistory($db, $memeId, $rating) // Aktualizuje historię
getMemeHistory($db, $memeId, $limit)     // Pobiera historię ratingu
getMemeBattles($db, $memeId, $limit)     // Pobiera historię walk
```

## Zmodyfikowane pliki

### `db.php`
- Automatyczne tworzenie nowych tabel przy starcie
- Automatyczne tworzenie indeksów

### `vote.php`
- Zapisywanie pojedynków do tabeli `battles`
- Aktualizacja `rating_history` po każdym głosowaniu

### `upload.php`
- Obliczanie hashu przed zapisem
- Sprawdzanie duplikatów
- Dodawanie początkowego wpisu do `rating_history`

### `ranking.php`
- Dodana kolumna "Statystyki" z linkiem do `meme_stats.php`

## Jak używać

### 1. Aktualizacja istniejącej bazy
Jeśli masz już memów w bazie, uruchom skrypt aktualizacji:
```bash
php update_existing_db.php
```
lub otwórz w przeglądarce: `http://localhost:8088/update_existing_db.php`

### 2. Upload memów
- System automatycznie sprawdzi czy mem już istnieje (po hashu)
- Jeśli plik już jest w bazie, wyświetli komunikat o duplikacie
- Nowe memy automatycznie dostaną wpis w rating_history

### 3. Głosowanie
- Każdy pojedynek jest automatycznie zapisywany
- Historia ratingu aktualizuje się po każdym głosowaniu

### 4. Statystyki
- Kliknij "Zobacz" w kolumnie statystyk w rankingu
- Lub wejdź bezpośrednio: `meme_stats.php?id=1`

## Przykładowe zapytania SQL

### Top 10 memów z największym wzrostem ratingu
```sql
SELECT m.id, m.filename, 
    (SELECT rating FROM rating_history WHERE meme_id = m.id ORDER BY recorded_at DESC LIMIT 1) -
    (SELECT rating FROM rating_history WHERE meme_id = m.id ORDER BY recorded_at ASC LIMIT 1) as rating_change
FROM memes m
ORDER BY rating_change DESC
LIMIT 10;
```

### Historia pojedynków między dwoma konkretnymi memami
```sql
SELECT * FROM battles 
WHERE (winner_id = 1 AND loser_id = 2) 
   OR (winner_id = 2 AND loser_id = 1)
ORDER BY battle_date DESC;
```

### Średni przyrost/spadek ratingu dla mema
```sql
SELECT meme_id, 
    AVG(CASE WHEN result = 'won' THEN winner_rating_after - winner_rating_before 
             ELSE loser_rating_after - loser_rating_before END) as avg_change
FROM (
    SELECT winner_id as meme_id, 'won' as result, 
           winner_rating_before, winner_rating_after, 
           loser_rating_before, loser_rating_after
    FROM battles
    UNION ALL
    SELECT loser_id, 'lost', 
           winner_rating_before, winner_rating_after,
           loser_rating_before, loser_rating_after
    FROM battles
)
GROUP BY meme_id;
```

## Bezpieczeństwo

- Wszystkie zapytania SQL używają prepared statements
- Hashe plików są obliczane po stronie serwera
- Walidacja typów danych (INTEGER, TEXT)
- Foreign keys z CASCADE DELETE

## Wydajność

- Indeksy na wszystkich często używanych kolumnach
- Limit wyników w funkcjach (domyślnie 20-100 rekordów)
- Lazy loading wykresów (tylko gdy są dane)

## Możliwe rozszerzenia

1. **Panel administracyjny**
   - Usuwanie duplikatów
   - Merge'owanie memów
   - Export statystyk do CSV

2. **API endpoint**
   - `/api/meme_stats.php?id=X` - JSON z danymi
   - Integracja z zewnętrznymi narzędziami

3. **Zaawansowane wykresy**
   - Porównanie wielu memów na jednym wykresie
   - Heatmapa pojedynków
   - Prediction win rate

4. **Notyfikacje**
   - Email gdy mem osiągnie milestone
   - Discord webhook z wynikami
