Dokumentation · Technische Dokumentation

Architektur-Übersicht

Dieses Dokument beschreibt die übergeordnete Architektur des ADP Car Market Hub WordPress-Plugins: wie der Quellcode organisiert ist, welche Klassen die Hauptverantwortung tragen und wie die wichtigsten Funktionen zur Laufzeit miteinander verknüpft sind.

Wann Sie dieses Dokument verwenden sollten

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

  • Einen Überblick über die PHP-Codebasis des Plugins erhalten, bevor Sie sich in ein bestimmtes Subsystem vertiefen.
  • Verstehen, welche Klasse für eine bestimmte Funktion verantwortlich ist.
  • Eine Anpassung, Integration oder ein Code-Review planen.

Für die schrittweise Bootstrap-Reihenfolge siehe Plugin Bootstrap And Lifecycle. Für Details zur Speicherung siehe Data Model und Database Schema.

Übersicht

Das Plugin ist in PHP implementiert und folgt den Standardkonventionen für WordPress-Plugins. Es verwendet:

  • Eine einzige Root-Datei (adp-car-market-hub.php), die Plugin-Konstanten definiert, einen Autoloader registriert und Bootstrap-Callbacks einhängt.
  • Einen PHP-Namespace AS24CI\ für alle Klassen.
  • Die WordPress-Core-APIs für Custom Post Types, Taxonomien, Optionen, WP-Cron, REST-API, AJAX-Handler und von dbDelta verwaltete benutzerdefinierte Tabellen.
  • Ein zentrales AS24CI\Plugin-Singleton, das jede Funktion bei der plugins_loaded-Action miteinander verknüpft.

Verzeichnisstruktur auf oberster Ebene

Das Repository ist wie folgt organisiert (es sind nur Verzeichnisse aufgeführt, die für die Laufzeitarchitektur relevant sind):

  • adp-car-market-hub.php — Haupt-Plugin-Datei. Definiert Konstanten, registriert den Autoloader, lädt die Textdomain, registriert Aktivierungs-/Deaktivierungs-Hooks, registriert benutzerdefinierte WP-Cron-Intervalle und bootstrappt das AS24CI\Plugin-Singleton auf plugins_loaded.
  • includes/ — Gemeinsam genutzte und Frontend-PHP-Klassen, eine Klasse pro Datei. Dateinamen folgen dem Muster class-as24ci-<name>.php und werden über den Autoloader zur Klasse AS24CI\<Name> aufgelöst.
  • includes/admin/ — Nur für den Admin-Bereich bestimmte PHP-Klassen (Einstellungs-Tabs, List-Table-Hilfsklassen, Dashboard-Widgets). Werden vom selben Autoloader als Fallback aufgelöst, wenn eine Klasse unter includes/ nicht gefunden wird.
  • src/Core/Helpers.php — Gemeinsam genutzte prozedurale Hilfsfunktionen, die bedingungslos aus der Haupt-Plugin-Datei geladen werden.
  • templates/ — Frontend-Templates und Template-Teile, die von Themes überschrieben werden können.
  • assets/ — Admin- und Frontend-CSS, JavaScript und Bilder.
  • languages/ — Übersetzungsdateien; die Textdomain ist adp-car-market-hub.
  • uninstall.php — Wird ausgeführt, wenn das Plugin aus WordPress gelöscht wird, und entfernt Plugin-Optionen sowie (optional) importierte Inhalte.

Autoloader

adp-car-market-hub.php registriert einen kleinen PSR-4-kompatiblen Autoloader für das Präfix AS24CI\. Klassennamen werden in die Dateinamenskonvention class-as24ci-<lower-case-name-with-dashes>.php konvertiert. Der Autoloader sucht zuerst in includes/ und dann in includes/admin/, sodass gemeinsam genutzte und nur für den Admin-Bereich bestimmte Klassen einen einzigen Namespace teilen können.

Kernklassen und ihre Aufgaben

Die folgenden Klassen bilden das Rückgrat des Plugins. Die Namen sind in ihrer vollqualifizierten Form (AS24CI\<Class>) angegeben.

