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:

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

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

Übersicht

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

1. Fahrzeug (Vehicle) – ein einzelnes Fahrzeuginserat, das aus AutoScout24 importiert wurde.
2. Lead – eine Kontaktformular- oder Anfrageübermittlung, die (optional) an ein Fahrzeug gebunden ist.
3. Suchauftrag (Search Agent) – die gespeicherten Suchkriterien eines Besuchers mit E-Mail-Benachrichtigungen.
4. Analytics-Event – ein einzelnes erfasstes 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-Events leben in ihren eigenen benutzerdefinierten Tabellen.

Fahrzeug (Vehicle)

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, Erstzulassungsjahr, Kraftstoffart, Ausstattung usw.), den rohen 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 außerdem eine eindeutige Spalte as24_id, die den AutoScout24-Inseratsbezeichner 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, Datumsangaben für Erstzulassung) direkt abgefragt und sortiert werden können, ohne die Kosten und Unklarheiten von meta_query-Joins in Kauf nehmen zu müssen.
• 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 einen kleinen Satz von 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 Warteschlange des KI-Assistenten und dem Löschvorgang zu vermeiden.

Manuelle Galerie-Anhänge, die in _as24ci_manual_image_ids nachverfolgt werden, werden als benutzerzugehörig 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 alle manuellen Ü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 auf 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 diesen Berechtigungssatz Administratoren und der benutzerdefinierten Rolle as24ci_editor. Administratoren erhalten zusätzlich die Berechtigung manage_as24_imports (Plugin::CAP_MANAGE), die den Zugriff auf den Importer, die Einstellungen, die Werkzeuge und die Protokoll-Benutzeroberfläche regelt. WordPress-Benutzer mit der Rolle "Redakteur" (Editor) erhalten standardmäßig keine Fahrzeug-Berechtigungen.

Lead

Ein Lead stellt eine Kontaktformular- oder Anfrageübermittlung dar. Er wird als WordPress-Beitrag des Beitragstyps as24ci_lead gespeichert, der von AS24CI\Leads_CPT registriert wird. 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äßig 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ückfällt. 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 Inserat anzeigen kann.

Suchauftrag (Search Agent)

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 zum Abbestellen verwendet wird.
• frequency – Benachrichtigungshäufigkeit (standardmäßig daily).
• status – einer der Werte pending, active, inactive oder paused, die als Konstanten auf AS24CI\Search_Agent definiert sind.
• 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

Ein Analytics-Event zeichnet eine einzelne Besucherinteraktion auf (Seitenaufruf, Filternutzung, Kontakt-Öffnung usw.). Events 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 Events wie Filtersuchen.
• event_type – den Event-Bezeichner (die zulässigen Werte werden gegen die klasseneigene Liste ALLOWED_EVENTS validiert).
• extra_data – optionaler JSON-kodierter Payload.
• created_at – Zeitstempel des Events.

Events werden nur aufgezeichnet, wenn Options::ANALYTICS_ENABLED auf 1 gesetzt ist. Eine tägliche Bereinigung zur Datenaufbewahrung läuft über den Cron-Hook as24ci_daily_cleanup. 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 eingebunden sind:

• Cars ([as24ci_archive]) – die Hauptseite für das Fahrzeugarchiv.
• 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 streng 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 (Options)

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 Sharing, PDF-Datenblatt, Suchauftrag, Analytics, KI-Assistent, 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 Speicherung von Optionen und Einstellungen 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-Zugriffstoken.
• 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 entsprechend gelöscht.

---

---

Konfigurationsreferenz

Betriebliche Hinweise

• Ein Fahrzeug existiert, solange sowohl sein Post als auch seine Tabellenzeile existieren. Die Bereinigung über AS24CI\Vehicle_Deleter ist während der Plugin-Konstruktion so verdrahtet, dass jeder Pfad zur dauerhaften Löschung (natives WP-Löschen, vollständige Synchronisierung des Importers, Massenaktion) denselben idempotenten Ablauf durchläuft.
• Das Repository hält einen kleinen In-Process-Cache (Object-Cache-Gruppe as24ci_vehicles, ~1 Stunde TTL) für Abfragen einzelner Zeilen bereit. 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 Quell-Payload aus dem Import. Dies ist nützlich für das Debugging von Mapping-Problemen, sollte jedoch nicht als stabiler Vertrag herangezogen werden; die Payload-Struktur wird durch die AutoScout24-API bestimmt.
• Manuelle Galeriebilder 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 sie bei Bedarf manuell aus der WordPress-Mediathek.

Fehlerbehebung

• Einem Fahrzeug fehlen Feldwerte im Frontend, 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 der Eintrag außerhalb 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.
• Suchauftrags- oder Analysezeilen 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.

Zugehörige Dokumente

• Architekturübersicht
• Plugin-Bootstrap und Lebenszyklus
• Datenbankschema
• Bereichsübersicht