From a0ef957a7fd148ef4bc3b054629fea15a813f1f8 Mon Sep 17 00:00:00 2001 From: Martin Porwoll Date: Sat, 14 Feb 2026 18:02:59 +0000 Subject: [PATCH] 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 --- CLAUDE.md | 4 + docs/CLAUDE_REFERENCE.md | 81 +++++++++++ docs/anleitungen/API_ANLEITUNG.md | 225 ++++++++++++++++++++++++++++++ 3 files changed, 310 insertions(+) diff --git a/CLAUDE.md b/CLAUDE.md index 551b4c7..0d8c1a8 100644 --- 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` diff --git a/docs/CLAUDE_REFERENCE.md b/docs/CLAUDE_REFERENCE.md index 2cbf33f..89d0478 100644 --- 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 | diff --git a/docs/anleitungen/API_ANLEITUNG.md b/docs/anleitungen/API_ANLEITUNG.md index 7b3f4fe..18e6c9a 100644 --- 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