Import-Engine

Dieses Dokument beschreibt, wie das ADP Car Market Hub-Plugin Fahrzeugdaten aus der AutoScout24-API in WordPress importiert. Es behandelt die Aufgaben der Importer-Klassen, den Ablauf pro Fahrzeug, die Änderungserkennung, die Löschung beim Vollabgleich (Full-Sync) und den öffentlichen Hook, der nach dem Import eines Fahrzeugs ausgelöst wird.

Wann Sie dieses Dokument lesen sollten

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

• Verstehen, was während eines Importlaufs passiert.
• Diagnostizieren, warum ein Fahrzeug hinzugefügt, aktualisiert, übersprungen oder entfernt wurde.
• Eine eigene Integration erstellen, die über die Aktion as24ci_vehicle_imported auf Importe reagiert.
• Kapazitäts- oder Hosting-Anforderungen für große Fahrzeugbestände planen.

Details zur Zeitplanung und zu Cron-Jobs finden Sie unter Cron-Events und Scheduler. Informationen zur Bildverarbeitung finden Sie unter Bild-Importer und Warteschlange.

Übersicht

Die Import-Engine besteht aus mehreren Klassen, die zusammenarbeiten:

• AS24CI\Client – führt authentifizierte HTTP-Anfragen an die AutoScout24-API aus, verwaltet OAuth-Tokens (einschließlich des transienten Caches as24ci_access_token) und stellt Hilfsfunktionen für Vorschauseiten und die Ausstattung pro Fahrzeug bereit.
• AS24CI\Importer – koordiniert den Import pro Fahrzeug. Entscheidet, ob ein Fahrzeug hinzugefügt, aktualisiert oder übersprungen wird, und schreibt den Beitrag (Post), die Postmeta-Daten sowie die Bildreferenzen des Fahrzeugs. Ist für die Änderungserkennung zuständig.
• AS24CI\Mapper – ordnet die Rohdaten von AutoScout24 den Feldern zu, die über AS24CI\Vehicle_Repository in der Tabelle as24_vehicles gespeichert werden. Pflegt abwärtskompatible Postmeta-Schlüssel.
• AS24CI\Vehicle_Repository – speichert die Fahrzeugfelddaten in der dedizierten Tabelle {$wpdb->prefix}as24_vehicles.
• AS24CI\Image_Importer – lädt Bilder herunter, konvertiert sie optional in das WebP-Format und hängt sie an den Fahrzeug-Beitrag an. Siehe Bild-Importer und Warteschlange.
• AS24CI\Scheduler – umschließt Importer::import_all_for_seller() in einem sperr- und wiederholungssicheren Runner, der von WP-Cron, dem REST-Cron-Endpunkt und der manuellen Schaltfläche „Jetzt ausführen“ verwendet wird.

Dieselbe Importer-Instanz wird vom manuellen Batch-Wizard, dem Cron-Runner und dem REST-Cron-Endpunkt wiederverwendet.

Anforderungen oder Voraussetzungen

Vor der Durchführung eines Imports benötigen Sie:

• Gültige AutoScout24-API-Zugangsdaten, die im Plugin konfiguriert sind (as24ci_base_url, as24ci_token_url, as24ci_client_id, as24ci_client_secret, as24ci_token_audience).
• Eine oder mehrere Händler-IDs (Seller-IDs) in as24ci_seller_ids (kommagetrennt).
• Einen WordPress-Benutzer, der als Standard-Beitragsautor festgelegt ist (as24ci_default_post_author); Importe fallen auf den aktuellen Benutzer zurück, wenn kein Standardwert festgelegt ist.
• Funktionierenden ausgehenden HTTPS-Zugriff vom WordPress-Server auf die AutoScout24-API und auf die in der API-Antwort referenzierten Bild-Hosts.
• Ausreichende PHP-Ausführungszeit. Der Scheduler erhöht das Zeitlimit über set_time_limit(300) für Cron- und REST-Läufe auf 300 Sekunden; einige Hoster können dies überschreiben.

Ablauf pro Fahrzeug

AS24CI\Importer::upsert_post_from_listing() ist die zentrale Routine pro Fahrzeug. Der vereinfachte Ablauf ist:

