MyClub/DOCS/ANALYTICS_INTEGRATION.md

# Integrace analytiky do dashboardu

## Co bylo provedeno

### 1. Frontend změny

#### Analytické služby (`frontend/src/services/analyticsService.ts`)
- Přidány nové funkce pro práci s analytikou:
  - `getAnalyticsOverview()` - získání celkového přehledu (page views, visitors)
  - `getTopPages()` - nejnavštěvovanější stránky
  - `getTopArticles()` - nejčtenější články
  - `getTopInteractions()` - nejčastější interakce uživatelů
  - `trackEvent()` - odeslání tracking eventu na backend

#### Oprava trackingu (`frontend/src/hooks/useUmami.ts`)
- Hook nyní automaticky trackuje změny stránek (page views)
- Tracking probíhá **současně** do Umami i backend analytiky
- Využívá `useLocation` z React Router pro automatické sledování navigace

#### Utility funkce (`frontend/src/utils/umami.ts`)
- Všechny tracking funkce (`trackButtonClick`, `trackFormSubmit`, atd.) nyní posílají data:
  1. Do Umami (pokud je nakonfigurováno)
  2. Do backend analytiky
- `trackButtonClick` nyní trackuje i jako "interakci" pro backend analytics

#### Admin Dashboard (`frontend/src/pages/admin/AdminDashboardPage.tsx`)
- **Nové statistiky** v horní části:
  - Zobrazení stránek (celkem)
  - Unikátní návštěvníci
  - Zobrazení za týden
  - Zobrazení dnes
- **Dvě nové analytické tabulky**:
  - Nejnavštěvovanější stránky (top 5)
  - Nejčastější interakce za 7 dní (top 5)
- Odkazy na detailní stránku analytiky (`/admin/analytika`)

### 2. Backend změny

#### Model (`internal/models/visitor_event.go`)
Přidána nová pole do `VisitorEvent`:
- `PagePath` - úplná cesta stránky
- `PageName` - lidsky čitelný název stránky
- `Data` - generické JSONB pole pro libovolná event data

#### Controller (`internal/controllers/analytics_controller.go`)
- Automatická synchronizace `Page` a `PagePath` polí
- Přidán tracking `Referrer` hlavičky
- Zachování IP adresy v hashované podobě pro ochranu soukromí

#### Migrace (`database/migrations/000009_*.sql`)
- Přidání nových sloupců do tabulky `visitor_events`
- Vytvoření indexů pro rychlejší queries:
  - `idx_visitor_events_page_path`
  - `idx_visitor_events_created_at`
  - `idx_visitor_events_event_type_created_at`

## Jak spustit

### 1. Spuštění migrací

```bash
# Nastavte RUN_MIGRATIONS=true v .env nebo spusťte:
go run main.go
```

Nebo manuálně:
```bash
cd database
migrate -path migrations -database "postgresql://user:pass@localhost:5432/fotbal_club?sslmode=disable" up
```

### 2. Restart backendu

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

### 3. Frontend

Frontend se automaticky připojí k novým endpointům. Pokud je frontend spuštěný, stačí obnovit stránku.

```bash
cd frontend
npm start
```

## Testování

### Test page view tracking
1. Otevřete aplikaci v prohlížeči
2. Navigujte mezi různými stránkami
3. V admin dashboardu (`/admin`) zkontrolujte:
   - Počet zobrazení stránek
   - Seznam nejnavštěvovanějších stránek

### Test interaction tracking
1. Klikněte na různé tlačítka v aplikaci
2. V dashboardu zkontrolujte sekci "Nejčastější interakce"
3. Měly by se tam zobrazit elementy, na které jste klikali

### Kontrola dat v databázi

```sql
-- Zobrazit poslední tracked eventy
SELECT event_type, page_path, page_name, created_at 
FROM visitor_events 
ORDER BY created_at DESC 
LIMIT 10;

-- Počet page views
SELECT COUNT(*) FROM visitor_events WHERE event_type = 'page_view';

-- Nejnavštěvovanější stránky
SELECT page_path, COUNT(*) as views 
FROM visitor_events 
WHERE event_type = 'page_view' 
GROUP BY page_path 
ORDER BY views DESC 
LIMIT 10;
```

## API Endpointy

### Veřejné
- `POST /api/v1/analytics/track` - tracking eventů (rate-limited)

### Admin (vyžaduje autentizaci)
- `GET /api/v1/admin/analytics/overview` - celkový přehled
- `GET /api/v1/admin/analytics/top-pages?limit=10` - top stránky
- `GET /api/v1/admin/analytics/top-articles?limit=10` - top články
- `GET /api/v1/admin/analytics/top-interactions?days=7&limit=10` - top interakce

## Použití v kódu

### Tracking page view (automaticky)
Page views se trackují automaticky při změně URL pomocí `useUmami` hooku v `App.tsx`.

### Tracking tlačítka
```typescript
import { trackButtonClick } from '@/utils/umami';

const handleClick = () => {
  trackButtonClick('Název tlačítka', '/aktualni/cesta');
  // ... zbytek logiky
};
```

### Tracking formuláře
```typescript
import { trackFormSubmit } from '@/utils/umami';

const handleSubmit = async (data) => {
  try {
    await submitForm(data);
    trackFormSubmit('Kontaktní formulář', true);
  } catch (error) {
    trackFormSubmit('Kontaktní formulář', false);
  }
};
```

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

trackEvent('Video Play', {
  video_id: '123',
  video_title: 'Góly týdne'
});
```

## Poznámky

- **Privacy-first**: IP adresy jsou hashovány pomocí SHA-256 před uložením
- **Dual tracking**: Data se ukládají do vlastní DB i posílají do Umami (pokud je nakonfigurováno)
- **Rate limiting**: Public tracking endpoint je limitován na 120 requestů za minutu
- **Performance**: Tracking requesty neblokují UI, používají `catch` pro tichý fail
- **GDPR**: Sledování je anonymní, žádné cookies, žádné PII (personally identifiable information)

## Troubleshooting

### Tracking nefunguje
1. Zkontrolujte browser console - měly by být pouze `console.debug` zprávy
2. Zkontrolujte Network tab - měl by být POST request na `/api/v1/analytics/track`
3. Ověřte, že backend běží a je dostupný

### Data se nezobrazují v dashboardu
1. Zkontrolujte, že migrace proběhla úspěšně
2. Ověřte data v databázi (viz SQL queries výše)
3. Zkontrolujte browser console pro chyby při načítání dat

### Duplicitní tracking
- To je očekávané chování - data jdou současně do Umami i backend DB
- Pokud chcete vypnout jedno z nich, upravte kód v `useUmami.ts` nebo `umami.ts`