Instagram & Collector Services

Die Instagram-Datenerhebung erfolgt asynchron über einen externen Collector-Service. Die Services in diesem Bereich verwalten das Job-Dispatching, die Ergebnis-Verarbeitung und die Keyword-Extraktion für Instagram-Profile.

CollectorJobDispatcher

Location: app/Services/Collector/CollectorJobDispatcher.php

Erstellt Collector-Jobs in der collector_jobs-Tabelle und steuert die Priorität. Der externe Collector pollt diese Tabelle via REST-API, least Jobs und meldet Ergebnisse zurück.

Public Methods

Method	Parameter	Return	Beschreibung
dispatch()	string $source, string $handle, string $jobType, array $payload = [], int $priority = 0	CollectorJob	Collector-Job erstellen

Job-Typen

Job Type	Beschreibung	Priorität
daily_scrape	Tägliches Profil-Update	Konfigurierbar via postbox.instagram_priority_*
watcher_import	Neues Profil importieren (User-Aktion)	Höchste Priorität (50)
profile_retry	Retry eines deaktivierten Profils	Niedrige Priorität

Job-Lifecycle

dispatch() → Queued → Leased (Collector pollt) → Completed/Failed

1. dispatch() erstellt einen CollectorJob mit Status Queued
2. Collector-API least den Job (Status -> Leased, leased_by gesetzt)
3. Collector meldet Ergebnis: Completed mit Payload oder Failed mit Fehler
4. InstagramDailyScrapeProcessor oder InstagramWatcherImportProcessor verarbeitet das Ergebnis

Prioritäts-System

Jobs werden in Reihenfolge der Priorität geleased (höhere Zahl = höhere Priorität):

• Priority 50: Watcher-Import (User wartet aktiv)
• Priority 30: Rescrape nach Follower-Range
• Priority 10: Daily Scrape (Standard)
• Priority 0: Profile Retry, Background-Tasks

Abhängigkeiten

• CollectorJob Model, Config (postbox.instagram_priority_*)

Verwendet von

• QueueDailyInstagramScrapes-Command, Watcher-Import, RetryInactiveProfiles-Command

InstagramWatcherImportProcessor

Location: app/Services/Collector/InstagramWatcherImportProcessor.php

Verarbeitet abgeschlossene Collector-Jobs vom Typ watcher_import. Erstellt oder aktualisiert das SocialProfile, legt die erste SocialProfileDailyMetric an und verknüpft das Profil mit dem Watcher.

Public Methods

Method	Parameter	Return	Beschreibung
handleCompletion()	CollectorJob $job	void	Erfolgreichen Import verarbeiten
handleFailure()	CollectorJob $job	void	Fehlgeschlagenen Import verarbeiten

Ablauf handleCompletion()

1. Collector-Payload parsen (Follower, Following, Posts, Bio, etc.)
2. SocialProfile erstellen oder aktualisieren (Deduplizierung via Handle)
3. SocialProfileDailyMetric für heute anlegen
4. Profil-Bild herunterladen via ProfileImageUpdater
5. Bio parsen via ProfileDescriptionParser
6. Keywords extrahieren via ProfileKeywordExtractor
7. WatcherSource mit dem Profil verknüpfen
8. Admin-Workspace-Spiegelung via AdminWorkspaceManager::ensureProfileWatcher()
9. WatcherImportProgress-Event dispatchen (WebSocket)

Fehlerbehandlung (handleFailure())

• Job wird als Failed markiert
• WatcherImportProgress-Event mit Fehlerstatus dispatchen
• Kein Retry auf Processor-Ebene (Collector hat eigene Retry-Logik)

Abhängigkeiten

• ProfileImageUpdater, ProfileDescriptionParser, ProfileKeywordExtractor, AdminWorkspaceManager
• WatcherImportProgress Event

Verwendet von

• CollectorJobsController (API-Callback bei Job-Completion)

InstagramDailyScrapeProcessor

Location: app/Services/Collector/InstagramDailyScrapeProcessor.php

Verarbeitet die Ergebnisse täglicher Instagram-Scrapes. Aktualisiert Metriken, Bio-Daten, Profil-Bilder und erkennt Profilname-Änderungen.

Public Methods

Method	Parameter	Return	Beschreibung
handleCompletion()	CollectorJob $job	void	Erfolgreichen Daily Scrape verarbeiten
handleFailure()	CollectorJob $job	void	Fehlgeschlagenen Daily Scrape verarbeiten

Ablauf handleCompletion()

1. Collector-Payload parsen
2. SocialProfileDailyMetric erstellen/aktualisieren (Follower, Following, Posts)
3. Profil-Daten aktualisieren (Title, Description, is_private, is_verified, profile_type)
4. Bio-Änderung erkennen und ProfileDescriptionParser ausführen
5. Profil-Bild aktualisieren falls URL geändert
6. Keywords aktualisieren via ProfileKeywordExtractor
7. Related Profiles aus Collector-Payload verarbeiten (falls vorhanden)
8. Fail-Streak auf 0 zurücksetzen bei erfolgreichem Scrape
9. DailyScrapeCompleted-Event dispatchen für WebSocket-Notification

Fail-Streak-Logik (handleFailure())

• fail_streak Counter inkrementieren
• Bei Überschreitung des konfigurierten Thresholds: deactivated_at setzen
• Deaktivierte Profile werden vom RetryInactiveProfiles-Command nach konfigurierten Intervallen erneut versucht

Abhängigkeiten

• ProfileImageUpdater, ProfileDescriptionParser, ProfileKeywordExtractor
• DailyScrapeCompleted Event

Verwendet von

• CollectorJobsController (API-Callback bei Job-Completion)

ProfileKeywordExtractor

Location: app/Services/Instagram/ProfileKeywordExtractor.php

Extrahiert relevante Keywords aus Instagram-Profil-Daten (Bio, Handle, Username) und speichert sie in der instagram_profile_keywords-Tabelle. Diese Keywords werden für Cross-Platform-Matching und Kategorie-Erkennung verwendet.

Public Methods

Method	Parameter	Return	Beschreibung
extractAndStore()	SocialProfile $profile	array	Keywords extrahieren und in DB speichern
extract()	SocialProfile $profile	array	Keywords extrahieren (ohne Speicherung)
extractFromText()	string $text	array	Keywords aus beliebigem Text extrahieren
extractFromHandle()	string $handle	array	Keywords aus Handle/Username extrahieren

Extraktions-Quellen

Quelle	Beispiel	Gewicht
Bio-Text	"Fashion Blogger aus Berlin"	Hoch
Handle	fashion_blogger_de	Mittel
Username/Title	"Lisa Fashion"	Mittel

Keyword-Verarbeitung

• Stopwords werden gefiltert (deutsch + englisch)
• Mindestlänge: 3 Zeichen
• Normalisierung auf Lowercase
• Handle-Splitting: fashion_blogger -> ["fashion", "blogger"]

Abhängigkeiten

• InstagramProfileKeyword Model

Verwendet von

• InstagramDailyScrapeProcessor, InstagramWatcherImportProcessor, CrossPlatformRelatedCalculator, DetectChannelLanguages-Command