Datenmodell

Dieses Dokument beschreibt das logische Datenmodell, das vom ADP Car Market Hub-Plugin verwendet wird: welche Entitäten existieren, wie sie auf den WordPress-Speicher abgebildet werden und wie die verschiedenen Speicherebenen (benutzerdefinierte Datenbanktabellen, Beiträge, Postmeta und Optionen) zusammenarbeiten.

Wann Sie dieses Dokument verwenden sollten

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

• Verstehen, welche Entität (Fahrzeug, Lead, Suchauftrag, Analytics-Event) in welcher Tabelle oder in welchem Beitragstyp (Post Type) liegt.
• Entscheiden, wo Daten gelesen oder geschrieben werden sollen, wenn Sie eine benutzerdefinierte Integration oder einen Bericht erstellen.
• Verstehen, wie die Fahrzeugfelddaten zwischen der dedizierten as24_vehicles-Tabelle und den Legacy-Postmeta-Schlüsseln aufgeteilt sind.

Für unformatierte Spaltenlisten siehe Database Schema. Für die Postmeta-Schlüssel, die in der Metabox-Benutzeroberfläche des Admins angezeigt werden, siehe die Import- und Template-Dokumente in diesem Abschnitt.

Übersicht

Das Plugin unterscheidet zwischen vier primären Entitäten:

1. Vehicle (Fahrzeug) — ein einzelnes Fahrzeugangebot, das aus AutoScout24 importiert wurde.
2. Lead (Anfrage) — eine Kontaktformular- oder Anfrageübermittlung, die (optional) an ein Fahrzeug gebunden ist.
3. Search Agent (Suchauftrag) — die gespeicherten Suchkriterien eines Besuchers mit E-Mail-Benachrichtigungen.
4. Analytics Event (Analytics-Ereignis) — ein einzelnes nachverfolgtes Ereignis auf der öffentlichen Website (Seitenaufruf, Filternutzung, Kontakt-Öffnung usw.).

Jede Entität verwendet die Speicherebene, die am besten zu ihrem Zugriffsmuster passt. Fahrzeuge sind aufgeteilt zwischen WordPress-Beiträgen (für Permalinks, Taxonomien, Templates) und einer dedizierten relationalen Tabelle (für typisierte Spalten und schnelle Abfragen). Leads sind vollständige WordPress-Beiträge. Suchaufträge und Analytics-Ereignisse leben in ihren eigenen benutzerdefinierten Tabellen.

Vehicle (Fahrzeug)

Ein Fahrzeug ist die zentrale Entität des Plugins. Es wird durch zwei eng miteinander verknüpfte Datensätze dargestellt:

• Ein WordPress-Beitrag des Beitragstyps as24ci_car. Der Beitrag liefert den Permalink (/cars/<slug>/), den Titel und den Auszug (Excerpt), das Beitragsbild (Featured Image), den Editor-Inhalt, die zugewiesenen Taxonomie-Begriffe und die WordPress-Berechtigungsebene.
• Eine Zeile in der dedizierten Tabelle {$wpdb->prefix}as24_vehicles, die AS24CI\Vehicle_Repository gehört. Die Zeile enthält die typisierten Fahrzeugfelddaten (Preis, Kilometerstand, Zulassungsjahr, Kraftstoffart, Ausstattung usw.), das rohe API-Payload und Metadaten, die für die Änderungserkennung verwendet werden.

Die beiden Datensätze sind über die Spalte post_id verknüpft, die einen eindeutigen Index in der Tabelle besitzt. Jede Zeile hat ausserdem eine eindeutige Spalte as24_id, die den AutoScout24-Angebotsidentifikator enthält.

Warum eine dedizierte Tabelle

Fahrzeugfelddaten wurden ursprünglich in wp_postmeta gespeichert. Das Plugin hat diese Daten in eine dedizierte Tabelle verschoben, damit:

• Typisierte Spalten (Dezimalzahlen für Preise, Ganzzahlen für Kilometerstand, Daten für die Erstzulassung) direkt abgefragt und sortiert werden können, ohne die Kosten und die Unklarheit von meta_query-Joins.
• Zusammengesetzte Indizes wie idx_make_model, idx_fuel_condition und idx_status_live die Archivfilterung beschleunigen.
• Die Änderungserkennung (content_hash) direkt neben den Daten liegt, die sie beschreibt.

