Modèle de données

Ce document décrit le modèle de données logique utilisé par le plugin ADP Car Market Hub : quelles entités existent, comment elles se mappent sur le stockage WordPress et comment les différentes couches de stockage (tables de base de données personnalisées, publications, postmeta et options) fonctionnent ensemble.

Quand utiliser ce document

Lisez ce document si vous devez :

• Comprendre quelle entité (véhicule, lead, alerte de recherche, événement d'analyse) réside dans quelle table ou type de publication.
• Décider où lire ou écrire des données lors de la création d'une intégration ou d'un rapport personnalisé.
• Comprendre comment les données des champs de véhicules sont réparties entre la table dédiée as24_vehicles et les clés postmeta héritées.

Pour les listes de colonnes brutes, voir Database Schema. Pour les clés postmeta exposées dans l'interface utilisateur des métaboxes d'administration, voir les documents d'importation et de modèle dans cette section.

Aperçu

Le plugin distingue quatre entités principales :

1. Véhicule — une annonce de véhicule unique importée depuis AutoScout24.
2. Lead — une soumission de formulaire de contact ou de demande liée (facultativement) à un véhicule.
3. Alerte de recherche — les critères de recherche enregistrés d'un visiteur avec notifications par e-mail.
4. Événement d'analyse — un événement unique suivi sur le site public (consultation de page, utilisation de filtre, ouverture de contact, etc.).

Chaque entité utilise la couche de stockage qui correspond le mieux à son modèle d'accès. Les véhicules sont répartis entre les publications WordPress (pour les permaliens, les taxonomies, les modèles) et une table relationnelle dédiée (pour les colonnes typées et les requêtes rapides). Les leads sont des publications WordPress complètes. Les alertes de recherche et les événements d'analyse résident dans leurs propres tables personnalisées.

Véhicule

Un véhicule est l'entité centrale du plugin. Il est représenté par deux enregistrements étroitement liés :

• Une publication WordPress de type de publication as24ci_car. La publication fournit le permalien (/cars/<slug>/), le titre et l'extrait, l'image mise en avant, le contenu de l'éditeur, les termes de taxonomie attribués et la surface de fonctionnalités WordPress.
• Une ligne dans la table dédiée {$wpdb->prefix}as24_vehicles, détenue par AS24CI\Vehicle_Repository. La ligne contient les données de champ de véhicule typées (prix, kilométrage, année d'immatriculation, type de carburant, équipements, etc.), la charge utile brute de l'API et les métadonnées utilisées pour la détection des modifications.

Les deux enregistrements sont liés par la colonne post_id, qui possède un index unique sur la table. Chaque ligne possède également une colonne unique as24_id qui contient l'identifiant d'annonce AutoScout24.

Pourquoi une table dédiée

Les données de champ de véhicule étaient à l'origine stockées dans wp_postmeta. Le plugin a déplacé ces données dans une table dédiée afin que :

• Les colonnes typées (décimales pour les prix, entiers pour le kilométrage, dates pour la première immatriculation) puissent être interrogées et triées directement sans le coût et l'ambiguïté des jointures meta_query.
• Les index composites tels que idx_make_model, idx_fuel_condition et idx_status_live accélèrent le filtrage des archives.
• La détection des modifications (content_hash) réside à côté des données qu'elle décrit.

Pour des raisons de compatibilité ascendante, l'importateur continue d'écrire un petit jeu de clés postmeta ; voir la section suivante.

Clés postmeta toujours écrites pour les véhicules

Même avec la table personnalisée en place, les clés postmeta suivantes restent sur les publications as24ci_car. Elles sont intentionnellement préservées pour maintenir le fonctionnement des anciennes intégrations et éviter les régressions dans l'interface d'administration, la file d'attente de l'Assistant IA et le flux de suppression.

Les pièces jointes manuelles de la galerie suivies dans _as24ci_manual_image_ids sont traitées comme appartenant à l'utilisateur et ne sont pas supprimées par le code de suppression ou de désinstallation du plugin, même lorsque les pièces jointes importées sont supprimées.

Surcharges manuelles

La table des véhicules comprend une colonne JSON manual_overrides. Lorsqu'un administrateur modifie un champ de véhicule que l'importateur gère normalement, la modification est stockée sous forme d'entrée clé/valeur dans cette colonne. Le AS24CI\Vehicle_Field_Resolver lit d'abord à partir de la ligne, puis applique les surcharges manuelles afin que les importations ultérieures n'effacent pas les modifications manuelles. Le filet de sécurité dbDelta dans Vehicle_Repository::maybe_create_table() ajoute cette colonne sur les tables existantes si elle est manquante.

Taxonomies de véhicules

Les publications as24ci_car sont liées à 15 taxonomies non hiérarchiques enregistrées par AS24CI\Taxonomies :

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.

Les termes de taxonomie alimentent les filtres d'archives et fournissent des URL WordPress natives (par exemple /as24ci_brand/<slug>/). Un grand nombre de ces mêmes valeurs existent également sous forme de colonnes dénormalisées dans la table des véhicules (par exemple make, fuel_type, transmission_type) afin que les requêtes d'archives puissent s'exécuter sans jointure avec wp_term_relationships.

Fonctionnalités de véhicules

Le type de publication as24ci_car utilise des fonctionnalités personnalisées de la forme as24ci_car / as24ci_cars (map_meta_cap est activé). Lors de l'activation, le plugin accorde cet ensemble de fonctionnalités aux administrateurs et au rôle personnalisé as24ci_editor. Les administrateurs reçoivent en outre la fonctionnalité manage_as24_imports (Plugin::CAP_MANAGE), qui contrôle l'accès à l'importateur, aux réglages, aux outils et à l'interface des journaux. Les utilisateurs "Éditeur" de WordPress ne reçoivent pas les fonctionnalités de véhicules par défaut.

Lead

Un lead représente une soumission de formulaire de contact ou de demande. Il est stocké sous forme de publication WordPress de type de publication as24ci_lead, enregistrée par AS24CI\Leads_CPT. La publication stocke le message du visiteur dans le contenu/extrait de la publication et les coordonnées de l'expéditeur dans postmeta.

Le statut du lead est stocké dans la clé postmeta _as24ci_lead_status et vaut par défaut new. Les valeurs valides sont exposées sous forme de constantes sur AS24CI\Leads_CPT :

• STATUS_NEW (new)
• STATUS_CONTACTED (contacted)
• STATUS_CLOSED (closed)
• STATUS_SPAM (spam)

Leads_CPT::get_lead_status() protège contre les valeurs invalides en utilisant par défaut new. Leads_CPT::update_lead_status() valide la valeur entrante avant de l'écrire.

Si un lead a été soumis depuis une page de véhicule, le véhicule concerné est référencé dans les postmeta du lead afin que l'onglet Leads de l'administration puisse afficher l'annonce d'origine.

Alerte de recherche

Une alerte de recherche représente les critères de recherche enregistrés d'un visiteur avec un abonnement par e-mail. Les alertes de recherche sont stockées dans la table dédiée {$wpdb->prefix}as24ci_search_agents, détenue par AS24CI\Search_Agent.

Chaque ligne contient :

• name et email — identité du visiteur.
• criteria — les filtres de recherche enregistrés (stockés sous forme de texte).
• token — jeton opaque utilisé pour confirmer ou se désabonner.
• frequency — fréquence de notification (par défaut daily).
• status — l'un des statuts pending, active, inactive ou paused, exposés sous forme de constantes sur AS24CI\Search_Agent.
• created_at et confirmed_at — horodatages pour le flux de double opt-in conforme au RGPD.

Comme les alertes de recherche contiennent des données personnelles, la table est toujours supprimée lors de la désinstallation, quel que soit le réglage as24ci_delete_data_on_uninstall.

Événement d'analyse

Un événement d'analyse enregistre une interaction unique d'un visiteur (consultation de page, utilisation de filtre, ouverture de contact, etc.). Les événements sont stockés dans la table dédiée {$wpdb->prefix}as24ci_analytics, détenue par AS24CI\Analytics.

Chaque ligne contient :

• post_id — l'ID de la publication du véhicule concerné, ou 0 pour les événements globaux tels que les recherches par filtre.
• event_type — l'identifiant de l'événement (les valeurs autorisées sont validées par rapport à la propre liste ALLOWED_EVENTS de la classe).
• extra_data — charge utile facultative encodée en JSON.
• created_at — horodatage de l'événement.

Les événements ne sont enregistrés que lorsque Options::ANALYTICS_ENABLED est défini sur 1. Un nettoyage quotidien de rétention s'exécute via l'accroche cron as24ci_daily_cleanup. Tout comme la table des alertes de recherche, la table d'analyse est toujours supprimée lors de la désinstallation car elle peut contenir des données de suivi des visiteurs.

Pages gérées à l'activation

Lors de l'activation, le plugin peut créer trois pages WordPress qui hébergent les shortcodes destinés au public :

• Cars ([as24ci_archive]) — la page principale d'archive des véhicules.
• Compare Cars ([as24ci_compare]) — la page de comparaison.
• Favorites ([as24ci_favorites]) — la page des favoris / liste d'envies.

Les ID sont stockés dans les options as24ci_page_archive_id, as24ci_page_compare_id et as24ci_page_favorites_id. Ces pages ne font pas strictement partie du modèle de données ; elles sont créées pour que les shortcodes aient un emplacement par défaut, et ce sont les seules pages WordPress que le plugin supprime lors d'une désinstallation destructive.

Réglages (options)

Tous les réglages configurables par l'utilisateur sont stockés dans wp_options. Les clés sont définies comme des constantes sur AS24CI\Options. Les exemples incluent :

• API et authentification : as24ci_base_url, as24ci_token_url, as24ci_seller_ids, as24ci_client_id, as24ci_client_secret, as24ci_token_audience.
• Comportement de l'importateur : as24ci_default_post_status, as24ci_default_post_author, as24ci_import_images, as24ci_max_images, as24ci_convert_to_webp, as24ci_webp_quality, as24ci_full_sync.
• Planificateur : as24ci_auto_import_enabled, as24ci_cron_schedule, as24ci_cron_start_time, as24ci_cron_custom_minutes, as24ci_cron_max_vehicles, as24ci_cron_token.
• Activation des fonctionnalités : constantes Options::FEATURE_* pour le sitemap, le schéma, les favoris, la comparaison, le partage social, la fiche technique PDF, l'alerte de recherche, l'analyse, l'Assistant IA, l'API REST, le widget du tableau de bord, etc.
• Marqueurs de schéma/version : as24ci_db_version, as24ci_caps_version, as24ci_vehicles_db_version, as24ci_search_agent_db_version.

L'inventaire complet et le comportement de ces options sont documentés dans le document Options And Settings Storage.

Transitoires (transients)

Le plugin utilise un petit nombre de transitoires pour l'état à court terme. Les plus pertinents pour le modèle de données sont :

• as24ci_access_token — jeton d'accès OAuth AutoScout24 mis en cache.
• as24ci_cron_import_running — verrou d'exécution qui empêche les importations simultanées (Scheduler::LOCK_TRANSIENT, TTL d'environ 40 minutes).
• as24ci_image_queue_running — verrou d'exécution pour le processus de la file d'attente des images.
• as24ci_batch_queue — charge utile de la file d'attente pour l'assistant de traitement par lot manuel.

Les transitoires sont supprimés lors de la désactivation et de la désinstallation, selon le cas.

---

Référence de configuration

Notes opérationnelles

• Un véhicule existe tant que sa publication et sa ligne de table existent toutes deux. Le nettoyage AS24CI\Vehicle_Deleter est raccordé lors de la construction du plugin afin que chaque chemin de suppression permanente (suppression native WordPress, synchronisation complète de l'importateur, action groupée) passe par le même flux idempotent.
• Le dépôt conserve un petit cache en cours de processus (groupe de cache d'objets as24ci_vehicles, TTL d'environ 1 heure) pour les recherches sur une seule ligne. Les écritures directes dans la table à partir d'un code personnalisé contournent ce cache ; pensez à l'invalider manuellement lorsque vous étendez le dépôt.
• La colonne raw_data de la table des véhicules préserve la charge utile source de l'importation. Cela est utile pour déboguer les problèmes de mapping mais ne doit pas être considéré comme un contrat stable ; la structure de la charge utile est déterminée par l'API AutoScout24.
• Les images de la galerie manuelle sont délibérément traitées comme la propriété de l'administrateur. Elles ne sont pas supprimées lorsque les images importées sont supprimées, et elles ne sont pas supprimées lors de la désinstallation. Supprimez-les manuellement de la médiathèque WordPress si nécessaire.

Dépannage

• Un véhicule n'a pas de valeurs de champs sur le frontend mais existe dans la liste des publications. Vérifiez que la table des véhicules contient une ligne avec le post_id correspondant. Si la ligne est absente, l'annonce a été créée en dehors de l'importateur ou la migration vers la table personnalisée ne s'est pas terminée.
• Les modifications dans la metabox sont écrasées par l'importation suivante. Vérifiez que le champ concerné est bien écrit dans la colonne JSON manual_overrides. La couche de surcharge nécessite l'existence de la colonne manual_overrides ; la mise à niveau du schéma l'ajoute si nécessaire.
• Une image importée disparaît. Le plugin supprime uniquement les pièces jointes suivies dans _as24ci_image_ids. Les images qui ont été ajoutées via la galerie manuelle (_as24ci_manual_image_ids) sont conservées. Vérifiez quelle liste contient l'ID de pièce jointe concerné.
• Des lignes d'agents de recherche ou d'analyse apparaissent toujours après la suppression du plugin. Confirmez que uninstall.php a été exécuté. Les deux tables sont supprimées sans condition lors de la désinstallation. Si la désinstallation n'a pas été exécutée (par exemple parce que le plugin a seulement été désactivé), les lignes restent en place.

Documents connexes

• Aperçu de l'architecture
• Amorçage et cycle de vie du plugin
• Schéma de la base de données
• Aperçu de la section