Cron-Events und Scheduler

Dieses Dokument beschreibt die WP-Cron-Events, die das Plugin ADP Car Market Hub plant, die benutzerdefinierten Intervalle, die es registriert, und die Sperrstrategie (Locking), die überschneidende Ausführungen verhindert.

Wann Sie dieses Dokument verwenden sollten

Lesen Sie dieses Dokument, wenn Sie Folgendes tun müssen:

• Automatische Importe im Admin-Tab Automatisierung konfigurieren.
• Einen externen System-Cron einrichten, um Importe zuverlässig auszulösen.
• Ausgefallene, überlappende oder blockierte Importläufe diagnostizieren.
• Produktions-Deployments planen, bei denen WP-Cron zugunsten eines echten Cronjobs deaktiviert ist.

Für die Importlogik pro Fahrzeug siehe Import-Engine. Für die Funktionsweise der Bildwarteschlange siehe Bild-Importer und Warteschlange.

Übersicht

Das Plugin verwendet zwei komplementäre Trigger-Pfade:

• WP-Cron — der in WordPress integrierte Pseudo-Cron, der durch Frontend-Seitenaufrufe ausgelöst wird. Das Plugin registriert hier Cron-Hooks und benutzerdefinierte Intervalle.
• REST-Cron-Endpunkt — GET /wp-json/as24ci/v1/cron-import, authentifiziert durch ein Token, ermöglicht es einem echten System-Cron, Importe selbst auf Websites mit geringem Traffic auszulösen.

Beide Pfade rufen denselben gemeinsamen Runner auf, AS24CI\Scheduler::run_import(), der eine temporäre Sperre (Transient Lock) erwirbt, an den Importer delegiert, optional Full-Sync-Löschungen durchführt, den Bild-Warteschlangen-Worker plant und den Durchlauf protokolliert.

Vom Plugin registrierte Cron-Hooks

AS24CI\Scheduler wird während des Bootstraps von AS24CI\Plugin instanziiert und registriert die folgenden WordPress-Hooks:

Zusätzlich registriert die Hauptdatei des Plugins (adp-car-market-hub.php) einen separaten Filter cron_schedules, der das Intervall as24ci_every_5_minutes (300 Sekunden) bedingungslos hinzufügt – nützlich für die KI-Warteschlange und alle benutzerdefinierten Integrationen, die einen Takt von unter einer Stunde benötigen.

Andere Plugin-Subsysteme planen ihre eigenen Events unabhängig:

• as24ci_daily_cleanup — tägliche Bereinigung der Analytics-Aufbewahrung, verwaltet von AS24CI\Analytics. Bei der Aktivierung geplant und bei der Deaktivierung entfernt.
• Preisfindungs-Engine-Cron — täglich, verwaltet von AS24CI\Pricing_Engine (Hook-Tag as24ci_pricing_analysis_cron). Geplant, wenn die Funktion aktiviert ist, und bei Deaktivierung gelöscht.
• Datenqualitäts-Scanner — läuft nach eigenem Zeitplan (Hook-Tag as24ci_automated_taxonomy_scan, verwaltet von AS24CI\Data_Quality_Scanner), gesteuert durch as24ci_dq_scan_frequency und as24ci_dq_scan_time.
• KI-Warteschlangen-Worker — Hook-Tag as24ci_process_ai_queue, verwaltet von AS24CI\Ai_Assistant. Bedingungslos gebunden; geplant im Intervall as24ci_every_5_minutes nur, wenn der KI-Assistent aktiviert ist, und bei Deaktivierung gelöscht.
• Lizenz-Revalidierung — Hook-Tag as24ci_license_refresh, verwaltet von AS24CI\License_Manager. Geplant daily bei Aktivierung (und über eine Selbstheilung admin_init) und gelöscht bei Deaktivierung. Dies ist die maßgebliche tägliche Aktualisierung des ADP Car Market Hub-Lizenz- / Feature-Rechte-Status.

Benutzerdefinierte Intervalle

