# YouTube Analytics Dashboard - Design

**Datum:** 2026-02-13
**Status:** Approved

## Übersicht

Custom Admin View für YouTube Analytics unter `/admin/youtube-analytics`.
Kombiniertes Dashboard mit 4 Tabs: Performance, Pipeline, Goals, Community.
Channel-Selector + Period-Selector oben. Sidebar Nav-Link im YouTube-Bereich.

## Architektur

### Ansatz
Einzelnes Dashboard mit Tab-Navigation (Ansatz A).
Jeder Tab lädt Daten lazy beim Wechsel über eine gemeinsame API-Route.

### Dateien

```
src/
├── components/admin/
│   ├── YouTubeAnalyticsDashboard.tsx       # Haupt-Component (Client)
│   ├── YouTubeAnalyticsDashboardView.tsx   # Wrapper für Payload Custom View
│   ├── YouTubeAnalyticsDashboard.scss      # BEM-Styling
│   └── YouTubeAnalyticsNavLinks.tsx        # Sidebar Nav-Link Component
├── app/(payload)/api/youtube/
│   └── analytics/route.ts                  # API-Route für alle Tabs
```

### Registrierung (payload.config.ts)

```typescript
admin: {
  components: {
    afterNavLinks: [
      '@/components/admin/CommunityNavLinks#CommunityNavLinks',
      '@/components/admin/YouTubeAnalyticsNavLinks#YouTubeAnalyticsNavLinks',
    ],
    views: {
      TenantDashboard: { ... },
      YouTubeAnalyticsDashboard: {
        Component: '@/components/admin/YouTubeAnalyticsDashboardView#YouTubeAnalyticsDashboardView',
        path: '/youtube-analytics',
      },
    },
  },
},
```

### Datenfluss

```
Browser → YouTubeAnalyticsDashboard (Client Component)
  → fetch('/api/youtube/analytics?tab=X&channel=Y&period=Z')
    → API Route → payload.find() / payload.count() parallel
      → Aggregierte JSON-Response
```

## Tab-Struktur & Metriken

### Tab 1: Performance

**Stat-Cards:**
- Gesamt-Views (Zeitraum) mit Trend vs. Vorperiode
- Gesamt Watch Time (Stunden)
- Durchschnittliche CTR (%)
- Subscriber-Gewinn (Zeitraum)

**Sektionen:**
- Top 5 Videos (nach Views): Thumbnail-Text, Title, Views, CTR, Avg. Retention
- Bottom 5 Videos (nach Views): gleiche Felder
- Engagement-Übersicht: Likes, Comments, Shares aggregiert

### Tab 2: Pipeline

**Stat-Cards:**
- Videos in Produktion (status < published)
- Diese Woche geplant
- Überfällige Aufgaben
- Offene Approvals

**Sektionen:**
- Pipeline-Balken: Visueller Balken mit Anzahl pro Status-Stufe (idea → published)
- Nächste Veröffentlichungen: Liste der scheduled Videos mit Datum
- Überfällige Tasks: Liste mit Assignee, Deadline, Video-Titel

### Tab 3: Goals

**Stat-Cards:**
- Content-Ziel-Fortschritt (z.B. "8/12 Videos")
- Subscriber-Ziel-Fortschritt
- Views-Ziel-Fortschritt
- Gesamt-Zielerreichung (%)

**Sektionen:**
- Monatsziele-Übersicht: Alle Goals mit Progress-Bars (Target vs. Current)
- Custom Goals: User-definierte Metriken aus YtMonthlyGoals

### Tab 4: Community

**Stat-Cards:**
- Unbearbeitete Kommentare
- Sentiment-Verteilung (% positiv)
- Durchschnittliche Antwortzeit
- Eskalationen offen

**Sektionen:**
- Sentiment-Breakdown: Positiv/Neutral/Negativ mit Zähler
- Letzte Interaktionen: 5 neueste unbearbeitete Kommentare
- Top-Themen: Häufigste Topics aus AI-Analyse

## API-Route

**Endpoint:** `GET /api/youtube/analytics`

| Param | Werte | Default |
|-------|-------|---------|
| `tab` | `performance`, `pipeline`, `goals`, `community` | `performance` |
| `channel` | `all` oder Channel-ID | `all` |
| `period` | `7d`, `30d`, `90d` | `30d` |

**Auth:** Cookie-basiert, YouTube-Access Check.
**Response:** Tab-spezifisches JSON. Nur Daten des angeforderten Tabs.

## UI/Styling

- BEM mit `.yt-analytics` Prefix
- Payload CSS-Variablen (`--theme-elevation-*`, `--theme-success-*`, etc.)
- Tab-Bar: Horizontal unter Header, aktiver Tab mit Border-Bottom
- Stat-Cards: 4er Grid mit farbigen Left-Borders (wie TenantDashboard)
- Pipeline-Balken: Horizontal segmentiert, jede Status-Stufe eine Farbe
- Progress-Bars: Success-Color für On-Track, Warning für At-Risk
- Responsive: 2-Spalten Grid auf Mobile, Tabs horizontal scrollbar
- Dark Mode: `.dark .yt-analytics` Overrides

## Datenquellen

| Collection | Verwendung |
|------------|------------|
| YouTubeContent | Performance-Metriken, Pipeline-Status, Veröffentlichungen |
| YouTubeChannels | Channel-Liste für Selector, Subscriber-Count |
| YtMonthlyGoals | Goals-Tab: Target vs. Current |
| YtTasks | Pipeline-Tab: Überfällige Tasks, Workload |
| YtBatches | Pipeline-Tab: Batch-Fortschritt |
| CommunityInteractions | Community-Tab: Sentiment, Antwortzeit, Themen |

## Patterns (aus TenantDashboard)

- `useTenantSelection()` für Tenant-Kontext
- `useState` + `useEffect` + `useCallback` für Daten-Fetching
- `credentials: 'include'` für Auth-Cookies
- Loading/Error States mit Spinner/Error-Box
- Period-Selector als `<select>`
- Refresh-Button mit Spin-Animation