Documentation · Documentation technique

Schéma de la base de données

Ce document décrit les tables de base de données personnalisées créées par le plugin ADP Car Market Hub. Toutes les tables sont gérées avec l'assistant dbDelta() de WordPress et sont créées lors de l'activation du plugin. Leurs versions de schéma sont suivies dans wp_options afin que dbDelta puisse appliquer les modifications de colonnes en toute sécurité lors d'une mise à jour.

Quand utiliser ce document

Lisez ce document si vous devez :

Planifier des sauvegardes, de la rétention ou des travaux de conformité pour les données du plugin.
Créer des rapports personnalisés basés sur les tables du plugin.
Diagnostiquer des échecs de mise à jour de schéma ou des colonnes manquantes.
Comprendre quelles tables sont supprimées lors de la désinstallation et lesquelles ne le sont pas.

Pour le modèle d'entité logique qui utilise ces tables, voir le Modèle de données.

Aperçu

Le plugin crée cinq tables personnalisées :

Suffixe de table	Objectif	Option de version de schéma
`as24_vehicles`	Données de champs de véhicules, remplaçant la majeure partie de l'utilisation de `wp_postmeta`.	`as24ci_vehicles_db_version`
`as24ci_analytics`	Événements analytiques pour les pages de véhicules et les actions de filtre globales.	`as24ci_analytics_db_version`
`as24ci_search_agents`	Abonnements aux alertes de recherche des visiteurs (Smart Stock Alerts).	`as24ci_search_agent_db_version`
`as24ci_content_studio_jobs`	Tâches de génération du Content Studio (une ligne par tâche).	`as24ci_content_studio_db_version`
`as24ci_content_studio_assets`	Ressources générées par le Content Studio, liées à une tâche par `job_id`.	`as24ci_content_studio_db_version`

Les noms réels des tables utilisent le préfixe {$wpdb->prefix} de WordPress (généralement wp_). La version du schéma de la table d'analyse est stockée dans as24ci_analytics_db_version (constante AS24CI\Analytics::DB_VERSION_KEY). Les deux tables du Content Studio partagent une seule option de version de schéma (as24ci_content_studio_db_version, valeur actuelle 1.3.0) définie sur AS24CI\Content_Studio_Options::DB_VERSION et gérée par AS24CI\Content_Studio_Repository::maybe_create_tables().

Le plugin s'appuie également sur les tables de base de WordPress wp_posts, wp_postmeta, wp_term_relationships, wp_term_taxonomy et wp_terms pour les types de publication as24ci_car et as24ci_lead ainsi que pour les 15 taxonomies de véhicules. Ces tables suivent le schéma standard de WordPress et ne sont pas redéfinies par le plugin.

Les cinq tables personnalisées sont supprimées automatiquement lors de la désinstallation (voir la section Comportement lors de la désinstallation ci-dessous), quel que soit le réglage as24ci_delete_data_on_uninstall.

Table : `{$wpdb->prefix}as24_vehicles`

Propriétaire : AS24CI\Vehicle_Repository. Créée via Vehicle_Repository::maybe_create_table() lors de l'activation et vérifiée à nouveau lors des exécutions ultérieures. La constante de version actuelle du schéma est 1.1, stockée dans l'option as24ci_vehicles_db_version.

La table contient une ligne par véhicule, liée à sa publication as24ci_car par la colonne post_id. La colonne as24_id contient l'identifiant d'annonce AutoScout24. Les deux colonnes ont des index uniques.

Colonnes