Aus Gründen der Abwärtskompatibilität schreibt der Importer weiterhin eine kleine Auswahl an Postmeta-Schlüsseln; siehe den nächsten Abschnitt.

Postmeta-Schlüssel, die weiterhin für Fahrzeuge geschrieben werden

Auch mit der benutzerdefinierten Tabelle bleiben die folgenden Postmeta-Schlüssel auf as24ci_car-Beiträgen bestehen. Sie werden bewusst beibehalten, um ältere Integrationen funktionsfähig zu halten und Regressionen in der Admin-Benutzeroberfläche, der AI Assistant-Warteschlange und dem Löschvorgang zu vermeiden.

Manuelle Galerie-Anhänge, die in _as24ci_manual_image_ids nachverfolgt werden, werden als benutzerdefiniert behandelt und vom Lösch- oder Deinstallationscode des Plugins nicht entfernt, selbst wenn importierte Anhänge gelöscht werden.

Manuelle Überschreibungen

Die Fahrzeugtabelle enthält eine JSON-Spalte manual_overrides. Wenn ein Administrator ein Fahrzeugfeld bearbeitet, das normalerweise vom Importer verwaltet wird, wird die Änderung als Schlüssel/Wert-Eintrag in dieser Spalte gespeichert. Der AS24CI\Vehicle_Field_Resolver liest zuerst aus der Zeile und überlagert dann allfällige manuelle Überschreibungen, sodass nachfolgende Importe manuelle Bearbeitungen nicht überschreiben. Das dbDelta-Sicherheitsnetz in Vehicle_Repository::maybe_create_table() fügt diese Spalte bei bestehenden Tabellen hinzu, falls sie fehlt.

Fahrzeug-Taxonomien

as24ci_car-Beiträge sind an 15 nicht-hierarchische Taxonomien gebunden, die von AS24CI\Taxonomies registriert werden:

as24ci_brand, as24ci_model, as24ci_body_type, as24ci_condition, as24ci_fuel_type, as24ci_transmission, as24ci_drive, as24ci_ext_color, as24ci_int_color, as24ci_emission_std, as24ci_energy_label, as24ci_vehicle_cat, as24ci_warranty_type, as24ci_warranty_det, as24ci_cyl_arrange.

Taxonomie-Begriffe steuern die Archivfilter und stellen native WordPress-URLs bereit (zum Beispiel /as24ci_brand/<slug>/). Viele derselben Werte existieren auch als denormalisierte Spalten in der Fahrzeugtabelle (zum Beispiel make, fuel_type, transmission_type), sodass Archivabfragen ohne Join mit wp_term_relationships ausgeführt werden können.

Fahrzeug-Berechtigungen (Capabilities)

Der Beitragstyp as24ci_car verwendet benutzerdefinierte Berechtigungen der Form as24ci_car / as24ci_cars (map_meta_cap ist aktiviert). Bei der Aktivierung gewährt das Plugin diese Berechtigungen Administratoren und der benutzerdefinierten Rolle as24ci_editor. Administratoren erhalten zusätzlich die Berechtigung manage_as24_imports (Plugin::CAP_MANAGE), welche den Zugriff auf den Importer, die Einstellungen, die Tools und die Logs-Benutzeroberfläche regelt. WordPress-Benutzer mit der Rolle "Redaktor" (Editor) erhalten standardmässig keine Fahrzeug-Berechtigungen.

Lead (Anfrage)

Ein Lead stellt eine Kontaktformular- oder Anfrageübermittlung dar. Er wird als ein WordPress-Beitrag des Beitragstyps as24ci_lead gespeichert, registriert von AS24CI\Leads_CPT. Der Beitrag speichert die Nachricht des Besuchers im Beitragsinhalt/-auszug und die Kontaktdaten des Absenders in den Postmeta.

Der Lead-Status wird im Postmeta-Schlüssel _as24ci_lead_status gespeichert und ist standardmässig new. Die gültigen Werte sind als Konstanten auf AS24CI\Leads_CPT definiert:

• STATUS_NEW (new)
• STATUS_CONTACTED (contacted)
• STATUS_CLOSED (closed)
• STATUS_SPAM (spam)

Leads_CPT::get_lead_status() schützt vor ungültigen Werten, indem es auf new zurückgreift. Leads_CPT::update_lead_status() validiert den eingehenden Wert, bevor er geschrieben wird.

