Models Übersicht
Postbox verwendet 79 Eloquent Models, verteilt auf 7 Domänen. Zusätzlich existieren 3 Tabellen ohne dediziertes Model (dashboard_leaderboard_snapshots, dashboard_global_snapshots, queue_metrics), die per Query Builder angesprochen werden.
Location: app/Models/
Alle Models nach Domäne
Core
| Model | Tabelle | Wichtige Relations | Beschreibung |
|---|---|---|---|
SocialProfile | social_profiles | metrics, images, latestImage, scores, youtubeVideos, watcherSources, contactLinks, exploreMetrics, relatedChannels, relatedProfiles, crossPlatformRelated | Zentrales Profil-Model (YouTube/Instagram) |
SocialProfileDailyMetric | social_profile_daily_metrics | profile | Tägliche Follower/View/Video-Metriken |
SocialProfileImage | social_profile_images | profile | Profilbilder mit Varianten (path_large 512px, path_medium 256px, path_thumbnail 128px, BlurHash) |
SocialProfileLink | social_profile_links | socialProfile, approver | Kontakt-Links (URL, E-Mail, Social) |
SocialProfileScore | social_profile_scores | profile | Score-Verlauf (0–100, tier-normalisiert) |
ProfileComparison | profile_comparisons | user, workspace, items, snapshots | Gespeicherte 2–4-Profil-Vergleiche mit optionalen wöchentlichen Reminders |
ProfileComparisonItem | profile_comparison_items | comparison, socialProfile | Einzelnes Profil in einem Vergleich (Position 1–4, feste Chart-Farbe) |
ProfileComparisonSnapshot | profile_comparison_snapshots | comparison, overallLeader | Historischer Snapshot für Vergleichs-Trends und wöchentliche Reminder |
Watcher
| Model | Tabelle | Wichtige Relations | Beschreibung |
|---|---|---|---|
Watcher | watchers | workspace, creator, sources, primarySource | Sammlung beobachteter Profile |
WatcherSource | watcher_sources | watcher, profile | Verknüpfung Watcher ↔ SocialProfile |
WatcherImportRun | watcher_import_runs | failures, items | Bulk-Import-Durchlauf |
WatcherImportItem | watcher_import_items | run | Einzelne URL im Import |
WatcherImportFailure | watcher_import_failures | run | Fehlgeschlagene Import-URL |
YouTube
| Model | Tabelle | Wichtige Relations | Beschreibung |
|---|---|---|---|
YouTubeVideo | youtube_videos | profile, dailyMetrics, scores, latestScore | Video-Metadaten (PK: video_id string) |
YouTubeVideoDailyMetric | youtube_video_daily_metrics | video | Tägliche Video-Statistiken |
YouTubeVideoScore | youtube_video_scores | video, profile | Video-Score (View Perf. + Engagement + Growth + Freshness) |
YouTubeVideoSync | youtube_video_syncs | profile, requester | Sync-Status für Video-Pipeline |
YouTubeRelatedChannel | youtube_related_channels | sourceProfile, relatedProfile | Verwandte YouTube-Channels |
YouTubeResearchQuery | youtube_research_queries | — | Gespeicherte Recherche-Abfragen |
YouTubeResearchKeywordCooldown | youtube_research_keyword_cooldowns | — | 14-Tage-Cooldown für verwendete Research-Keywords |
YouTubeVideoStatsDailyAggregation | youtube_video_stats_daily_aggregations | — | Tägliche Aggregation der Video-Stats-Coverage mit Gründe-Breakdown und Health-Score |
YouTubePublishingWeeklyStat | youtube_publishing_weekly_stats | socialProfile | Aggregierte Publishing-Statistiken pro Channel/Wochentag (VFR, Engagement, Stunden) |
WebSubSubscription | websub_subscriptions | socialProfile | WebSub-Subscription für YouTube-Push-Notifications mit Lease-Renewal |
PendingYouTubeChannelImport | pending_you_tube_channel_imports | sourceProfile | Import-Queue für entdeckte Channels |
Instagram
| Model | Tabelle | Wichtige Relations | Beschreibung |
|---|---|---|---|
CollectorJob | collector_jobs | leasedBy | Scraping-Auftrag (UUID-basiert) |
CollectorClient | collector_clients | leasedJobs | Authentifizierter Scraping-Client (Sanctum) |
InstagramProfileKeyword | instagram_profile_keywords | socialProfile | Extrahierte Keywords aus Profil-Bio |
InstagramRelatedProfile | instagram_related_profiles | sourceProfile, relatedProfile | Verwandte Instagram-Profile |
Dashboard & Explore
| Model | Tabelle | Wichtige Relations | Beschreibung |
|---|---|---|---|
DashboardDailyRollup | dashboard_daily_rollups | — | Aggregierte Tagesmetriken pro Watcher/Profil |
DailyScrapeProgress | daily_scrape_progress | user | Fortschritt des täglichen Scraping pro User |
DailySyncRun | daily_sync_runs | — | Status eines Sync-Durchlaufs (Datum-basiert) |
ExploreProfileMetric | explore_profile_metrics | socialProfile | Growth-, Trending- und Tier-Metriken |
ExploreTrendingVideo | explore_trending_videos | socialProfile, latestScore | Trending-Videos für Explore-Seite |
ExploreCategory | explore_categories | — | Kategorien für Explore-Filterung |
CrossPlatformRelatedProfile | cross_platform_related_profiles | sourceProfile, relatedProfile | Plattformübergreifende Profil-Verknüpfung |
ExploreDailySnapshot | explore_daily_snapshots | — | Täglicher Snapshot des Explore-Inventars (Profil-Counts, Plattform-Split, Tier-Verteilung) |
PublicExplorerProfile | public_explorer_profiles | socialProfile | Öffentliches Explorer-Profil mit AI-Beschreibungen (DE/EN), Kategorie, OG-Image-Pfad |
OgImageLog | og_image_logs | publicExplorerProfile | Protokoll der OG-Image-Generierung (Status, Dauer, Fehlerdetails) |
User & Notification
| Model | Tabelle | Wichtige Relations | Beschreibung |
|---|---|---|---|
User | users | workspaces, notificationPreferences, quietHours, notifications | Benutzer (WorkOS SSO) |
Workspace | workspaces | owner, watchers | Workspace mit Watchers |
FavoriteSocialProfile | favorite_social_profiles | user, profile | Favorisierte Profile |
UserQuietHours | user_quiet_hours | user | Ruhezeiten-Konfiguration |
NotificationPreference | notification_preferences | user, workspace | Benachrichtigungs-Einstellungen |
NotificationStat | notification_stats | — | Aggregierte Benachrichtigungs-Statistiken |
Announcement | announcements | reads | Geteilte Benachrichtigungen (1:n Reads) |
AnnouncementRead | announcement_reads | user, announcement | Read/Dismiss-Status |
DatabaseNotification | notifications | — | Per-User Notification (extends Laravel) |
UserBlock | user_blocks | user, admin | Audit-Log für User-Block/Unblock-Aktionen mit Grund |
PersonalAccessToken | personal_access_tokens | revokedByUser, usageLogs | Custom Sanctum-Token mit Soft-Revoke, IP-Whitelist und stündlichem Usage-Tracking |
SearchHistory | search_history | user | User-Suchverlauf (max. 25 Einträge mit Auto-Pruning) |
Admin & System
| Model | Tabelle | Wichtige Relations | Beschreibung |
|---|---|---|---|
BlockedTag | blocked_tags | blocker | Gesperrte Tags mit Cache |
TagAlias | tag_aliases | — | Tag-Umbenennungen mit Cache |
TagConsolidationLog | tag_consolidation_logs | — | Protokoll Tag-Konsolidierung (MassPrunable) |
GoogleApiQuotaLimit | google_api_quota_limits | — | YouTube API Quota-Limits |
GoogleApiQuotaUsage | google_api_quota_usages | — | YouTube API Quota-Verbrauch |
AiDetectionLog | ai_detection_logs | socialProfile | Protokoll AI-Erkennung (Sprache/Land) |
AiManualOverrideLog | ai_manual_override_logs | socialProfile, user | Audit-Log für Admin-Overrides von AI-Feldern |
ApiTokenUsageLog | api_token_usage_logs | personalAccessToken | Stündliche API-Token-Request-Aggregation (90 Tage Retention) |
ContactSubmission | contact_submissions | user (optional) | Archiv der Kontaktformular-Einreichungen mit Anhängen und E-Mail-Status |
CronHeartbeatEvent | cron_heartbeat_events | — | Cron-Heartbeat-Zustandsänderungen für SLA-Berechnung (30 Tage Retention) |
DbMonitoringSnapshot | db_monitoring_snapshots | — | PostgreSQL-Systemmetriken alle 15 Min. (Connections, Locks, Cache-Hit-Ratio) |
DbSlowQueryLog | db_slow_query_log | — | Stündliche Snapshots der Top-Slow-Queries aus pg_stat_statements |
DbTableSizeSnapshot | db_table_size_snapshots | — | 15-Min-Snapshots der Top-10-Tabellen nach Größe für DB-Monitoring |
DismissedErrorPath | dismissed_error_paths | dismisser | Markiert Fehlerpfade als „kein Redirect nötig" + optional stummgeschaltet |
ErrorPageDailyStat | error_page_daily_stats | — | Tägliches Rollup der Error-Page-Logs für Chart-Anzeige |
ErrorPageLog | error_page_logs | — | 1 Zeile pro Pfad+Status+Stunde mit Hit-Count (PostgreSQL UPSERT) |
HealthCheckLog | health_check_logs | — | Temporäres Health-Check-Kalibrierungs-Log (14 Tage Retention) |
IndexNowSubmission | index_now_submissions | — | Tracking aller an IndexNow gesendeten URLs (30 Tage Retention) |
MailLog | mail_log | user | E-Mail-Versandprotokoll |
Page | pages | creator, updater | CMS-Seiten (Auditable) mit EN/DE-Feldern |
PipelineRun | pipeline_runs | — | Persistente Pipeline-Step-Ausführungen (1 pro Step/Tag) für Trend-Analyse |
R2MetricSnapshot | r2_metric_snapshots | — | Täglicher R2-Bucket-Metriken-Snapshot (unbegrenzte Retention) |
R2MetricHourlySnapshot | r2_metric_hourly_snapshots | — | Stündlicher R2-Metriken-Snapshot für Intraday-Trends (1 Jahr Retention) |
SearchConsoleMetric | search_console_metrics | — | Tägliche Google-Search-Console-Metriken pro URL/Query (Clicks, Impressions, CTR) |
ServerMetric | server_metrics | — | Server-Metriken alle 5 Min. (CPU, RAM, Swap, Disk, PG) — 90 Tage Retention |
ServerMetricHourly | server_metrics_hourly | — | Stündliche Aggregation der Server-Metriken (365 Tage Retention) |
SitemapDailySnapshot | sitemap_daily_snapshots | — | Täglicher Snapshot der Sitemap-Generierung (URL-Counts, Dateigröße, Validierung) |
UrlRedirect | url_redirects | creator | URL-Redirect mit Regex-Support und Hit-Counter (HandleRedirects Middleware) |
WebVitalMetric | web_vitals_metrics | — | Aggregierte Web-Vitals-Metriken pro URL und Metrik-Name (LCP, FID, CLS) |
Tabellen ohne Model
| Tabelle | Verwendet in | Beschreibung |
|---|---|---|
dashboard_leaderboard_snapshots | BuildDashboardLeaderboardSnapshots, LeaderboardPriorityService | Tägliche Top-100-Snapshots |
dashboard_global_snapshots | BuildGlobalLeaderboardSnapshots, TopsFlops/Index | Globale Leaderboard-Daten |
queue_metrics | SnapshotQueueMetrics, QueueMetricsChart | Queue-Performance-Metriken |
SocialProfile Status-Hierarchie
Das zentrale SocialProfile-Model besitzt mehrere unabhängige Status-Flags, die verschiedene Aspekte des Profil-Lifecycles steuern:
| Flag | Typ | Gesetzt durch | Bedeutung | Ausschluss von |
|---|---|---|---|---|
blocked_at | datetime | Admin manuell | Admin-Sperre | Explore, Related, Scoring, Scraping |
sanitized_at | datetime | profiles:sanitize Command | Auto-Deaktivierung (Low-Value-Metriken) | Explore, Related, Scoring, Scraping |
deactivated_at | datetime | Collector-Jobs (Fail-Streak) | Scraping-Fehler, Retry-Lifecycle | Scraping |
archived_at | datetime | profiles:retry-inactive | Permanent archiviert (>6 Monate inaktiv) | Alles (kein Retry) |
tracking_enabled | boolean | Diverse Systeme | Master-Schalter für Tracking | Scraping, Scoring |
Scopes
// Nur nicht-gesperrte Profile
SocialProfile::notBlocked() // whereNull('blocked_at')
// Nur nicht-sanitized Profile
SocialProfile::notSanitized() // whereNull('sanitized_at')
// Ausschluss aller inaktiven Profile (für Explore, Related, Leaderboards)
SocialProfile::notExcluded() // whereNull('blocked_at') + whereNull('sanitized_at') + whereNull('archived_at')
Admin Override (Sanitizer)
Wenn ein Admin ein sanitized Profil über enableTracking() reaktiviert, wird sanitize_checked_at beibehalten. Der Sanitizer überspringt Profile mit sanitize_checked_at IS NOT NULL AND sanitized_at IS NULL -- permanenter Schutz vor erneuter Auto-Deaktivierung.
Ausschluss-Filter (Pflicht)
Bei allen öffentlich sichtbaren Queries (Explore, Related Channels/Profiles, Leaderboards) muss notExcluded() oder ein manueller whereNull-Check verwendet werden:
// Explore / Related / Leaderboards
SocialProfile::notExcluded()->where(...)
// Related-Profile mit Eager Loading
->whereHas('relatedProfile', fn ($q) => $q
->whereNull('blocked_at')
->whereNull('sanitized_at')
->whereNull('archived_at')
)
Location: app/Models/SocialProfile.php