MyClub/DOCS/QUICK_START_ANALYTICS.md

# Rychlý start - Analytika v dashboardu

## ✅ Co je hotovo

### Backend
- ✅ Analytické endpointy (`/admin/analytics/*`)
- ✅ Model `VisitorEvent` s novými poli
- ✅ Migrace databáze (000009)
- ✅ Privacy-first tracking (hashované IP adresy)
- ✅ Rate limiting pro public endpoint

### Frontend
- ✅ Admin dashboard zobrazuje analytiku
- ✅ Automatický tracking page views
- ✅ Tracking interakcí (clicks, formuláře)
- ✅ Dual tracking (Umami + vlastní backend)
- ✅ Tabulky top stránek a interakcí

## 🚀 Jak spustit

### 1. Migrace databáze

```bash
# V hlavní složce projektu
# Buď nastavit v .env:
RUN_MIGRATIONS=true

# Nebo spustit přímo
go run main.go
```

Migrace automaticky:
- Přidá sloupce `page_path`, `page_name`, `data` do tabulky `visitor_events`
- Vytvoří indexy pro rychlejší queries
- Zkopíruje existující data z `page` do `page_path`

### 2. Spuštění backendu

```bash
go run main.go
```

Server běží na `http://localhost:8080` (nebo váš konfigurovaný port).

### 3. Spuštění frontendu

```bash
cd frontend
npm start
```

Frontend běží na `http://localhost:3000`.

## 📊 Co uvidíte v dashboardu

### Horní statistiky (6 karet)
1. **Uživatelé (admin)** - celkový počet admin uživatelů
2. **Události** - nadcházející události
3. **Články** - celkem a publikované
4. **Zobrazení stránek** - celkový počet page views + dnes
5. **Unikátní návštěvníci** - celkem + tento týden
6. **Zobrazení (týden)** - za posledních 7 dní

### Analytické tabulky (2 karty)

#### Nejnavštěvovanější stránky
| Stránka | Zobrazení | Návštěvníci |
|---------|-----------|-------------|
| /       | 145       | 89          |
| /blog   | 87        | 56          |
| /kontakt| 34        | 28          |

#### Nejčastější interakce (7 dní)
| Element           | Stránka  | Počet |
|-------------------|----------|-------|
| Newsletter button | /        | 45    |
| Contact form      | /kontakt | 23    |

### Widgety
- Návštěvnost (graf za 30 dní)
- Nadcházející zápasy
- Poslední články
- Aktuální scoreboard

## 🧪 Testování

### Otevřete aplikaci
```
http://localhost:3000
```

### Navigujte mezi stránkami
1. Úvodní stránka `/`
2. Blog `/blog`
3. Kontakt `/kontakt`
4. O klubu `/o-klubu`

### Klikejte na tlačítka
- Newsletter subscribe
- Odkazy v menu
- Tlačítka v článcích

### Zkontrolujte admin dashboard
```
http://localhost:3000/admin
```

Po přihlášení byste měli vidět:
- Počet zobrazení stránek se zvyšuje
- V tabulce "Nejnavštěvovanější stránky" se objevují stránky, které jste navštívili
- V tabulce "Nejčastější interakce" se objevují elementy, na které jste klikli

## 🔍 Kontrola databáze

```sql
-- Počet tracked eventů
SELECT event_type, COUNT(*) as count 
FROM visitor_events 
GROUP BY event_type;

-- Poslední page views
SELECT page_path, page_name, created_at 
FROM visitor_events 
WHERE event_type = 'page_view' 
ORDER BY created_at DESC 
LIMIT 10;

-- Top stránky
SELECT page_path, COUNT(*) as views, COUNT(DISTINCT ip_address) as visitors
FROM visitor_events 
WHERE event_type = 'page_view'
GROUP BY page_path 
ORDER BY views DESC 
LIMIT 10;

-- Top interakce za posledních 7 dní
SELECT page, element, COUNT(*) as count
FROM visitor_events 
WHERE event_type IN ('click', 'interaction') 
  AND created_at >= NOW() - INTERVAL '7 days'
GROUP BY page, element 
ORDER BY count DESC 
LIMIT 10;
```

