Dokumentation · Technische Dokumentation

Architektur-Übersicht

Dieses Dokument beschreibt die übergeordnete Architektur des ADP Car Market Hub WordPress-Plugins: wie der Quellcode-Baum 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:

  • 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 And Lifecycle. Für Speicherdetails siehe Data Model und Database Schema.

Ü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 AS24CI\ PHP-Namespace 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 Aktion plugins_loaded 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/ — 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 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/, wodurch sich gemeinsam genutzte und nur für den Admin-Bereich bestimmte Klassen einen einzigen Namespace teilen können.

Kernklassen und ihre Verantwortlichkeiten

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

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 — Zentralisiertes Register von Optionsschlüsseln, 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 Entfernen des Plugins zu bereinigen.

Daten und Speicherung

  • AS24CI\CPT — Registriert den Custom Post Type as24ci_car mit benutzerdefiniertem Capability-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, Treibstoff, Getriebe, Antrieb, Zustand, Aussen-/Innenfarbe, Schadstoffklasse, Energieetikette, Fahrzeugkategorie, Garantieart, Garantiedetails, Zylinderanordnung).
  • AS24CI\Leads_CPT — Registriert den Custom Post Type as24ci_lead, der zum Speichern von Kontaktformular-Einsendungen 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-Management (maybe_create_table()), CRUD-Hilfsklassen sowie Filter-/Sortierungs-Whitelists, die von find() verwendet werden.
  • AS24CI\Vehicle_Field_Resolver — Zentralisierter Reader, der Fahrzeugfelder auflöst, indem er Repository-Daten mit manuellen Überschreibungen kombiniert. Wird während der Konstruktion 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öschen des Importers, Massenaktion). Wird während der Konstruktion 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 zu, die vom Repository verwendet wird, und schreibt die Postmeta _as24ci_listing_id für die 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 — Besitzt 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 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.

Frontend, SEO und Integrationen

  • AS24CI\Templates — Leitet Fahrzeug-Archiv- und Einzelansicht-Templates durch den Template-Loader des Plugins, was Theme-Überschreibungen ermöglicht.
  • AS24CI\Assets — Registriert und reiht CSS- und JavaScript-Bundles für den Admin-Bereich und das Frontend ein.
  • AS24CI\Archive_Filters — Rendert die Benutzeroberfläche des Archivfilters und wendet Abfrageänderungen basierend auf den Benutzerauswahlen 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 Schalter Options::FEATURE_* 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 — Seitenaufruf-, Filter- und Lead-Tracking. Besitzt die Tabelle {$wpdb->prefix}as24ci_analytics und den Aufbewahrungs-Cron as24ci_daily_cleanup.
  • AS24CI\Ai_Assistant — Generiert AI-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 Platform bereitgestellt und über AS24CI\Ai_Credential_Manager verschlüsselt 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 AI-Integration nutzt.
  • AS24CI\Pricing_Engine — Tägliche Preisanalyse, die auf dem Hook as24ci_pricing_analysis_cron läuft.
  • AS24CI\Locations, AS24CI\Seller_Profile_Fields — Garagen-Standorte, Öffnungszeiten und Verkäuferprofil-Metadaten.
  • AS24CI\Team / AS24CI\Admin_Team — CMH Team: Verkaufsansprechpartner 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 verwandten Optionsschlüsseln aufbewahrt, was dem Muster 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- / Managed-Access-Ebene der ADP Car Market Hub API Platform. License_Manager besitzt den täglichen Re-Validierungs-Cron (as24ci_license_refresh), die Speicherung von Funktionsrechten, die Steuerung des operativen/AI-Schreibpfads 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 Platform 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 Marketinginhalte aus bestehenden Fahrzeugdaten generiert. Es besitzt eigene Tabellen (as24ci_content_studio_jobs, as24ci_content_studio_assets), eigene as24ci_content_studio_*-Optionen sowie einen Hintergrund-Worker und wird aus der Haupt-Plugin-Datei anstatt aus dem Admin-Router initialisiert. Es liest bestehende Fahrzeug-/Importdaten schreibgeschützt.

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.

Funktionsschalter und "sichere Erst-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_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ässig deaktiviert; frontend-freundliche Funktionen (Sitemap, Schema, Favoriten, Vergleich, Finanzierungsrechner, Dashboard-Widget, Export, Lazy Loading, Layout Manager) sind standardmässig aktiviert. Bestehende Installationen werden niemals überschrieben, da der Seeder add_option() verwendet.

Speicher-Layout (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 — Analytics-Ereignisse, im Besitz von AS24CI\Analytics. - {$wpdb->prefix}as24ci_search_agents — Suchabo-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 mit dem Status in _as24ci_lead_status.
  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). 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 auf einen Blick

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) 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. Die nachfolgende Aktivität (ein Cron-Lauf, eine REST-Anfrage, ein Seitenaufruf im Frontend) wird 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, die 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 Link "Einstellungen" zu seiner Zeile auf der WordPress-Plugin-Seite hinzu.

Fehlerbehebung

  • Eine Funktion scheint sich nicht zu registrieren. Überprüfen Sie den entsprechenden Schalter in Options::FEATURE_*. 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.

Verwandte Dokumente