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 lesen sollten

Lesen Sie dieses Dokument, wenn Sie:

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

Für die schrittweise Bootstrap-Reihenfolge siehe Plugin-Bootstrap und Lebenszyklus. Für Speicherdetails siehe Datenmodell und Datenbankschema.

Übersicht

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

  • Eine einzelne 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 Core-APIs von WordPress 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 beim plugins_loaded-Hook 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 initialisiert das AS24CI\Plugin-Singleton bei 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/ – CSS, JavaScript und Bilder für Admin und Frontend.
  • languages/ – Übersetzungsdateien; die Textdomain lautet 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 den 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 denselben Namespace nutzen können.

Kernklassen und ihre Verantwortlichkeiten

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

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 Callbacks activate() / deactivate() / init() 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 beim Löschen des Plugins zu bereinigen.

Daten und Speicherung

  • AS24CI\CPT – Registriert den Custom Post Type as24ci_car mit benutzerdefinierter Berechtigungszuordnung (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, Außen-/Innenfarbe, Schadstoffklasse, Energielabel, Fahrzeugkategorie, Garantieart, Garantiedetails, Zylinderanordnung).
  • AS24CI\Leads_CPT – Registriert den Custom Post Type as24ci_lead, der zum Speichern 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-Hilfsklassen sowie Filter-/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 Instanziierung von Plugin über Vehicle_Field_Resolver::set_repository() verknüpft.
  • AS24CI\Vehicle_Deleter – Einziger, idempotenter Bereinigungspfad, der verwendet wird, wann immer ein Fahrzeug dauerhaft gelöscht wird (natives WP-Löschen, Importer-Vollsynchronisations-Löschen, Massenaktion). Wird während der Instanziierung 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 – Ordnet eingehende AutoScout24-Fahrzeugdaten der internen Feldstruktur zu, die vom Repository verwendet wird, und schreibt die Postmeta _as24ci_listing_id für 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 Postmeta _as24ci_image_ids.
  • AS24CI\Scheduler – Verwaltet die WP-Cron-Hooks as24ci_scheduled_import und as24ci_image_queue_process, die Ausführungssperren-Transients (as24ci_cron_import_running, as24ci_image_queue_running) und das manuelle Batch-Wizard-Warteschlangen-Transient as24ci_batch_queue. Derselbe Ablauf run_import() wird von WP-Cron, dem REST-Cron-Endpunkt und dem Admin-Button „Jetzt ausführen“ verwendet.
  • AS24CI\Cron_Endpoint – REST-Endpunkt, der es externen Servern ermöglicht, Importe über eine token-gesicherte URL auszulösen.

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 Admin und Frontend in die Warteschlange 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 sowie Open Graph / Twitter Card Meta-Tags zu einzelnen Fahrzeugseiten hinzu. Optional, gesteuert durch Options::FEATURE_SCHEMA.
  • AS24CI\Sitemap – Integriert Fahrzeuge in die Core-Sitemap von WordPress und ist kompatibel mit Yoast und Rank Math. Optional, gesteuert durch Options::FEATURE_SITEMAP.
  • 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 verschlüsselt über AS24CI\Ai_Credential_Manager gespeichert; im Admin-Bereich kann kein Anbieter, Modell oder API-Schlüssel ausgewählt werden.
  • AS24CI\Data_Quality_Scanner – Optionaler Taxonomie-Tippfehler-Detektor, 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 des Autohauses, Öffnungszeiten und Verkäuferprofil-Metadaten.
  • AS24CI\Team / AS24CI\Admin_Team – CMH-Team: Verkaufsansprechpartner des Autohauses, 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 Locations entspricht. Admin_Team registriert ein eigenes übergeordnetes Admin-Menü.
  • 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 von operativen/KI-Schreibpfaden 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 Gemini-Anmeldedaten des Kunden, die von der API-Plattform bereitgestellt werden.
  • 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 seine eigenen Tabellen (as24ci_content_studio_jobs, as24ci_content_studio_assets), seine eigenen as24ci_content_studio_*-Optionen sowie einen Hintergrund-Worker und wird direkt aus der Haupt-Plugin-Datei statt über den Router Admin initialisiert. Es liest bestehende Fahrzeug-/Importdaten schreibgeschützt.

Admin-Benutzeroberfläche

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

Funktionsschalter und „sichere Ersteinrichtung“

Die meisten nicht essenziellen Funktionen werden in AS24CI\Plugin::register_hooks() konditional registriert, basierend auf Optionen, deren Konstanten in AS24CI\Options definiert sind (zum Beispiel FEATURE_SCHEMA, FEATURE_SITEMAP, FEATURE_FAVORITES, FEATURE_COMPARE, FEATURE_PDF_DATASHEET, REST_API_ENABLED, AI_ASSISTANT_ENABLED, ANALYTICS_ENABLED, TEST_DRIVE_ENABLED).

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

Speicherlayout (High-Level)

Das Plugin verwendet drei Speicherebenen:

  1. Eigene Datenbanktabellen, die über dbDelta verwaltet werden: - {$wpdb->prefix}as24_vehicles — Fahrzeugfelddaten, im Besitz von AS24CI\Vehicle_Repository. - {$wpdb->prefix}as24ci_analytics — Analyse-Ereignisse, im Besitz von AS24CI\Analytics. - {$wpdb->prefix}as24ci_search_agents — Suchauftrags-Abonnements, im Besitz von AS24CI\Search_Agent. - {$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, deren Status in _as24ci_lead_status hinterlegt ist.
  3. wp_options — Alle vom Benutzer konfigurierbaren Einstellungen. Schlüssel sind als Konstanten in AS24CI\Options definiert (und für das Content Studio in AS24CI\Content_Studio_Options). 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). CMH-Teamkontakte werden ebenfalls in den Optionen gespeichert (as24ci_team_*).

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

Laufzeit-Ablauf im Überblick

Eine typische Anfrage durchläuft die folgenden Phasen (vereinfacht):

  1. WordPress lädt adp-car-market-hub.php, was die 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) wird AS24CI\Plugin::init() ausgeführt, 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. Nachfolgende Aktivitäten (ein Cron-Lauf, eine REST-Anfrage, ein Frontend-Seitenaufruf) werden von den registrierten Hooks verarbeitet.

Betriebshinweise

  • 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 abbilden kann. Direkte Abfragen sind auf Repository-, Analyse-, Suchagenten- und 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 (WordPress) hinzu.

Fehlerbehebung

  • Eine Funktion scheint sich nicht zu registrieren. Überprüfen Sie den entsprechenden Options::FEATURE_*-Schalter. 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, hängen jedoch möglicherweise von reinen Admin-Globals oder -Berechtigungen ab. Überprüfen Sie das Verhalten in der aktuellen Plugin-Version, bevor Sie sich darauf verlassen.

Zugehörige Dokumente