Bootstrap und gemeinsam genutzte Dienste

  • AS24CI\Plugin — Singleton-Einstiegspunkt. Erstellt die gemeinsam genutzten Dienstinstanzen (Logger, Client, Image_Importer, Vehicle_Repository, Importer, Scheduler), verknüpft alle WordPress-Hooks für den aktiven Funktionsumfang und stellt die statischen activate() / deactivate() / init()-Callbacks bereit.
  • AS24CI\Logger — Leichtgewichtiger Logger, der im gesamten Plugin für Importer- und Scheduler-Meldungen verwendet wird.
  • AS24CI\Options — Zentrales Register für Optionsschlüssel, die als Klassenkonstanten bereitgestellt werden (z. B. Options::DB_VERSION, Options::DEFAULT_CURRENCY, Options::AUTO_IMPORT_ENABLED). Das Skript uninstall.php verwendet Options::get_all_keys(), um Optionen bei der Deinstallation des Plugins zu bereinigen.

Daten und Speicherung

  • AS24CI\CPT — Registriert den Custom Post Type as24ci_car mit benutzerdefiniertem Berechtigungs-Mapping (as24ci_car / as24ci_cars) und der kombinierten Metabox "AutoScout24 API Import".
  • AS24CI\Taxonomies — Registriert die 15 Fahrzeugattribut-Taxonomien, die an as24ci_car angehängt sind (Marke, Modell, Karosserieform, Kraftstoffart, Getriebe, Antrieb, Zustand, Aussen-/Innenfarbe, Schadstoffklasse, Energieetikette, Fahrzeugkategorie, Garantieart, Garantiedetails, Zylinderanordnung).
  • AS24CI\Leads_CPT — Registriert den Custom Post Type as24ci_lead, der zur Speicherung von Kontaktformular-Anfragen verwendet wird, mit Statuskonstanten für new, contacted, closed und spam.
  • AS24CI\Vehicle_Repository — Repository für die dedizierte benutzerdefinierte Tabelle {$wpdb->prefix}as24_vehicles, die Fahrzeugfelddaten enthält (anstelle von wp_postmeta). Bietet Schema-Verwaltung (maybe_create_table()), CRUD-Hilfsmethoden sowie Filter- und Sortierungs-Whitelists, die von find() verwendet werden.
  • AS24CI\Vehicle_Field_Resolver — Zentraler Reader, der Fahrzeugfelder auflöst, indem er Repository-Daten mit manuellen Überschreibungen kombiniert. Wird während der Erstellung von Plugin über Vehicle_Field_Resolver::set_repository() verknüpft.
  • AS24CI\Vehicle_Deleter — Einziger, idempotenter Bereinigungspfad, der immer dann verwendet wird, wenn ein Fahrzeug dauerhaft gelöscht wird (natives WP-Löschen, Vollsynchronisations-Löschung des Importers, Massenaktion). Wird während der Erstellung von Plugin verknüpft.

Import-Pipeline

  • AS24CI\Client — HTTP-Client für die AutoScout24-API. Übernimmt die Authentifizierung und die Ausführung von Anfragen.
  • AS24CI\Mapper — Weist eingehende AutoScout24-Fahrzeugdaten der internen Feldstruktur des Repositories zu und schreibt die _as24ci_listing_id-Postmeta aus Gründen der Abwärtskompatibilität.
  • AS24CI\Importer — Koordiniert den Import pro Fahrzeug: Ruft Daten über Client ab, transformiert sie über Mapper, speichert Fahrzeuge über das Repository und verfolgt die Änderungserkennung über die Postmeta-Schlüssel _as24ci_content_hash und _as24ci_images_hash.
  • AS24CI\Image_Importer — Lädt Fahrzeugbilder herunter und hängt sie an, optional unter Konvertierung in WebP. Speichert Attachment-IDs in der _as24ci_image_ids-Postmeta.
  • AS24CI\Scheduler — Verwaltet die WP-Cron-Hooks as24ci_scheduled_import und as24ci_image_queue_process, die Run-Lock-Transients (as24ci_cron_import_running, as24ci_image_queue_running) und das manuelle Batch-Wizard-Warteschlangen-Transient as24ci_batch_queue. Derselbe run_import()-Ablauf wird von WP-Cron, dem REST-Cron-Endpunkt und der Admin-Schaltfläche "Jetzt ausführen" verwendet.
  • AS24CI\Cron_Endpoint — REST-Endpunkt, der es externen Servern ermöglicht, Importe über eine mit einem Token gesicherte URL auszulösen.

