cms.c2sgmbh/docs/reports/community-phase1-implementation.md
Martin Porwoll 22592bf759 fix(Community): convert custom views to client components
- Fix Server Components render error by using 'use client' directive
- Remove DefaultTemplate which requires server-side props
- Add Community Analytics Dashboard view with charts
- Add Analytics API endpoints (overview, sentiment, response metrics, etc.)
- Add implementation report for design AI

The custom views now work correctly within Payload's RootLayout context.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-16 11:05:39 +00:00

615 lines
27 KiB
Markdown

# 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