cms.c2sgmbh/docs/YOUTUBE_OPERATIONS_HUB.md

# YouTube Operations Hub - Konzeptübersicht

## 1. Übersicht

Der YouTube Operations Hub ist ein integriertes Modul im Payload CMS zur Verwaltung von YouTube-Kanälen, Video-Content, Aufgaben und Team-Workflows. Er wurde speziell für Multi-Channel-Betreiber entwickelt, die mehrere YouTube-Kanäle professionell managen.

### Hauptfunktionen

- **Kanalverwaltung**: Mehrere YouTube-Kanäle mit Branding und Metriken
- **Content-Pipeline**: Video-Workflow von Idee bis Veröffentlichung
- **Task-Management**: Aufgabenzuweisung und -verfolgung
- **Benachrichtigungen**: Systemweite Notifications für Team-Mitglieder
- **Rollenbasierter Zugriff**: Feingranulare Berechtigungen

---

## 2. Datenmodell

### 2.1 Collections

```
┌─────────────────────┐     ┌─────────────────────┐
│  YouTube Channels   │────<│   YouTube Content   │
│  (youtube-channels) │     │  (youtube-content)  │
└─────────────────────┘     └─────────────────────┘
         │                           │
         │                           │
         ▼                           ▼
┌─────────────────────┐     ┌─────────────────────┐
│      YT Tasks       │────<│  YT Notifications   │
│     (yt-tasks)      │     │ (yt-notifications)  │
└─────────────────────┘     └─────────────────────┘
         │
         ▼
┌─────────────────────┐
│       Users         │
│  (mit youtubeRole)  │
└─────────────────────┘
```

### 2.2 YouTube Channels (`youtube-channels`)

Verwaltet YouTube-Kanäle mit allen relevanten Metadaten.

| Feld | Typ | Beschreibung |
|------|-----|--------------|
| `name` | text (lokalisiert) | Kanalname (z.B. "BlogWoman by Caroline Porwoll") |
| `slug` | text (unique) | Interner Kurzname (z.B. "blogwoman") |
| `youtubeChannelId` | text | YouTube Channel ID (UCxxxxx) |
| `youtubeHandle` | text | YouTube Handle (@blogwoman) |
| `language` | select | Sprache: `de`, `en` |
| `category` | select | Kategorie: `lifestyle`, `corporate`, `b2b` |
| `status` | select | Status: `active`, `planned`, `paused`, `archived` |