Wenn ein Lead von einer Fahrzeugseite aus gesendet wurde, wird das entsprechende Fahrzeug in den Postmeta des Leads referenziert, sodass der Admin-Tab "Leads" das ursprüngliche Angebot anzeigen kann.

Search Agent (Suchauftrag)

Ein Suchauftrag stellt die gespeicherten Suchkriterien eines Besuchers mit einem E-Mail-Abonnement dar. Suchaufträge werden in der dedizierten Tabelle {$wpdb->prefix}as24ci_search_agents gespeichert, die AS24CI\Search_Agent gehört.

Jede Zeile enthält:

• name und email — Identität des Besuchers.
• criteria — die gespeicherten Suchfilter (als Text gespeichert).
• token — ein opaker Token, der zur Bestätigung oder Abmeldung verwendet wird.
• frequency — Benachrichtigungshäufigkeit (standardmässig daily).
• status — einer der Werte pending, active, inactive oder paused, definiert als Konstanten auf AS24CI\Search_Agent.
• created_at und confirmed_at — Zeitstempel für den DSGVO-konformen Double-Opt-In-Ablauf.

Da Suchaufträge personenbezogene Daten enthalten, wird die Tabelle bei der Deinstallation immer gelöscht, unabhängig von der Einstellung as24ci_delete_data_on_uninstall.

Analytics Event (Analytics-Ereignis)

Ein Analytics-Ereignis zeichnet eine einzelne Besucherinteraktion auf (Seitenaufruf, Filternutzung, Kontakt-Öffnung usw.). Ereignisse werden in der dedizierten Tabelle {$wpdb->prefix}as24ci_analytics gespeichert, die AS24CI\Analytics gehört.

Jede Zeile enthält:

• post_id — die zugehörige Fahrzeug-Beitrags-ID oder 0 für globale Ereignisse wie Filtersuchen.
• event_type — der Ereignisbezeichner (die zulässigen Werte werden gegen die klasseneigene Liste ALLOWED_EVENTS validiert).
• extra_data — optionales JSON-codiertes Payload.
• created_at — Zeitstempel des Ereignisses.

Ereignisse werden nur aufgezeichnet, wenn Options::ANALYTICS_ENABLED auf 1 gesetzt ist. Eine tägliche Bereinigung zur Datenaufbewahrung läuft über den as24ci_daily_cleanup-Cron-Hook. Wie die Suchauftrags-Tabelle wird auch die Analytics-Tabelle bei der Deinstallation immer gelöscht, da sie Besucher-Tracking-Daten enthalten kann.

Durch Aktivierung verwaltete Seiten

Während der Aktivierung kann das Plugin drei WordPress-Seiten erstellen, auf denen die öffentlich zugänglichen Shortcodes gehostet werden:

• Cars ([as24ci_archive]) — die Hauptseite des Fahrzeugarchivs.
• Compare Cars ([as24ci_compare]) — die Vergleichsseite.
• Favorites ([as24ci_favorites]) — die Favoriten-/Wunschzettelseite.

Die IDs werden in den Optionen as24ci_page_archive_id, as24ci_page_compare_id und as24ci_page_favorites_id gespeichert. Diese Seiten sind nicht strikt Teil des Datenmodells; sie werden erstellt, damit die Shortcodes ein Standard-Zuhause haben, und sie sind die einzigen WordPress-Seiten, die das Plugin bei einer destruktiven Deinstallation entfernt.

Einstellungen (Optionen)

Alle vom Benutzer konfigurierbaren Einstellungen werden in wp_options gespeichert. Die Schlüssel sind als Konstanten auf AS24CI\Options definiert. Beispiele hierfür sind:

• API und Authentifizierung: as24ci_base_url, as24ci_token_url, as24ci_seller_ids, as24ci_client_id, as24ci_client_secret, as24ci_token_audience.
• Verhalten des Importers: as24ci_default_post_status, as24ci_default_post_author, as24ci_import_images, as24ci_max_images, as24ci_convert_to_webp, as24ci_webp_quality, as24ci_full_sync.
• Scheduler: as24ci_auto_import_enabled, as24ci_cron_schedule, as24ci_cron_start_time, as24ci_cron_custom_minutes, as24ci_cron_max_vehicles, as24ci_cron_token.
• Feature-Toggles: Options::FEATURE_*-Konstanten für Sitemap, Schema, Favoriten, Vergleich, Social Share, PDF-Datenblatt, Suchauftrag, Analytics, AI Assistant, REST-API, Dashboard-Widget usw.
• Schema-/Versionsmarkierungen: as24ci_db_version, as24ci_caps_version, as24ci_vehicles_db_version, as24ci_search_agent_db_version.