## 📝 Příklady použití v kódu

### Automatický tracking (už funguje)
Page views se trackují automaticky v `App.tsx` pomocí `useUmami` hooku.

### Manuální tracking tlačítka

```typescript
import { trackButtonClick } from '@/utils/umami';

function MyComponent() {
  const handleNewsletterClick = () => {
    trackButtonClick('Newsletter Subscribe Button');
    // ... zbytek logiky
  };

  return (
    <button onClick={handleNewsletterClick}>
      Přihlásit se k odběru
    </button>
  );
}
```

### Tracking formuláře

```typescript
import { trackFormSubmit } from '@/utils/umami';

const handleSubmit = async (values) => {
  try {
    await api.post('/contact', values);
    trackFormSubmit('Contact Form', true);
    toast.success('Odesláno!');
  } catch (error) {
    trackFormSubmit('Contact Form', false);
    toast.error('Chyba při odesílání');
  }
};
```

### Custom tracking

```typescript
import { trackEvent } from '@/utils/umami';

// Track článku
trackEvent('Article View', {
  article_id: article.id,
  article_title: article.title,
  category: article.category
});

// Track video play
trackEvent('Video Play', {
  video_id: video.id,
  video_title: video.title
});

// Track download
trackEvent('Download', {
  file_name: 'rozpis-zapasu.pdf',
  file_type: 'pdf'
});
```

## 🎯 Co dál?

### Doporučené další kroky:

1. **Spusťte aplikaci** a nechte ji běžet pár dní pro sběr dat
2. **Sledujte dashboard** - všimněte si, které stránky jsou nejpopulárnější
3. **Přidejte tracking** na důležitá tlačítka ve vaší aplikaci
4. **Analyzujte data** - použijte insights k vylepšení UX

### Volitelné rozšíření:

1. **Grafy v detailní analytice** (`/admin/analytika`)
   - Časové grafy návštěvnosti
   - Rozložení podle dne v týdnu
   - Top articles s trendy

2. **Export dat** - přidat možnost exportu do CSV/Excel

3. **Real-time dashboard** - WebSocket pro live tracking

4. **Heatmapy** - vizuální zobrazení, kam uživatelé klikají

5. **Conversion tracking** - sledování konkrétních cílů (registrace, newsletter, atd.)

## ⚠️ Poznámky

- **Tracking je neblokující** - pokud selže, neovlivní to UX
- **Privacy-first** - IP adresy jsou hashovány, žádné cookies
- **Rate limit** - 120 requestů/minutu na tracking endpoint
- **Performance** - indexy zajišťují rychlé queries i s velkým objemem dat
- **Dual tracking** - data jdou do Umami i vlastní DB současně

## 🐛 Troubleshooting

### Server se nespouští
```bash
# Zkontrolujte porty
netstat -ano | findstr :8080

# Zkontrolujte DB connection
psql -U postgres -d fotbal_club -c "SELECT version();"
```

### Migrace selhaly
```bash
# Zkontrolujte DB připojení v .env
cat .env | grep DB_

# Spusťte migrace manuálně
cd database
migrate -path migrations -database "your_connection_string" up
```

### Tracking nefunguje
1. Otevřete Developer Tools (F12)
2. Zkontrolujte Network tab - měl by být POST na `/api/v1/analytics/track`
3. Zkontrolujte Console - měly by být debug zprávy
4. Ověřte, že backend běží a odpovídá

### Data se nezobrazují
1. Zkontrolujte, že máte data v DB (SQL queries výše)
2. Obnovte stránku dashboardu (F5)
3. Zkontrolujte browser console pro chyby
4. Ověřte, že jste přihlášení jako admin

## 📞 Podpora

Pokud narazíte na problémy:
1. Zkontrolujte tento dokument
2. Přečtěte si `ANALYTICS_INTEGRATION.md` pro detaily
3. Zkontrolujte DB logs a browser console
4. Otevřete issue na GitHubu (pokud používáte)

---

**Vše hotovo! 🎉 Analytika je připravena k použití.**