Connections-Importer

Ein zweites, herstellerunabhängiges Import-Frontend (Admin-Bereich "Connections", Slug as24ci-universal-import; interne Klasse AS24CI\Universal_Importer), das dieselbe AS24CI\Importer-Pipeline speist wie der AutoScout24-Pfad (über Importer::upsert_external_listing()):

  • AS24CI\Universal_Importer — Orchestriert einen Durchlauf: Parsen → Zuordnen → Validieren → Upsert → optionale quellspezifische Vollsynchronisation.
  • AS24CI\Import_Reader — Format-Dispatcher (CSV / XML / XLSX / JSON / ZIP), der eine einheitliche { header, rows }-Struktur zurückgibt, unterstützt durch Import_Csv_Reader, Import_Xml_Reader, Import_Xlsx_Reader, Import_Json_Reader und Import_Zip_Reader.
  • AS24CI\Import_Encoding — Normalisiert Quelltext zu UTF-8 (Windows-1252 / ISO-8859 / BOM-Handling).
  • AS24CI\Import_Template — Ordnet Quellspalten AutoScout24-strukturierten Feldern mit numerischer/boolescher Normalisierung und Wertetabellen zu.
  • AS24CI\Import_Feed, AS24CI\Import_Mail, AS24CI\Import_Carcuro, AS24CI\Import_Mobile — Die benannten geplanten Konnektoren (URL/FTP/SFTP-Feed, IMAP-Postfach, carcuro-API und die mobile.de-API, includes/class-as24ci-import-mobile.php), die Einstellungen sowie (falls zutreffend) ein verschlüsseltes Secret über AS24CI\Secrets speichern und nach Zeitplan importieren. Feed und E-Mail laufen über eigene Cron-Events; carcuro und mobile.de nutzen den zentralen as24ci_scheduled_import-Zeitplan. Initialisiert in AS24CI\Plugin über den jeweiligen register_hooks() des Konnektors. Der Admin-Tab Connections (interne Klasse AS24CI\Admin_Tab_Universal_Import) rendert das Konnektor-Akkordeon und den Datei-Upload-Assistenten.

Siehe Import Engine für den Ablauf des Durchlaufs.

