mirror of
https://github.com/complexcaresolutions/cms.c2sgmbh.git
synced 2026-03-17 16:14:12 +00:00
Martin Porwoll
31d44af0bd
Technical documentation for "Konzept KI" covering: - Architecture diagram with collections and services - 5 collections (SocialPlatforms, SocialAccounts, CommunityInteractions, CommunityRules, CommunityTemplates) - Access control system (communityRole-based) - Integration services (YouTubeClient, ClaudeAnalysisService) - API endpoints and database schema - Environment variables and file structure Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
521 lines
18 KiB
Markdown
521 lines
18 KiB
Markdown
# Community Management - Implementierungsübersicht
|
|
|
|
## Übersicht
|
|
|
|
Das Community Management System ermöglicht die zentrale Verwaltung von Social Media Interaktionen (Kommentare, DMs, Mentions) mit KI-gestützter Analyse und automatisierten Workflows.
|
|
|
|
## Architektur
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────────┐
|
|
│ Payload CMS Admin │
|
|
├─────────────────────────────────────────────────────────────────────┤
|
|
│ │
|
|
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────────────────┐ │
|
|
│ │ Social │ │ Social │ │ Community │ │
|
|
│ │ Platforms │──│ Accounts │──│ Interactions │ │
|
|
│ │ (YouTube, │ │ (Kanäle, │ │ (Kommentare, DMs) │ │
|
|
│ │ LinkedIn) │ │ Tokens) │ │ │ │
|
|
│ └──────────────┘ └──────────────┘ └──────────────────────────┘ │
|
|
│ │ │ │
|
|
│ │ ┌────────────────────────┼───────────────┐ │
|
|
│ │ │ │ │ │
|
|
│ ▼ ▼ ▼ │ │
|
|
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────────────┐ │ │
|
|
│ │ Community │ │ Community │ │ Users │ │ │
|
|
│ │ Rules │ │ Templates │ │ (communityRole) │ │ │
|
|
│ │ (Automation)│ │ (Antworten) │ │ │ │ │
|
|
│ └──────────────┘ └──────────────┘ └──────────────────────┘ │ │
|
|
│ │
|
|
└─────────────────────────────────────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────────────┐
|
|
│ Integration Services │
|
|
├─────────────────────────────────────────────────────────────────────┤
|
|
│ │
|
|
│ ┌──────────────────┐ ┌──────────────────────────────────────┐ │
|
|
│ │ YouTubeClient │ │ ClaudeAnalysisService │ │
|
|
│ │ (googleapis) │ │ (@anthropic-ai/sdk) │ │
|
|
│ │ │ │ │ │
|
|
│ │ - getComments │ │ - analyzeComment (Sentiment) │ │
|
|
│ │ - replyComment │ │ - generateReply (KI-Antwort) │ │
|
|
│ │ - markAsSpam │ │ - analyzeCommentsBatch │ │
|
|
│ └──────────────────┘ └──────────────────────────────────────┘ │
|
|
│ │ │ │
|
|
│ └──────────────┬───────────────┘ │
|
|
│ ▼ │
|
|
│ ┌──────────────────────┐ │
|
|
│ │ CommentsSyncService │ │
|
|
│ │ (Orchestrierung) │ │
|
|
│ └──────────────────────┘ │
|
|
│ │
|
|
└─────────────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
## Collections
|
|
|
|
### 1. SocialPlatforms (`social-platforms`)
|
|
|
|
**Zweck:** Definiert unterstützte Social Media Plattformen.
|
|
|
|
**Pfad:** `src/collections/SocialPlatforms.ts`
|
|
|
|
**Felder:**
|
|
| Feld | Typ | Beschreibung |
|
|
|------|-----|--------------|
|
|
| name | text | Plattformname (z.B. "YouTube") |
|
|
| slug | text | Unique Identifier |
|
|
| icon | text | Emoji oder Icon-Name |
|
|
| color | text | Hex-Farbcode für UI |
|
|
| isActive | checkbox | Plattform aktiv? |
|
|
| apiStatus | select | disconnected / development / connected |
|
|
| apiConfig | group | API-Konfiguration (Typ, URL, Auth) |
|
|
| apiConfig.scopes | array | OAuth Scopes |
|
|
| rateLimits | group | API Rate Limits |
|
|
| interactionTypes | array | Unterstützte Interaktionstypen |
|
|
|
|
**Seed-Daten:** YouTube wird automatisch bei Migration erstellt.
|
|
|
|
---
|
|
|
|
### 2. SocialAccounts (`social-accounts`)
|
|
|
|
**Zweck:** Verknüpft Plattformen mit konkreten Accounts/Kanälen.
|
|
|
|
**Pfad:** `src/collections/SocialAccounts.ts`
|
|
|
|
**Felder:**
|
|
| Feld | Typ | Beschreibung |
|
|
|------|-----|--------------|
|
|
| platform | relationship | → social-platforms |
|
|
| linkedChannel | relationship | → youtube-channels |
|
|
| displayName | text | Anzeigename |
|
|
| accountHandle | text | @handle |
|
|
| externalId | text | Plattform-ID |
|
|
| credentials | group | OAuth Tokens (verschlüsselt) |
|
|
| syncSettings | group | Auto-Sync Konfiguration |
|
|
| stats | group | Follower, Posts, Last Sync |
|
|
|
|
**Besonderheit:** `linkedChannel` verbindet mit bestehenden YouTube-Kanälen aus dem YouTube Operations Hub.
|
|
|
|
---
|
|
|
|
### 3. CommunityInteractions (`community-interactions`)
|
|
|
|
**Zweck:** Zentrale Sammlung aller eingehenden Interaktionen.
|
|
|
|
**Pfad:** `src/collections/CommunityInteractions.ts`
|
|
|
|
**Felder:**
|
|
| Feld | Typ | Beschreibung |
|
|
|------|-----|--------------|
|
|
| platform | relationship | → social-platforms |
|
|
| socialAccount | relationship | → social-accounts |
|
|
| linkedContent | relationship | → youtube-content |
|
|
| type | select | comment / reply / dm / mention |
|
|
| externalId | text | Unique ID von der Plattform |
|
|
| parentInteraction | relationship | → self (für Antwort-Threads) |
|
|
| **Author-Gruppe** | | |
|
|
| author.name | text | Autorname |
|
|
| author.handle | text | @handle |
|
|
| author.isVerified | checkbox | Verifizierter Account? |
|
|
| author.isSubscriber | checkbox | Abonnent? |
|
|
| author.subscriberCount | number | Follower des Autors |
|
|
| **Inhalt** | | |
|
|
| message | textarea | Nachrichtentext |
|
|
| messageHtml | textarea | HTML-Version |
|
|
| publishedAt | date | Veröffentlichungsdatum |
|
|
| attachments | array | Bilder, Videos |
|
|
| **KI-Analyse** | | |
|
|
| analysis.sentiment | select | positive / neutral / negative / mixed |
|
|
| analysis.sentimentScore | number | -1.0 bis 1.0 |
|
|
| analysis.confidence | number | 0-100% |
|
|
| analysis.topics | array | Erkannte Themen |
|
|
| analysis.suggestedTemplate | relationship | → community-templates |
|
|
| analysis.suggestedReply | textarea | KI-generierter Antwortvorschlag |
|
|
| **Flags** | | |
|
|
| flags.isMedicalQuestion | checkbox | Medizinische Frage? |
|
|
| flags.requiresEscalation | checkbox | Eskalation nötig? |
|
|
| flags.isSpam | checkbox | Spam? |
|
|
| flags.isFromInfluencer | checkbox | Von Influencer? |
|
|
| **Workflow** | | |
|
|
| status | select | new / read / in_progress / awaiting / responded / closed |
|
|
| priority | select | urgent / high / normal / low |
|
|
| assignedTo | relationship | → users |
|
|
| responseDeadline | date | Antwort-Frist |
|
|
| **Antwort** | | |
|
|
| response.text | textarea | Gesendete Antwort |
|
|
| response.usedTemplate | relationship | → community-templates |
|
|
| response.sentAt | date | Gesendet am |
|
|
| response.sentBy | relationship | → users |
|
|
| **Engagement** | | |
|
|
| engagement.likes | number | Likes |
|
|
| engagement.replies | number | Anzahl Antworten |
|
|
| engagement.isHearted | checkbox | Geherzt? |
|
|
| engagement.isPinned | checkbox | Angepinnt? |
|
|
|
|
**Hooks:**
|
|
- `beforeChange`: Setzt automatisch `priority: urgent` wenn `flags.isMedicalQuestion` oder `flags.requiresEscalation`
|
|
|
|
---
|
|
|
|
### 4. CommunityTemplates (`community-templates`)
|
|
|
|
**Zweck:** Vordefinierte Antwortvorlagen.
|
|
|
|
**Pfad:** `src/collections/CommunityTemplates.ts`
|
|
|
|
**Felder:**
|
|
| Feld | Typ | Beschreibung |
|
|
|------|-----|--------------|
|
|
| name | text (localized) | Template-Name |
|
|
| template | textarea (localized) | Antworttext mit Variablen |
|
|
| category | select | greeting / thank_you / question / support / medical / promotion |
|
|
| platforms | relationship | → social-platforms (hasMany) |
|
|
| channel | relationship | → youtube-channels |
|
|
| variables | array | Verfügbare Variablen |
|
|
| variables.variable | text | z.B. `{{author_name}}` |
|
|
| variables.description | text | Beschreibung |
|
|
| variables.defaultValue | text | Fallback-Wert |
|
|
| autoSuggestKeywords | array | Keywords für Auto-Suggest |
|
|
| requiresReview | checkbox | Muss vor Senden geprüft werden? |
|
|
| usageCount | number | Verwendungszähler |
|
|
|
|
**Lokalisierung:** `name` und `template` sind mehrsprachig (de/en).
|
|
|
|
---
|
|
|
|
### 5. CommunityRules (`community-rules`)
|
|
|
|
**Zweck:** Automatisierungsregeln für eingehende Interaktionen.
|
|
|
|
**Pfad:** `src/collections/CommunityRules.ts`
|
|
|
|
**Felder:**
|
|
| Feld | Typ | Beschreibung |
|
|
|------|-----|--------------|
|
|
| name | text | Regelname |
|
|
| priority | number | Ausführungsreihenfolge (niedrig = zuerst) |
|
|
| isActive | checkbox | Regel aktiv? |
|
|
| platforms | relationship | → social-platforms (hasMany) |
|
|
| channel | relationship | → youtube-channels |
|
|
| **Trigger** | | |
|
|
| trigger.type | select | keyword / sentiment / influencer / medical / new_subscriber |
|
|
| trigger.keywords | array | Keyword-Liste mit Match-Typ |
|
|
| trigger.sentimentValues | array | positive / negative / mixed |
|
|
| trigger.influencerMinFollowers | number | Min. Follower für Influencer |
|
|
| **Actions** | | |
|
|
| actions | array | Auszuführende Aktionen |
|
|
| actions.action | select | set_priority / assign_to / apply_template / flag / auto_reply / notify |
|
|
| actions.value | text | Wert (z.B. "urgent") |
|
|
| actions.targetUser | relationship | → users |
|
|
| actions.targetTemplate | relationship | → community-templates |
|
|
| **Stats** | | |
|
|
| stats.timesTriggered | number | Ausführungszähler |
|
|
| stats.lastTriggeredAt | date | Letzte Ausführung |
|
|
|
|
---
|
|
|
|
## Access Control
|
|
|
|
**Datei:** `src/lib/communityAccess.ts`
|
|
|
|
### Rollen-Hierarchie
|
|
|
|
```
|
|
communityRole:
|
|
none → Kein Zugriff
|
|
viewer → Nur Lesen
|
|
moderator → Lesen + Bearbeiten zugewiesener Interaktionen
|
|
manager → Vollzugriff (CRUD auf alle Community-Collections)
|
|
```
|
|
|
|
### Access Functions
|
|
|
|
| Funktion | Beschreibung |
|
|
|----------|--------------|
|
|
| `isCommunityManager` | Prüft `communityRole === 'manager'` oder `isSuperAdmin` |
|
|
| `isCommunityModeratorOrAbove` | Prüft `communityRole in ['moderator', 'manager']` |
|
|
| `hasCommunityAccess` | Prüft `communityRole !== 'none'` |
|
|
| `canAccessAssignedInteractions` | Moderator sieht nur zugewiesene Interaktionen |
|
|
|
|
### Integration mit YouTube-Rollen
|
|
|
|
Community-Rollen ergänzen die bestehenden YouTube-Rollen:
|
|
- Ein User kann `youtubeRole: 'manager'` UND `communityRole: 'moderator'` haben
|
|
- Super-Admins haben automatisch vollen Zugriff
|
|
|
|
---
|
|
|
|
## Integration Services
|
|
|
|
### YouTubeClient
|
|
|
|
**Datei:** `src/lib/integrations/youtube/YouTubeClient.ts`
|
|
|
|
**Abhängigkeit:** `googleapis`
|
|
|
|
```typescript
|
|
class YouTubeClient {
|
|
constructor(accessToken: string, refreshToken?: string)
|
|
|
|
// Kommentare abrufen
|
|
async getVideoComments(videoId: string, maxResults?: number)
|
|
async getChannelComments(channelId: string, maxResults?: number)
|
|
|
|
// Aktionen
|
|
async replyToComment(parentId: string, text: string)
|
|
async markAsSpam(commentId: string)
|
|
async deleteComment(commentId: string)
|
|
|
|
// Token Management
|
|
async refreshAccessToken(): Promise<string>
|
|
|
|
// Stats
|
|
async getChannelStats(channelId: string)
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### ClaudeAnalysisService
|
|
|
|
**Datei:** `src/lib/integrations/claude/ClaudeAnalysisService.ts`
|
|
|
|
**Abhängigkeit:** `@anthropic-ai/sdk`
|
|
|
|
```typescript
|
|
interface CommentAnalysis {
|
|
sentiment: 'positive' | 'neutral' | 'negative' | 'mixed'
|
|
sentimentScore: number // -1.0 bis 1.0
|
|
confidence: number // 0-100
|
|
topics: string[]
|
|
isMedicalQuestion: boolean
|
|
requiresEscalation: boolean
|
|
isSpam: boolean
|
|
suggestedReply?: string
|
|
language: string
|
|
}
|
|
|
|
class ClaudeAnalysisService {
|
|
constructor(apiKey?: string)
|
|
|
|
async analyzeComment(
|
|
comment: string,
|
|
context?: { channelName?: string; videoTitle?: string }
|
|
): Promise<CommentAnalysis>
|
|
|
|
async generateReply(
|
|
comment: string,
|
|
template?: string,
|
|
context?: object
|
|
): Promise<string>
|
|
|
|
async analyzeCommentsBatch(
|
|
comments: Array<{ id: string; text: string }>
|
|
): Promise<Map<string, CommentAnalysis>>
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### CommentsSyncService
|
|
|
|
**Datei:** `src/lib/integrations/youtube/CommentsSyncService.ts`
|
|
|
|
**Orchestriert** YouTubeClient + ClaudeAnalysisService:
|
|
|
|
```typescript
|
|
class CommentsSyncService {
|
|
constructor(payload: Payload)
|
|
|
|
async syncCommentsForAccount(
|
|
socialAccountId: number,
|
|
options?: {
|
|
maxComments?: number
|
|
analyzeWithAI?: boolean
|
|
}
|
|
): Promise<SyncResult>
|
|
}
|
|
```
|
|
|
|
**Ablauf:**
|
|
1. Social Account laden
|
|
2. YouTube-Kommentare abrufen
|
|
3. Für jeden neuen Kommentar:
|
|
- Claude-Analyse durchführen
|
|
- CommunityInteraction erstellen/aktualisieren
|
|
4. Sync-Timestamp aktualisieren
|
|
|
|
---
|
|
|
|
## API Endpoints
|
|
|
|
### POST `/api/community/sync-comments`
|
|
|
|
**Zweck:** Manueller Kommentar-Sync für einen Account.
|
|
|
|
**Auth:** Erforderlich (communityRole >= moderator)
|
|
|
|
**Body:**
|
|
```json
|
|
{
|
|
"socialAccountId": 1,
|
|
"maxComments": 100,
|
|
"analyzeWithAI": true
|
|
}
|
|
```
|
|
|
|
**Response:**
|
|
```json
|
|
{
|
|
"success": true,
|
|
"synced": 47,
|
|
"created": 12,
|
|
"updated": 35,
|
|
"errors": []
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### POST `/api/community/reply`
|
|
|
|
**Zweck:** Antwort auf eine Interaktion senden.
|
|
|
|
**Auth:** Erforderlich (communityRole >= moderator)
|
|
|
|
**Body:**
|
|
```json
|
|
{
|
|
"interactionId": 123,
|
|
"text": "Vielen Dank für Ihren Kommentar!",
|
|
"templateId": 5
|
|
}
|
|
```
|
|
|
|
**Response:**
|
|
```json
|
|
{
|
|
"success": true,
|
|
"externalReplyId": "Ugw8x7y9z..."
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Datenbank-Schema
|
|
|
|
### Haupt-Tabellen
|
|
|
|
| Tabelle | Beschreibung |
|
|
|---------|--------------|
|
|
| `social_platforms` | Plattform-Definitionen |
|
|
| `social_accounts` | Account-Konfigurationen |
|
|
| `community_interactions` | Alle Interaktionen |
|
|
| `community_templates` | Antwortvorlagen |
|
|
| `community_templates_locales` | Lokalisierte Felder |
|
|
| `community_rules` | Automatisierungsregeln |
|
|
|
|
### Array-Tabellen
|
|
|
|
| Tabelle | Parent |
|
|
|---------|--------|
|
|
| `social_platforms_api_config_scopes` | social_platforms |
|
|
| `social_platforms_interaction_types` | social_platforms |
|
|
| `community_interactions_attachments` | community_interactions |
|
|
| `community_interactions_analysis_topics` | community_interactions |
|
|
| `community_templates_variables` | community_templates |
|
|
| `community_templates_auto_suggest_keywords` | community_templates |
|
|
| `community_rules_trigger_keywords` | community_rules |
|
|
| `community_rules_trigger_sentiment_values` | community_rules |
|
|
| `community_rules_actions` | community_rules |
|
|
|
|
### Relationship-Tabellen
|
|
|
|
| Tabelle | Beschreibung |
|
|
|---------|--------------|
|
|
| `community_templates_rels` | Templates ↔ Platforms |
|
|
| `community_rules_rels` | Rules ↔ Platforms |
|
|
|
|
### Users-Erweiterung
|
|
|
|
```sql
|
|
ALTER TABLE users ADD COLUMN community_role enum_users_community_role;
|
|
-- Values: 'none', 'viewer', 'moderator', 'manager'
|
|
```
|
|
|
|
---
|
|
|
|
## Migrationen
|
|
|
|
| Migration | Beschreibung |
|
|
|-----------|--------------|
|
|
| `20260113_180000_add_community_phase1` | Erstellt alle Community-Tabellen |
|
|
| `20260114_200000_fix_community_role_enum` | Konvertiert community_role zu ENUM |
|
|
|
|
---
|
|
|
|
## Umgebungsvariablen
|
|
|
|
```env
|
|
# YouTube API (für Comment-Sync)
|
|
YOUTUBE_CLIENT_ID=your-client-id
|
|
YOUTUBE_CLIENT_SECRET=your-client-secret
|
|
|
|
# Claude AI (für Sentiment-Analyse)
|
|
ANTHROPIC_API_KEY=your-api-key
|
|
```
|
|
|
|
---
|
|
|
|
## Erweiterungsmöglichkeiten
|
|
|
|
### Neue Plattform hinzufügen
|
|
|
|
1. **SocialPlatform erstellen** im Admin
|
|
2. **Client-Klasse implementieren** in `src/lib/integrations/{platform}/`
|
|
3. **SyncService erweitern** für neue Plattform
|
|
|
|
### Neue Automatisierungsregel
|
|
|
|
1. **Trigger-Typ hinzufügen** in `CommunityRules.ts`
|
|
2. **Action-Handler implementieren** im Rules-Engine (noch zu implementieren)
|
|
|
|
### Dashboard (Phase 2)
|
|
|
|
Geplante Features:
|
|
- Interaktions-Inbox mit Filtern
|
|
- Sentiment-Übersicht (Charts)
|
|
- Response-Time-Tracking
|
|
- Team-Performance-Metriken
|
|
|
|
---
|
|
|
|
## Dateien-Übersicht
|
|
|
|
```
|
|
src/
|
|
├── collections/
|
|
│ ├── SocialPlatforms.ts
|
|
│ ├── SocialAccounts.ts
|
|
│ ├── CommunityInteractions.ts
|
|
│ ├── CommunityTemplates.ts
|
|
│ ├── CommunityRules.ts
|
|
│ └── Users.ts (erweitert um communityRole)
|
|
├── lib/
|
|
│ ├── communityAccess.ts
|
|
│ └── integrations/
|
|
│ ├── youtube/
|
|
│ │ ├── YouTubeClient.ts
|
|
│ │ └── CommentsSyncService.ts
|
|
│ └── claude/
|
|
│ └── ClaudeAnalysisService.ts
|
|
├── app/(payload)/api/community/
|
|
│ ├── sync-comments/route.ts
|
|
│ └── reply/route.ts
|
|
└── migrations/
|
|
├── 20260113_180000_add_community_phase1.ts
|
|
└── 20260114_200000_fix_community_role_enum.ts
|
|
```
|