cms.c2sgmbh/docs/reports/community-phase1-implementation.md

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

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

{
  "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

{
  "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

{
  "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

{
  "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