Das vollständige Inventar und das Verhalten dieser Optionen sind im Dokument Options And Settings Storage dokumentiert.

Transients

Das Plugin verwendet eine kleine Anzahl von Transients für kurzlebige Zustände. Die für das Datenmodell relevantesten sind:

• as24ci_access_token — zwischengespeicherter AutoScout24 OAuth-Access-Token.
• as24ci_cron_import_running — Ausführungssperre (Run-Lock), die überschneidende Importe verhindert (Scheduler::LOCK_TRANSIENT, ~40 Minuten TTL).
• as24ci_image_queue_running — Ausführungssperre für den Bildwarteschlangen-Worker.
• as24ci_batch_queue — Warteschlangen-Payload für den manuellen Batch-Assistenten.

Transients werden bei der Deaktivierung und Deinstallation nach Bedarf gelöscht.

---

---

Konfigurationsreferenz

Betriebliche Hinweise

• Ein Fahrzeug existiert so lange, wie sowohl sein Post als auch seine Tabellenzeile existieren. Die Bereinigung über AS24CI\Vehicle_Deleter wird während der Plugin-Konstruktion so eingebunden, dass jeder Pfad zur dauerhaften Löschung (natives WP-Löschen, vollständiger Import-Sync, Massenaktion) denselben idempotenten Ablauf durchläuft.
• Das Repository verwaltet einen kleinen In-Process-Cache (Objekt-Cache-Gruppe as24ci_vehicles, ca. 1 Stunde TTL) für Abfragen einzelner Zeilen. Direkte Schreibvorgänge in die Tabelle durch benutzerdefinierten Code umgehen diesen Cache; denken Sie daran, ihn manuell zu invalidieren, wenn Sie das Repository erweitern.
• Die Spalte raw_data in der Fahrzeugtabelle bewahrt die Original-Payload aus dem Import. Dies ist nützlich für das Debugging von Mapping-Problemen, sollte jedoch nicht als stabile Schnittstelle herangezogen werden; die Struktur der Payload wird durch die AutoScout24-API bestimmt.
• Bilder der manuellen Galerie werden bewusst als Eigentum des Administrators behandelt. Sie werden nicht entfernt, wenn importierte Bilder gelöscht werden, und sie werden auch bei der Deinstallation nicht gelöscht. Entfernen Sie diese bei Bedarf manuell aus der WordPress-Mediathek.

Fehlerbehebung

• Einem Fahrzeug fehlen im Frontend Feldwerte, aber es existiert in der Post-Liste. Überprüfen Sie, ob die Fahrzeugtabelle eine Zeile mit der passenden post_id enthält. Wenn die Zeile fehlt, wurde das Inserat ausserhalb des Importers erstellt oder die Migration zur benutzerdefinierten Tabelle wurde nicht abgeschlossen.
• Änderungen in der Metabox werden beim nächsten Import überschrieben. Stellen Sie sicher, dass das betroffene Feld in die JSON-Spalte manual_overrides geschrieben wird. Die Überschreibungsebene erfordert die Existenz der Spalte manual_overrides; das Schema-Upgrade fügt diese bei Bedarf hinzu.
• Ein importiertes Bild verschwindet. Das Plugin löscht nur Anhänge, die in _as24ci_image_ids nachverfolgt werden. Bilder, die über die manuelle Galerie (_as24ci_manual_image_ids) hinzugefügt wurden, bleiben erhalten. Überprüfen Sie, welche Liste die betroffene Anhang-ID enthält.
• Suchabo- oder Analytics-Zeilen werden nach dem Löschen des Plugins immer noch angezeigt. Vergewissern Sie sich, dass uninstall.php ausgeführt wurde. Die beiden Tabellen werden bei der Deinstallation bedingungslos gelöscht. Wenn die Deinstallation nicht ausgeführt wurde (beispielsweise weil das Plugin nur deaktiviert wurde), bleiben die Zeilen bestehen.

Verwandte Dokumente

• Architektur-Übersicht
• Plugin-Bootstrap und Lebenszyklus
• Datenbankschema
• Sektionsübersicht