# Community Management Phase 1 - Implementation Report

**Datum:** 15. Januar 2026
**Version:** 1.0
**Status:** ✅ Abgeschlossen

---

## Executive Summary

Community Management Phase 1 ist ein umfassendes System zur Verwaltung von YouTube-Kommentaren und Social-Media-Interaktionen innerhalb des Payload CMS Admin-Panels. Das System ermöglicht effizientes Community-Management durch automatisierte Regeln, Sentiment-Analyse und eine zentrale Inbox-Ansicht.

---

## 1. Systemarchitektur

### 1.1 Komponenten-Übersicht

```
┌─────────────────────────────────────────────────────────────────────┐
│                        PAYLOAD CMS ADMIN                            │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐     │
│  │  Community      │  │  Community      │  │  Community      │     │
│  │  Inbox View     │  │  Rules          │  │  Templates      │     │
│  │  (Custom View)  │  │  (Collection)   │  │  (Collection)   │     │
│  └────────┬────────┘  └────────┬────────┘  └────────┬────────┘     │
│           │                    │                    │               │
│           └────────────────────┼────────────────────┘               │
│                                │                                    │
│                    ┌───────────▼───────────┐                        │
│                    │    Rules Engine       │                        │
│                    │    (Auto-Processing)  │                        │
│                    └───────────┬───────────┘                        │
│                                │                                    │
└────────────────────────────────┼────────────────────────────────────┘
                                 │
┌────────────────────────────────┼────────────────────────────────────┐
│                    DATENBANK (PostgreSQL)                           │
├────────────────────────────────┼────────────────────────────────────┤
│                                │                                    │
│  ┌─────────────────┐  ┌────────▼────────┐  ┌─────────────────┐     │
│  │ social_platforms│  │ community_      │  │ community_      │     │
│  │                 │  │ interactions    │  │ templates       │     │
│  └─────────────────┘  └─────────────────┘  └─────────────────┘     │
│                                                                     │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐     │
│  │ social_accounts │  │ community_rules │  │ youtube_channels│     │
│  └─────────────────┘  └─────────────────┘  └─────────────────┘     │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘
                                 │
                                 ▼
┌─────────────────────────────────────────────────────────────────────┐
│                      EXTERNE SERVICES                               │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐     │
│  │  YouTube API    │  │  OpenAI API     │  │  Export Service │     │
│  │  (Comments)     │  │  (Sentiment)    │  │  (PDF/Excel)    │     │
│  └─────────────────┘  └─────────────────┘  └─────────────────┘     │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘
```

### 1.2 Datenfluss

```
YouTube Kommentar
        │
        ▼
┌───────────────────┐
│  Cron Job         │  ← Alle 15 Minuten
│  (syncAllComments)│
└────────┬──────────┘
         │
         ▼
┌───────────────────┐
│  YouTube API      │
│  (Comments.list)  │
└────────┬──────────┘
         │
         ▼
┌───────────────────┐
│  Datenbank        │
│  (Interaction)    │
└────────┬──────────┘
         │
         ▼
┌───────────────────┐
│  Rules Engine     │  ← Automatische Verarbeitung
│  (processNew)     │
└────────┬──────────┘
         │
         ├─► Priorität setzen
         ├─► Zuweisen an User
         ├─► Flags setzen (Medical, Spam, etc.)
         ├─► Template vorschlagen
         └─► Notification senden
         │
         ▼
┌───────────────────┐
│  Community Inbox  │  ← Admin-Ansicht
│  (React View)     │
└───────────────────┘
```

---

## 2. Collections (Datenmodelle)

### 2.1 Community Interactions

**Slug:** `community-interactions`
**Beschreibung:** Zentrale Sammlung aller Social-Media-Interaktionen

| Feldgruppe | Felder | Beschreibung |
|------------|--------|--------------|
| **Quelle** | platform, socialAccount, linkedContent | Woher kommt die Interaction |
| **Typ & ID** | type, externalId, parentInteraction | Art und Identifikation |
| **Autor** | authorName, authorHandle, authorAvatarUrl, authorIsVerified, authorIsSubscriber, authorSubscriberCount | Informationen zum Kommentator |
| **Inhalt** | message, messageHtml, publishedAt, attachments | Der eigentliche Kommentar |
| **Analyse** | sentiment, sentimentScore, confidence, language, topics, suggestedTemplate, suggestedReply | AI-Analyse |
| **Flags** | isMedicalQuestion, requiresEscalation, isSpam, isFromInfluencer | Automatische Markierungen |
| **Workflow** | status, priority, assignedTo, responseDeadline | Bearbeitungsstatus |
| **Antwort** | responseText, usedTemplate, sentAt, sentBy, externalReplyId | Gesendete Antwort |
| **Engagement** | likes, replies, isHearted, isPinned | YouTube-Metriken |

