Import-Engine

Dieses Dokument beschreibt, wie das ADP Car Market Hub-Plugin Fahrzeugdaten aus der AutoScout24-API in WordPress importiert. Es deckt die Aufgaben der Importer-Klassen, den Ablauf pro Fahrzeug, die Änderungserkennung, die Löschung bei Vollsynchronisation sowie den öffentlichen Hook ab, der nach dem Import eines Fahrzeugs ausgelöst wird.

Wann Sie dieses Dokument verwenden sollten

Lesen Sie dieses Dokument, wenn Sie:

• Verstehen möchten, was während eines Importlaufs geschieht.
• Diagnostizieren wollen, warum ein Fahrzeug hinzugefügt, aktualisiert, übersprungen oder entfernt wurde.
• Eine eigene Integration erstellen möchten, die über die Aktion as24ci_vehicle_imported auf Importe reagiert.
• Kapazitäts- oder Hosting-Anforderungen für grosse Kataloge planen.

Für Details zur Zeitplanung und zu Cron-Jobs siehe Cron-Events und Scheduler. Für die Bildverarbeitung siehe Bild-Importer und Warteschlange.

Übersicht

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

• AS24CI\Client — sendet authentifizierte HTTP-Anfragen an die AutoScout24-API, verwaltet OAuth-Tokens (einschliesslich 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 eingefügt, aktualisiert oder übersprungen wird, und schreibt den Beitrag des Fahrzeugs, Postmeta und Bildreferenzen. 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 WebP und hängt sie an den Fahrzeugbeitrag an. Siehe Bild-Importer und Warteschlange.
• AS24CI\Scheduler — verpackt Importer::import_all_for_seller() in einen sperrsicheren, wiederholungsfähigen 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 dem Ausführen 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 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 Standard definiert ist.
• Funktionierenden ausgehenden HTTPS-Zugriff vom WordPress-Server auf die AutoScout24-API und auf die in der API-Antwort referenzierten Bild-Hosts.
• Ausreichend 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 Hosts 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 bestehenden Fahrzeugbeitrag anhand der Listing-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 und Inhalt erstellen. Wenn der AI Lock (_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 schreiben: _as24ci_listing_id, _as24ci_seller_id, _as24ci_last_modified (sofern von der API geliefert) und _as24ci_last_sync.
8. Sicherstellen, dass der Slug mit der Listing-ID endet (ensure_slug_has_listing_id()).
9. Die Listing-Daten ü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 der Begrenzung 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 rohen API-Fahrzeugdaten und einem Boolean $is_update auslösen.
14. Einen der Strings inserted, updated, skipped oder error (bei Fehlschlagen von wp_insert_post / wp_update_post) zurückgeben.

Änderungserkennung

Der Importer überspringt Fahrzeuge, die sich seit dem letzten Durchlauf nicht geändert haben, unter Verwendung von zwei kaskadierenden Prüfungen:

• Primär: das von der API zurückgegebene Feld lastModifiedDate. Wenn das lokale Postmeta _as24ci_last_modified mit dem Remote-Wert übereinstimmt, wird das Fahrzeug als unverändert behandelt. Der Importer aktualisiert dennoch _as24ci_last_sync, damit die Vollsynchronisations-Logik weiss, 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 zum Bild-Importer beschrieben.

AI Lock

Wenn _as24ci_ai_locked auf 'yes' steht, behält der Importer den bestehenden 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.

Slug-Stabilität

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

Massenoperationen

AS24CI\Importer stellt die folgenden übergeordneten Methoden bereit:

• get_seller_ids() — gibt die bereinigte Liste der konfigurierten Seller-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-Angebote für eine einzelne Garage 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 Listing-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 eine Garage 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 Schutz vor versehentlichem Löschen aller Daten.
• hard_delete_listing( $listing_id ) — manuelles, destruktives Löschen für ein einzelnes Fahrzeug; 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" in WordPress auf der Fahrzeugliste.
• Vollsynchronisation des Importers (full_sync_after_import()).
• Massenaktionen (AS24CI\Bulk_Actions).
• Manuelles Importer::hard_delete_listing().

Der Löschvorgang läuft auf 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 bewusst 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 zum Bild-Importer.

Konfigurationsreferenz

Betriebliche Hinweise

• Der Importer bricht bei einem einzelnen fehlerhaften Fahrzeug nie 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 Lauf jedoch nicht ab.
• Dank der Änderungserkennung ist ein vollständiger Re-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 abwärtskompatiblen Schlüsselmenge, die in Datenmodell dokumentiert ist.
• Die Vollsynchronisation ist optional (Opt-in). Wenn as24ci_full_sync aktiviert ist, stellen Sie sicher, dass die konfigurierten Seller-IDs den gesamten Katalog abdecken, den Sie online halten möchten; Fahrzeuge, deren Daten in der API verschwinden, werden dauerhaft gelöscht.
• Die ausführliche Protokollierung (Verbose Logging) erzeugt detaillierte Logzeilen und wächst bei grossen Katalogen schnell an. Das Plugin erzwingt eine Log-Grössenbegrenzung von 10 MB mit Rotation; passen Sie die ausführliche Protokollierung an, um Diagnosebedarf und Speicherplatz auszubalancieren.

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ässig 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 Re-Importe aktualisieren immer 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 aktiver Vollsynchronisation wird jedes in der API fehlende Fahrzeug dauerhaft gelöscht (einschliesslich 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 Protokollzeile bei ausführlicher Protokollierung für unveränderte Fahrzeuge; sie bestätigt, dass die Änderungserkennung funktioniert.

---

Verwandte Dokumente

• Image Importer And Queue
• Cron Events And Scheduler
• Architecture Overview
• Data Model
• Database Schema
• Section overview