1. Überprüfen, ob das Fahrzeug eine id hat. Andernfalls überspringen.
2. Fahrzeuge überspringen, deren API-Status nicht activated ist oder deren Flag live leer ist.
3. Nach einem vorhandenen Fahrzeug-Beitrag anhand der Fahrzeug-ID suchen (find_post_id_by_listing_id()).
4. Änderungserkennung ausführen (siehe unten). Wenn sich nichts geändert hat, _as24ci_last_sync schreiben und skipped zurückgeben.
5. Beitragstitel, Auszug (Excerpt) und Inhalt erstellen. Wenn die KI-Sperre (_as24ci_ai_locked = 'yes') aktiv ist, den Beitragsauszug oder -inhalt nicht überschreiben.
6. Den WordPress-Beitrag mit dem konfigurierten Standard-Beitragsstatus und -Autor einfügen oder aktualisieren.
7. Abwärtskompatible Postmeta-Daten schreiben: _as24ci_listing_id, _as24ci_seller_id, _as24ci_last_modified (sofern von der API bereitgestellt) und _as24ci_last_sync.
8. Sicherstellen, dass der Slug mit der Fahrzeug-ID endet (ensure_slug_has_listing_id()).
9. Die Fahrzeugdaten über AS24CI\Mapper::map_listing_to_post() zuordnen, sodass die typisierten Felder in die Tabelle as24_vehicles geschrieben werden.
10. Ausstattung über Client::get_listing_equipment() abrufen und dem Beitrag über Mapper::map_equipment_to_post() zuordnen. Fehler werden protokolliert, führen aber nicht zum Fehlschlagen des Fahrzeugimports.
11. Bilder importieren (abhängig von der Option as24ci_import_images und dem Limit as24ci_max_images). Der Bildablauf ist im Dokument Bild-Importer und Warteschlange ausführlich beschrieben.
12. _as24ci_content_hash und _as24ci_original_description aktualisieren.
13. Die Aktion as24ci_vehicle_imported mit der Beitrags-ID, den API-Rohdaten des Fahrzeugs und einem Boolean $is_update auslösen.
14. Einen der Strings inserted, updated, skipped oder error (bei Fehlern in wp_insert_post / wp_update_post) zurückgeben.

Änderungserkennung

Der Importer überspringt Fahrzeuge, die sich seit dem letzten Durchlauf nicht geändert haben, und nutzt dafür zwei kaskadierende Prüfungen:

• Primär: das von der API zurückgegebene Feld lastModifiedDate. Wenn der lokale Postmeta-Wert _as24ci_last_modified mit dem Remote-Wert übereinstimmt, wird das Fahrzeug als unverändert behandelt. Der Importer aktualisiert dennoch _as24ci_last_sync, damit die Vollabgleich-Logik weiß, dass das Fahrzeug remote existiert.
• Fallback: Wenn lastModifiedDate fehlt, berechnet der Importer einen MD5-Hash der JSON-codierten Daten und vergleicht ihn mit dem gespeicherten Wert _as24ci_content_hash.

Die Änderungserkennung für Bilder läuft unabhängig und ist in der Dokumentation des Bild-Importers beschrieben.

KI-Sperre (AI Lock)

Wenn _as24ci_ai_locked auf 'yes' gesetzt ist, behält der Importer den vorhandenen Wert von post_content und post_excerpt bei, sodass KI-generierte Texte einen erneuten Import überstehen. Alle anderen Felder, Taxonomie-Zuweisungen, Ausstattungen und Bilder werden weiterhin aktualisiert. Die ursprüngliche API-Beschreibung wird zudem separat in _as24ci_original_description aufbewahrt.

Stabilität des Slugs

ensure_slug_has_listing_id() aktualisiert den Beitrags-Slug so, dass er immer auf -<listing_id> endet, wenn sich der Slug ändert. Dies hält die URLs über erneute Importe hinweg stabil und verhindert versehentliche Weiterleitungen bei Titeländerungen.

Massenoperationen

AS24CI\Importer stellt die folgenden übergeordneten Methoden bereit:

• get_seller_ids() – gibt die bereinigte Liste der konfigurierten Händler-IDs zurück.
• get_all_preview_listings_for_seller( $seller_id, $max_pages = 20, $page_size = 50 ) – blättert durch die API und gibt alle aktivierten, Live-Fahrzeuge für einen einzelnen Händler zurück.
• preview_listings_for_seller( $seller_id, $page = 1, $per_page = 50 ) – paginierte Vorschau, die von der Benutzeroberfläche des Wizards verwendet wird.
• import_selected_listings( $seller_id, $listing_ids, $max_vehicles = 0 ) – importiert die angegebenen Fahrzeug-IDs. Berücksichtigt das Budget $max_vehicles; übersprungene Fahrzeuge verbrauchen kein Budget.
• import_all_for_seller( $seller_id, $max_vehicles = 0 ) – ruft die vollständige Vorschauliste für einen Händler ab und delegiert an import_selected_listings(). Gibt die Anzahl sowie listing_ids (alle in diesem Durchlauf erfassten Fahrzeuge) und api_active (Anzahl der von der API zurückgegebenen aktiven Fahrzeuge) zurück.
• full_sync_after_import( array $remote_listing_ids ) – löscht lokale as24ci_car-Beiträge, deren _as24ci_listing_id nicht im angegebenen Remote-Set enthalten ist. Wird übersprungen, wenn das Remote-Set leer ist, als Schutzmaßnahme gegen versehentliches Löschen des gesamten Bestands.
• hard_delete_listing( $listing_id ) – manuelles, destruktives Löschen eines einzelnen Fahrzeugs; durchläuft dieselbe Bereinigung Vehicle_Deleter wie das native Löschen in WordPress.