Frontend, SEO und Integrationen

  • AS24CI\Templates — Leitet Fahrzeug-Archiv- und Einzelansichts-Templates durch den Template-Loader des Plugins, was Theme-Überschreibungen ermöglicht.
  • AS24CI\Assets — Registriert und reiht CSS- und JavaScript-Bundles für das Admin- und Frontend ein.
  • AS24CI\Archive_Filters — Rendert die Benutzeroberfläche des Archivfilters und wendet Abfrageänderungen basierend auf der Benutzerauswahl an.
  • AS24CI\Schema — Fügt strukturierte Daten von Schema.org und Open Graph / Twitter Card Meta-Tags zu einzelnen Fahrzeugseiten hinzu. Optional, gesteuert durch Options::FEATURE_SCHEMA.
  • AS24CI\Sitemap — Integriert Fahrzeuge in die WordPress-Core-Sitemap und ist kompatibel mit Yoast und Rank Math. Optional, gesteuert durch Options::FEATURE_SITEMAP.
  • AS24CI\Vehicle_Redirects — Wandelt den 404-Fehler, den ein dauerhaft gelöschtes Fahrzeug andernfalls erzeugen würde, in eine 301-Weiterleitung zu einer vorgefilterten Suche nach Marke/Modell um. Bei before_delete_post (Priorität 5, vor AS24CI\Vehicle_Deleter) zeichnet es den Slug des gelöschten Fahrzeugs sowie seine as24ci_brand / as24ci_model Term-Slugs in der Tabelle {$wpdb->prefix}as24ci_redirects auf; bei template_redirect gleicht es den Slug einer 404-Anfrage ab und ermittelt das beste aktive Ziel, wobei es make+model → make → /cars/ archive herabstuft, damit es nie auf einem leeren Ergebnis landet. Das Ziel ist immer eine Suchanfrage (nie ein anderes Fahrzeug), sodass keine Weiterleitungsketten entstehen. Optional, gesteuert durch Options::FEATURE_VEHICLE_REDIRECTS und den Filter as24ci_vehicle_redirects_enabled. Einträge werden nach einem Aufbewahrungsfenster von 365 Tagen bereinigt und aufgelöste Ziele werden für eine Stunde zwischengespeichert.
  • AS24CI\Social_Share, AS24CI\Pdf_Datasheet, AS24CI\Favorites, AS24CI\Compare, AS24CI\Export, AS24CI\Bulk_Actions, AS24CI\Financing_Calculator, AS24CI\Test_Drive, AS24CI\Search_Agent — Optionale Funktionen, die jeweils ihre eigenen Hooks registrieren. Die meisten werden durch einen Options::FEATURE_*-Schalter gesteuert (siehe seed_safe_defaults() in AS24CI\Plugin für die Standardeinstellungen bei einer Neuinstallation).
  • AS24CI\Webhooks — Ausgehende Webhooks für CRM- und Integrations-Anwendungsfälle.
  • AS24CI\Rest_Api — Öffentliche REST-API für Fahrzeugangebote, gesteuert durch Options::REST_API_ENABLED.
  • AS24CI\Analytics — Tracking von Seitenaufrufen, Filtern und Leads. Verwaltet die Tabelle {$wpdb->prefix}as24ci_analytics und den Aufbewahrungs-Cron as24ci_daily_cleanup.
  • AS24CI\Ai_Assistant — Generiert KI-Beschreibungen, SEO-Metadaten und Ausstattungs-Highlights unter Verwendung der verwalteten Google Gemini-Konfiguration, die von AS24CI\Ai_Config bereitgestellt wird. Der Gemini-Schlüssel des Kunden wird Server-zu-Server von der API-Plattform bereitgestellt und über AS24CI\Ai_Credential_Manager verschlüsselt gespeichert; in der Admin-Benutzeroberfläche kann kein Anbieter, Modell oder API-Schlüssel ausgewählt werden.
  • AS24CI\Data_Quality_Scanner — Optionaler Detektor für Tippfehler in Taxonomien, der die KI-Integration nutzt.
  • AS24CI\Pricing_Engine — Tägliche Preisanalyse, die über den Hook as24ci_pricing_analysis_cron ausgeführt wird.
  • AS24CI\Locations, AS24CI\Seller_Profile_Fields — Standorte der Garage, Öffnungszeiten und Verkäuferprofil-Metadaten.
  • AS24CI\Team / AS24CI\Admin_Team — CMH Team: Verkaufsberater der Garage, die keine WordPress-Benutzerkonten benötigen. Die Speicherung basiert auf Optionen (keine benutzerdefinierte Tabelle oder CPT); Kontakte werden in Options::TEAM_MEMBERS und zugehörigen Optionsschlüsseln gespeichert, was dem Muster von Locations entspricht. Admin_Team registriert ein dediziertes Admin-Menü auf oberster Ebene.
  • AS24CI\License_Manager, AS24CI\License_Client, AS24CI\License_Refresh_Signal, AS24CI\License_Signal_Secret — Lizenz- / verwaltete Zugriffsebene der ADP Car Market Hub-API-Plattform. License_Manager verwaltet den täglichen Re-Validierungs-Cron (as24ci_license_refresh), die Speicherung von Funktionsrechten, die Steuerung der Schreibpfade für Betrieb/KI und Admin-Hinweise. License_Refresh_Signal stellt den eingehenden Endpunkt POST /as24ci/v1/license-refresh-signal bereit.
  • AS24CI\Ai_Credential_Manager — Speichert und entschlüsselt die von der API-Plattform bereitgestellten Gemini-Zugangsdaten des Kunden.
  • Content Studio (AS24CI\Content_Studio_*, z. B. Content_Studio_Repository, Content_Studio_Options, Content_Studio_Admin_Worker, Admin_Tab_Content_Studio) — Ein weitgehend eigenständiges Modul, das Marketing-Inhalte aus bestehenden Fahrzeugdaten generiert. Es verwaltet eigene Tabellen (as24ci_content_studio_jobs, as24ci_content_studio_assets), eigene as24ci_content_studio_*-Optionen sowie einen Hintergrund-Worker und wird direkt aus der Hauptdatei des Plugins anstatt über den Admin-Router initialisiert. Es liest bestehende Fahrzeug-/Importdaten schreibgeschützt aus.

