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 in 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 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. Fahrzeug — ein einzelnes Fahrzeuginserat, das aus AutoScout24 oder über den Connections-Importer importiert wurde (interne Klasse Universal_Importer; CSV / XML / XLSX / JSON / ZIP und die Feed- / E-Mail- / carcuro- / mobile.de-Konnektoren). Beide Pfade nutzen denselben Speicher und die nachgelagerte Pipeline.
2. Lead — ein Kontaktformular- oder Anfrage-Eintrag, der (optional) an ein Fahrzeug gebunden ist.
3. Suchauftrag — 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

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-Berechtigungsstruktur.
• 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.), die rohen API-Nutzdaten (Payload) und Metadaten, die für die Änderungserkennung verwendet werden.

Die beiden Datensätze sind durch 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-Inseratsidentifikator 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 Kilometerstände, Daten für die Erstzulassung) direkt abgefragt und sortiert werden können, ohne die Kosten und Unklarheiten 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 absichtlich beibehalten, um ältere Integrationen funktionsfähig zu halten und Regressionen in der Admin-Benutzeroberfläche, der AI Assistant-Warteschlange und dem Lösch-Workflow 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 manual_overrides-JSON-Spalte. 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 legt anschliessend alle manuellen Überschreibungen darüber, 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 mit 15 nicht-hierarchischen Taxonomien verknüpft, 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.

Alle 15 Taxonomien sind als nicht öffentlich registriert (public=false, publicly_queryable=false, rewrite=false, query_var=false, show_in_rest=true; siehe includes/class-as24ci-taxonomies.php:204-223). Sie können im WordPress-Admin bearbeitet werden, haben aber keine öffentlichen Begriff-Archiv-URLs — zum Beispiel wird /as24ci_brand/<slug>/ nicht aufgelöst. Begriffe steuern die Admin-Benutzeroberfläche und die Archiv-Filterlogik, keine eigenständigen Begriffsseiten. Viele der gleichen Werte existieren auch als denormalisierte Spalten in der Fahrzeugtabelle (z. B. make, fuel_type, transmission_type), sodass Archivabfragen ohne Join von wp_term_relationships ausgeführt werden können.

Fahrzeug-Berechtigungen

Der Beitragstyp as24ci_car verwendet benutzerdefinierte Berechtigungen (Capabilities) 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), die den Zugriff auf den Importer, die Einstellungen, die Tools und die Logs-Benutzeroberfläche regelt. WordPress "Redaktor"-Benutzer erhalten standardmässig keine Fahrzeug-Berechtigungen.

---

Lead

Ein Lead repräsentiert eine Kontaktaufnahme oder eine Anfrage über ein Formular. 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-Daten.

Der Lead-Status wird im Postmeta-Schlüssel _as24ci_lead_status gespeichert und ist standardmässig auf new gesetzt. Die gültigen Werte sind als Konstanten in 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 auf new zurückgegriffen wird. 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-Daten des Leads referenziert, sodass der Admin-Tab "Leads" das ursprüngliche Inserat anzeigen kann.

Suchauftrag

Ein Suchauftrag repräsentiert die gespeicherten Suchkriterien eines Besuchers mit einem E-Mail-Abonnement. Suchaufträge werden in der dedizierten Tabelle {$wpdb->prefix}as24ci_search_agents gespeichert, die von AS24CI\Search_Agent verwaltet wird.

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 für die Abmeldung verwendet wird.
• frequency — Benachrichtigungshäufigkeit (Standardwert ist daily).
• status — einer der Werte pending, active, inactive oder paused, die als Konstanten in 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 unabhängig von der Einstellung as24ci_delete_data_on_uninstall immer gelöscht.

Analytics-Event

Ein Analytics-Event zeichnet eine einzelne Interaktion eines Besuchers auf (Seitenaufruf, Filternutzung, Kontaktöffnung usw.). Events werden in der dedizierten Tabelle {$wpdb->prefix}as24ci_analytics gespeichert, die von AS24CI\Analytics verwaltet wird.

Jede Zeile enthält:

• post_id — die Beitrags-ID des entsprechenden Fahrzeugs oder 0 für globale Events wie Filtersuchen.
• event_type — die Event-Kennung (die zulässigen Werte werden mit der klasseneigenen Liste ALLOWED_EVENTS abgeglichen).
• 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 Daten zur Besucher-Nachverfolgung enthalten kann.

Aktivierungsgesteuerte Seiten

Während der Aktivierung kann das Plugin drei WordPress-Seiten erstellen, auf denen die öffentlich sichtbaren Shortcodes eingebunden sind:

• Cars ([as24ci_archive]) — die Hauptseite für das Fahrzeugarchiv.
• Compare Cars ([as24ci_compare]) — die Vergleichsseite.
• Favorites ([as24ci_favorites]) — die Favoriten-/Merkzettelseite.

Die IDs werden in den Optionen as24ci_page_archive_id, as24ci_page_compare_id und as24ci_page_favorites_id gespeichert. Diese Seiten sind nicht im engeren Sinne Teil des Datenmodells; sie werden erstellt, damit die Shortcodes eine Standard-Heimat haben, und sie sind die einzigen WordPress-Seiten, die das Plugin bei einer vollständigen Deinstallation entfernt.

Einstellungen (Optionen)

Alle vom Benutzer konfigurierbaren Einstellungen werden in wp_options gespeichert. Die Schlüssel sind als Konstanten in 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.
• Funktions-Schalter: Options::FEATURE_*-Konstanten für Sitemap, Schema, Favoriten, Vergleich, Social Sharing, PDF datasheet, 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.

Der vollständige Bestand 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 wichtigsten sind:

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

Transients werden bei der Deaktivierung und Deinstallation entsprechend gelöscht.

Konfigurationsreferenz

Betriebliche Hinweise

• Ein Fahrzeug existiert so lange, wie sowohl sein Beitrag als auch seine Tabellenzeile existieren. Die Bereinigung AS24CI\Vehicle_Deleter ist während der Plugin-Konstruktion so verdrahtet, dass jeder Pfad zum dauerhaften Löschen (natives WP-Löschen, vollständige Synchronisierung des Importers, Massenaktion) denselben idempotenten Ablauf durchläuft.
• Das Repository hält einen kleinen prozessinternen Cache (Objekt-Cache-Gruppe as24ci_vehicles, ca. 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 den Quell-Payload aus dem Import. Dies ist nützlich für das Debugging von Mapping-Problemen, sollte jedoch nicht als stabile Schnittstelle 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 diese bei Bedarf manuell aus der WordPress-Mediathek.

---

Fehlerbehebung

• Ein Fahrzeug weist im Frontend fehlende Feldwerte auf, existiert jedoch in der Beitragsliste. Überprüfen Sie, ob die Fahrzeugtabelle eine Zeile mit der passenden post_id enthält. Wenn die Zeile fehlt, wurde das Fahrzeug ausserhalb des Importers erstellt oder die Migration zur benutzerdefinierten Tabelle wurde nicht abgeschlossen.
• Bearbeitungen 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, in welcher Liste sich die betroffene Anhangs-ID befindet.
• 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
• Kapitelübersicht