docs: add YouTube Operations Hub documentation

Add comprehensive YouTube feature documentation covering 9 collections, 12 custom API endpoints, 3 cron jobs, admin views, services, hooks, and access control across CLAUDE.md, CLAUDE_REFERENCE.md, and API_ANLEITUNG.md. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-17 18:34:13 +00:00 · 2026-02-14 18:02:59 +00:00 · 2026-02-14 18:02:59 +00:00 · a0ef957a7f
commit a0ef957a7f
parent 7446318bf3
3 changed files with 310 additions and 0 deletions
--- a/CLAUDE.md
+++ b/CLAUDE.md
@ -220,6 +220,7 @@ Deutsch (default) + Englisch. API: `?locale=de|en`. DB: `_locales` Tabellen.
 | Redis Caching | `src/lib/redis.ts` | `docs/CLAUDE_REFERENCE.md` |
 | Backup | `scripts/backup/` | `scripts/backup/README.md` |
 | Community Management | `src/lib/integrations/meta/`, `src/lib/jobs/` | `docs/CLAUDE_REFERENCE.md` |
+| YouTube Operations Hub | `src/lib/youtube/`, API: `/api/youtube/*` | `docs/CLAUDE_REFERENCE.md` |
 | FormSubmissions CRM | `src/collections/FormSubmissionsOverrides.ts` | `docs/CLAUDE_REFERENCE.md` |

 ## Collections (55+)
@ -349,6 +350,9 @@ Deutsch (default) + Englisch. API: `?locale=de|en`. DB: `_locales` Tabellen.
 | `/api/cron/community-sync` | alle 15 Min | Kommentar-Sync (YouTube, Facebook, Instagram) |
 | `/api/cron/token-refresh` | 6:00 + 18:00 UTC | OAuth-Token-Erneuerung |
 | `/api/cron/send-reports` | stündlich | Community-Reports per E-Mail |
+| `/api/cron/youtube-sync` | alle 15 Min | YouTube-Kommentar-Sync |
+| `/api/cron/youtube-channel-sync` | täglich 04:00 UTC | Kanal-Statistiken (Abos, Views) |
+| `/api/cron/youtube-metrics-sync` | alle 6 Stunden | Video-Performance-Metriken |

 Auth: `Authorization: Bearer $CRON_SECRET`

--- a/docs/CLAUDE_REFERENCE.md
+++ b/docs/CLAUDE_REFERENCE.md
@ -429,3 +429,84 @@ curl "https://your-domain/api/cron/token-refresh?dryRun=true" \
 - HEAD-Requests: Status-Header (`X-Sync-Running`, `X-Last-Run`)
 - Bei laufendem Job: HTTP 423 (Locked)
 - Fehlerhafte Tokens → `yt-notifications`