Admin-Benutzeroberfläche

  • AS24CI\Admin — Admin-Controller auf oberster Ebene, der nur instanziiert wird, wenn is_admin() wahr ist. Setzt intern Tab-Klassen aus includes/admin/ zusammen (Importer, Einstellungen, Mapping, Design, Layout-Manager, Leads, AI Assistant, Systemstatus usw.).
  • AS24CI\Dashboard_Widget — Optionales WordPress-Dashboard-Widget, gesteuert durch Options::FEATURE_DASHBOARD_WIDGET.

Feature-Toggles und "sichere erste Einrichtung"

Die meisten nicht essenziellen Funktionen werden in AS24CI\Plugin::register_hooks() bedingt registriert, basierend auf Optionen, deren Konstanten in AS24CI\Options definiert sind (zum Beispiel FEATURE_SCHEMA, FEATURE_SITEMAP, FEATURE_VEHICLE_REDIRECTS, FEATURE_FAVORITES, FEATURE_COMPARE, FEATURE_PDF_DATASHEET, REST_API_ENABLED, AI_ASSISTANT_ENABLED, ANALYTICS_ENABLED, TEST_DRIVE_ENABLED). AS24CI\Vehicle_Redirects wird bedingungslos registriert und wertet seinen Toggle zur Laufzeit aus, sodass Weiterleitungen für gelöschte Fahrzeuge ein- oder ausgeschaltet werden können, ohne das Plugin neu zu initialisieren.

Bei einer Neuinstallation setzt das Plugin konservative Standardwerte über AS24CI\Plugin::seed_safe_defaults(). Datenschutzrelevante, externe oder Batch-Funktionen sind standardmässig deaktiviert; frontend-freundliche Funktionen (Sitemap, Schema, Favoriten, Vergleich, Finanzierungsrechner, Dashboard-Widget, Export, Lazy Loading, Layout Manager) sind standardmässig aktiviert. Bestehende Installationen werden nie überschrieben, da der Seeder add_option() verwendet.

Speicher-Layout (High-Level)

Das Plugin verwendet drei Speicherebenen:

  1. Eigene Datenbanktabellen, verwaltet über dbDelta: - {$wpdb->prefix}as24_vehicles — Fahrzeug-Felddaten, im Besitz von AS24CI\Vehicle_Repository. - {$wpdb->prefix}as24ci_analytics — Analytics-Ereignisse, im Besitz von AS24CI\Analytics. - {$wpdb->prefix}as24ci_search_agents — Suchabo-Abonnements, im Besitz von AS24CI\Search_Agent. - {$wpdb->prefix}as24ci_sync_state — Letzter Synchronisations-Heartbeat pro Fahrzeug (post_id PK, last_sync), im Besitz von AS24CI\Sync_State und verzögert (lazy) bei admin_init erstellt, nicht bei der Aktivierung. - {$wpdb->prefix}as24ci_redirects — Weiterleitungs-Map für gelöschte Fahrzeuge (slug unique, make_slug, model_slug, created_at), im Besitz von AS24CI\Vehicle_Redirects. Erstellt bei der Aktivierung und über die Migration v11, und bereinigt nach einem Aufbewahrungsfenster von 365 Tagen. - {$wpdb->prefix}as24ci_content_studio_jobs und {$wpdb->prefix}as24ci_content_studio_assets — Content Studio-Jobs und generierte Assets, im Besitz von AS24CI\Content_Studio_Repository.
  2. WordPress-Beiträge und Postmeta: - as24ci_car-Beiträge bilden die Grundlage für die WordPress-Permalinks, Taxonomien und Templates für jedes Fahrzeug. Eine kleine Auswahl an Postmeta-Schlüsseln verbleibt aus Gründen der Abwärtskompatibilität in wp_postmeta (zum Beispiel _as24ci_listing_id, _as24ci_content_hash, _as24ci_images_hash, _as24ci_image_ids, _as24ci_manual_image_ids). - as24ci_lead-Beiträge speichern Kontaktformular-Anfragen mit dem in _as24ci_lead_status gespeicherten Status.
  3. wp_options — Alle vom Benutzer konfigurierbaren Einstellungen. Schlüssel sind als Konstanten in AS24CI\Options (und für das Content Studio in AS24CI\Content_Studio_Options) definiert. Schema-Versionen für die eigenen Tabellen werden ebenfalls als Optionen gespeichert (as24ci_db_version, as24ci_vehicles_db_version, as24ci_search_agent_db_version, as24ci_content_studio_db_version). Kontakte des CMH Team werden ebenfalls in den Optionen gespeichert (as24ci_team_*).