Standardmäßige WordPress-Intervalle (hourly, twicedaily, daily) werden ebenfalls vom Import-Zeitplan akzeptiert.

Planen des Haupt-Import-Events

Das Haupt-Import-Event ist as24ci_scheduled_import, geplant von AS24CI\Scheduler::reschedule(). Die Methode:

1. Ruft unschedule() auf, um alle vorhandenen Vorkommen des Hooks zu löschen.
2. Kehrt sofort zurück, wenn as24ci_auto_import_enabled auf 0 steht (es wird kein Event geplant).
3. Liest as24ci_cron_schedule (Standard hourly). Zulässige Werte: hourly, as24ci_every_6_hours, twicedaily, daily, as24ci_custom.
4. Berechnet den Zeitstempel für den nächsten Durchlauf über calculate_next_run(): - Für daily und twicedaily wird die konfigurierte Startzeit as24ci_cron_start_time (HH:MM, 24 h) verwendet, interpretiert in der Zeitzone der WordPress-Website. Wenn die heutige Startzeit bereits vergangen ist, wird der nächste Durchlauf auf morgen verschoben. - Für alle anderen Zeitpläne ist der nächste Durchlauf sofort.
5. Ruft wp_schedule_event( $next_run, $schedule, 'as24ci_scheduled_import' ) auf.

Der Scheduler plant nie mehr als ein Vorkommen des Hooks; unschedule() löscht jeden ausstehenden Eintrag, bevor reschedule() einen neuen hinzufügt.

Der gemeinsame Runner

AS24CI\Scheduler::run_import( string $source = 'manual' ) ist der einzige Einstiegspunkt, der verwendet wird von:

• Dem Cron-Hook as24ci_scheduled_import (Quelle: wp-cron).
• Dem REST-Cron-Endpunkt (Quelle: rest).
• Dem Admin-Button "Jetzt ausführen" (Quelle: manual).

Der Runner:

1. Erwirbt die temporäre Sperre as24ci_cron_import_running (Scheduler::LOCK_TRANSIENT) mit einer Gültigkeitsdauer (TTL) von Scheduler::LOCK_TTL. Eine veraltete Sperre (älter als die TTL) wird automatisch gelöscht.
2. Erhöht für Cron- und REST-Quellen das PHP-Ausführungszeitlimit über set_time_limit(300) auf 300 Sekunden.
3. Liest as24ci_cron_max_vehicles (Standard 50) und as24ci_cron_image_queue (Standard 1).
4. Ruft entsprechend Importer::set_cron_image_queue( true|false ) auf.
5. Iteriert über die konfigurierten Händler-IDs und ruft für jede Importer::import_all_for_seller() auf, wobei die Anzahl der Fahrzeuge und das vollständige in diesem Durchlauf gefundene Set listing_ids akkumuliert werden. Stoppt, sobald das Fahrzeuglimit erreicht ist.
6. Wenn der Full-Sync aktiviert ist (as24ci_full_sync = 1) und der Durchlauf nicht durch das Limit abgebrochen wurde, wird Importer::full_sync_after_import( $remote_ids ) aufgerufen. Der Full-Sync-Aufruf ist wirkungslos (No-Op), wenn das Remote-ID-Set leer ist (Sicherheitsvorkehrung).
7. Plant den Bild-Warteschlangen-Worker (maybe_schedule_image_queue_worker).
8. Gibt die Sperre frei und setzt den Cron-Bild-Warteschlangen-Modus im Block finally zurück, sodass nachfolgende manuelle Aufrufe unbeeinflusst bleiben.
9. Protokolliert as24ci_last_run_time und as24ci_last_run_status (Array mit Zählern { inserted, updated, skipped, errors, sync_deleted, sync_kept, api_active }).
10. Invalidiert den temporären Dashboard-Wert "API-Status" (Admin_Page::TRANSIENT_API_STATUS), sodass die Dashboard-Karten beim nächsten Laden der Seite aktualisiert werden.

Der Runner gibt array{ success: bool, message: string, counts: array<string,int> } zurück.

REST-Cron-Endpunkt

