Documentation · Documentation technique

Aperçu de l'architecture

Ce document décrit l'architecture de haut niveau du plugin ADP Car Market Hub WordPress : comment l'arborescence des sources est organisée, quelles classes portent les principales responsabilités et comment les fonctionnalités majeures sont connectées entre elles au moment de l'exécution.

Quand utiliser ce document

Lisez ce document si vous devez :

  • Obtenir un aperçu de la base de code PHP du plugin avant de vous plonger dans un sous-système spécifique.
  • Comprendre quelle classe est responsable d'une fonctionnalité donnée.
  • Planifier une personnalisation, une intégration ou une revue de code.

Pour l'ordre d'initialisation étape par étape, voir Plugin Bootstrap And Lifecycle. Pour les détails de stockage, voir Data Model et Database Schema.

Aperçu

Le plugin est implémenté en PHP et suit les conventions standard des plugins WordPress. Il utilise :

  • Un seul fichier racine (adp-car-market-hub.php) qui définit les constantes du plugin, enregistre un chargeur automatique (autoloader) et accroche les rappels d'initialisation (bootstrap).
  • Un espace de noms PHP AS24CI\ pour toutes les classes.
  • Les API de base de WordPress pour les types de publication personnalisés (CPT), les taxonomies, les options, WP-Cron, l'API REST, les gestionnaires AJAX et les tables personnalisées gérées par dbDelta.
  • Un singleton central AS24CI\Plugin qui connecte chaque fonctionnalité sur l'action plugins_loaded.

Structure des répertoires de premier niveau

Le dépôt est organisé comme suit (seuls les répertoires pertinents pour l'architecture d'exécution sont listés) :

  • adp-car-market-hub.php — fichier principal du plugin. Définit les constantes, enregistre l'autoloader, charge le domaine de texte, enregistre les hooks d'activation/désactivation, enregistre les intervalles WP-Cron personnalisés et initialise le singleton AS24CI\Plugin sur plugins_loaded.
  • includes/ — classes PHP partagées et frontend, une classe par fichier. Les noms de fichiers suivent le modèle class-as24ci-<name>.php et se résolvent vers la classe AS24CI\<Name> via l'autoloader.
  • includes/admin/ — classes PHP réservées à l'administration (onglets de réglages, assistants de listes de tables, widgets du tableau de bord). Résolues par le même autoloader en tant que solution de repli lorsqu'une classe n'est pas trouvée sous includes/.
  • src/Core/Helpers.php — assistants procéduraux partagés chargés inconditionnellement depuis le fichier principal du plugin.
  • templates/ — modèles frontend et parties de modèles qui peuvent être surchargés par les thèmes.
  • assets/ — CSS, JavaScript et images pour l'administration et le frontend.
  • languages/ — fichiers de traduction ; le domaine de texte est adp-car-market-hub.
  • uninstall.php — s'exécute lorsque le plugin est supprimé de WordPress et supprime les options du plugin et (facultativement) le contenu importé.

Autoloader

adp-car-market-hub.php enregistre un petit autoloader compatible PSR-4 pour le préfixe AS24CI\. Les noms de classes sont convertis selon la convention de nommage de fichiers class-as24ci-<lower-case-name-with-dashes>.php. Le chargeur automatique cherche d'abord dans includes/ puis dans includes/admin/, ce qui permet aux classes partagées et réservées à l'administration de partager un espace de noms unique.

Classes de base et leurs responsabilités

Les classes suivantes forment l'épine dorsale du plugin. Les noms sont écrits sous leur forme pleinement qualifiée (AS24CI\<Class>).

Initialisation et services partagés

  • AS24CI\Plugin — Point d'entrée du singleton. Construit les instances de services partagés (Logger, Client, Image_Importer, Vehicle_Repository, Importer, Scheduler), connecte tous les hooks WordPress pour l'ensemble de fonctionnalités actives et expose les rappels statiques activate() / deactivate() / init().
  • AS24CI\Logger — Enregistreur (logger) léger utilisé dans tout le plugin pour les messages de l'importateur et du planificateur.
  • AS24CI\Options — Registre centralisé des clés d'options exposées sous forme de constantes de classe (par exemple Options::DB_VERSION, Options::DEFAULT_CURRENCY, Options::AUTO_IMPORT_ENABLED). Le script uninstall.php utilise Options::get_all_keys() pour nettoyer les options lors de la suppression du plugin.

