# Dokumentacja Systemu Meczów - Sonics NBA Manager

## Przegląd

System meczów Seattle SuperSonics został zaimplementowany w wtyczce WordPress "Sonics NBA Manager". Pozwala na import, zarządzanie i wyświetlanie kompletnej historii meczów drużyny z lat 1967-2008.

## Spis Treści

1. [Import Danych](#import-danych)
2. [Struktura Bazy Danych](#struktura-bazy-danych)
3. [Interfejs Administracyjny](#interfejs-administracyjny)
4. [Shortcodes](#shortcodes)
5. [API Funkcji PHP](#api-funkcji-php)

---

## Import Danych

### Import przez Panel Admina

1. Przejdź do **Sonics → Mecze** w panelu WordPress
2. Znajdź sekcję "Import danych z Basketball Reference"
3. Dostępne opcje:
   - **Importuj mecze sezonu** - importuje mecze dla wybranego sezonu
   - **Importuj WSZYSTKIE sezony (1967-2008)** - importuje kompletną historię (może potrwać kilka minut)

### Import Programowy

```php
// Importuj wszystkie sezony
$importer = new Sonics_API_Importer();
$stats = $importer->import_all_seasons();

// Wynik:
// array(
//   'seasons_imported' => 41,
//   'games_imported' => 3300+,
//   'errors' => array()
// )

// Importuj pojedynczy sezon
$season_id = 1; // ID sezonu z bazy
$season_year = 2007; // Rok rozpoczęcia sezonu (2007-08)
$games_count = $importer->import_games( $season_id, $season_year );
```

---

## Struktura Bazy Danych

### Tabela: `wp_sonics_games`

| Kolumna | Typ | Opis |
|---------|-----|------|
| `id` | mediumint(9) | ID meczu |
| `season_id` | mediumint(9) | ID powiązanego sezonu |
| `game_number` | smallint(3) | Numer meczu w sezonie |
| `game_date` | date | Data meczu |
| `opponent` | varchar(100) | Nazwa przeciwnika |
| `opponent_code` | varchar(5) | Kod przeciwnika (np. LAL, BOS) |
| `home_away` | varchar(4) | 'HOME' lub 'AWAY' |
| `sonics_score` | smallint(3) | Punkty Sonics |
| `opponent_score` | smallint(3) | Punkty przeciwnika |
| `win_loss` | varchar(1) | 'W' lub 'L' |
| `win_loss_record` | varchar(10) | Bilans po meczu (np. "45-20") |
| `overtime` | varchar(5) | Dogrywka (OT, 2OT, 3OT, etc.) |
| `attendance` | int(6) | Frekwencja |
| `game_type` | varchar(20) | 'Regular Season' lub 'Playoffs' |
| `arena` | varchar(100) | Nazwa areny |
| `box_score_url` | varchar(255) | URL do box score |
| `box_score` | longtext | Dane box score (JSON) |
| `game_notes` | text | Notatki o meczu |
| `created_at` | datetime | Data utworzenia rekordu |

---

## Interfejs Administracyjny

### Lokalizacja
**Sonics → Mecze** w menu WordPress admin

### Funkcjonalności

#### 1. Filtrowanie
- **Wybór sezonu** - dropdown z wszystkimi sezonami
- **Typ meczu** - Sezon regularny lub Playoffs

#### 2. Statystyki Sezonu
- Bilans (W-L)
- Procent wygranych
- Informacje o trenerze
- Liczba meczów

#### 3. Tabela Meczów
Wyświetla:
- Numer meczu
- Data
- Lokalizacja (vs/@ - dom/wyjazd)
- Przeciwnik
- Wynik (W/L)
- Wynik punktowy
- Dogrywka (jeśli była)
- Bilans po meczu
- Frekwencja

#### 4. Kolorystyka
- **Zielone tło** - wygrana
- **Czerwone tło** - przegrana

---

## Shortcodes

### 1. `[sonics_games]`

Wyświetla listę meczów z opcjami filtrowania.

**Parametry:**
- `season` - rok sezonu (np. "2007-08")
- `season_id` - ID sezonu z bazy
- `limit` - liczba meczów do wyświetlenia (domyślnie: 10)
- `type` - typ meczu: "Regular Season", "Playoffs", "all" (domyślnie: "Regular Season")
- `home_away` - "HOME", "AWAY" lub puste dla wszystkich
- `style` - "table" lub "cards" (domyślnie: "table")

**Przykłady:**

```shortcode
<!-- Ostatnie 10 meczów sezonu regularnego -->
[sonics_games season="2007-08" limit="10"]

<!-- Wszystkie mecze playoff -->
[sonics_games season="1996-97" type="Playoffs"]

<!-- Mecze domowe jako karty -->
[sonics_games season="1978-79" home_away="HOME" style="cards"]

<!-- Wszystkie mecze w formie tabeli -->
[sonics_games season="2007-08" type="all" limit="100"]
```

### 2. `[sonics_season_schedule]`

Wyświetla pełny harmonogram sezonu (sezon regularny + playoffs).

**Parametry:**
- `season` - rok sezonu (np. "1978-79")
- `season_id` - ID sezonu z bazy

**Przykłady:**

```shortcode
<!-- Pełny harmonogram sezonu mistrzowskiego 1978-79 -->
[sonics_season_schedule season="1978-79"]

<!-- Pełny harmonogram ostatniego sezonu w Seattle -->
[sonics_season_schedule season="2007-08"]
```

**Wyświetla:**
- Nagłówek sezonu z nazwą drużyny
- Bilans sezonu regularnego (W-L i procent)
- Imię trenera
- Tabelę meczów sezonu regularnego
- Tabelę meczów playoff (jeśli były)

### 3. `[sonics_last_game]`

Wyświetla ostatni rozegrany mecz (jako kartę).

**Przykład:**
```shortcode
[sonics_last_game]
```

### 4. `[sonics_next_game]`

Wyświetla następny mecz (jako kartę).

**Przykład:**
```shortcode
[sonics_next_game]
```

---

## API Funkcji PHP

### Klasa: `Sonics_Database`

#### `get_games( $season_id, $args )`

Pobiera mecze z opcjami filtrowania.

```php
$db = Sonics_Database::get_instance();

// Podstawowe użycie
$games = $db->get_games( $season_id );

// Z filtrami
$games = $db->get_games( $season_id, array(
    'limit'     => 20,
    'offset'    => 0,
    'game_type' => 'Playoffs',
    'home_away' => 'HOME',
    'order'     => 'ASC',
    'orderby'   => 'game_date'
) );
```

#### `get_game( $game_id )`

Pobiera pojedynczy mecz.

```php
$game = $db->get_game( 123 );
echo $game->opponent; // "Los Angeles Lakers"
```

#### `get_season_record( $season_id, $game_type )`

Pobiera bilans sezonu.

```php
$record = $db->get_season_record( $season_id, 'Regular Season' );
// array(
//   'wins'   => 64,
//   'losses' => 18,
//   'total'  => 82
// )
```

#### `add_game( $args )`

Dodaje nowy mecz.

```php
$game_id = $db->add_game( array(
    'season_id'       => 1,
    'game_number'     => 1,
    'game_date'       => '2007-10-31',
    'opponent'        => 'Denver Nuggets',
    'opponent_code'   => 'DEN',
    'home_away'       => 'HOME',
    'sonics_score'    => 106,
    'opponent_score'  => 99,
    'win_loss'        => 'W',
    'win_loss_record' => '1-0',
    'overtime'        => '',
    'attendance'      => 17072,
    'game_type'       => 'Regular Season',
    'arena'           => 'KeyArena',
) );
```

### Klasa: `Sonics_API_Importer`

#### `import_games( $season_id, $season_year )`

Importuje mecze z Basketball-Reference.com.

```php
$importer = new Sonics_API_Importer();
$games_count = $importer->import_games( $season_id, 2007 );
echo "Zaimportowano: $games_count meczów";
```

#### `import_all_seasons()`

Importuje wszystkie sezony (1967-2008).

```php
$stats = $importer->import_all_seasons();
echo "Sezony: " . $stats['seasons_imported'];
echo "Mecze: " . $stats['games_imported'];
```

---

## Przykłady Użycia

### Przykład 1: Strona Sezonu Mistrzowskiego 1978-79

```html
<h1>Sezon 1978-79 - Mistrzostwo NBA!</h1>

<p>Seattle SuperSonics zdobyli tytuł mistrzowski, pokonując Washington Bullets 4-1 w finale.</p>

<!-- Pełny harmonogram -->
[sonics_season_schedule season="1978-79"]

<!-- Dodatkowe informacje -->
<h2>Finały NBA 1979</h2>
[sonics_games season="1978-79" type="Playoffs" limit="5"]
```

### Przykład 2: Dashboard "Ostatnie Mecze"

```html
<div class="sonics-dashboard">
    <h2>Ostatni Mecz</h2>
    [sonics_last_game]
    
    <h2>Następny Mecz</h2>
    [sonics_next_game]
</div>
```

### Przykład 3: Strona Historii Meczów

```html
<h1>Historia Meczów Seattle SuperSonics</h1>

<h2>Sezon 2007-08 (Ostatni sezon w Seattle)</h2>
[sonics_season_schedule season="2007-08"]

<h2>Sezon 1995-96 (Finał NBA)</h2>
[sonics_season_schedule season="1995-96"]

<h2>Sezon 1978-79 (Mistrzostwo)</h2>
[sonics_season_schedule season="1978-79"]
```

### Przykład 4: Widget Boczny z Kartami Meczów

```html
<!-- Widget z ostatnimi 3 meczami jako karty -->
[sonics_games season="2007-08" limit="3" style="cards"]
```

---

## Stylizacja CSS

### Klasy CSS dla Tabel

- `.sonics-games-table` - główna tabela
- `.sonics-games-table tbody tr.win` - wiersz wygranego meczu (zielone tło)
- `.sonics-games-table tbody tr.loss` - wiersz przegranego meczu (czerwone tło)
- `.sonics-games-table .wl-w` - litera W (zielona)
- `.sonics-games-table .wl-l` - litera L (czerwona)

### Klasy CSS dla Kart

- `.sonics-game-card` - główna karta meczu
- `.sonics-game-card.sonics-win` - wygrana (zielony border)
- `.sonics-game-card.sonics-loss` - przegrana (czerwony border)
- `.sonics-game-matchup` - sekcja z wynikiem
- `.sonics-game-info` - informacje dodatkowe

### Personalizacja

```css
/* Zmień kolory zwycięstw */
.sonics-games-table tbody tr.win {
    background-color: rgba(0, 166, 81, 0.1) !important;
    border-left-color: #00A651 !important;
}

/* Większa czcionka dla wyniku */
.sonics-game-card .sonics-team-score {
    font-size: 40px !important;
}
```

---

## Dane Historyczne

### Podsumowanie
- **Lata działalności:** 1967-2008 (41 sezonów)
- **Liczba meczów:** ~3,300+ (sezon regularny + playoffs)
- **Mistrzostwo NBA:** 1979
- **Finały NBA:** 1978, 1979, 1996
- **Areny:**
  - Seattle Center Coliseum (1967-1995)
  - KeyArena (1995-2008)

### Ważne Sezony

| Sezon | Bilans | Osiągnięcie |
|-------|--------|-------------|
| 1967-68 | 23-59 | Inauguracyjny sezon |
| 1978-79 | 52-30 | **Mistrzostwo NBA** |
| 1995-96 | 64-18 | Finał NBA (przegrana z Bulls) |
| 2004-05 | 52-30 | Ostatni sezon playoff |
| 2007-08 | 20-62 | Ostatni sezon w Seattle |

---

## Wsparcie i Rozwój

### Planowane funkcje:
- [ ] Import box score (statystyki zawodników z meczu)
- [ ] Filtry zaawansowane (przeciwnik, arena, zakres dat)
- [ ] Eksport do CSV/PDF
- [ ] Wykresy statystyczne
- [ ] Porównanie sezonów

### Zgłaszanie błędów
Jeśli napotkasz problemy z importem lub wyświetlaniem danych, sprawdź:
1. Logi błędów WordPress
2. Połączenie z Basketball-Reference.com
3. Limity PHP (time limit, memory limit)

---

## Licencja

© 2025 Sonics Polska - Wtyczka WordPress dla fanów Seattle SuperSonics