Colonne	Type	Notes
`id`	`bigint(20) unsigned`	Clé primaire, auto-incrémentation.
`post_id`	`bigint(20) unsigned`	ID de publication WordPress pour le `as24ci_car` lié. Unique.
`as24_id`	`varchar(64)`	Identifiant d'annonce AutoScout24. Unique. Valeur par défaut : chaîne vide.
`seller_id`	`varchar(64)`	Identifiant de vendeur AutoScout24.
`make`	`varchar(100)`
`model`	`varchar(100)`
`version_full_name`	`varchar(255)`	Libellé complet de la finition/version tel que fourni par l'API.
`condition_type`	`varchar(50)`	Par ex. `new`, `used`, `demo` (les valeurs reflètent l'API source).
`body_type`	`varchar(50)`
`fuel_type`	`varchar(50)`
`transmission_type`	`varchar(50)`
`drive_type`	`varchar(50)`
`color_exterior`	`varchar(100)`
`color_interior`	`varchar(100)`
`doors`	`tinyint(3) unsigned`	Valeur par défaut : `0`.
`seats`	`tinyint(3) unsigned`	Valeur par défaut : `0`.
`mileage`	`int(10) unsigned`	Valeur par défaut : `0`.
`cubic_capacity`	`int(10) unsigned`	Cylindrée du moteur.
`range_km`	`int(10) unsigned`	Autonomie électrique en kilomètres.
`first_registration`	`date`	Autorise la valeur Null.
`first_reg_year`	`smallint(5) unsigned`	Composante année de `first_registration`. Valeur par défaut : `0`.
`power_kw`	`smallint(5) unsigned`
`power_hp`	`smallint(5) unsigned`
`co2_emission`	`smallint(5) unsigned`	g/km.
`price`	`decimal(10,2)`	Prix de vente.
`list_price`	`decimal(10,2)`	Prix catalogue/MSRP (si fourni).
`currency`	`char(3)`	Code ISO 4217 ; valeur par défaut : `EUR`.
`emission_standard`	`varchar(20)`	Par ex. Euro 6.
`energy_label`	`char(5)`	Étiquette énergétique A-G.
`battery_capacity`	`decimal(6,2)`	kWh.
`vin`	`varchar(20)`	Numéro d'identification du véhicule (VIN).
`status`	`varchar(30)`	Statut de l'annonce tel que fourni par l'API.
`is_live`	`tinyint(1)`	`1` si l'annonce est actuellement en ligne, `0` sinon.
`had_accident`	`tinyint(1)`
`equipment_codes`	`longtext`	Tableau JSON de codes d'équipement. Autorise la valeur Null.
`equipment_standard`	`longtext`	Liste JSON d'équipements de série. Autorise la valeur Null.
`equipment_optional`	`longtext`	Liste JSON d'équipements optionnels. Autorise la valeur Null.
`images`	`longtext`	Liste JSON d'URL d'images telles que fournies par l'API.
`raw_data`	`longtext`	Charge utile source complète conservée pour le diagnostic.
`manual_overrides`	`longtext`	Objet JSON des champs modifiés par l'administrateur qui surchargent les valeurs importées.
`content_hash`	`varchar(64)`	Hash utilisé pour ignorer les réimportations d'annonces inchangées.
`imported_at`	`datetime`	Valeur par défaut : `CURRENT_TIMESTAMP`.
`updated_at`	`datetime`	Valeur par défaut : `CURRENT_TIMESTAMP`. Voir la note d'implémentation ci-dessous.

Note d'implémentation : updated_at est créé avec uniquement DEFAULT CURRENT_TIMESTAMP à l'intérieur du SQL dbDelta car l'ajout direct de ON UPDATE CURRENT_TIMESTAMP amène dbDelta à réémettre un ALTER à chaque chargement du plugin. La sémantique de ON UPDATE est appliquée via un ALTER unique après l'exécution de dbDelta.

Index

Index	Type	Colonnes	Objectif
`PRIMARY`	Primary	`id`	Clé primaire de substitution.
`uk_as24_id`	Unique	`as24_id`	Une ligne par annonce AutoScout24.
`uk_post_id`	Unique	`post_id`	Une ligne par publication de véhicule WordPress.
`idx_make_model`	Index	`make`, `model`	Gère les filtres d'archive marque/modèle.
`idx_price`	Index	`price`	Tri des prix / filtrage par plage.
`idx_mileage`	Index	`mileage`	Tri du kilométrage / filtrage par plage.
`idx_first_reg_year`	Index	`first_reg_year`	Tri de l'année / filtrage par plage.
`idx_fuel_condition`	Index	`fuel_type`, `condition_type`	Filtre combiné commun.
`idx_status_live`	Index	`status`, `is_live`	Requêtes d'annonces en ligne.
`idx_content_hash`	Index	`content_hash`	Recherches lors de la détection de changements.

Filet de sécurité pour `manual_overrides`

Après l'exécution de dbDelta, le dépôt effectue une vérification SHOW COLUMNS ... LIKE 'manual_overrides' et, si la colonne est manquante, émet un ALTER TABLE ... ADD COLUMN manual_overrides longtext DEFAULT NULL AFTER raw_data explicite. Cela compense les problèmes occasionnels de détection de colonnes dans certaines combinaisons MySQL/MariaDB et garantit que la couche de surcharge manuelle dispose toujours d'un emplacement pour stocker les données.

Table : `{$wpdb->prefix}as24ci_analytics`

Propriétaire : AS24CI\Analytics. Créée via Analytics::maybe_create_table() lors de l'activation et vérifiée à chaque chargement de page d'administration (la méthode est également liée à admin_init afin que les installations existantes récupèrent les nouvelles colonnes sans réactivation manuelle).

Colonnes

Colonne	Type	Notes
`id`	`bigint(20) unsigned`	Clé primaire, auto-incrémentation.
`post_id`	`bigint(20) unsigned`	ID de publication du véhicule. `0` pour les événements globaux tels que les recherches par filtre.
`event_type`	`varchar(20)`	Identifiant d'événement ; valeur par défaut : `view`. Validé par rapport à `ALLOWED_EVENTS`.
`extra_data`	`longtext`	Charge utile facultative encodée en JSON. Autorise la valeur Null.
`created_at`	`datetime`	Valeur par défaut : `CURRENT_TIMESTAMP`.

Index

Index	Type	Colonnes
`PRIMARY`	Primary	`id`
`post_event_date`	Index	`post_id`, `event_type`, `created_at`
`event_type`	Index	`event_type`, `created_at`
`created_at`	Index	`created_at`

Rétention

Les insertions ne se produisent que lorsque Options::ANALYTICS_ENABLED est 1. Une tâche de rétention quotidienne s'exécute via le hook cron as24ci_daily_cleanup (planifié lors de l'activation, supprimé lors de la désactivation). La fenêtre de rétention est configurée via l'onglet d'administration de l'analyse.