Données et stockage

  • AS24CI\CPT — Enregistre le type de publication personnalisé as24ci_car avec un mappage de capacités personnalisé (as24ci_car / as24ci_cars) et la boîte de méta (metabox) combinée "AutoScout24 API Import".
  • AS24CI\Taxonomies — Enregistre les 15 taxonomies d'attributs de véhicules associées à as24ci_car (marque, modèle, type de carrosserie, type de carburant, transmission, transmission intégrale, état, couleur extérieure/intérieure, norme d'émission, étiquette énergétique, catégorie de véhicule, type de garantie, détails de la garantie, disposition des cylindres).
  • AS24CI\Leads_CPT — Enregistre le type de publication personnalisé as24ci_lead utilisé pour stocker les soumissions de formulaires de contact, avec des constantes de statut pour new, contacted, closed et spam.
  • AS24CI\Vehicle_Repository — Répertoire pour la table personnalisée dédiée {$wpdb->prefix}as24_vehicles qui contient les données de champs de véhicules (au lieu de wp_postmeta). Fournit la gestion du schéma (maybe_create_table()), des assistants CRUD et des listes blanches de filtrage/tri utilisées par find().
  • AS24CI\Vehicle_Field_Resolver — Lecteur centralisé qui résout les champs de véhicules en combinant les données du répertoire avec les surcharges manuelles. Connecté lors de la construction de Plugin via Vehicle_Field_Resolver::set_repository().
  • AS24CI\Vehicle_Deleter — Chemin de nettoyage unique et idempotent utilisé chaque fois qu'un véhicule est définitivement supprimé (suppression native WP, suppression par synchronisation complète de l'importateur, action groupée). Connecté lors de la construction de Plugin.

Pipeline d'importation

  • AS24CI\Client — Client HTTP pour l'API AutoScout24. Gère l'authentification et l'exécution des requêtes.
  • AS24CI\Mapper — Mappe les charges utiles d'annonces AutoScout24 entrantes vers la structure de champ interne utilisée par le répertoire et écrit le postmeta _as24ci_listing_id pour la compatibilité ascendante.
  • AS24CI\Importer — Coordonne l'importation par annonce : récupère les données via Client, les transforme via Mapper, enregistre les véhicules via le répertoire et suit la détection des changements grâce aux clés postmeta _as24ci_content_hash et _as24ci_images_hash.
  • AS24CI\Image_Importer — Télécharge et associe les images des véhicules, en les convertissant éventuellement en WebP. Stocke les ID de pièces jointes dans le postmeta _as24ci_image_ids.
  • AS24CI\Scheduler — Détient les hooks WP-Cron as24ci_scheduled_import et as24ci_image_queue_process, les transients de verrouillage d'exécution (as24ci_cron_import_running, as24ci_image_queue_running) et le transient de file d'attente manuelle de l'assistant de lot (Batch-Wizard) as24ci_batch_queue. Le même flux run_import() est utilisé par WP-Cron, le point de terminaison cron REST et le bouton "Lancer maintenant" de l'administration.
  • AS24CI\Cron_Endpoint — Point de terminaison REST qui permet aux serveurs externes de déclencher des importations via une URL sécurisée par jeton.

