Cron-Events und Scheduler

Dieses Dokument beschreibt die WP-Cron-Events, die das ADP Car Market Hub-Plugin 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 Automation konfigurieren.
• Einen externen System-Cron einrichten, um Importe zuverlässig auszulösen.
• Verpasste, ü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 Image Importer And Queue.

Ü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, den Import an den Importer delegiert, optional Full-Sync-Löschungen durchführt, den Image-Queue-Worker plant und den Durchlauf protokolliert.

Vom Plugin registrierte Cron-Hooks

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

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

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.
• Pricing-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.
• Data Quality 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.
• AI-Queue-Worker — Hook-Tag as24ci_process_ai_queue, verwaltet von AS24CI\Ai_Assistant. Bedingungslos gebunden; geplant im as24ci_every_5_minutes-Intervall nur, wenn der AI Assistant aktiviert ist, und bei Deaktivierung gelöscht.
• Lizenz-Revalidierung — Hook-Tag as24ci_license_refresh, verwaltet von AS24CI\License_Manager. Geplant daily bei der Aktivierung (und über einen admin_init Self-Heal) und bei Deaktivierung gelöscht. Dies ist die autoritative tägliche Aktualisierung des ADP Car Market Hub-Lizenz- / Feature-Rechte-Status.
• Intelligence Portal Observation-Sync — Hook-Tag as24ci_intelligence_sync (AS24CI\Intelligence_Sync::CRON_HOOK), verwaltet von AS24CI\Intelligence_Sync. Geplant daily und gelöscht bei Deaktivierung (Intelligence_Sync::clear_cron()).
• Webhook-Wiederholungsversuche — Hook-Tag as24ci_webhook_retry (AS24CI\Webhooks). Geplant als einzelne (einmalige) Events mit einer Back-off-Verzögerung, wenn eine Webhook-Zustellung fehlschlägt, und dann erneut ausgelöst durch Webhooks::handle_retry(). Siehe Webhooks.
• Connections-Feed-Abruf — Hook-Tag as24ci_import_feed_event (AS24CI\Import_Feed::CRON_HOOK), verwaltet von AS24CI\Import_Feed. Geplant im konfigurierten Intervall (hourly, twicedaily oder daily), wann immer der Feed aktiviert und eine URL hinterlegt ist; neu geplant beim Speichern und gelöscht bei Deaktivierung.
• Connections-E-Mail-Empfang — Hook-Tag as24ci_import_mail_event (AS24CI\Import_Mail::CRON_HOOK), verwaltet von AS24CI\Import_Mail. Geplant im konfigurierten Intervall, wenn das Postfach aktiviert und ein Host hinterlegt ist; gelöscht bei Deaktivierung.

Connections Central-Schedule-Connectors

Der carcuro-Connector (AS24CI\Import_Carcuro), der mobile.de-Connector (AS24CI\Import_Mobile, includes/class-as24ci-import-mobile.php) und der AutoScout24-Importer laufen alle auf dem zentralen Import-Hook AS24CI\Scheduler::CRON_HOOK (as24ci_scheduled_import), der unter Import & Limits konfiguriert ist. carcuro hat kein eigenes Cron-Event: Import_Carcuro::register_hooks() bindet Import_Carcuro::run() an Scheduler::CRON_HOOK, und sein run() ist wirkungslos (No-op), ausser carcuro ist aktiviert und ein Token ist vorhanden. mobile.de verhält sich genauso: Import_Mobile::register_hooks() bindet Import_Mobile::run() an den zentralen Hook, und sein run() ist wirkungslos, ausser mobile.de ist aktiviert und Zugangsdaten sind vorhanden. Die veralteten (Legacy) quellspezifischen Events as24ci_import_carcuro_event und as24ci_import_mobile_event (die immer noch als Import_Carcuro::CRON_HOOK / Import_Mobile::CRON_HOOK nur für Bereinigungszwecke bereitgestellt werden) werden bei der Registrierung, beim Speichern und bei der Deaktivierung aktiv gelöscht (clear_schedule()).

Die Feed- und E-Mail-Connectors registrieren im Gegensatz dazu ihre eigenen Cron-Events, wie oben aufgeführt. Alle Connectors speisen die gemeinsame nachgelagerte Pipeline über Importer::upsert_external_listing(); siehe Import Engine und die Connections-Admin-Referenz.

Benutzerdefinierte Intervalle

Standard-WordPress-Intervalle (hourly, twicedaily, daily) werden vom Import-Zeitplan ebenfalls akzeptiert.

Planung des Haupt-Import-Events