**Status-Workflow:**
```
new → in_review → waiting → answered → closed
                     ↓
                  escalated
```

**Prioritäten:**
- `urgent` - Sofort bearbeiten (rot)
- `high` - Heute bearbeiten (orange)
- `normal` - Standard (grau)
- `low` - Wenn Zeit ist (grün)

### 2.2 Community Rules

**Slug:** `community-rules`
**Beschreibung:** Automatisierungsregeln für Interactions

| Feld | Typ | Beschreibung |
|------|-----|--------------|
| name | Text | Name der Regel |
| priority | Number | Ausführungsreihenfolge (niedrig = zuerst) |
| isActive | Checkbox | Regel aktiv? |
| channel | Relationship | Optional: Nur für diesen Kanal |
| platforms | Relationship[] | Optional: Nur für diese Plattformen |

**Trigger-Typen:**

| Trigger | Beschreibung | Zusätzliche Felder |
|---------|--------------|-------------------|
| `keyword` | Keyword-Match | keywords[] mit matchType (contains/exact/regex) |
| `sentiment` | Sentiment-Wert | sentimentValues[] (positive/negative/neutral/question) |
| `question_detected` | Frage erkannt | - |
| `medical_detected` | Medizinischer Inhalt | - |
| `influencer` | Influencer-Kommentar | influencerMinFollowers (default: 10000) |
| `all_new` | Alle neuen Kommentare | - |
| `contains_link` | Enthält URL | - |
| `contains_email` | Enthält E-Mail | - |

**Aktionen:**

| Aktion | Wert-Parameter | Beschreibung |
|--------|---------------|--------------|
| `set_priority` | urgent/high/normal/low | Priorität setzen |
| `assign_to` | targetUser | Zuweisen an Benutzer |
| `set_flag` | medical/spam/escalate | Flag setzen |
| `suggest_template` | targetTemplate | Antwort-Vorlage vorschlagen |
| `send_notification` | targetUser | Benachrichtigung senden |
| `flag_medical` | - | Als medizinische Frage markieren |
| `escalate` | - | Eskalieren |
| `mark_spam` | - | Als Spam markieren |
| `set_deadline` | Stunden | Deadline setzen |

### 2.3 Community Templates

**Slug:** `community-templates`
**Beschreibung:** Wiederverwendbare Antwort-Vorlagen

| Feld | Typ | Beschreibung |
|------|-----|--------------|
| name | Text (lokalisiert) | Template-Name |
| category | Select | Kategorie (greeting, faq, support, etc.) |
| template | Textarea (lokalisiert) | Template-Text mit Variablen |
| variables | Array | Definierte Variablen |
| channel | Relationship | Optional: Kanal-spezifisch |
| platforms | Relationship[] | Plattform-Filter |
| autoSuggest.keywords | Array | Keywords für Auto-Suggest |
| requiresReview | Checkbox | Vor dem Senden prüfen? |

**Variablen-Syntax:** `{{variableName}}`

**Beispiel-Template:**
```
Hallo {{authorName}}! 👋

Vielen Dank für deine Frage zu {{topic}}.

{{customResponse}}

Liebe Grüße,
{{channelName}} Team
```

### 2.4 Social Platforms

**Slug:** `social-platforms`
**Beschreibung:** Konfiguration der Social-Media-Plattformen

| Feld | Typ | Beschreibung |
|------|-----|--------------|
| name | Text | Plattform-Name |
| slug | Text | Eindeutiger Slug |
| icon | Text | Emoji oder Icon |
| color | Text | Hex-Farbcode |
| apiConfig | Group | API-Konfiguration |
| rateLimits | Group | API Rate Limits |
| interactionTypes | Array | Unterstützte Interaction-Typen |

