docs: add YouTube Operations Hub extensions design

Design for 4 extensions: YouTube API Integration (metrics sync,
video upload, comment import), Analytics Dashboard (comparison,
trends, ROI), Workflow Automation (auto-status, deadline reminders,
capacity planning), Content Calendar (FullCalendar, drag & drop,
conflict detection).

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

docs/plans/2026-02-14-youtube-operations-hub-extensions-design.md

@@ -0,0 +1,481 @@
+# YouTube Operations Hub - Erweiterungen Design
+
+**Datum:** 2026-02-14
+**Status:** Genehmigt
+**Geschätzter Aufwand:** ~80 Stunden (4 Phasen)
+
+## Zusammenfassung
+
+Implementierung der 4 Erweiterungsmöglichkeiten aus dem YouTube Operations Hub (Abschnitt 11):
+
+1. **YouTube API Integration** - Metriken-Sync, Video-Upload, Kommentar-Import
+2. **Analytics Dashboard** - Performance-Vergleich, Trend-Analyse, ROI
+3. **Workflow-Automatisierung** - Status-Änderungen, Deadline-Erinnerungen, Kapazitätsplanung
+4. **Content-Kalender** - Visuelle Übersicht, Drag & Drop, Konflikt-Erkennung
+
+## Bestandsanalyse
+
+### Vorhandene Infrastruktur
+- **YouTubeClient** (`src/lib/integrations/youtube/YouTubeClient.ts`) - nur Comment-Methoden
+- **OAuth 2.0** - funktioniert, Scopes: `youtube.readonly`, `youtube.force-ssl`, `youtube`
+- **YouTubeContent Collection** - `performance.*` Felder existieren (nie befüllt)
+- **YouTubeChannels Collection** - `currentMetrics.*` Felder (nur bei OAuth-Connect aktualisiert)
+- **BullMQ** - Email/PDF-Worker laufen, Queue-Infrastruktur vorhanden
+- **Recharts 3.6.0** - bereits installiert
+- **YouTubeAnalyticsDashboard** - existiert mit 4 Tabs (Daten nur aus CMS)
+- **CommentsSyncService** - importiert nur Top-Level-Kommentare
+
+### Fehlende Komponenten
+- `youtube.videos.list()` API-Aufrufe (Metriken)
+- `youtube.videos.insert()` API-Aufrufe (Upload)
+- `youtubeAnalytics` API v2 (detaillierte Analytics)
+- OAuth-Scopes: `youtube.upload`, `yt-analytics.readonly`
+- Reply-Thread-Import bei Kommentaren
+- Deadline-Scheduler/Cron
+- Kalender-Bibliothek (FullCalendar)
+
+---
+
+## Phase 1: YouTube API Integration (~30h)
+
+### 1.1 Metriken-Sync Service
+
+**Neue Datei:** `src/lib/integrations/youtube/VideoMetricsSyncService.ts`
+
+```
+YouTubeClient.getVideoStatistics(videoIds[])
+    → youtube.videos.list({ part: 'statistics,snippet', id: videoIds })
+    → Batch-Update: YouTubeContent.performance.* Felder
+```
+
+**Sync-Strategie:**
+- Batch-Verarbeitung: Max 50 Video-IDs pro API-Call (YouTube-Limit)
+- Inkrementeller Sync: Nur Videos mit Status `published` oder `tracked`
+- Frequenz: Alle 6 Stunden via Cron (`/api/cron/youtube-metrics-sync`)
+- Quota-Budget: ~300 Einheiten/Tag (bei 150 Videos = 3 Calls x 100 Quota)
+
+**Befüllte Felder in YouTubeContent:**
+| Feld | API-Quelle | Typ |
+|------|-----------|-----|
+| `performance.views` | `statistics.viewCount` | number |
+| `performance.likes` | `statistics.likeCount` | number |
+| `performance.comments` | `statistics.commentCount` | number |
+| `performance.estimatedMinutesWatched` | Analytics API | number |
+| `performance.averageViewDuration` | Analytics API | number |
+| `performance.ctr` | Analytics API | number |
+| `performance.impressions` | Analytics API | number |
+| `performance.subscribersGained` | Analytics API | number |
+
+**Neue Datei:** `src/lib/integrations/youtube/ChannelMetricsSyncService.ts`
+
+```
+YouTubeClient.getChannelStatistics(channelId)
+    → youtube.channels.list({ part: 'statistics', id: channelId })
+    → Update: YouTubeChannels.currentMetrics.* Felder
+```
+
+### 1.2 Erweiterter Kommentar-Import
+
+**Änderung:** `src/lib/integrations/youtube/CommentsSyncService.ts`
+
+Erweiterungen:
+- Reply-Threads importieren (youtube.comments.list für parentId)
+- `parentComment` Relationship-Feld in CommunityInteractions nutzen
+- Thread-Tiefe: Max 2 Ebenen (YouTube-Limit)
+- Neue Kommentare seit letztem Sync (publishedAfter-Filter)
+
+### 1.3 Video-Upload Service
+
+**Neue Datei:** `src/lib/integrations/youtube/VideoUploadService.ts`
+
+**Upload-Flow:**
+```
+Admin UI "Veröffentlichen" Button
+    → API Route POST /api/youtube/upload
+    → BullMQ Job in youtube-upload Queue
+    → VideoUploadWorker:
+        1. Media-Datei aus Payload laden
+        2. youtube.videos.insert() mit Resumable Upload
+        3. YouTubeContent Status → 'published'
+        4. YouTube-Video-ID speichern
+        5. Notification erstellen
+```
+
+**Neue Dateien:**
+- `src/lib/queue/jobs/youtube-upload-job.ts`
+- `src/lib/queue/workers/youtube-upload-worker.ts`
+- `src/app/(payload)/api/youtube/upload/route.ts`
+
+**OAuth-Scope hinzufügen:**
+- `src/lib/integrations/youtube/oauth.ts`: Scope `https://www.googleapis.com/auth/youtube.upload`
+
+**Upload-Metadaten (aus YouTubeContent-Feldern):**
+- `youtube.metadata.title` → Video-Titel
+- `youtube.metadata.description` → Beschreibung
+- `youtube.metadata.tags` → Tags
+- `youtube.metadata.categoryId` → Kategorie
+- `youtube.metadata.visibility` → public/unlisted/private
+- `youtube.metadata.language` → Sprache
+- `scheduledPublishDate` → Geplante Veröffentlichung
+
+**Quota-Tracking:**
+- Neue Collection oder Felder in YouTubeChannels: `quotaUsedToday`, `quotaResetAt`
+- Video-Upload: ~1.600 Quota-Einheiten pro Upload
+- Tägliches Limit: 10.000 Einheiten (Standard)
+- Warnung bei >80% Auslastung via NotificationService
+
+### 1.4 Cron-Jobs
+
+| Endpoint | Schedule | Beschreibung |
+|----------|----------|--------------|
+| `/api/cron/youtube-metrics-sync` | `0 */6 * * *` | Video-Metriken alle 6h |
+| `/api/cron/youtube-channel-sync` | `0 4 * * *` | Kanal-Statistiken täglich |
+
+**Änderung:** `vercel.json` - Neue Cron-Einträge
+
+---
+
+## Phase 2: Analytics Dashboard (~16h)
+
+### 2.1 YouTube Analytics API Client
+
+**Neue Datei:** `src/lib/integrations/youtube/YouTubeAnalyticsClient.ts`
+
+```typescript
+// Methoden:
+getVideoAnalytics(videoId, startDate, endDate, metrics[])
+getChannelAnalytics(channelId, startDate, endDate, metrics[])
+getTopVideos(channelId, metric, limit)
+getDemographics(channelId, startDate, endDate)
+```
+
+**OAuth-Scope hinzufügen:**
+- `yt-analytics.readonly` in `src/lib/integrations/youtube/oauth.ts`
+
+### 2.2 Performance-Vergleich Tab
+
+**Erweiterung:** `src/components/admin/YouTubeAnalyticsDashboard.tsx`
+
+Neuer Tab "Vergleich" mit:
+- Multi-Select für Videos (max 5)
+- Metriken-Auswahl: Views, Likes, CTR, Watch Time
+- Zeitreihen-Chart (Recharts LineChart mit mehreren Serien)
+- Normalisierte Ansicht (prozentual) für unterschiedliche Größenordnungen
+- Tabelle mit Delta-Werten
+
+### 2.3 Trend-Analyse Tab
+
+Neuer Tab "Trends" mit:
+- Automatische Trend-Erkennung (gleitender Durchschnitt, 7/30 Tage)
+- Wachstumsrate pro Metrik (WoW, MoM)
+- Prognose-Linie (lineare Regression, nächste 30 Tage)
+- Saisonalitäts-Erkennung (Wochentag-Heatmap)
+- Best/Worst Performer Ranking
+
+**Berechnung im Backend:** `src/app/(payload)/api/youtube/analytics/route.ts`
+- Neuer Query-Parameter: `tab=trends`
+- Berechnungen serverseitig für Performance
+
+### 2.4 ROI-Berechnung Tab
+
+Neuer Tab "ROI" mit:
+- Neue Felder in YouTubeContent:
+  - `costs.estimatedProductionHours` (number)
+  - `costs.estimatedProductionCost` (number, EUR)
+  - `costs.estimatedRevenue` (number, EUR - manuell oder via Analytics API)
+- ROI-Formel: `(Revenue - Cost) / Cost * 100`
+- CPV (Cost per View): `Cost / Views`
+- Revenue per View: `Revenue / Views`
+- Break-Even-Analyse
+- Chart: Kosten vs. Einnahmen über Zeit
+
+**Keine separate Collection** - pragmatischer Ansatz mit Feldern direkt in YouTubeContent.
+
+### 2.5 API-Erweiterungen
+
+**Änderung:** `src/app/(payload)/api/youtube/analytics/route.ts`
+
+Neue Query-Parameter:
+- `tab=comparison&videoIds=id1,id2,id3`
+- `tab=trends&metric=views&period=30d`
+- `tab=roi&channelId=X`
+
+---
+
+## Phase 3: Workflow-Automatisierung (~14h)
+
+### 3.1 Automatische Status-Übergänge
+
+**Neue Datei:** `src/hooks/youtubeContent/autoStatusTransitions.ts`
+
+Regeln (konfigurierbar):
+| Bedingung | Aktion |
+|-----------|--------|
+| Alle Checklisten-Items erledigt | Status → nächste Phase |
+| Video auf YouTube veröffentlicht | Status → `published` |
+| 7 Tage nach Veröffentlichung | Status → `tracked` |
+| Upload-Job abgeschlossen | Status → `published` |
+
+**Hook-Typ:** `afterChange` auf YouTubeContent
+- Prüft Checklisten-Completion via YtTasks
+- Erstellt Notification bei automatischem Übergang
+- Audit-Log-Eintrag
+
+### 3.2 Deadline-Erinnerungen
+
+**Neue Datei:** `src/app/(payload)/api/cron/deadline-reminders/route.ts`
+
+**Schedule:** `0 9 * * 1-5` (Mo-Fr 9:00 UTC)
+
+**Prüfungen:**
+1. `editDeadline` in 2 Tagen → Erinnerung
+2. `editDeadline` überschritten → Warnung (Priorität: high)
+3. `reviewDeadline` in 1 Tag → Erinnerung
+4. `scheduledPublishDate` in 3 Tagen → Erinnerung
+5. Batch-Deadline (`YtBatches.targetCompletionDate`) in 3 Tagen → Erinnerung
+
+**Notification-Typen:** Nutzt bestehendes `NotificationService` + `YtNotifications`:
+- `task_due` - Deadline naht
+- `task_overdue` - Deadline überschritten
+- Neuer Typ: `deadline_warning` (3 Tage vorher)
+
+**Zustellung:**
+- YtNotifications Collection (Admin-Inbox)
+- Optional: E-Mail via AlertService (konfigurierbar pro User)
+
+### 3.3 Team-Kapazitätsplanung
+
+**Neue Datei:** `src/app/(payload)/api/youtube/capacity/route.ts`
+
+**Datenquellen:**
+- YtTasks (zugewiesene Aufgaben pro User)
+- YouTubeContent (Videos in Produktion pro Assignee)
+- YtBatches (geplante Batches)
+
+**Berechnung:**
+```
+Pro Team-Mitglied:
+  - Aktive Tasks (status: in_progress, pending)
+  - Geschätzte Stunden (aus Tasks estimatedHours)
+  - Videos in Pipeline (zugewiesen, nicht abgeschlossen)
+  - Auslastung = aktive Stunden / verfügbare Stunden (40h/Woche default)
+```
+
+**UI-Komponente:** Integration in YouTubeAnalyticsDashboard
+- Neuer Tab "Team" oder Widget im bestehenden "Pipeline" Tab
+- Balkendiagramm: Auslastung pro Person
+- Farbcodierung: Grün (<70%), Gelb (70-90%), Rot (>90%)
+- Warnung bei Überbelastung via NotificationService
+
+---
+
+## Phase 4: Content-Kalender (~20h)
+
+### 4.1 Bibliothek & Setup
+
+**Neue Dependency:** `@fullcalendar/react` + Plugins
+- `@fullcalendar/core`
+- `@fullcalendar/daygrid`
+- `@fullcalendar/timegrid`
+- `@fullcalendar/interaction` (Drag & Drop)
+- `@fullcalendar/list`
+
+### 4.2 Kalender API
+
+**Neue Datei:** `src/app/(payload)/api/youtube/calendar/route.ts`
+
+**GET** - Events abrufen:
+```
+?channelId=X&start=2026-01-01&end=2026-02-28
+```
+
+**Response-Format:**
+```typescript
+{
+  events: [{
+    id: string,           // YouTubeContent ID
+    title: string,        // Video-Titel
+    start: string,        // scheduledPublishDate (ISO)
+    end: string,          // scheduledPublishDate + 1h
+    color: string,        // Channel branding.primaryColor
+    extendedProps: {
+      status: string,
+      contentType: 'video' | 'short',
+      channelName: string,
+      seriesName?: string,
+      hasConflict: boolean,
+    }
+  }]
+}
+```
+
+**PATCH** - Datum per Drag & Drop ändern:
+```
+{ contentId: string, newDate: string }
+```
+- Validierung: Nur Videos mit Status vor `published`
+- Konflik-Prüfung vor Speicherung
+- Audit-Log-Eintrag
+
+### 4.3 Content-Kalender Komponente
+
+**Neue Datei:** `src/components/admin/ContentCalendar.tsx`
+
+Features:
+- Monats-, Wochen-, Tages-, Listen-Ansicht
+- Farbcodierung nach Kanal (`branding.primaryColor`)
+- Status-Icons auf Events (Draft, Review, Ready, Published)
+- Tooltip mit Video-Details bei Hover
+- Click → Navigation zum YouTubeContent-Dokument
+
+**Neue Datei:** `src/components/admin/ContentCalendar.module.scss`
+- BEM-Konventionen
+- Payload CSS-Variablen für Dark/Light Mode
+- Responsive Layout
+
+### 4.4 Drag & Drop
+
+FullCalendar's eingebautes `interaction` Plugin:
+- Event-Verschiebung → PATCH API-Call
+- Bestätigungsdialog vor Speicherung
+- Undo-Möglichkeit (vorheriges Datum merken)
+- Nur für Videos vor Status `published`
+
+### 4.5 Konflikt-Erkennung
+
+**Neue Datei:** `src/lib/youtube/ConflictDetectionService.ts`
+
+**Regeln:**
+1. **Zeitkonflikt:** Zwei Videos am selben Tag auf demselben Kanal
+2. **Serien-Konflikt:** Serien-Folge vor vorheriger Folge geplant
+3. **Frequenz-Konflikt:** Mehr Videos als `publishingSchedule.longformPerWeek` / `shortsPerWeek`
+4. **Wochenend-Warnung:** Video am Wochenende geplant (konfigurierbar)
+
+**Anzeige:**
+- Rote Markierung auf Kalender-Events mit Konflikten
+- Warnung-Banner im Kalender
+- Konflikte als Tooltip auf betroffenen Events
+- API-Response enthält `hasConflict: boolean` pro Event
+
+### 4.6 Admin View Registrierung
+
+**Änderung:** `src/payload.config.ts`
+
+Neuer Custom View: `/admin/content-calendar`
+- Registrierung analog zu `YouTubeAnalyticsDashboard`
+- Navigation-Link via `afterNavLinks`
+
+---
+
+## Technische Querschnittsthemen
+
+### OAuth-Scope-Erweiterungen
+
+**Datei:** `src/lib/integrations/youtube/oauth.ts`
+
+Neue Scopes:
+```typescript
+const SCOPES = [
+  'https://www.googleapis.com/auth/youtube.readonly',
+  'https://www.googleapis.com/auth/youtube.force-ssl',
+  'https://www.googleapis.com/auth/youtube',
+  'https://www.googleapis.com/auth/youtube.upload',        // NEU
+  'https://www.googleapis.com/auth/yt-analytics.readonly', // NEU
+]
+```
+
+**Hinweis:** Bestehende OAuth-Tokens müssen nach Scope-Änderung neu autorisiert werden. Re-Auth-Flow in Admin UI einbauen.
+
+### Quota-Management
+
+YouTube Data API v3 Quota: 10.000 Einheiten/Tag (Standard)
+
+| Operation | Kosten | Häufigkeit | Tägliche Kosten |
+|-----------|--------|------------|-----------------|
+| videos.list (50 IDs) | 100 | 4x/Tag | 400 |
+| channels.list | 100 | 1x/Tag | 100 |
+| commentThreads.list | 100 | 4x/Tag | 400 |
+| comments.list (Replies) | 100 | 4x/Tag | 400 |
+| videos.insert (Upload) | 1.600 | ~2/Tag | 3.200 |
+| **Gesamt** | | | **~4.500** |
+
+Budget: ~45% des Tageslimits. Spielraum für manuelle API-Calls.
+
+### Migration
+
+Neue Felder in YouTubeContent (Phase 2 ROI):
+```sql
+ALTER TABLE youtube_content
+  ADD COLUMN IF NOT EXISTS "costs_estimated_production_hours" numeric,
+  ADD COLUMN IF NOT EXISTS "costs_estimated_production_cost" numeric,
+  ADD COLUMN IF NOT EXISTS "costs_estimated_revenue" numeric;
+```
+
+### Error Handling
+
+Alle neuen Services folgen bestehendem Pattern:
+- Try/Catch mit strukturiertem Logging (SafeLogger)
+- YouTube API-Fehler: Retry mit exponential Backoff (max 3)
+- Quota-Exceeded (403): Job delayed auf nächsten Tag
+- Token-Expired (401): Auto-Refresh via TokenRefreshService
+- Upload-Fehler: Resumable Upload mit Checkpoint
+
+---
+
+## Abhängigkeiten zwischen Phasen
+
+```
+Phase 1 (API) ──────────► Phase 2 (Analytics)
+    │                          │
+    │ Metriken-Daten           │ Dashboard-Patterns
+    │ verfügbar                │
+    ▼                          ▼
+Phase 3 (Workflow) ──────► Phase 4 (Kalender)
+    │                          │
+    │ Status-Logik             │ Scheduling-Daten
+    │ Deadline-System          │ Konflikt-Erkennung
+    └──────────────────────────┘
+```
+
+Phase 1 muss zuerst abgeschlossen werden (Datengrundlage für Analytics).
+Phasen 3 und 4 können teilweise parallel entwickelt werden.
+
+---
+
+## Neue Dateien (Übersicht)
+
+### Phase 1
+- `src/lib/integrations/youtube/VideoMetricsSyncService.ts`
+- `src/lib/integrations/youtube/ChannelMetricsSyncService.ts`
+- `src/lib/integrations/youtube/VideoUploadService.ts`
+- `src/lib/queue/jobs/youtube-upload-job.ts`
+- `src/lib/queue/workers/youtube-upload-worker.ts`
+- `src/app/(payload)/api/youtube/upload/route.ts`
+- `src/app/(payload)/api/cron/youtube-metrics-sync/route.ts`
+- `src/app/(payload)/api/cron/youtube-channel-sync/route.ts`
+
+### Phase 2
+- `src/lib/integrations/youtube/YouTubeAnalyticsClient.ts`
+
+### Phase 3
+- `src/hooks/youtubeContent/autoStatusTransitions.ts`
+- `src/app/(payload)/api/cron/deadline-reminders/route.ts`
+- `src/app/(payload)/api/youtube/capacity/route.ts`
+
+### Phase 4
+- `src/components/admin/ContentCalendar.tsx`
+- `src/components/admin/ContentCalendar.module.scss`
+- `src/lib/youtube/ConflictDetectionService.ts`
+- `src/app/(payload)/api/youtube/calendar/route.ts`
+
+### Geänderte Dateien
+- `src/lib/integrations/youtube/YouTubeClient.ts` (neue Methoden)
+- `src/lib/integrations/youtube/oauth.ts` (neue Scopes)
+- `src/lib/integrations/youtube/CommentsSyncService.ts` (Reply-Threads)
+- `src/collections/YouTubeContent.ts` (ROI-Felder)
+- `src/app/(payload)/api/youtube/analytics/route.ts` (neue Tabs)
+- `src/components/admin/YouTubeAnalyticsDashboard.tsx` (neue Tabs)
+- `src/lib/queue/queue-service.ts` (youtube-upload Queue)
+- `src/payload.config.ts` (Content Calendar View)
+- `vercel.json` (neue Cron-Jobs)
+- `package.json` (FullCalendar Dependencies)