**Branding-Gruppe:**
| Feld | Typ | Beschreibung |
|------|-----|--------------|
| `branding.primaryColor` | text | Primärfarbe (Hex, z.B. #1278B3) |
| `branding.secondaryColor` | text | Sekundärfarbe (Hex) |
| `branding.logo` | upload (media) | Kanal-Logo |
| `branding.thumbnailTemplate` | upload (media) | Thumbnail-Vorlage |

**Content-Serien (Array):**
| Feld | Typ | Beschreibung |
|------|-----|--------------|
| `contentSeries[].name` | text (lokalisiert) | Serienname |
| `contentSeries[].slug` | text | Serien-Slug |
| `contentSeries[].description` | textarea (lokalisiert) | Beschreibung |
| `contentSeries[].color` | text | Farbe für UI |
| `contentSeries[].isActive` | checkbox | Aktiv-Status |

**Veröffentlichungsplan:**
| Feld | Typ | Beschreibung |
|------|-----|--------------|
| `publishingSchedule.defaultDays` | select (hasMany) | Standard-Veröffentlichungstage |
| `publishingSchedule.defaultTime` | text | Standard-Uhrzeit |
| `publishingSchedule.shortsPerWeek` | number | Shorts pro Woche (Default: 4) |
| `publishingSchedule.longformPerWeek` | number | Longform pro Woche (Default: 1) |

**Metriken (via YouTube API):**
| Feld | Typ | Beschreibung |
|------|-----|--------------|
| `currentMetrics.subscriberCount` | number | Abonnenten |
| `currentMetrics.totalViews` | number | Gesamtaufrufe |
| `currentMetrics.videoCount` | number | Anzahl Videos |
| `currentMetrics.lastSyncedAt` | date | Letzter Sync |

### 2.3 YouTube Content (`youtube-content`)

Verwaltet einzelne Videos durch den gesamten Produktionsprozess.

| Feld | Typ | Beschreibung |
|------|-----|--------------|
| `title` | text (lokalisiert) | Video-Titel |
| `slug` | text | URL-Slug |
| `channel` | relationship | Zugehöriger Kanal |
| `contentSeries` | text | Content-Serie |
| `format` | select | Format: `short`, `longform`, `premiere` |
| `status` | select | Status (siehe Status-Workflow) |
| `priority` | select | Priorität: `urgent`, `high`, `normal`, `low` |
| `assignedTo` | relationship (users) | Zuständige Person |
| `createdBy` | relationship (users) | Ersteller |

**Status-Workflow:**
```
idea → script_draft → script_review → script_approved →
shoot_scheduled → shot → rough_cut → fine_cut →
final_review → approved → upload_scheduled → published → tracked
                                                    ↓
                                               discarded
```

**Script-Felder:**
| Feld | Typ | Beschreibung |
|------|-----|--------------|
| `description` | textarea (lokalisiert) | Beschreibung |
| `hook` | text (lokalisiert) | Hook/Einstieg |
| `keyPoints[]` | array (lokalisiert) | Kernpunkte |
| `callToAction` | text (lokalisiert) | Call-to-Action |
| `scriptContent` | richText (lokalisiert) | Vollständiges Script |
| `scriptUrl` | text | Link zu externem Script |

**Zeitplanung:**
| Feld | Typ | Beschreibung |
|------|-----|--------------|
| `shootDate` | date | Drehdatum |
| `editDeadline` | date | Schnitt-Deadline |
| `reviewDeadline` | date | Review-Deadline |
| `scheduledPublishDate` | date | Geplante Veröffentlichung |
| `actualPublishDate` | date | Tatsächliche Veröffentlichung |

**Medien:**
| Feld | Typ | Beschreibung |
|------|-----|--------------|
| `thumbnail` | upload (media) | Haupt-Thumbnail |
| `thumbnailAlt` | upload (media) | Alternatives Thumbnail |
| `videoFile` | upload (media) | Video-Datei |
| `rawFootage[]` | array | Rohmaterial |

**Freigaben:**
| Freigabe | Felder |
|----------|--------|
| Script Approval | `approved`, `approvedBy`, `approvedAt`, `notes` |
| Medical Approval | `required`, `approved`, `approvedBy`, `approvedAt`, `notes` |
| Legal Approval | `approved`, `approvedBy`, `approvedAt`, `notes`, `disclaimerIncluded` |
| Final Approval | `approved`, `approvedBy`, `approvedAt`, `notes` |

**YouTube-Metadaten:**
| Feld | Typ | Beschreibung |
|------|-----|--------------|
| `youtubeVideoId` | text | YouTube Video ID |
| `youtubeUrl` | text | YouTube URL |
| `youtubeMetadata.youtubeTitle` | text (lokalisiert) | YouTube-Titel |
| `youtubeMetadata.youtubeDescription` | textarea (lokalisiert) | YouTube-Beschreibung |
| `youtubeMetadata.tags[]` | array | Tags |
| `youtubeMetadata.visibility` | select | `public`, `unlisted`, `private` |
| `youtubeMetadata.chapters` | textarea | Kapitelmarken |
| `youtubeMetadata.pinnedComment` | textarea (lokalisiert) | Angepinnter Kommentar |

**Performance-Metriken:**
| Feld | Typ | Beschreibung |
|------|-----|--------------|
| `performance.views` | number | Aufrufe |
| `performance.likes` | number | Likes |
| `performance.comments` | number | Kommentare |
| `performance.shares` | number | Shares |
| `performance.watchTimeMinutes` | number | Watch Time |
| `performance.avgViewDuration` | number | Avg. View Duration |
| `performance.avgViewPercentage` | number | Avg. View % |
| `performance.ctr` | number | Click-Through-Rate |
| `performance.impressions` | number | Impressions |
| `performance.subscribersGained` | number | Gewonnene Abonnenten |

### 2.4 YT Tasks (`yt-tasks`)

Aufgabenverwaltung für Video-Produktion.

| Feld | Typ | Beschreibung |
|------|-----|--------------|
| `title` | text (lokalisiert) | Aufgabentitel |
| `description` | textarea (lokalisiert) | Beschreibung |
| `video` | relationship | Zugehöriges Video |
| `channel` | relationship | Zugehöriger Kanal |
| `taskType` | select | Aufgabentyp |
| `status` | select | Status |
| `priority` | select | Priorität |
| `assignedTo` | relationship (users) | Zuständige Person |
| `dueDate` | date | Fälligkeitsdatum |
| `completedAt` | date | Abschlussdatum |
| `completedBy` | relationship (users) | Abgeschlossen von |
| `blockedReason` | text (lokalisiert) | Blockierungsgrund |
| `attachments[]` | array | Anhänge (file, note) |
| `comments[]` | array | Kommentare (author, content, createdAt) |

**Task Types:**
- `script_write` - Script schreiben
- `script_review` - Script Review
- `shoot_prep` - Dreh-Vorbereitung
- `shoot` - Dreh
- `edit` - Schnitt
- `graphics` - Grafiken
- `thumbnail` - Thumbnail
- `review` - Review
- `upload` - Upload
- `track` - Tracking
- `comments` - Kommentare beantworten
- `other` - Sonstiges

**Task Status:**
- `todo` - Offen
- `in_progress` - In Bearbeitung
- `blocked` - Blockiert
- `waiting_review` - Wartet auf Review
- `done` - Erledigt
- `cancelled` - Abgebrochen

### 2.5 YT Notifications (`yt-notifications`)

Benachrichtigungssystem für Team-Mitglieder.

| Feld | Typ | Beschreibung |
|------|-----|--------------|
| `title` | text (lokalisiert) | Benachrichtigungstitel |
| `message` | textarea (lokalisiert) | Nachricht |
| `recipient` | relationship (users) | Empfänger |
| `type` | select | Benachrichtigungstyp |
| `link` | text | Link zur Aktion |
| `relatedVideo` | relationship | Zugehöriges Video |
| `relatedTask` | relationship | Zugehörige Aufgabe |
| `read` | checkbox | Gelesen |
| `readAt` | date | Gelesen am |
| `emailSent` | checkbox | E-Mail gesendet |

**Notification Types:**
- `task_assigned` - Aufgabe zugewiesen
- `task_due` - Aufgabe fällig
- `task_overdue` - Aufgabe überfällig
- `approval_required` - Freigabe erforderlich
- `approved` - Freigegeben
- `rejected` - Abgelehnt
- `video_published` - Video veröffentlicht
- `comment` - Kommentar
- `mention` - Erwähnung
- `system` - Systemmeldung

---

## 3. User-Erweiterung

### 3.1 Neue Felder in Users Collection

| Feld | Typ | Beschreibung |
|------|-----|--------------|
| `youtubeRole` | select | YouTube-Rolle des Users |
| `youtubeChannels` | relationship (hasMany) | Zugewiesene Kanäle |

### 3.2 YouTube-Rollen

| Rolle | Beschreibung | Berechtigungen |
|-------|--------------|----------------|
| `none` | Kein YouTube-Zugriff | - |
| `viewer` | Nur Ansicht | Lesen |
| `editor` | Bearbeiter | Lesen, eigene Inhalte bearbeiten |
| `producer` | Produzent | Lesen, Bearbeiten, Tasks verwalten |
| `creator` | Creator | Wie Producer + Inhalte erstellen |
| `manager` | Manager | Vollzugriff auf alle YouTube-Funktionen |

---

## 4. Access Control

### 4.1 Zugriffsfunktionen (`src/lib/youtubeAccess.ts`)

```typescript
// Manager oder Super-Admin
isYouTubeManager: Access

// Creator oder höher (creator, manager)
isYouTubeCreatorOrAbove: Access

// Mindestens Viewer-Zugriff
hasYouTubeAccess: Access

// Zugewiesene Inhalte oder Manager
canAccessAssignedContent: Access

// Eigene Benachrichtigungen
canAccessOwnNotifications: Access
```

### 4.2 Berechtigungsmatrix

| Collection | Read | Create | Update | Delete |
|------------|------|--------|--------|--------|
| youtube-channels | hasYouTubeAccess | isYouTubeManager | isYouTubeManager | isYouTubeManager |
| youtube-content | canAccessAssignedContent | isYouTubeCreatorOrAbove | canAccessAssignedContent | isYouTubeManager |
| yt-tasks | canAccessAssignedContent | isYouTubeCreatorOrAbove | canAccessAssignedContent | isYouTubeManager |
| yt-notifications | canAccessOwnNotifications | isYouTubeCreatorOrAbove | canAccessOwnNotifications | isYouTubeManager |

---

## 5. API Endpoints

### 5.1 Custom API Routes

| Endpoint | Methode | Beschreibung |
|----------|---------|--------------|
| `/api/youtube/dashboard` | GET | Dashboard-Daten (Stats, Tasks, Videos) |
| `/api/youtube/my-tasks` | GET | Eigene offene Aufgaben |
| `/api/youtube/complete-task/[id]` | POST | Aufgabe als erledigt markieren |

### 5.2 Standard Payload API

| Endpoint | Beschreibung |
|----------|--------------|
| `/api/youtube-channels` | CRUD für Kanäle |
| `/api/youtube-content` | CRUD für Videos |
| `/api/yt-tasks` | CRUD für Aufgaben |
| `/api/yt-notifications` | CRUD für Benachrichtigungen |

---

## 6. Datenbank-Schema

### 6.1 Haupttabellen

```sql
youtube_channels
youtube_channels_locales
youtube_channels_content_series
youtube_channels_content_series_locales
youtube_channels_publishing_schedule_default_days

youtube_content
youtube_content_locales
youtube_content_key_points
youtube_content_key_points_locales
youtube_content_raw_footage
youtube_content_youtube_metadata_tags

yt_tasks
yt_tasks_locales
yt_tasks_attachments
yt_tasks_comments

yt_notifications
yt_notifications_locales

users_rels (für youtubeChannels Relationship)
```

### 6.2 Enums

```sql
enum_users_youtube_role
enum_youtube_channels_language
enum_youtube_channels_category
enum_youtube_channels_status
enum_youtube_content_format
enum_youtube_content_status
enum_youtube_content_priority
enum_youtube_content_visibility
enum_yt_tasks_task_type
enum_yt_tasks_status
enum_yt_tasks_priority
enum_yt_notifications_type
```

---

## 7. Hooks & Automatisierungen

### 7.1 Task-Erstellung Hook

Bei Erstellung eines neuen Videos wird automatisch eine Task erstellt:

```typescript
// src/hooks/youtube/createTaskOnVideoCreate.ts
afterChange: async ({ doc, operation, req }) => {
  if (operation === 'create') {
    await req.payload.create({
      collection: 'yt-tasks',
      data: {
        title: `Script für "${doc.title}"`,
        video: doc.id,
        channel: doc.channel,
        taskType: 'script_write',
        assignedTo: doc.assignedTo,
        // ...
      }
    })
  }
}
```

### 7.2 Benachrichtigungs-Hook

Bei Task-Zuweisung wird automatisch eine Notification erstellt:

```typescript
// src/hooks/youtube/notifyOnTaskAssignment.ts
afterChange: async ({ doc, previousDoc, operation, req }) => {
  if (doc.assignedTo !== previousDoc?.assignedTo) {
    await req.payload.create({
      collection: 'yt-notifications',
      data: {
        title: 'Neue Aufgabe zugewiesen',
        recipient: doc.assignedTo,
        type: 'task_assigned',
        relatedTask: doc.id,
        // ...
      }
    })
  }
}
```

---

## 8. Admin-UI Konfiguration

### 8.1 Gruppierung

Alle YouTube-Collections sind unter der Gruppe "YouTube" zusammengefasst:

```typescript
admin: {
  group: 'YouTube',
}
```

### 8.2 Spalten-Konfiguration

| Collection | Spalten |
|------------|---------|
| youtube-channels | name, youtubeHandle, status, language |
| youtube-content | title, channel, status, format, scheduledPublishDate |
| yt-tasks | title, video, taskType, status, assignedTo, dueDate |
| yt-notifications | title, type, recipient, read, createdAt |

---

## 9. Mehrsprachigkeit

Alle kundenorientierten Felder sind lokalisiert (de/en):

- Kanal-Namen
- Video-Titel und Beschreibungen
- Scripts
- Task-Titel und Beschreibungen
- Benachrichtigungen
- Content-Serien

---

## 10. Dateien-Übersicht

```
src/
├── collections/
│   ├── YouTubeChannels.ts
│   ├── YouTubeContent.ts
│   ├── YtTasks.ts
│   └── YtNotifications.ts
├── lib/
│   └── youtubeAccess.ts
├── hooks/youtube/
│   ├── createTaskOnVideoCreate.ts
│   └── notifyOnTaskAssignment.ts
├── app/(payload)/api/youtube/
│   ├── dashboard/route.ts
│   ├── my-tasks/route.ts
│   └── complete-task/[id]/route.ts
└── migrations/
    └── 20260112_150000_add_youtube_operations_hub.ts
```

---

## 11. Erweiterungsmöglichkeiten

### Geplante Features

1. **YouTube API Integration**
   - Automatischer Metriken-Sync
   - Video-Upload direkt aus CMS
   - Kommentar-Import

2. **Analytics Dashboard**
   - Performance-Vergleich zwischen Videos
   - Trend-Analyse
   - ROI-Berechnung

3. **Workflow-Automatisierung**
   - Automatische Status-Änderungen
   - Deadline-Erinnerungen
   - Team-Kapazitätsplanung

4. **Content-Kalender**
   - Visuelle Übersicht
   - Drag & Drop Planung
   - Konflikt-Erkennung

---

*Letzte Aktualisierung: 12.01.2026*