+
+## YouTube Operations Hub
+
+Umfassendes YouTube-Management-System mit Content-Pipeline, Analytics, Kalender und Task-Management.
+
+### Collections (9)
+
+| Slug | Beschreibung |
+|------|--------------|
+| `youtube-channels` | Multi-Kanal-Verwaltung mit OAuth |
+| `youtube-content` | Videos + Shorts mit Status-Pipeline |
+| `yt-series` | Serien mit Branding (Logo, Farben, Playlist) |
+| `yt-notifications` | Handlungsbedarf-System |
+| `yt-tasks` | Aufgaben mit Zuweisung und Fälligkeitsdatum |
+| `yt-batches` | Produktions-Batches mit Ziel-Tracking |
+| `yt-checklist-templates` | Checklisten-Vorlagen (Upload, Produktion, Review) |
+| `yt-monthly-goals` | Monatsziele (Content, Audience, Engagement, Business) |
+| `yt-script-templates` | Skript-Vorlagen pro Kanal/Serie |
+
+### Content-Pipeline Status
+
+`idea` → `script` → `review` → `production` → `editing` → `ready` → `published`
+
+Hooks automatisieren Übergänge und erstellen Tasks bei Statuswechsel.
+
+### Custom API Endpoints
+
+| Methode | Endpoint | Beschreibung | Auth |
+|---------|----------|--------------|------|
+| GET | `/api/youtube/auth` | OAuth-Flow starten (`?socialAccountId=`) | User |
+| GET | `/api/youtube/callback` | OAuth-Callback, Token-Speicherung | Public (State) |
+| POST | `/api/youtube/refresh-token` | Access Token erneuern | User + CSRF |
+| GET | `/api/youtube/dashboard` | Pipeline-Status, Freigaben, Aufgaben | YouTube-Rolle |
+| GET | `/api/youtube/analytics` | Multi-Tab Analytics (`?tab=&channel=&period=`) | YouTube-Rolle |
+| GET | `/api/youtube/calendar` | Content-Kalender mit Konflikterkennung | User |
+| PATCH | `/api/youtube/calendar` | Drag-&-Drop-Umplanung | User |
+| GET | `/api/youtube/capacity` | Team-Kapazität und Auslastung | User |
+| GET | `/api/youtube/my-tasks` | Eigene offene Tasks | YouTube-Rolle |
+| POST | `/api/youtube/complete-task/[id]` | Task als erledigt markieren | Assignee/Manager |
+| POST/GET | `/api/youtube/upload` | Video-Upload via BullMQ-Queue | User |
+| POST | `/api/youtube/thumbnails/bulk` | Bulk-Thumbnail-Download (`?dryRun=true`) | SuperAdmin |
+
+### Cron Jobs
+
+| Endpoint | Schedule | Beschreibung |
+|----------|----------|--------------|
+| `/api/cron/youtube-sync` | alle 15 Min | YouTube-Kommentar-Sync |
+| `/api/cron/youtube-channel-sync` | täglich 04:00 UTC | Kanal-Statistiken (Abos, Views, Videos) |
+| `/api/cron/youtube-metrics-sync` | alle 6 Stunden | Video-Performance-Metriken |
+
+### Admin Views
+
+- **YouTube Analytics Dashboard** (`/admin/views/youtube-analytics`) — 7 Tabs: Performance, Pipeline, Goals, Community, Comparison, Trends, ROI
+- **Content Calendar** (`/admin/views/content-calendar`) — FullCalendar mit Drag-&-Drop und Konflikterkennung
+
+### Services & Utilities
+
+| Datei | Beschreibung |
+|-------|--------------|
+| `src/lib/youtube/ConflictDetectionService.ts` | Erkennt Terminüberschneidungen bei Content-Planung |
+| `src/lib/youtube/analytics-helpers.ts` | Trend-Berechnung, Vergleiche, ROI |
+| `src/lib/youtube/capacity-calculator.ts` | Team-Auslastungsberechnung |
+| `src/lib/youtube/youtubeAccess.ts` | Rollen-basierte Zugriffskontrolle |
+
+### Hooks (Automatisierung)
+
+- **youtubeChannels/downloadChannelImage** — Profilbild automatisch herunterladen
+- **youtubeContent/downloadThumbnail** — Video-Thumbnails automatisch herunterladen
+- **youtubeContent/createTasksOnStatusChange** — Tasks bei Statuswechsel erstellen
+- **youtubeContent/autoStatusTransitions** — Automatische Pipeline-Übergänge
+- **ytTasks/notifyOnAssignment** — Benachrichtigung bei Task-Zuweisung
+
+### Zugriffskontrolle
+
+| Funktion | Beschreibung |
+|----------|--------------|
+| `hasYouTubeAccess()` | Lese-Zugriff (YouTube-Rolle) |
+| `isYouTubeManager()` | Manager-Level (Erstellen, Löschen, Freigaben) |
+| `isYouTubeCreatorOrAbove()` | Creator+ Zugriff |
+| `canAccessAssignedContent()` | Nur zugewiesene Inhalte |
+| `canAccessOwnNotifications()` | Nur eigene Benachrichtigungen |
--- a/docs/anleitungen/API_ANLEITUNG.md
+++ b/docs/anleitungen/API_ANLEITUNG.md
@ -968,6 +968,11 @@ Das System verwendet einen zentralen Rate-Limiter mit Redis-Backend (Fallback au
 | YouTube Content | `youtube-content` | Nein | Videos + Shorts mit Statistiken |
 | YT Series | `yt-series` | Nein | Serien mit Branding (Logo, Farben) |
 | YT Notifications | `yt-notifications` | Nein | Handlungsbedarf-System |
+| YT Tasks | `yt-tasks` | Nein | Aufgaben mit Zuweisung |
+| YT Batches | `yt-batches` | Nein | Produktions-Batches |
+| YT Checklist Templates | `yt-checklist-templates` | Nein | Checklisten-Vorlagen |
+| YT Monthly Goals | `yt-monthly-goals` | Nein | Monatsziele pro Kanal |
+| YT Script Templates | `yt-script-templates` | Nein | Skript-Vorlagen |
 | Social Platforms | `social-platforms` | Nein | Plattform-Konfiguration |
 | Social Accounts | `social-accounts` | Nein | OAuth-Verbindungen |
 | Community Interactions | `community-interactions` | Nein | Kommentare/Nachrichten aller Plattformen |
@ -1188,6 +1193,226 @@ curl "https://pl.porwoll.tech/api/yt-notifications?where[priority][equals]=high"
 | `channel` | relation | Betroffener Kanal |
 | `content` | relation | Betroffenes Video |

+### YT Tasks API (Auth erforderlich)
+
+```bash
+# Alle Tasks
+curl "https://pl.porwoll.tech/api/yt-tasks" \
+  -H "Authorization: JWT your-token"
+
+# Tasks eines Videos
+curl "https://pl.porwoll.tech/api/yt-tasks?where[video][equals]=1" \
+  -H "Authorization: JWT your-token"
+
+# Offene Tasks nach Priorität
+curl "https://pl.porwoll.tech/api/yt-tasks?where[status][not_equals]=done&sort=priority" \
+  -H "Authorization: JWT your-token"
+```
+
+**Felder:**
+
+| Feld | Typ | Beschreibung |
+|------|-----|--------------|
+| `title` | string | Aufgabentitel (lokalisiert) |
+| `description` | textarea | Beschreibung (lokalisiert) |
+| `video` | relation | Zugehöriges Video |
+| `channel` | relation | Kanal (auto-populiert) |
+| `taskType` | select | script_write, script_review, shoot_prep, shoot, edit, graphics, thumbnail, review, upload, track, comments, other |
+| `status` | select | todo, in_progress, blocked, waiting_review, done, cancelled |
+| `priority` | select | urgent, high, normal, low |
+| `assignedTo` | relation | Zugewiesener User |
+| `dueDate` | date | Fälligkeitsdatum |
+| `completedAt` | date | Abschlussdatum (auto) |
+| `completedBy` | relation | Abgeschlossen von (auto) |
+
+### YT Batches API (Auth erforderlich)
+
+```bash
+# Alle Batches
+curl "https://pl.porwoll.tech/api/yt-batches" \
+  -H "Authorization: JWT your-token"
+
+# Batches eines Kanals
+curl "https://pl.porwoll.tech/api/yt-batches?where[channel][equals]=1" \
+  -H "Authorization: JWT your-token"
+```
+
+**Felder:**
+
+| Feld | Typ | Beschreibung |
+|------|-----|--------------|
+| `name` | string | Batch-Name |
+| `channel` | relation | YouTube-Kanal |
+| `status` | select | planning, production, published |
+| `productionPeriodStart` | date | Produktionsbeginn |
+| `productionPeriodEnd` | date | Produktionsende |
+| `targets.shortsTarget` | number | Shorts-Ziel |
+| `targets.longformsTarget` | number | Longform-Ziel |
+| `progress.percentage` | number | Fortschritt in % |
+
+### YT Checklist Templates API (Auth erforderlich)
+
+```bash
+# Alle Templates
+curl "https://pl.porwoll.tech/api/yt-checklist-templates" \
+  -H "Authorization: JWT your-token"
+
+# Nach Typ filtern
+curl "https://pl.porwoll.tech/api/yt-checklist-templates?where[type][equals]=upload" \
+  -H "Authorization: JWT your-token"
+```
+
+**Felder:**
+
+| Feld | Typ | Beschreibung |
+|------|-----|--------------|
+| `name` | string | Template-Name (lokalisiert) |
+| `channel` | relation | Kanal-spezifisch (optional) |
+| `type` | select | upload, production, review, post_publish |
+| `format` | select | all, short, longform |
+| `items` | array | Checklisten-Items (order, task, category, isRequired) |
+| `isDefault` | boolean | Auto-Zuordnung bei neuen Videos |
+
+### YT Monthly Goals API (Auth erforderlich)
+
+```bash
+# Monatsziele eines Kanals
+curl "https://pl.porwoll.tech/api/yt-monthly-goals?where[channel][equals]=1" \
+  -H "Authorization: JWT your-token"
+```
+
+**Felder:**
+
+| Feld | Typ | Beschreibung |
+|------|-----|--------------|
+| `channel` | relation | YouTube-Kanal |
+| `month` | date | Zielmonat |
+| `contentGoals` | group | longformsTarget/Current, shortsTarget/Current |
+| `audienceGoals` | group | subscribersTarget/Current, viewsTarget/Current |
+| `engagementGoals` | group | avgCtrTarget/Current, avgRetentionTarget/Current |
+| `businessGoals` | group | newsletterSignupsTarget/Current, affiliateRevenueTarget/Current |
+
+### YT Script Templates API (Auth erforderlich)
+
+```bash
+# Vorlagen eines Kanals
+curl "https://pl.porwoll.tech/api/yt-script-templates?where[channel][equals]=1" \
+  -H "Authorization: JWT your-token"
+```
+
+**Felder:**
+
+| Feld | Typ | Beschreibung |
+|------|-----|--------------|
+| `name` | string | Vorlagenname (lokalisiert) |
+| `channel` | relation | YouTube-Kanal |
+| `series` | string | Serienname |
+| `format` | select | short (45-60s), longform (8-16 Min) |
+| `description` | textarea | Beschreibung (lokalisiert) |
+
+---
+
+## YouTube Custom API Endpoints
+
+### OAuth & Authentifizierung
+
+```bash
+# OAuth-Flow starten
+curl "https://pl.porwoll.tech/api/youtube/auth?socialAccountId=1" \
+  -H "Authorization: JWT your-token"
+# → Redirect zu Google OAuth
+
+# Token erneuern
+curl -X POST "https://pl.porwoll.tech/api/youtube/refresh-token" \
+  -H "Authorization: JWT your-token" \
+  -H "Content-Type: application/json" \
+  -d '{"socialAccountId": 1}'
+```
+
+### Dashboard & Analytics
+
+```bash
+# Dashboard-Übersicht (Pipeline, Freigaben, Aufgaben)
+curl "https://pl.porwoll.tech/api/youtube/dashboard" \
+  -H "Authorization: JWT your-token"
+
+# Analytics (Tabs: performance, pipeline, goals, community, comparison, trends, roi)
+curl "https://pl.porwoll.tech/api/youtube/analytics?tab=performance&channel=all&period=30d" \
+  -H "Authorization: JWT your-token"
+
+# Video-Vergleich
+curl "https://pl.porwoll.tech/api/youtube/analytics?tab=comparison&videoIds=1,2,3&metric=views" \
+  -H "Authorization: JWT your-token"
+```
+
+### Content Calendar
+
+```bash
+# Kalender-Events abrufen (FullCalendar-kompatibel)
+curl "https://pl.porwoll.tech/api/youtube/calendar?start=2026-02-01&end=2026-02-28&channelId=all" \
+  -H "Authorization: JWT your-token"
+
+# Content per Drag-&-Drop umplanen
+curl -X PATCH "https://pl.porwoll.tech/api/youtube/calendar" \
+  -H "Authorization: JWT your-token" \
+  -H "Content-Type: application/json" \
+  -d '{"contentId": 1, "newDate": "2026-02-20T10:00:00Z"}'
+```
+
+### Tasks & Kapazität
+
+```bash
+# Eigene offene Tasks
+curl "https://pl.porwoll.tech/api/youtube/my-tasks" \
+  -H "Authorization: JWT your-token"
+
+# Task als erledigt markieren
+curl -X POST "https://pl.porwoll.tech/api/youtube/complete-task/5" \
+  -H "Authorization: JWT your-token"
+
+# Team-Kapazität
+curl "https://pl.porwoll.tech/api/youtube/capacity" \
+  -H "Authorization: JWT your-token"
+```
+
+### Upload & Thumbnails
+
+```bash
+# Video-Upload-Job erstellen (BullMQ)
+curl -X POST "https://pl.porwoll.tech/api/youtube/upload" \
+  -H "Authorization: JWT your-token" \
+  -H "Content-Type: application/json" \
+  -d '{"contentId": 1}'
+
+# Upload-Status abfragen
+curl "https://pl.porwoll.tech/api/youtube/upload?jobId=abc123" \
+  -H "Authorization: JWT your-token"
+
+# Bulk-Thumbnail-Download (Super-Admin)
+curl -X POST "https://pl.porwoll.tech/api/youtube/thumbnails/bulk?dryRun=true" \
+  -H "Authorization: JWT your-token"
+```
+
+### YouTube Cron Jobs
+
+```bash
+# YouTube-Kommentar-Sync (alle 15 Min)
+curl "https://pl.porwoll.tech/api/cron/youtube-sync" \
+  -H "Authorization: Bearer $CRON_SECRET"
+
+# Kanal-Statistiken (täglich 04:00 UTC)
+curl "https://pl.porwoll.tech/api/cron/youtube-channel-sync" \
+  -H "Authorization: Bearer $CRON_SECRET"
+
+# Video-Performance-Metriken (alle 6 Stunden)
+curl "https://pl.porwoll.tech/api/cron/youtube-metrics-sync" \
+  -H "Authorization: Bearer $CRON_SECRET"
+
+# Status-Check (HEAD → 200 idle, 423 running)
+curl -I "https://pl.porwoll.tech/api/cron/youtube-channel-sync" \
+  -H "Authorization: Bearer $CRON_SECRET"
+```
+
 ### Community Interactions API (Auth erforderlich)

 ```bash