# API Dokumentace - České Kluby Loga API

## 🚀 Rychlý Start

### ⬆️ Nahrání loga klubu - Základní příkaz

    curl -X POST http://localhost:8080/logos/{club-uuid} \
      -F "file=@logo.svg" \
      -F "club_name=Název Klubu"

Povinné: Club UUID v URL, soubor loga (SVG/PNG/PDF), název klubu

Volitelné: club_type, club_website, club_city

### 📥 Stažení loga klubu

    # Přímo z backendu
    curl http://localhost:8080/logos/{uuid}

    # Přes frontend proxy
    curl http://localhost:3000/api/logos/{uuid}

Vrátí PNG obrázek loga (SVG jako fallback)

## 📡 Endpointy

GET `/logos`

Seznam všech nahraných log

#### Response 200:

    [
      {
        "id": "uuid-here",
        "club_name": "AC Sparta Praha",
        "club_type": "football",
        "has_svg": true,
        "has_png": true,
        "logo_url": "http://localhost:8080/logos/uuid-here",
        "created_at": "2024-01-01T12:00:00Z"
      }
    ]

GET `/logos/:id`

Získání souboru loga (PNG preferováno, SVG jako fallback)

#### Query Parameters (volitelné):

`format` string - "png" nebo "svg"

#### Response 200:

Binární data obrázku (image/png nebo image/svg+xml)

GET `/logos/:id/json`

Získání metadat loga ve formátu JSON

#### Response 200:

    {
      "id": "uuid-here",
      "club_name": "AC Sparta Praha",
      "club_type": "football",
      "club_website": "https://sparta.cz",
      "has_svg": true,
      "has_png": true,
      "primary_format": "png",
      "logo_url": "http://localhost:8080/logos/uuid-here",
      "logo_url_svg": "http://localhost:8080/logos/uuid-here?format=svg",
      "logo_url_png": "http://localhost:8080/logos/uuid-here?format=png",
      "file_size_svg": 12345,
      "file_size_png": 54321,
      "created_at": "2024-01-01T12:00:00Z",
      "updated_at": "2024-01-01T12:00:00Z"
    }

POST `/logos/:id`

Nahrání nového loga klubu s kompletními daty (ID klubu, název, logo soubory)

#### URL Parameters:

`:id` * UUID - Jedinečné ID klubu (např. `550e8400-e29b-41d4-a716-446655440000`)

#### Content-Type:

`multipart/form-data`

#### Form Data (Povinné pole):

`file` * file (SVG nebo PNG)

Soubor loga. Podporované formáty: SVG (doporučeno), PNG, PDF

`club_name` * string

Název klubu (např. "AC Sparta Praha")

#### Form Data (Volitelné):

`club_type` string

Typ klubu: `"football"` (výchozí) nebo `"futsal"`

`club_website` string

URL webové stránky klubu (např. "https://sparta.cz")

`club_city` string

Město klubu (např. "Praha")

#### Response 200 (Úspěch):

    {
      "success": true,
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "club_name": "AC Sparta Praha",
      "has_svg": true,
      "has_png": true,
      "size_svg": 12543,
      "size_png": 45210,
      "message": "logo uploaded successfully"
    }

#### Response 400 (Chyba):

    {
      "error": "club_name is required"
    }

Možné chyby: `"no file provided"`, `"invalid UUID format"`, `"only .svg, .png and .pdf files are allowed"`

## 💡 Příklady Použití - Nahrání Loga

### 🔧 cURL (Terminal)

#### Minimální nahrání (pouze povinná pole):

    curl -X POST http://localhost:8080/logos/550e8400-e29b-41d4-a716-446655440000 \
      -F "file=@sparta_logo.svg" \
      -F "club_name=AC Sparta Praha"

#### Kompletní nahrání (všechna data):

    curl -X POST http://localhost:8080/logos/550e8400-e29b-41d4-a716-446655440000 \
      -F "file=@sparta_logo.svg" \
      -F "club_name=AC Sparta Praha" \
      -F "club_type=football" \
      -F "club_website=https://sparta.cz" \
      -F "club_city=Praha"

#### Nahrání PNG místo SVG:

    curl -X POST http://localhost:8080/logos/550e8400-e29b-41d4-a716-446655440000 \
      -F "file=@sparta_logo.png" \
      -F "club_name=AC Sparta Praha"

### 📜 JavaScript (Fetch API)

    // Funkce pro nahrání loga s kompletními daty
    async function uploadClubLogo(clubId, file, clubData) {
      const formData = new FormData();

      // Povinná pole
      formData.append('file', file);
      formData.append('club_name', clubData.name);

      // Volitelná pole
      if (clubData.type) formData.append('club_type', clubData.type);
      if (clubData.website) formData.append('club_website', clubData.website);
      if (clubData.city) formData.append('club_city', clubData.city);

      const response = await fetch(`http://localhost:8080/logos/${clubId}`, {
        method: 'POST',
        body: formData
      });

      if (!response.ok) {
        const error = await response.json();
        throw new Error(error.error);
      }

      return await response.json();
    }

    // Použití s file input
    const fileInput = document.getElementById('logoFile');
    const clubId = '550e8400-e29b-41d4-a716-446655440000';

    const result = await uploadClubLogo(clubId, fileInput.files[0], {
      name: 'AC Sparta Praha',
      type: 'football',
      website: 'https://sparta.cz',
      city: 'Praha'
    });

    console.log('Upload successful:', result);

### 🐍 Python (requests)

    import requests

    def upload_club_logo(club_id, file_path, club_name, **optional_data):
        """
        Nahraje logo klubu s kompletními daty

        Args:
            club_id: UUID klubu
            file_path: Cesta k souboru loga
            club_name: Název klubu (povinný)
            **optional_data: club_type, club_website, club_city
        """
        with open(file_path, 'rb') as f:
            files = {'file': f}
            data = {'club_name': club_name}
            data.update(optional_data)

            response = requests.post(
                f"http://localhost:8080/logos/{club_id}",
                files=files,
                data=data
            )
            response.raise_for_status()
            return response.json()

    # Použití
    result = upload_club_logo(
        club_id='550e8400-e29b-41d4-a716-446655440000',
        file_path='sparta_logo.svg',
        club_name='AC Sparta Praha',
        club_type='football',
        club_website='https://sparta.cz',
        club_city='Praha'
    )

    print(f"Upload úspěšný: {result['message']}")
    print(f"Has SVG: {result['has_svg']}, Has PNG: {result['has_png']}")

### 💻 PowerShell

    # Nahrání loga s kompletními daty
    $clubId = "550e8400-e29b-41d4-a716-446655440000"
    $logoFile = "C:\logos\sparta_logo.svg"

    $form = @{
        file = Get-Item -Path $logoFile
        club_name = "AC Sparta Praha"
        club_type = "football"
        club_website = "https://sparta.cz"
        club_city = "Praha"
    }

    $result = Invoke-RestMethod `
        -Uri "http://localhost:8080/logos/$clubId" `
        -Method Post `
        -Form $form

    Write-Host "Upload úspěšný: $($result.message)" -ForegroundColor Green
    Write-Host "Club: $($result.club_name)" -ForegroundColor Cyan

## ⚠️ Chybové Kódy

200

#### OK

Požadavek úspěšně dokončen

400

#### Bad Request

Neplatné parametry nebo chybějící povinná pole

404

#### Not Found

Logo nebo klub nenalezen

500

#### Internal Server Error

Interní chyba serveru