upload

2026-06-03 18:22:57 +00:00 · 2025-10-16 13:32:05 +02:00
commit 12cba639b9
663 changed files with 168914 additions and 0 deletions
@@ -0,0 +1,194 @@
+# 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`