Frontend, SEO et intégrations

  • AS24CI\Templates — Oriente les modèles d'archives et de véhicules uniques à travers le chargeur de modèles du plugin, permettant des surcharges par le thème.
  • AS24CI\Assets — Enregistre et met en file d'attente les bundles CSS et JavaScript de l'administration et du frontend.
  • AS24CI\Archive_Filters — Génère l'interface utilisateur du filtre d'archive et applique les modifications de requête en fonction des sélections de l'utilisateur.
  • AS24CI\Schema — Ajoute des données structurées Schema.org et des balises méta Open Graph / Twitter Card aux pages de véhicules uniques. Optionnel, conditionné par Options::FEATURE_SCHEMA.
  • AS24CI\Sitemap — Intègre les véhicules dans le plan du site (sitemap) de base de WordPress et est compatible avec Yoast et Rank Math. Optionnel, conditionné par 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 — Fonctionnalités optionnelles qui enregistrent chacune leurs propres hooks. La plupart sont conditionnées par une activation Options::FEATURE_* (voir seed_safe_defaults() dans AS24CI\Plugin pour les valeurs par défaut fournies lors d'une nouvelle installation).
  • AS24CI\Webhooks — Webhooks sortants pour les cas d'utilisation de CRM et d'intégration.
  • AS24CI\Rest_Api — API REST publique pour les annonces de véhicules, conditionnée par Options::REST_API_ENABLED.
  • AS24CI\Analytics — Suivi des pages vues, des filtres et des leads. Détient la table {$wpdb->prefix}as24ci_analytics et le cron de rétention as24ci_daily_cleanup.
  • AS24CI\Ai_Assistant — Génère des descriptions par IA, des métadonnées SEO et des points forts d'équipements en utilisant la configuration gérée de Google Gemini exposée par AS24CI\Ai_Config. La clé Gemini du client est transmise de serveur à serveur par l'API Platform et stockée de manière chiffrée via AS24CI\Ai_Credential_Manager ; aucun fournisseur, modèle ou clé API n'est sélectionnable dans l'interface d'administration.
  • AS24CI\Data_Quality_Scanner — Détecteur de fautes de frappe dans les taxonomies optionnel qui utilise l'intégration de l'IA.
  • AS24CI\Pricing_Engine — Analyse quotidienne des prix qui s'exécute sur le hook as24ci_pricing_analysis_cron.
  • AS24CI\Locations, AS24CI\Seller_Profile_Fields — Emplacements des concessions, horaires d'ouverture et métadonnées du profil du vendeur.
  • AS24CI\Team / AS24CI\Admin_Team — CMH Team : contacts commerciaux de la concession qui ne nécessitent pas de comptes d'utilisateurs WordPress. Le stockage est basé sur les options (pas de table personnalisée ni de CPT) ; les contacts sont conservés dans Options::TEAM_MEMBERS et les clés d'options associées, reflétant le modèle Locations. Admin_Team enregistre un menu d'administration dédié de premier niveau.
  • AS24CI\License_Manager, AS24CI\License_Client, AS24CI\License_Refresh_Signal, AS24CI\License_Signal_Secret — Licence de l'API Platform ADP Car Market Hub / couche d'accès géré. License_Manager détient le cron de revalidation quotidienne (as24ci_license_refresh), le stockage des droits d'accès aux fonctionnalités, le contrôle des chemins d'écriture opérationnels/IA et les notifications d'administration. License_Refresh_Signal expose le point de terminaison entrant POST /as24ci/v1/license-refresh-signal.
  • AS24CI\Ai_Credential_Manager — Stocke et déchiffre l'identifiant Gemini du client fourni par l'API Platform.
  • Content Studio (AS24CI\Content_Studio_*, par exemple Content_Studio_Repository, Content_Studio_Options, Content_Studio_Admin_Worker, Admin_Tab_Content_Studio) — Un module largement autonome qui génère du contenu marketing à partir des données de véhicules existantes. Il possède ses propres tables (as24ci_content_studio_jobs, as24ci_content_studio_assets), ses propres options as24ci_content_studio_* et un processus d'arrière-plan, et est initialisé à partir du fichier principal du plugin plutôt que du routeur Admin. Il lit les données existantes de véhicules/importations en lecture seule.

Interface d'administration

  • AS24CI\Admin — Contrôleur d'administration de premier niveau, instancié uniquement lorsque is_admin() est vrai. Compose en interne les classes d'onglets de includes/admin/ (importateur, réglages, mapping, design, gestionnaire de mise en page, leads, Assistant IA, état du système, etc.).
  • AS24CI\Dashboard_Widget — Widget de tableau de bord WordPress optionnel, conditionné par Options::FEATURE_DASHBOARD_WIDGET.

Boutons d'activation des fonctionnalités et "première configuration sécurisée"

La plupart des fonctionnalités non essentielles sont enregistrées de manière conditionnelle dans AS24CI\Plugin::register_hooks() sur la base d'options dont les constantes sont définies sur AS24CI\Options (par exemple FEATURE_SCHEMA, FEATURE_SITEMAP, FEATURE_FAVORITES, FEATURE_COMPARE, FEATURE_PDF_DATASHEET, REST_API_ENABLED, AI_ASSISTANT_ENABLED, ANALYTICS_ENABLED, TEST_DRIVE_ENABLED).

Lors d'une nouvelle installation, le plugin injecte des valeurs par défaut prudentes via AS24CI\Plugin::seed_safe_defaults(). Les fonctionnalités liées à la confidentialité, externes ou de traitement par lots sont désactivées par défaut ; les fonctionnalités adaptées au frontend (plan du site, schéma, favoris, comparaison, calculateur de financement, widget de tableau de bord, exportation, chargement différé, gestionnaire de mise en page) sont activées par défaut. Les installations existantes ne sont jamais écrasées car l'injecteur utilise add_option().

Structure de stockage (haut niveau)

Le plugin utilise trois couches de stockage :

  1. Tables de base de données personnalisées gérées via dbDelta : - {$wpdb->prefix}as24_vehicles — données des champs de véhicules, détenues par AS24CI\Vehicle_Repository. - {$wpdb->prefix}as24ci_analytics — événements d'analyse, détenus par AS24CI\Analytics. - {$wpdb->prefix}as24ci_search_agents — abonnements aux alertes de recherche, détenus par AS24CI\Search_Agent. - {$wpdb->prefix}as24ci_content_studio_jobs et {$wpdb->prefix}as24ci_content_studio_assets — tâches et ressources générées du Content Studio, détenues par AS24CI\Content_Studio_Repository.
  2. Publications et postmeta WordPress : - Les publications as24ci_car soutiennent les permaliens, taxonomies et modèles WordPress pour chaque véhicule. Un petit ensemble de clés postmeta reste dans wp_postmeta pour des raisons de compatibilité ascendante (par exemple _as24ci_listing_id, _as24ci_content_hash, _as24ci_images_hash, _as24ci_image_ids, _as24ci_manual_image_ids). - Les publications as24ci_lead stockent les soumissions de formulaires de contact avec un statut stocké dans _as24ci_lead_status.
  3. wp_options — Tous les réglages configurables par l'utilisateur. Les clés sont définies comme des constantes sur AS24CI\Options (et, pour le Content Studio, sur AS24CI\Content_Studio_Options). Les versions de schéma pour les tables personnalisées sont également stockées en tant qu'options (as24ci_db_version, as24ci_vehicles_db_version, as24ci_search_agent_db_version, as24ci_content_studio_db_version). Les contacts de la CMH Team sont également stockés dans les options (as24ci_team_*).

Pour les détails au niveau des colonnes, voir le Schéma de la base de données. Pour le modèle d'entité logique et la manière dont les postmeta et la table personnalisée interagissent, voir le Modèle de données.

Flux d'exécution en un coup d'œil

Une requête typique passe par les étapes suivantes (simplifiées) :

  1. WordPress charge adp-car-market-hub.php, qui définit les constantes du plugin, enregistre l'autoloader et ajoute des intervalles WP-Cron personnalisés.
  2. Sur plugins_loaded (priorité 1), le domaine de texte est chargé.
  3. Sur plugins_loaded (priorité par défaut), AS24CI\Plugin::init() s'exécute, instancie le singleton et enregistre tous les hooks pour les fonctionnalités actives.
  4. Les classes de fonctionnalités enregistrent leurs propres hooks sur init, rest_api_init, wp_ajax_*, wp_footer, etc.
  5. L'activité ultérieure (une exécution de cron, une requête REST, un affichage de page frontend) est gérée par les hooks enregistrés.

Notes opérationnelles

  • Le plugin suppose les versions de WordPress et PHP déclarées dans l'en-tête du plugin (Requires at least: 6.2, Requires PHP: 8.1). Les versions inférieures ne sont pas prises en charge.
  • La plupart des sous-systèmes utilisent directement wpdb uniquement lorsque dbDelta ne peut pas exprimer le schéma ou la requête requis. Les requêtes directes sont limitées au code du dépôt, de l'analyse, de l'agent de recherche et de désinstallation.
  • L'architecture sépare délibérément le rendu frontend de l'importation des données. L'importateur ne restitue jamais de modèles ; les modèles ne déclenchent jamais de requêtes réseau vers AutoScout24.
  • Le plugin ajoute un lien « Réglages » à sa ligne sur l'écran des extensions WordPress via le filtre plugin_action_links_<basename>.

Dépannage

  • Une fonctionnalité ne semble pas s'enregistrer. Vérifiez le commutateur Options::FEATURE_* correspondant. La méthode register_hooks() dans AS24CI\Plugin ignore les fonctionnalités désactivées.
  • Une classe est introuvable. Vérifiez la convention de nommage des fichiers (class-as24ci-<lower-dashed-name>.php) et assurez-vous que le fichier réside dans includes/ ou includes/admin/. L'autoloader recherche uniquement dans ces deux répertoires.
  • Une classe réservée à l'administration est référencée depuis le frontend. Les classes d'administration sont chargées à la demande par l'autoloader, mais elles peuvent dépendre de variables globales ou de capacités réservées à l'administration. Vérifiez le comportement dans la version actuelle du plugin avant de vous y fier.

Documents connexes