Table : `{$wpdb->prefix}as24ci_search_agents`

Propriétaire : AS24CI\Search_Agent. Créée via Search_Agent::maybe_create_table() sur init (priorité 1) afin qu'elle soit disponible à la fois pour les gestionnaires AJAX de l'administration et du frontend. La version actuelle du schéma est 1.1, stockée dans l'option as24ci_search_agent_db_version. La création est conditionnée par le basculement Options::FEATURE_SEARCH_AGENT, mais le schéma est enregistré sans condition lorsque la classe de fonctionnalité est chargée.

Colonnes

Colonne	Type	Notes
`id`	`BIGINT UNSIGNED`	Clé primaire, auto-incrémentation.
`name`	`VARCHAR(255)`	Nom d'affichage du visiteur ; chaîne vide par défaut.
`email`	`VARCHAR(255)`	Adresse e-mail du visiteur.
`criteria`	`TEXT`	Critères de recherche enregistrés (représentation sérialisée).
`token`	`VARCHAR(64)`	Jeton pour les liens de confirmation et de désinscription.
`frequency`	`VARCHAR(20)`	Fréquence de notification ; `daily` par défaut.
`status`	`VARCHAR(20)`	L'un des éléments suivants : `pending`, `active`, `inactive`, `paused`. Valeur par défaut : `pending`.
`created_at`	`DATETIME`	Valeur par défaut : `CURRENT_TIMESTAMP`.
`confirmed_at`	`DATETIME`	Peut être nul ; défini lorsque le visiteur confirme via le Double-Opt-In.

Index

Index	Type	Colonnes
`PRIMARY`	Primary	`id`
`idx_status`	Index	`status`
`idx_token`	Index	`token`

Confidentialité

Comme la table contient des données personnelles (nom, e-mail, préférences de recherche), elle est supprimée lors de la désinstallation, quel que soit le réglage de as24ci_delete_data_on_uninstall. Les exploitants du site sont responsables des outils de conservation ou d'exportation supplémentaires requis par les réglementations locales en matière de confidentialité.

Table : `{$wpdb->prefix}as24ci_content_studio_jobs`

