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, die überschneidende Ausführungen verhindert.

Wann dieses Dokument zu verwenden ist

Lesen Sie dieses Dokument, wenn Sie:

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

Für die Importlogik pro Fahrzeug siehe Import Engine. Für die Mechanik der Bildwarteschlange siehe Image Importer And Queue.

Übersicht

Das Plugin verwendet zwei komplementäre Auslösepfade:

• 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 Bildwarteschlangen-Worker plant und den Lauf 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 der 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-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 AI Assistant aktiviert ist, und bei der 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 der Deaktivierung gelöscht. Dies ist die massgebliche tägliche Aktualisierung des ADP Car Market Hub-Lizenz- / Feature-Rechte-Status.

Benutzerdefinierte Intervalle

Standardmässige 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 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 auf 0 steht (es wird kein Event geplant).
3. Liest as24ci_cron_schedule (Standardwert hourly). Zulässige Werte: hourly, as24ci_every_6_hours, twicedaily, daily, as24ci_custom.
4. Berechnet den Zeitstempel für den nächsten Lauf über calculate_next_run(): - Für daily und twicedaily wird die konfigurierte as24ci_cron_start_time (HH:MM, 24 h) verwendet, interpretiert in der WordPress-Zeitzone der Website. Wenn die heutige Startzeit bereits vergangen ist, wird der nächste Lauf auf morgen verschoben. - Für alle anderen Zeitpläne ist der nächste Lauf 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 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 auf 300 Sekunden über set_time_limit(300).
3. Liest as24ci_cron_max_vehicles (Standardwert 50) und as24ci_cron_image_queue (Standardwert 1).
4. Ruft entsprechend Importer::set_cron_image_queue( true|false ) auf.
5. Iteriert über die konfigurierten Seller IDs und ruft Importer::import_all_for_seller() für jede auf, wobei die Anzahlen und das vollständige in diesem Lauf gefundene listing_ids-Set akkumuliert werden. Stoppt, sobald das Fahrzeuglimit erreicht ist.
6. Wenn Full-Sync aktiviert ist (as24ci_full_sync = 1) und der Lauf 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 (Sicherheitsmassnahme).
7. Plant den Bildwarteschlangen-Worker (maybe_schedule_image_queue_worker).
8. Gibt die Sperre frei und setzt den Cron-Bildwarteschlangen-Modus im finally-Block zurück, sodass nachfolgende manuelle Aufrufe unbeeinflusst bleiben.
9. Protokolliert as24ci_last_run_time und as24ci_last_run_status (Anzahl-Array { 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:

• Weist 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 über den Query-Parameter ?token=<token>.
• Ruft bei Erfolg Scheduler::run_import( 'rest' ) auf.

Das Plugin verfolgt auch "Externer Cron ist aktiv"-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 Parallelität

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

Eine veraltete Sperre (älter als die TTL) wird automatisch vom nächsten Runner gelöscht, sodass ein Prozess, der mitten im Lauf abgebrochen wurde, 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 Lauf früher erzwingen möchten, als es die TTL zulässt.

Konfigurationsreferenz

Die Konstanten für Scheduler::LOCK_TTL und den Bildwarteschlangen-Worker sind im Code definiert; überprüfen Sie die aktuellen Werte im Quellcode, wenn Sie exakte 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 ein.
3. Stellen Sie Auto-Import auf aktiviert (as24ci_auto_import_enabled = 1).
4. Wählen Sie einen Zeitplan. Für daily / twicedaily legen Sie die Startzeit fest. Für as24ci_custom legen Sie das Intervall fest (mindestens 15 Minuten).
5. Speichern Sie. Der Tab "Import & Limits" ruft Scheduler::reschedule() auf, um den nächsten Lauf zu registrieren.
6. (Optional) Reduzieren Sie die Fahrzeuge pro Cron-Lauf bei sehr grossen Katalogen, damit die einzelnen Lä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 noch aus, wenn etwas sie explizit auslöst.

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, 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 "Externer Cron ist aktiv", der im Admin-Status angezeigt wird.

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

---

Betriebliche Hinweise

• WP-Cron wird durch den Website-Traffic ausgelöst. Auf Websites mit geringem Traffic können geplante Ereignisse 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 alle seine geplanten Ereignisse gelöscht (as24ci_scheduled_import, die Analytics-Bereinigung, der AI-Warteschlangen-Zeitplan, der Zeitplan der Pricing-Engine und das as24ci_license_refresh-Ereignis – plus der veraltete as24ci_competitor_watcher_cron-Hook) und der Transient as24ci_cron_import_running wird 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 «Automation» erneut, um reschedule() aufzurufen.
• Import already in progress wird protokolliert. Die Sperre für den Einzellauf (Single-Run Lock) 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 via WP-CLI für einen sofortigen erneuten Versuch.
• 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. Ü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 Bild-Warteschlange wird nach einem Cron-Import nicht geleert. 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
• Sektionsübersicht