AS24CI\Cron_Endpoint::register_routes() registriert eine einzelne GET-Route:

• GET /wp-json/as24ci/v1/cron-import

Die Authentifizierung erfolgt innerhalb des Handlers. Das Token wird aus as24ci_cron_token gelesen. Der Endpunkt:

• Lehnt Anfragen ab, wenn kein Token konfiguriert ist (403, mit einer Meldung, die den Administrator auffordert, eines in der Admin-Benutzeroberfläche zu generieren).
• Akzeptiert das Token entweder über den Header Authorization: Bearer <token> (bevorzugt – hält das Token aus den Server-Zugriffsprotokollen fern) oder den Query-Parameter ?token=<token>.
• Ruft bei Erfolg Scheduler::run_import( 'rest' ) auf.

Das Plugin verfolgt auch Pings für "externer Cron ist aktiv" unabhängig vom REST-Endpunkt:

• Der Aufruf einer beliebigen URL mit ?as24ci_cron=1 aktualisiert as24ci_last_external_cron_run über Cron_Endpoint::record_external_ping() (eingehängt in init) auf den aktuellen Unix-Zeitstempel.

Sperren und Nebenläufigkeit

Das Plugin verwendet zwei kurzlebige Transients, um überlappende Arbeiten zu verhindern:

Eine veraltete Sperre (älter als die TTL) wird vom nächsten Runner automatisch gelöscht, sodass ein Prozess, der mitten im Durchlauf abgestürzt ist, zukünftige Importe nicht dauerhaft blockiert. Eine manuelle Behebung (Löschen des Transients via WP-CLI oder ein Datenbank-Tool) ist nur erforderlich, wenn Sie einen neuen Durchlauf früher erzwingen möchten, als es die TTL zulässt.

Konfigurationsreferenz

Die Konstanten für Scheduler::LOCK_TTL und den Bild-Warteschlangen-Worker sind im Code definiert; überprüfen Sie die aktuellen Werte im Quellcode, wenn Sie genaue Zahlen benötigen.

Schritt-für-Schritt-Anleitung

Aktivieren automatischer Importe über WP-Cron

1. Öffnen Sie den Admin-Tab Automatisierung.
2. Stellen Sie den Cron-Modus auf wp-cron ein.
3. Aktivieren Sie den Auto-Import (as24ci_auto_import_enabled = 1).
4. Wählen Sie einen Zeitplan. Legen Sie für daily / twicedaily die Startzeit fest. Legen Sie für as24ci_custom das Intervall fest (mindestens 15 Minuten).
5. Speichern Sie die Einstellungen. Der Tab "Import & Limits" ruft Scheduler::reschedule() auf, um den nächsten Durchlauf zu registrieren.
6. (Optional) Reduzieren Sie die Fahrzeuge pro Cron-Durchlauf bei sehr großen Katalogen, damit die einzelnen Durchläufe innerhalb des PHP-Zeitlimits des Hosts bleiben.

Auslösen von Importen über einen System-Cron

1. Wechseln Sie den Cron-Modus auf server-cron, damit die Admin-Benutzeroberfläche Hinweise zum Server-Cron anzeigt.
2. (Empfohlen) Deaktivieren Sie WP-Cron in wp-config.php:

• Setzen Sie define( 'DISABLE_WP_CRON', true );. WordPress führt geplante Events dann nur noch aus, wenn sie explizit angestoßen werden.

1. Generieren Sie ein Token im Bildschirm "Import & Limits". Das Plugin speichert es in as24ci_cron_token.
2. Konfigurieren Sie Ihren System-Cron so, dass er den REST-Endpunkt aufruft, beispielsweise stündlich:

   0 * * * * curl -fsS -H "Authorization: Bearer YOUR_TOKEN" \
     "https://example.com/wp-json/as24ci/v1/cron-import?as24ci_cron=1"

Der optionale Query-Parameter ?as24ci_cron=1 aktualisiert auch den im Admin-Status angezeigten Zeitstempel für "externer Cron ist aktiv".