Propriétaire : AS24CI\Content_Studio_Repository. Créée via Content_Studio_Repository::maybe_create_tables() (enregistré comme son propre hook d'activation dans le fichier principal du plugin et également appelé de manière paresseuse par la plupart des méthodes de dépôt). Contient une ligne par tâche de génération du Content Studio. Les valeurs de statut sont draft, queued, processing, ready et failed.

Colonnes

Colonne	Type	Notes
`id`	`bigint(20) unsigned`	Clé primaire, auto-incrémentation.
`vehicle_post_id`	`bigint(20) unsigned`	Publication du véhicule source. Valeur par défaut : `0`.
`vehicle_snapshot_hash`	`varchar(64)`	Empreinte (hash) de l'instantané du véhicule utilisé pour la tâche.
`content_type`	`varchar(40)`	Type de contenu demandé.
`platform_preset`	`varchar(40)`	Préréglage de la plateforme cible.
`output_format`	`varchar(20)`	Format de sortie.
`preset_key`	`varchar(80)`	Clé du catalogue de préréglages.
`status`	`varchar(20)`	Valeur par défaut : `draft`.
`prompt_payload`	`longtext`	Charge utile du prompt JSON. Peut être nul.
`provider`	`varchar(40)`	Valeur par défaut : `google`.
`model`	`varchar(80)`	Modèle du fournisseur.
`language`	`varchar(20)`	Langue de sortie.
`tone`	`varchar(40)`	Ton de voix.
`attempts`	`smallint(5) unsigned`	Tentatives de traitement. Valeur par défaut : `0`.
`last_error`	`text`	Dernier message d'erreur. Peut être nul.
`created_by`	`bigint(20) unsigned`	ID utilisateur WordPress. Valeur par défaut : `0`.
`created_at`	`datetime`	Valeur par défaut : `CURRENT_TIMESTAMP`.
`updated_at`	`datetime`	Valeur par défaut : `CURRENT_TIMESTAMP`.
`started_at`	`datetime`	Peut être nul.
`completed_at`	`datetime`	Peut être nul.

Index : PRIMARY (id), vehicle_post_id, status_created (status, created_at), platform_preset, content_type.

Table : `{$wpdb->prefix}as24ci_content_studio_assets`

Propriétaire : AS24CI\Content_Studio_Repository. Contient les ressources générées (texte, images, packs de rédaction) appartenant à une tâche, liées par job_id.

Colonnes

Colonne	Type	Notes
`id`	`bigint(20) unsigned`	Clé primaire, auto-incrémentation.
`job_id`	`bigint(20) unsigned`	Tâche parente. Valeur par défaut : `0`.
`vehicle_post_id`	`bigint(20) unsigned`	Publication du véhicule source. Valeur par défaut : `0`.
`asset_type`	`varchar(40)`	Type de ressource.
`file_path`	`text`	Chemin du fichier local. Peut être nul.
`file_url`	`text`	URL publique. Peut être nul.
`mime_type`	`varchar(120)`	Type MIME.
`file_size`	`bigint(20) unsigned`	Octets. Valeur par défaut : `0`.
`width`	`int(10) unsigned`	Largeur de l'image. Valeur par défaut : `0`.
`height`	`int(10) unsigned`	Hauteur de l'image. Valeur par défaut : `0`.
`duration_seconds`	`decimal(8,2)`	Durée du média. Valeur par défaut : `0.00`.
`caption`	`longtext`	Peut être nul.
`hashtags`	`longtext`	Peut être nul.
`alt_text`	`text`	Peut être nul.
`thumbnail_path`	`text`	Peut être nul.
`payload_json`	`longtext`	Charge utile structurée (ex. packs de rédaction). Peut être nul.
`scheduled_at`	`datetime`	Peut être nul.
`schedule_status`	`varchar(32)`	Valeur par défaut : `unscheduled`.
`created_at`	`datetime`	Valeur par défaut : `CURRENT_TIMESTAMP`.

Index : PRIMARY (id), job_id, vehicle_post_id, asset_type, created_at, schedule_status, scheduled_at.

Tables de cœur WordPress utilisées par le plugin

Le plugin ne modifie pas le schéma des tables de cœur WordPress. Il s'appuie sur elles de la manière suivante :

wp_posts — stocke les publications de as24ci_car (véhicules) et de as24ci_lead (leads).
wp_postmeta — stocke les métadonnées de publication (postmeta) de compatibilité descendante pour les publications de véhicules (_as24ci_listing_id, _as24ci_content_hash, _as24ci_images_hash, _as24ci_image_ids, _as24ci_manual_image_ids) et le statut du lead (_as24ci_lead_status).
wp_terms, wp_term_taxonomy, wp_term_relationships — stockent les 15 taxonomies de véhicules enregistrées par AS24CI\Taxonomies.
wp_options — stocke tous les réglages du plugin (clés définies comme constantes sur AS24CI\Options), ainsi que les marqueurs de version de schéma et les ID des pages créées lors de l'activation.
wp_users et wp_usermeta — utilisés indirectement via les capacités WordPress ; aucune écriture spécifique au plugin.

Les rôles et capacités personnalisés créés par le plugin (as24ci_editor, l'ensemble de capacités as24ci_car/as24ci_cars et manage_as24_imports) sont stockés via l'option standard des rôles WordPress (wp_user_roles).

Comportement lors de la désinstallation

Le script uninstall.php émet toujours DROP TABLE IF EXISTS pour les cinq tables personnalisées et supprime les options de version de schéma correspondantes :

{$wpdb->prefix}as24_vehicles (et as24ci_vehicles_db_version)
{$wpdb->prefix}as24ci_analytics
{$wpdb->prefix}as24ci_search_agents (et as24ci_search_agent_db_version)
{$wpdb->prefix}as24ci_content_studio_assets
{$wpdb->prefix}as24ci_content_studio_jobs (et as24ci_content_studio_db_version)

Sur les installations multisites, le script bascule sur chaque site et répète le nettoyage. Les publications, les pièces jointes et les pages créées lors de l'activation ne sont supprimées que lorsque l'administrateur a défini as24ci_delete_data_on_uninstall sur 1.

Notes opérationnelles

Les mises à niveau de schéma sont idempotentes. Chaque classe propriétaire vérifie son option de version de schéma et quitte rapidement lorsque la table correspond déjà à la version attendue. Le dépôt de véhicules vérifie en outre que la table existe physiquement avant de quitter rapidement.
Des requêtes directes wpdb sur ces tables existent dans les chemins de code du dépôt, de l'analyse, de l'agent de recherche et de la désinstallation. Elles sont protégées par des commentaires d'ignorance PHPCS le cas échéant. Le code personnalisé qui contourne le dépôt doit traiter le schéma comme faisant partie du contrat interne du plugin et se préparer à des modifications de colonnes entre les versions.
Les colonnes raw_data, equipment_* et images contiennent des données sérialisées. Traitez-les comme des blocs opaques (blobs) et accédez-y via les assistants du dépôt lorsque cela est possible.
La colonne manual_overrides est le seul endroit qui mélange l'état contrôlé par l'administrateur et l'état contrôlé par l'importateur. Évitez d'y écrire directement sans passer par la couche de surcharge.

Dépannage

maybe_create_table() n'a pas créé la table des véhicules. Confirmez que dbDelta() n'a signalé aucune erreur. Le dépôt écrit les erreurs dans error_log() car il s'exécute avant que le Logger du plugin ne soit disponible. Réexécuter l'activation (désactiver, activer) réexécute maybe_create_table().
Une nouvelle colonne est manquante après une mise à niveau du plugin. Vérifiez l'option de version de schéma pour la table concernée. Si elle est égale à la valeur actuelle mais que la colonne est manquante, supprimez l'option pour forcer la réexécution de dbDelta lors du prochain chargement de page d'administration. La table des véhicules dispose d'un filet de sécurité explicite manual_overrides pour ce cas.
La table d'analyse grandit rapidement. Réduisez la fenêtre de conservation ou désactivez l'analyse via Options::ANALYTICS_ENABLED. La tâche de nettoyage quotidienne est requise pour maintenir la table dans des limites raisonnables.
Les lignes de l'agent de recherche persistent après la désinstallation. Vérifiez que WordPress a exécuté uninstall.php. Si seul deactivate() s'est exécuté (par exemple parce que le plugin a été désactivé mais pas supprimé), la table est intentionnellement conservée jusqu'à la désinstallation.

Quand utiliser ce document

Aperçu

Table : {$wpdb->prefix}as24_vehicles

Colonnes

Index

Filet de sécurité pour manual_overrides

Table : {$wpdb->prefix}as24ci_analytics

Colonnes

Index

Rétention

Table : {$wpdb->prefix}as24ci_search_agents

Colonnes

Index

Confidentialité

Table : {$wpdb->prefix}as24ci_content_studio_jobs

Colonnes

Table : {$wpdb->prefix}as24ci_content_studio_assets

Colonnes

Tables de cœur WordPress utilisées par le plugin

Comportement lors de la désinstallation

Notes opérationnelles

Dépannage

Documents connexes

Table : `{$wpdb->prefix}as24_vehicles`

Filet de sécurité pour `manual_overrides`

Table : `{$wpdb->prefix}as24ci_analytics`

Table : `{$wpdb->prefix}as24ci_search_agents`

Table : `{$wpdb->prefix}as24ci_content_studio_jobs`

Table : `{$wpdb->prefix}as24ci_content_studio_assets`