Für Details auf Spaltenebene siehe Datenbankschema. Für das logische Entitätsmodell und das Zusammenspiel zwischen Postmeta und der eigenen Tabelle siehe Datenmodell.

Laufzeit-Ablauf im Überblick

Ein typischer Request durchläuft die folgenden Phasen (vereinfacht):

  1. WordPress lädt adp-car-market-hub.php, was Plugin-Konstanten definiert, den Autoloader registriert und eigene WP-Cron-Intervalle hinzufügt.
  2. Bei plugins_loaded (Priorität 1) wird die Textdomain geladen.
  3. Bei plugins_loaded (Standardpriorität) läuft AS24CI\Plugin::init(), instanziiert das Singleton und registriert alle Hooks für aktive Funktionen.
  4. Feature-Klassen registrieren ihre eigenen Hooks bei init, rest_api_init, wp_ajax_*, wp_footer usw.
  5. Anschliessende Aktivitäten (ein Cron-Lauf, ein REST-Request, ein Frontend-Seitenaufruf) werden von den registrierten Hooks verarbeitet.

Betriebliche Hinweise

  • Das Plugin setzt die im Plugin-Header deklarierten WordPress- und PHP-Versionen voraus (Requires at least: 6.2, Requires PHP: 8.1). Ältere Versionen werden nicht unterstützt.
  • Die meisten Subsysteme verwenden wpdb nur dann direkt, wenn dbDelta das erforderliche Schema oder die Abfrage nicht ausdrücken kann. Direkte Abfragen sind auf das Repository, Analytics, den Suchagenten und den Deinstallations-Code beschränkt.
  • Die Architektur trennt das Frontend-Rendering bewusst vom Datenimport. Der Importer rendert niemals Templates; die Templates lösen niemals Netzwerkanfragen an AutoScout24 aus.
  • Das Plugin fügt über den Filter plugin_action_links_<basename> einen "Einstellungen"-Link zu seiner Zeile in der WordPress-Plugin-Übersicht hinzu.

Fehlerbehebung

  • Eine Funktion scheint sich nicht zu registrieren. Überprüfen Sie den entsprechenden Options::FEATURE_*-Toggle. Die Methode register_hooks() in AS24CI\Plugin überspringt deaktivierte Funktionen.
  • Eine Klasse wird nicht gefunden. Überprüfen Sie die Namenskonvention für Dateien (class-as24ci-<lower-dashed-name>.php) und ob sich die Datei in includes/ oder includes/admin/ befindet. Der Autoloader sucht nur in diesen beiden Verzeichnissen.
  • Auf eine reine Admin-Klasse wird vom Frontend aus verwiesen. Admin-Klassen werden vom Autoloader bei Bedarf geladen, können jedoch von globalen Variablen oder Berechtigungen abhängen, die nur im Admin-Bereich verfügbar sind. Überprüfen Sie das Verhalten in der aktuellen Plugin-Version, bevor Sie sich darauf verlassen.

Verwandte Dokumente