Das Haupt-Import-Event ist as24ci_scheduled_import, geplant durch 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 gleich 0 ist (kein Event ist geplant).
3. Liest as24ci_cron_schedule (Standardwert hourly). Erlaubte 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 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 as24ci_scheduled_import-Cron-Hook (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 (Transient Lock) as24ci_cron_import_running (Scheduler::LOCK_TRANSIENT) mit einer 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 Seller-IDs und ruft für jede Importer::import_all_for_seller() auf, wobei die Zahlen und das vollständige in diesem Durchlauf gefundene listing_ids-Set akkumuliert werden. Stoppt, sobald das Fahrzeuglimit erreicht ist.
6. Wenn die Vollsynchronisation 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 Aufruf der Vollsynchronisation ist wirkungslos (No-Op), wenn das Remote-ID-Set leer ist (Sicherheitsmassnahme).
7. Plant den Image-Queue-Worker (maybe_schedule_image_queue_worker).
8. Gibt die Sperre frei und setzt den Cron-Image-Queue-Modus im finally-Block zurück, sodass manuelle nachfolgende Aufrufe unbeeinflusst bleiben.
9. Zeichnet as24ci_last_run_time und as24ci_last_run_status auf (Zähler-Array { inserted, updated, skipped, errors, sync_deleted, sync_kept, api_active }).
10. Invalidiert das Dashboard-Transient "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 wird innerhalb des Handlers durchgeführt. Der Token wird aus as24ci_cron_token ausgelesen. Der Endpunkt:

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

Das Plugin verfolgt auch "External Cron is alive"-Pings unabhängig vom REST-Endpunkt:

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

Sperren und Nebenläufigkeit

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

Eine veraltete Sperre (älter als die TTL) wird automatisch durch den nächsten Runner gelöscht, sodass ein Prozess, der mitten im Durchlauf abgebrochen ist, zukünftige Importe nicht unbegrenzt blockiert. Eine manuelle Behebung (Löschen des Transients über 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 Image-Queue-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 Automation.
2. Stellen Sie den Cron-Modus auf wp-cron.
3. Stellen Sie Auto-Import auf aktiviert (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. Der Tab "Import & Limits" ruft Scheduler::reschedule() auf, um den nächsten Durchlauf zu registrieren.
6. (Optional) Reduzieren Sie Fahrzeuge pro Cron-Durchlauf bei sehr grossen 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 dann geplante Events nur aus, wenn etwas sie explizit auslöst.

1. Generieren Sie einen Token im Bildschirm "Import & Limits". Das Plugin speichert ihn in as24ci_cron_token.
2. Konfigurieren Sie Ihren System-Cron so, dass er den REST-Endpunkt aufruft, zum Beispiel jede Stunde:

   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 Zeitstempel "External Cron is alive", der im Admin-Status angezeigt wird.

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

---

---

Betriebliche Hinweise

• 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 der Produktionsumgebung 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 Inserate aus der API verschwinden, dauerhaft gelöscht (einschliesslich ihrer importierten Anhänge). Stellen Sie sicher, dass die konfigurierten Seller IDs den gesamten Katalog abdecken, den Sie online halten möchten.
• Durch das Deaktivieren des Plugins werden die folgenden geplanten Events (AS24CI\Plugin::deactivate()) gelöscht: as24ci_scheduled_import, die Analytics-Bereinigung, der AI-Queue-Zeitplan, der Pricing-Engine-Zeitplan, der Connections-Feed (as24ci_import_feed_event), E-Mail (as24ci_import_mail_event), Legacy-Carcuro- (as24ci_import_carcuro_event) und Legacy-mobile.de-Events (as24ci_import_mobile_event), das as24ci_license_refresh-Event und das Intelligence-Sync-Event (as24ci_intelligence_sync) — plus der Legacy-Hook as24ci_competitor_watcher_cron und der Legacy-Hook as24ci_soft_delete_cleanup_cron (inline gelöscht via wp_clear_scheduled_hook( 'as24ci_soft_delete_cleanup_cron' ), sodass alle Überbleibsel der entfernten Soft-Delete-Funktion auf Installationen, die von älteren Versionen aktualisiert wurden, aus dem Zeitplan entfernt werden) — und der Transient as24ci_cron_import_running wird entfernt. Hinweis: Das Event des Data Quality Scanners (as24ci_automated_taxonomy_scan) wird nicht durch deactivate() gelöscht; es wird vom Scanner selbst via Data_Quality_Scanner::reschedule() neu geplant/gelöscht.
• 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 laufen nicht automatisch. Ü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 "Automation" erneut, um reschedule() aufzurufen.
• Import already in progress wird protokolliert. Die Einzelausführungssperre (Single-Run Lock) wird von einem anderen Prozess gehalten. Warten Sie, bis die Lock-TTL abläuft (der nächste Prozess löscht eine veraltete Sperre automatisch), oder löschen Sie den Transient as24ci_cron_import_running via 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 ausgeführt. Das Plugin verwendet die Website-Zeitzone WordPress (wp_timezone()). Überprüfen Sie die Zeitzone unter Einstellungen → Allgemein, nicht die lokale Serverzeit.
• REST-Endpunkt gibt 403 zurück. Entweder fehlt das Token (as24ci_cron_token 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. Überprüfen Sie, ob die von Ihnen aufgerufene URL ?as24ci_cron=1 enthält (oder ob der REST-Cron-Endpunkt erfolgreich ist) und ob die Anfrage die Website WordPress erreicht (keine Firewall, keine Authentifizierungssperre). Das Plugin aktualisiert as24ci_last_external_cron_run bei jedem erfolgreichen Ping.
• Die Bildwarteschlange leert sich nach einem Cron-Import nicht. Dies ist ein separater Worker. Siehe den Abschnitt zur Fehlerbehebung in Bild-Importer und Warteschlange.

Verwandte Dokumente

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