1. Überprüfen Sie die Antwort. Ein erfolgreicher Durchlauf gibt ein JSON-Payload mit Zählern zurück; ein 403 weist auf ein fehlendes oder falsches Token hin.

---

Betriebshinweise

• WP-Cron wird durch den Website-Traffic ausgelöst. Auf Websites mit geringem Traffic können geplante Events verspätet oder gar nicht ausgeführt werden. Verwenden Sie in Produktionsumgebungen einen echten System-Cron.
• Der Aufruf set_time_limit(300) wird möglicherweise von Hosts ignoriert, die PHP-Zeitlimits erzwingen. Das Plugin protokolliert in diesem Fall eine Warnung.
• Die Option as24ci_full_sync ist aus Sicherheitsgründen ein Opt-in. Wenn sie aktiviert ist, werden Fahrzeuge, deren Angebote aus der API verschwinden, dauerhaft gelöscht (einschließlich ihrer importierten Anhänge). Stellen Sie sicher, dass die konfigurierten Händler-IDs den gesamten Katalog abdecken, den Sie online halten möchten.
• Durch das Deaktivieren des Plugins werden alle seine geplanten Events gelöscht (as24ci_scheduled_import, die Bereinigung der Analysen, der Zeitplan für die KI-Warteschlange, der Zeitplan für die Preisfindungs-Engine und das Event as24ci_license_refresh – plus der veraltete Hook as24ci_competitor_watcher_cron) und der Transient as24ci_cron_import_running entfernt.
• Das Plugin codiert niemals externe Cron-URLs oder Token fest im Code. Das obige Beispiel verwendet einen Platzhalter; ersetzen Sie diesen vor dem Deployment durch Ihren eigenen Host und ein generiertes Token.

Fehlerbehebung

• Importe werden nicht automatisch ausgeführt. Überprüfen Sie as24ci_auto_import_enabled = 1, ob ein Zeitplan ausgewählt ist und ob wp_next_scheduled( 'as24ci_scheduled_import' ) einen zukünftigen Zeitstempel zurückgibt. Wenn der Wert false ist, speichern Sie den Tab „Automatisierung“ erneut, um reschedule() aufzurufen.
• Import already in progress wird protokolliert. Die Sperre für den Einzellauf wird von einem anderen Runner gehalten. Warten Sie, bis die TTL der Sperre abläuft (der nächste Runner löscht eine veraltete Sperre automatisch), oder löschen Sie den Transient as24ci_cron_import_running über WP-CLI für einen sofortigen Neuversuch.
• No seller IDs configured wird zurückgegeben. Legen Sie as24ci_seller_ids in den API-Einstellungen fest.
• Tägliche Zeitpläne werden zur falschen Zeit ausgelöst. Das Plugin verwendet die Website-Zeitzone WordPress (wp_timezone()). Überprüfen Sie die Zeitzone unter Einstellungen → Allgemein, nicht die lokale Zeit des Servers.
• REST-Endpunkt gibt 403 zurück. Entweder fehlt das Token (as24ci_cron_token ist leer – die Antwortnachricht bestätigt dies) oder das Token in der Anfrage stimmt nicht überein. Generieren Sie ein neues Token in der Admin-Benutzeroberfläche.
• Der externe Cron sieht im Admin-Status inaktiv aus. Stellen Sie sicher, dass die von Ihnen aufgerufene URL ?as24ci_cron=1 enthält (oder dass der REST-Cron-Endpunkt erfolgreich ist) und dass die Anfrage die Website WordPress erreicht (keine Firewall, keine Authentifizierungssperre). Das Plugin aktualisiert as24ci_last_external_cron_run bei jedem erfolgreichen Ping.
• Die Bildwarteschlange wird nach einem Cron-Import nicht geleert. Dies ist ein separater Worker. Siehe den Abschnitt zur Fehlerbehebung in Bild-Importer und Warteschlange.

Zugehörige Dokumente

• Import-Engine
• Bild-Importer und Warteschlange
• Plugin-Bootstrap und Lebenszyklus
• Speicherung von Optionen und Einstellungen
• Schnittsstellenübersicht