Die „All-in-One“-Version des Plugins sieht keine Begrenzung der Fahrzeuge vor; get_free_import_limit() und get_free_slots_left() geben PHP_INT_MAX zurück.

Fahrzeuglöschung

Jeder dauerhafte Löschpfad läuft über AS24CI\Vehicle_Deleter:

• Natives „Dauerhaft löschen“ von WordPress in der Fahrzeugliste.
• Vollabgleich des Importers (full_sync_after_import()).
• Massenaktionen (AS24CI\Bulk_Actions).
• Manuelles Importer::hard_delete_listing().

Der Löschvorgang läuft über before_delete_post / deleted_post und:

• Entfernt in _as24ci_image_ids nachverfolgte Anhänge.
• Entfernt die entsprechende Zeile in {$wpdb->prefix}as24_vehicles.
• Löst die Aktion as24ci_vehicle_deleted aus.

Manuelle Galerie-Anhänge (_as24ci_manual_image_ids) und andere Anhänge, die nicht vom Importer nachverfolgt werden, bleiben absichtlich erhalten.

Öffentliche Hooks

Die Import-Engine löst die folgenden Hooks aus. Überprüfen Sie die Hook-Signaturen in der aktuellen Plugin-Version, bevor Sie sich darauf verlassen.

Das Plugin liest auch den Filter as24ci_webp_quality, wenn Bilder konvertiert werden; siehe die Dokumentation des Bild-Importers.

Konfigurationsreferenz

Betriebshinweise

• Der Importer bricht niemals wegen eines einzelnen fehlerhaften Fahrzeugs ab. Fehler von wp_insert_post, wp_update_post, Client::get_listing_equipment und dem Bild-Importer werden über AS24CI\Logger protokolliert und gezählt, brechen den Durchlauf jedoch nicht ab.
• Dank der Änderungserkennung ist ein vollständiger erneuter Import eines unveränderten Katalogs ressourcenschonend: Die meisten Fahrzeuge werden übersprungen und Bild-Downloads werden nicht erneut gestartet.
• Der Mapper schreibt über das Repository in die Tabelle as24_vehicles, nicht in wp_postmeta, mit Ausnahme der kleinen Gruppe abwärtskompatibler Schlüssel, die im Datenmodell dokumentiert sind.
• Der Vollabgleich (Full-Sync) ist optional. Wenn as24ci_full_sync aktiviert ist, stellen Sie sicher, dass die konfigurierten Händler-IDs den gesamten Bestand abdecken, den Sie online halten möchten. Fahrzeuge, deren Daten nicht mehr in der API vorhanden sind, werden dauerhaft gelöscht.
• Die ausführliche Protokollierung (Verbose Logging) erzeugt detaillierte Logzeilen und wächst bei großen Beständen schnell an. Das Plugin erzwingt ein Log-Limit von 10 MB mit Rotation; passen Sie die ausführliche Protokollierung an, um ein ausgewogenes Verhältnis zwischen Diagnose und Speicherplatz zu finden.

Fehlerbehebung

• Keine Fahrzeuge importiert. Überprüfen Sie die API-Zugangsdaten, stellen Sie sicher, dass as24ci_seller_ids nicht leer ist und dass die API Fahrzeuge mit status = activated und live = true zurückgibt. Suchen Sie im Plugin-Log nach HTTP-Fehlern von AS24CI\Client.
• Fahrzeuge bleiben im Status draft. Das Plugin setzt as24ci_default_post_status standardmäßig auf draft, damit Administratoren die Zuordnungen überprüfen können. Ändern Sie die Option auf publish, sobald Sie zufrieden sind, oder veröffentlichen Sie einzelne Fahrzeuge aus der Admin-Liste.
• Wiederholte Importe aktualisieren immer wieder dieselben Fahrzeuge. Stellen Sie sicher, dass die API eine stabile lastModifiedDate liefert. Wenn diese fehlt, erkennt der Fallback-Inhaltshash Änderungen; der Hash ändert sich, sobald sich die API-Daten aus irgendeinem Grund ändern.
• Ein Fahrzeug ist nach einem Cron-Lauf verschwunden. Prüfen Sie, ob as24ci_full_sync aktiviert ist. Bei aktivem Vollabgleich wird jedes in der API fehlende Fahrzeug dauerhaft gelöscht (einschließlich seiner importierten Anhänge).
• Importer ran but no images were downloaded. Überprüfen Sie as24ci_import_images und as24ci_max_images. Bei Cron-/REST-Läufen mit as24ci_cron_image_queue = 1 wird nur das erste Bild sofort heruntergeladen und der Rest an die Bild-Warteschlange übergeben.
• Skipping listing_id=… : lastModifiedDate unchanged. Dies ist die erwartete ausführliche Logzeile für unveränderte Fahrzeuge; sie bestätigt, dass die Änderungserkennung funktioniert.

---

Verwandte Dokumente

• Bild-Importer und Warteschlange
• Cron-Events und Scheduler
• Architektur-Übersicht
• Datenmodell
• Datenbankschema
• Sektionsübersicht