MyClub/DOCS/README copy.md

# Fotbal Club – systém pro správu klubu

Moderní systém pro správu fotbalového klubu postavený na Go (Gin, GORM, PostgreSQL) a Reactu (Chakra UI, React Router, React Query).

## ✨ Funkce

- 🔐 Přihlášení pomocí JWT a role (admin/editor)
- 📝 Články (blog) s kategoriemi, publikací, nahráváním obrázků
- 🖼️ Bezpečné nahrávání souborů s kontrolou typu a velikosti
- ⚽ Správa týmů a hráčů
- 📅 Zápasy a tabulky s integrací FACR (cache, aliasy soutěží, override názvů/log)
- 💼 Sponzoři a bannery
- 📧 Kontaktní formulář s e‑mailovými notifikacemi
- 🚀 REST API (připraveno pro Swagger)
- 🐳 Docker pro snadný vývoj a nasazení
- 🔄 Automatické migrace DB a seed dat
- 🖥️ Moderní, responzivní frontend v češtině
- 🍪 Lišta cookies s kategoriemi (nezbytné, preference, analytické, marketingové)

## 🚀 Rychlý start

### Předpoklady

- [Docker](https://docs.docker.com/get-docker/)
- [Docker Compose](https://docs.docker.com/compose/install/)

### Spuštění přes Docker

1) Klonujte repozitář:
```bash
git clone <repository-url>
cd fotbal-club
```

2) Spusťte aplikaci:
```bash
docker-compose up -d
```

Spustí se backend API, databáze PostgreSQL, proběhnou migrace a nastartuje frontend.

3) Přístup do aplikace:
- Frontend: http://localhost:3000
- Backend API: http://localhost:8080
- Swagger (pokud povolíte): http://localhost:8080/swagger/index.html

4) První spuštění:
- Otevřete http://localhost:3000 – budete přesměrováni na průvodce nastavením (vytvoření admin účtu, nastavení klubu a barev).

## 📂 Struktura projektu

```
fotbal-club/
├── frontend/           # React frontend
├── internal/           # Backend
│   ├── config/         # Konfigurace
│   ├── controllers/    # HTTP kontrolery
│   ├── middleware/     # Middleware (auth, admin)
│   └── models/         # DB modely
├── pkg/                # Znovupoužitelné balíčky (logger, utils)
├── database/           # Migrace
├── uploads/            # Nahrané soubory
├── cache/              # Cache (prefetch)
├── static/             # Statická aktiva
├── docker-compose.yml  # Docker Compose
└── main.go             # Vstupní bod aplikace
```

## 🔧 Konfigurace

Zkopírujte `.env.example` na `.env` a upravte:

```bash
cp .env.example .env
```

Klíčové proměnné:
- `JWT_SECRET` – tajný klíč pro JWT (změňte pro produkci)
- `DATABASE_URL` – připojení na PostgreSQL
- `UPLOAD_DIR` – cílová složka pro uploady (výchozí `./uploads`)
- `MAX_UPLOAD_SIZE` – max. velikost souboru v bajtech
- `ALLOWED_ORIGINS` – povolené originy pro CORS (čárkou oddělené)
- `CONTACT_EMAIL`, `ADMIN_EMAIL`, `SMTP_*` – e‑mailová konfigurace

Frontend (`frontend/.env`):
- `REACT_APP_API_URL` – např. `http://localhost:8080/api/v1`
- `REACT_APP_API_BASE_URL` – alternativa (bez `/api`), např. `http://localhost:8080` (frontend automaticky připojí `/api/v1`)
- `REACT_APP_FACR_API_BASE_URL` – výchozí `http://localhost:8080/api/facr`
- `REACT_APP_FACR_CACHE_TTL` – TTL cache v ms (výchozí 3600000)

Poznámky k API URL na frontendu:

- Pokud zadáte pouze origin (např. `REACT_APP_API_BASE_URL=http://localhost:8080`), klient `frontend/src/services/api.ts` automaticky doplní suffix `/api/v1`.
- Při běhu přes Docker Compose se SPA vykresluje v prohlížeči hostitele. Proto musí být URL k backendu prohlížečem dosažitelná (použijte `http://localhost:8080`, nikoli název kontejneru jako `http://backend:8080`).

## 🛠 Lokální vývoj (bez Dockeru)

1) Závislosti backendu:
```bash
go mod download
```

2) Migrace a seed:
```bash
make migrate
make seed
```

3) Backend:
```bash
make run
```

4) Frontend:
```bash
cd frontend
npm install
npm start
```

## 🔒 Bezpečnost a zásady

- Backend přidává hlavičky (CSP, X-Content-Type-Options, X-Frame-Options, Referrer-Policy).
- JWT token je očekáván v `Authorization: Bearer <token>`.
- Middleware `JWTAuth` ověřuje token, načte uživatele a ukládá do kontextu `user`, `userID`, `userRole` a `claims`.
- Upload endpoint validuje MIME typy a velikost souboru; obrázky JPEG/PNG se komprimují.
- Lišta cookies umožňuje volbu kategorií; rozhodnutí je uloženo v `localStorage` pod klíčem `cookie_consent` a vyvolá událost `cookie-consent-change`.

## 🧭 Frontend – hlavní části

- Veřejné stránky: `Home`, `Blog`, `Článek`, `O klubu`, `Kalendář`, `Tabulky`, `Sponzoři`, `Kontakt`, právní stránky.
- Admin: přístup přes `/admin` (chráněno), layout s postranním menu, hlavičkou a pomocníkem.
- Na stránce `Admin Dashboard` je vložena komponenta `AdminHelp` s rychlými tipy.

## 🧪 Testování

```bash
make test
```

Krytí:
```bash
go test -coverprofile=coverage.out ./... && go tool cover -html=coverage.out
```

## 🚀 Nasazení

### Build Docker image
```bash
docker build -t fotbal-club .
```

### Spuštění kontejneru
```bash
docker run -d \
  --name fotbal-club \
  -p 8080:8080 \
  --env-file .env \
  fotbal-club
```

Nahrané soubory jsou servírovány z `/uploads` (viz `main.go`).

## 📚 API

Základní přehled viz `DOCS/api.md`. Po zapnutí Swaggeru:
- Swagger UI: http://localhost:8080/swagger/index.html
- OpenAPI JSON: http://localhost:8080/swagger/doc.json

## 📖 Dokumentace

Veškerá dokumentace projektu byla přesunuta do složky **`DOCS/`** pro lepší organizaci.

**Hlavní dokumenty:**
- **[DOCS/DOKUMENTACE.md](./DOCS/DOKUMENTACE.md)** - Kompletní česká dokumentace (100KB+)
- **[DOCS/README.md](./DOCS/README.md)** - Index všech dokumentů s kategoriemi
- **[DOCS/QUICK_START_10_10.md](./DOCS/QUICK_START_10_10.md)** - Rychlý start

**Kategorie dokumentace:**
- 🎨 MyUIbrix Visual Editor (Elementor)
- ⚽ Sparta Elements (nové!)
- 🗺️ Mapy a lokace
- 🧭 Navigační systém
- 📊 Analytika & tracking
- 📰 Správa obsahu
- 🎟️ Aktivity & události
- ⚽ Zápasy & týmy
- 📧 Newsletter
- 📞 Kontakty
- 🎨 Sponzoři & bannery
- 📊 Ankety
- 🔧 Admin & systém
- 🚀 Performance & zabezpečení

Více informací v **[DOCS/README.md](./DOCS/README.md)**

## 📄 Licence

MIT – viz soubor [LICENSE](LICENSE).