**Vorkonfigurierte Plattform:**
- YouTube (slug: `youtube`, icon: 📺, color: #FF0000)

### 2.5 Social Accounts

**Slug:** `social-accounts`
**Beschreibung:** Verbundene Social-Media-Accounts

| Feld | Typ | Beschreibung |
|------|-----|--------------|
| platform | Relationship | Zugehörige Plattform |
| linkedChannel | Relationship | Verknüpfter YouTube-Kanal |
| displayName | Text | Anzeigename |
| accountHandle | Text | @handle |
| externalId | Text | Externe ID |
| credentials | Group | OAuth-Tokens (verschlüsselt) |
| syncSettings | Group | Sync-Konfiguration |

---

## 3. Admin Views

### 3.1 Community Inbox

**Route:** `/admin/views/community/inbox`
**Komponente:** `CommunityInbox.tsx`

#### Layout (Desktop)

```
┌─────────────────────────────────────────────────────────────────────────┐
│  Community Inbox                                        [Sync] [Export] │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  ┌─────────────────────────────────────────────────────────────────┐   │
│  │  Stats: 📊 127 Total │ 🆕 23 Neu │ 🔴 5 Urgent │ 🏥 3 Medical   │   │
│  └─────────────────────────────────────────────────────────────────┘   │
│                                                                         │
│  ┌─────────────────────────────────────────────────────────────────┐   │
│  │  Filters: [Status ▼] [Priority ▼] [Platform ▼] [🔍 Search...]   │   │
│  └─────────────────────────────────────────────────────────────────┘   │
│                                                                         │
│  ┌──────────────────────────┬──────────────────────────────────────┐   │
│  │                          │                                      │   │
│  │  📋 Interaction List     │  📄 Detail View                      │   │
│  │                          │                                      │   │
│  │  ┌────────────────────┐  │  ┌────────────────────────────────┐  │   │
│  │  │ 🔴 @user1          │  │  │  👤 @selectedUser              │  │   │
│  │  │ "Tolles Video!"    │◄─┼──│  ─────────────────────────────  │  │   │
│  │  │ 2h ago • YouTube   │  │  │  "Der vollständige Kommentar   │  │   │
│  │  └────────────────────┘  │  │   wird hier angezeigt..."      │  │   │
│  │                          │  │                                  │  │   │
│  │  ┌────────────────────┐  │  │  ─────────────────────────────  │  │   │
│  │  │ 🟡 @user2          │  │  │                                  │  │   │
│  │  │ "Frage zu..."      │  │  │  📊 Analyse                      │  │   │
│  │  │ 5h ago • YouTube   │  │  │  Sentiment: 😊 Positiv (0.85)   │  │   │
│  │  └────────────────────┘  │  │  Topics: #frage #produkt        │  │   │
│  │                          │  │                                  │  │   │
│  │  ┌────────────────────┐  │  │  ─────────────────────────────  │  │   │
│  │  │ 🟢 @user3          │  │  │                                  │  │   │
│  │  │ "Danke für..."     │  │  │  💬 Antwort                      │  │   │
│  │  │ 1d ago • YouTube   │  │  │  ┌────────────────────────────┐ │  │   │
│  │  └────────────────────┘  │  │  │ Template: [Auswählen ▼]    │ │  │   │
│  │                          │  │  │                            │ │  │   │
│  │  [Load More...]          │  │  │ [Antwort-Text hier...]     │ │  │   │
│  │                          │  │  │                            │ │  │   │
│  │                          │  │  └────────────────────────────┘ │  │   │
│  │                          │  │                                  │  │   │
│  │                          │  │  [💾 Speichern] [📤 Senden]      │  │   │
│  │                          │  │                                  │  │   │
│  └──────────────────────────┴──────────────────────────────────────┘   │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘
```

#### Layout (Mobile)

```
┌─────────────────────────┐
│  Community Inbox    [≡] │
├─────────────────────────┤
│                         │
│  [Liste] [Detail] [⚙️]  │
│                         │
│  ┌───────────────────┐  │
│  │ 🔴 @user1         │  │
│  │ "Tolles Video!"   │  │
│  │ 2h ago            │  │
│  └───────────────────┘  │
│                         │
│  ┌───────────────────┐  │
│  │ 🟡 @user2         │  │
│  │ "Frage zu..."     │  │
│  │ 5h ago            │  │
│  └───────────────────┘  │
│                         │
│  ┌───────────────────┐  │
│  │ 🟢 @user3         │  │
│  │ "Danke für..."    │  │
│  │ 1d ago            │  │
│  └───────────────────┘  │
│                         │
└─────────────────────────┘
```

#### Farbkodierung

| Element | Farbe | Bedeutung |
|---------|-------|-----------|
| Priorität Urgent | `#dc2626` (Rot) | Sofort bearbeiten |
| Priorität High | `#f59e0b` (Orange) | Heute bearbeiten |
| Priorität Normal | `#6b7280` (Grau) | Standard |
| Priorität Low | `#10b981` (Grün) | Niedrig |
| Status New | `#3b82f6` (Blau) | Neu eingegangen |
| Status Answered | `#10b981` (Grün) | Beantwortet |
| Medical Flag | `#dc2626` (Rot) + 🏥 | Medizinische Frage |
| Influencer Flag | `#8b5cf6` (Lila) + ⭐ | Influencer |

#### Interaktionen

1. **Klick auf Interaction:** Öffnet Detail-Ansicht
2. **Filter anwenden:** Liste wird gefiltert
3. **Template auswählen:** Text wird in Antwort-Feld eingefügt
4. **Senden:** Antwort wird via YouTube API gepostet
5. **Sync:** Manuelle Synchronisation aller Kommentare
6. **Export:** Modal mit Format-Auswahl (PDF/Excel/CSV)

---

## 4. API Endpoints

### 4.1 Community APIs

| Endpoint | Methode | Beschreibung |
|----------|---------|--------------|
| `/api/community/stats` | GET | Statistiken (total, new, urgent, medical) |
| `/api/community/export` | POST | Export als PDF/Excel/CSV |
| `/api/community/reply` | POST | Antwort senden (via YouTube API) |
| `/api/community/sync-comments` | POST | Manuelle Synchronisation |

### 4.2 YouTube OAuth APIs

| Endpoint | Methode | Beschreibung |
|----------|---------|--------------|
| `/api/youtube/auth` | GET | OAuth-Flow starten |
| `/api/youtube/callback` | GET | OAuth-Callback |
| `/api/youtube/refresh-token` | POST | Token erneuern |

### 4.3 Collection APIs (Standard Payload)

| Endpoint | Beschreibung |
|----------|--------------|
| `/api/community-interactions` | CRUD für Interactions |
| `/api/community-rules` | CRUD für Rules |
| `/api/community-templates` | CRUD für Templates |
| `/api/social-platforms` | CRUD für Platforms |
| `/api/social-accounts` | CRUD für Accounts |

---

## 5. Rules Engine

### 5.1 Funktionsweise

```typescript
class RulesEngine {
  // Verarbeitet neue Interactions
  async processNewInteraction(interaction: Interaction): Promise<void>

  // Lädt aktive Regeln (sortiert nach Priorität)
  private async loadActiveRules(): Promise<Rule[]>

  // Prüft ob Trigger matcht
  private matchesTrigger(interaction: Interaction, rule: Rule): boolean

  // Führt Aktionen aus
  private executeActions(interaction: Interaction, actions: Action[]): Promise<void>
}
```

### 5.2 Beispiel-Regeln

**Regel 1: Medizinische Fragen**
```json
{
  "name": "Medizinische Fragen - Priorität hoch",
  "priority": 10,
  "trigger": {
    "type": "keyword",
    "keywords": [
      { "keyword": "arzt", "matchType": "contains" },
      { "keyword": "schmerz", "matchType": "contains" },
      { "keyword": "medikament", "matchType": "contains" }
    ]
  },
  "actions": [
    { "action": "set_priority", "value": "urgent" },
    { "action": "flag_medical" },
    { "action": "send_notification", "targetUser": "manager" }
  ]
}
```

**Regel 2: Influencer-Kommentare**
```json
{
  "name": "Influencer - Priorität urgent",
  "priority": 5,
  "trigger": {
    "type": "influencer",
    "influencerMinFollowers": 10000
  },
  "actions": [
    { "action": "set_priority", "value": "urgent" },
    { "action": "assign_to", "targetUser": "creator" }
  ]
}
```

**Regel 3: Spam-Erkennung**
```json
{
  "name": "Spam-Erkennung",
  "priority": 1,
  "trigger": {
    "type": "keyword",
    "keywords": [
      { "keyword": "free.*money", "matchType": "regex" },
      { "keyword": "click.*link", "matchType": "regex" }
    ]
  },
  "actions": [
    { "action": "mark_spam" },
    { "action": "set_priority", "value": "low" }
  ]
}
```

---

## 6. Scheduled Jobs

### 6.1 Comment Sync Cron

**Schedule:** `*/15 * * * *` (alle 15 Minuten)
**Job:** `syncAllComments`

```
1. Lade alle aktiven Social Accounts mit gültigen Tokens
2. Für jeden Account:
   a. Prüfe Rate Limits
   b. Hole neue Kommentare via YouTube API
   c. Speichere als Community Interactions
   d. Verarbeite mit Rules Engine
3. Logge Ergebnis
```

### 6.2 Token Refresh

**Trigger:** Vor Ablauf des Access Tokens
**Aktion:** Refresh Token verwenden für neuen Access Token

---

## 7. Berechtigungen

### 7.1 Rollen-Hierarchie

```
Super Admin
    │
    ├── YouTube Manager ──► Voller Zugriff auf YouTube & Community
    │
    ├── Community Manager ──► Voller Zugriff auf Community
    │
    ├── Community Moderator ──► Lesen & Antworten
    │
    └── Community Viewer ──► Nur Lesen
```

### 7.2 Access Control Matrix

| Aktion | Viewer | Moderator | Manager | Super Admin |
|--------|--------|-----------|---------|-------------|
| Interactions lesen | ✅ | ✅ | ✅ | ✅ |
| Interactions bearbeiten | ❌ | ✅ | ✅ | ✅ |
| Antworten senden | ❌ | ✅ | ✅ | ✅ |
| Rules verwalten | ❌ | ❌ | ✅ | ✅ |
| Templates verwalten | ❌ | ❌ | ✅ | ✅ |
| Export | ❌ | ✅ | ✅ | ✅ |
| OAuth verbinden | ❌ | ❌ | ✅ | ✅ |

---

## 8. Technische Details

### 8.1 Datenbank-Schema

**Haupttabellen:**
- `community_interactions` - Haupttabelle
- `community_interactions_attachments` - Anhänge (Array)
- `community_interactions_analysis_topics` - Topics (Array)
- `community_rules` - Regeln
- `community_rules_trigger_keywords` - Keywords (Array)
- `community_rules_trigger_sentiment_values` - Sentiment-Werte (hasMany Select)
- `community_rules_actions` - Aktionen (Array)
- `community_rules_rels` - Relationships
- `community_templates` - Templates
- `community_templates_locales` - Lokalisierte Felder
- `community_templates_variables` - Variablen (Array)
- `social_platforms` - Plattformen
- `social_accounts` - Accounts

### 8.2 Payload CMS Version

- **Payload:** 3.69.0
- **Next.js:** 15.5.9
- **React:** 19.2.3
- **Datenbank:** PostgreSQL 17.6

### 8.3 Abhängigkeiten

```json
{
  "googleapis": "^140.0.0",
  "exceljs": "^4.4.0"
}
```

---

## 9. Zukünftige Erweiterungen (Phase 2+)

### Geplant:
- [ ] Instagram Integration
- [ ] TikTok Integration
- [ ] AI-basierte Sentiment-Analyse (OpenAI)
- [ ] Auto-Reply für einfache Fragen
- [ ] Team-Zuweisungsregeln
- [ ] Analytics Dashboard
- [ ] Bulk-Aktionen
- [ ] Keyboard Shortcuts
- [ ] Notification Center

---

## 10. Dateistruktur

```
src/
├── collections/
│   ├── CommunityInteractions.ts
│   ├── CommunityRules.ts
│   ├── CommunityTemplates.ts
│   ├── SocialPlatforms.ts
│   └── SocialAccounts.ts
├── lib/
│   ├── communityAccess.ts          # Access Control
│   ├── services/
│   │   └── RulesEngine.ts          # Automatisierung
│   └── integrations/
│       └── youtube/
│           └── oauth.ts            # YouTube OAuth
├── jobs/
│   ├── scheduler.ts                # Cron-Jobs
│   └── syncAllComments.ts          # Comment Sync
└── app/(payload)/
    ├── admin/views/community/
    │   └── inbox/
    │       ├── page.tsx            # Page Route
    │       ├── CommunityInbox.tsx  # React Component
    │       └── inbox.scss          # Styles
    └── api/
        ├── community/
        │   ├── export/route.ts
        │   ├── stats/route.ts
        │   └── reply/route.ts
        └── youtube/
            ├── auth/route.ts
            ├── callback/route.ts
            └── refresh-token/route.ts
```

---

**Erstellt von:** Claude Opus 4.5
**Für:** Design AI / Dokumentation
**Projekt:** Payload CMS Multi-Tenant