Cron et traitement en arrière-plan

Objectif

ADP Car Market Hub dépend de tâches d'arrière-plan planifiées pour presque tout ce qui n'est pas une action directe de l'utilisateur : il importe les véhicules depuis AutoScout24, traite les images de manière asynchrone, nettoie les données d'analyse, actualise l'analyse des prix et exécute des analyses quotidiennes de la qualité des données. Ce document explique les mécanismes de cron utilisés par l'extension, les différences entre le planificateur intégré de WordPress et un véritable cron de serveur, les tâches récurrentes planifiées par l'extension et les signaux opérationnels à surveiller.

Quand utiliser ce document

Utilisez ce document lorsque vous :

• Devez choisir entre WP-Cron et un cron de serveur externe pour un nouveau site de concessionnaire.
• Configurez le mode cron, la fréquence et le jeton secret dans l'onglet Import & Limits.
• Connectez un planificateur externe (cron Linux, interface cron d'hébergement ou un pinger distant) à l'endpoint REST cron de l'extension.
• Enquêtez sur la raison pour laquelle les importations ne s'exécutent pas comme prévu, ou pourquoi le traitement des images est retardé.
• Auditez les tâches récurrentes enregistrées par l'extension et la durée de conservation de leurs données.

Aperçu

Le modèle de traitement en arrière-plan de l'extension comporte trois couches :

1. Une couche de déclenchement qui décide quand le travail doit commencer. Il peut s'agir du pseudo-cron de WordPress (déclenché par les visites du site sur wp-cron.php) ou d'un cron de serveur externe qui appelle soit wp-cron.php directement, soit l'endpoint REST sécurisé par jeton de l'extension à l'adresse /wp-json/as24ci/v1/cron-import.
2. Une couche de planification qui possède les tâches récurrentes. L'extension enregistre des intervalles personnalisés (toutes les 5 minutes, toutes les 6 heures, plus un intervalle configurable "toutes les N minutes" avec un minimum de 15 minutes) et un petit ensemble de hooks WP-Cron pour les importations, la file d'attente d'images, la file d'attente de génération de l'IA, le nettoyage des analyses, l'analyse des prix et l'analyse quotidienne de la taxonomie.
3. Une couche d'exécution (worker) qui effectue le travail réel. Chaque hook WP-Cron est lié à une méthode de classe (importateur, file d'attente d'images, nettoyage des analyses, etc.) qui utilise des verrous basés sur des transients pour empêcher les exécutions simultanées et écrit des options d'état/battement de cœur (heartbeat) que l'onglet System & Help / Health et le widget du tableau de bord lisent en retour.

Les trois chemins d'importation — le hook WP-Cron planifié, l'endpoint REST cron et le bouton d'administration "Déclencher maintenant" — appellent le même exécuteur partagé, de sorte que le comportement et le verrouillage sont identiques quel que soit le déclencheur.

Cron WordPress vs. cron de serveur

L'onglet Import & Limits propose deux modes de déclenchement ; tous deux sont pris en charge, mais ils présentent des profils de fiabilité très différents.

Cron WordPress (par défaut)

• Déclenché par le trafic des visiteurs. Chaque requête vers une page WordPress peut générer wp-cron.php en arrière-plan.
• Fonctionne sur n'importe quel hébergeur sans accès au serveur.
• Devient peu fiable sur les sites à faible trafic : sans visiteurs, il n'y a pas d'exécutions de cron.
• L'extension installe toujours tous ses hooks ; les exécutions manquées s'accumulent simplement jusqu'à la prochaine visite.

Cron de serveur (recommandé pour la production)

• Déclenché par le système d'exploitation ou le planificateur du panneau de contrôle de l'hébergement.
• Indépendant du trafic du site web, prévisible et requis par les contrôles de santé (Health) de l'extension pour obtenir un statut de production "entièrement prêt".
• Configuration recommandée : 1. Définissez define( 'DISABLE_WP_CRON', true ); dans wp-config.php afin de désactiver le cron déclenché par les visites. 2. Ajoutez une entrée de cron de serveur qui appelle l'endpoint REST de l'extension avec le jeton secret. 3. Ajoutez une deuxième entrée qui exécute wp-cron.php lui-même, afin que les tâches récurrentes autres que l'importation (file d'attente d'images, nettoyage des analyses, tarification, etc.) continuent de se déclencher.

Le passage à Server Cron dans l'onglet Import & Limits masque les champs de planification WP-Cron et affiche l'URL de déclenchement REST, le jeton secret et des exemples de commandes prêts à être copiés.

Tâches récurrentes enregistrées par l'extension

Les hooks WP-Cron suivants sont planifiés par l'extension (certains uniquement lorsque la fonctionnalité associée est configurée). L'onglet System & Help répertorie leur prochaine heure d'exécution planifiée afin qu'ils puissent être inspectés à tout moment.

L'activation enregistre les tâches récurrentes qui doivent toujours exister (importations, nettoyage des analyses, tarification, file d'attente d'images, file d'attente d'IA le cas échéant). La désactivation supprime les entrées WP-Cron de l'extension via wp_clear_scheduled_hook() pour chaque hook ci-dessus.

Importations récurrentes

L'exécuteur d'importation est partagé par les trois chemins de déclenchement et se comporte comme suit :

• Verrouillage. Avant d'effectuer tout travail, l'exécuteur définit un transient (as24ci_cron_import_running) avec une durée de vie (TTL) d'environ 40 minutes. Les exécutions ultérieures qui arrivent pendant que le verrou est actif se terminent proprement et signalent qu'une importation est déjà en cours. Cela empêche WP-Cron et un cron de serveur d'entrer en conflit.
• Traitement par vendeur. L'exécuteur parcourt chaque Seller ID configuré et appelle l'importateur pour chacun d'eux à son tour.
• Véhicules par exécution. L'onglet Import & Limits propose une limite de "Véhicules par exécution" (0 = pas de limite). La réduction de cette valeur est le principal levier de stabilité sur les hébergements partagés et les très grands inventaires ; les valeurs recommandées sont de 50 à 80 pour les grands catalogues.
• Persistance de l'état. Après chaque exécution, les options sont mises à jour avec l'horodatage de la dernière exécution, la source du déclencheur (wp-cron, rest, manuel) et les décomptes par vendeur. Le widget du tableau de bord et l'onglet System & Help lisent ces options pour afficher les informations de la dernière exécution.
• Synchronisation complète optionnelle. Lorsque l'option Full Sync est activée, l'exécuteur peut marquer comme supprimés les véhicules absents de la dernière réponse de l'API ; cette action est permanente, une stratégie de sauvegarde testée est donc requise (voir Configuration requise pour l'hébergement).

L'assistant par lots (Batch-Wizard) de l'interface d'administration utilise le même importateur mais traite un véhicule par étape à partir d'une liste en file d'attente (transient as24ci_batch_queue), ce qui est utile pour les très grandes importations initiales sur des hébergements limités.

File d'attente d'images et workers asynchrones

Lorsque l'option Enable Image Queue est activée (recommandé pour les importations contenant beaucoup d'images) :

• Pendant l'importation, seule la première image de chaque véhicule est téléchargée de manière synchrone, de sorte que la page s'affiche rapidement et que l'exécution du cron se termine bien en deçà des limites de temps d'exécution de PHP.
• Les URL des images restantes sont ajoutées à la file d'attente d'images (une option WordPress) et traitées par lots par le hook as24ci_image_queue_process toutes les 5 minutes.
• Le worker utilise son propre verrou transient (as24ci_image_queue_running, TTL de 10 minutes) et traite un nombre fixe d'images par lot.
• Une limite de sécurité (la constante de limite de taille de la file d'attente dans Scheduler) plafonne la taille que la file d'attente peut atteindre avant que l'extension n'enregistre un avertissement et ne supprime de force les doublons.

La file d'attente de génération d'IA suit un modèle similaire : les appels d'IA pendant l'importation sont différés dans une file d'attente et traités par un worker asynchrone afin que les exécutions d'importation ne soient pas bloquées par l'endpoint géré de Gemini.

Routines de nettoyage et de rétention

• Rétention des analyses. Analytics::cleanup_old_data() (hook as24ci_daily_cleanup) supprime les lignes d'analyse plus anciennes que la valeur définie dans le réglage Analytics retention days. La valeur par défaut est de 180 jours ; le minimum imposé dans le code est de 7 jours.
• Rotation des journaux. Les journaux de l'extension dans wp-content/uploads/as24ci-logs/ subissent une rotation lorsqu'un fichier atteint 10 Mo, et les fichiers archivés sont supprimés après 7 jours. Ce processus est indépendant de WP-Cron et s'exécute à chaque écriture de journal.
• Cache des jetons. Les jetons d'accès OAuth sont mis en cache dans un transient jusqu'à peu de temps avant leur expires_in annoncé. Un outil "Effacer le cache des jetons" existe pour le diagnostic.
• Suppression de véhicules. Lorsque l'extension supprime un véhicule (Full Sync ou suppression manuelle), elle nettoie les pièces jointes multimédias et les métadonnées associées via un chemin de suppression centralisé.

Endpoint REST cron

L'endpoint de déclenchement sécurisé par jeton est enregistré par Cron_Endpoint :

• Route : GET /wp-json/as24ci/v1/cron-import
• Authentification : un secret aléatoire de 32 caractères stocké dans l'option as24ci_cron_token. L'endpoint accepte le jeton de deux manières :
• Préférée : en-tête HTTP Authorization: Bearer <token> (conserve le jeton hors des journaux d'accès).
• Alternative : paramètre de requête ?token=<token>.
• Codes de réponse : 200 en cas de succès, 429 lorsque le verrou est déjà actif (une importation est déjà en cours), 403 pour les jetons manquants ou invalides, 500 pour les exceptions non gérées.
• Effet secondaire : chaque appel réussi met à jour l'option as24ci_last_external_cron_run, que l'onglet System & Help utilise pour confirmer que le cron externe est actif.
• Un battement de cœur (heartbeat) distinct et non authentifié est enregistré chaque fois qu'une URL WordPress est appelée avec ?as24ci_cron=1, ce qui est utile pour les pingers externes simples qui ont seulement besoin de confirmer l'accessibilité.

L'onglet Import & Limits génère des exemples de commandes prêts à être copiés, tels que :

*/15 * * * * curl -s "https://example.com/wp-json/as24ci/v1/cron-import?token=YOUR_TOKEN" > /dev/null
*/5  * * * * php /var/www/html/wp-cron.php > /dev/null 2>&1

La première entrée déclenche les importations ; la seconde maintient l'exécution des hooks WP-Cron autres que l'importation (file d'attente d'images, nettoyage des analyses, tarification, etc.) lorsque DISABLE_WP_CRON est défini sur true.

Surveillance opérationnelle

L'extension expose les signaux dont les opérateurs ont besoin pour effectuer la surveillance sans aucun outil supplémentaire :

• Onglet System & Help / Health. Répertorie chaque hook cron de l'extension, sa prochaine exécution planifiée et indique si la planification est actuellement gérée par WP-Cron ou par un cron de serveur externe. Comprend un encadré qui signale DISABLE_WP_CRON comme recommandé en mode cron de serveur.
• Widget du tableau de bord. Affiche l'exécution d'importation la plus récente, la prochaine importation planifiée (lorsque WP-Cron est utilisé), la taille de la file d'attente d'images et la prochaine exécution de la file d'attente.
• Journaux de l'extension. wp-content/uploads/as24ci-logs/ enregistre chaque exécution de cron, l'acquisition/libération de verrou, l'activité de la file d'attente d'images et toutes les erreurs HTTP. Les journaux subissent une rotation à 10 Mo avec une rétention de 7 jours.
• Options de dernière exécution. as24ci_last_external_cron_run et les options internes correspondantes peuvent être vérifiées directement via WP-CLI pour des alertes scriptées.

Une configuration de production simple comprend :

• Un contrôle de disponibilité (uptime) sur l'URL de l'archive publique (disponibilité du front-end).
• Un contrôle de disponibilité sur /wp-json/as24ci/v1/cron-import?token=… renvoyant un statut 2xx/429 (chemin cron accessible et authentifié).
• Une alerte d'espace disque sur le volume wp-content/uploads/ (croissance des images et journaux).
• Une transmission optionnelle des journaux ou un examen périodique du répertoire des journaux de l'extension.

---

---

Dépannage

• Les importations ne se lancent jamais automatiquement. Confirmez le mode cron dans l'onglet Import & Limits. Si WP-Cron est sélectionné, les sites à faible trafic peuvent ne pas déclencher le cron du tout — passez au cron du serveur. Si le cron du serveur est sélectionné, vérifiez que la commande curl/wget atteint effectivement le point de terminaison REST (HTTP 200 ou 429 attendu).
• Réponses « An import is already running » (HTTP 429). Le transient de verrouillage est toujours actif depuis une exécution précédente. Attendez que l'exécution se termine, ou effacez le transient as24ci_cron_import_running si un processus PHP précédent a planté sans libérer le verrou. Diminuez le paramètre Vehicles per Run pour maintenir les exécutions individuelles confortablement en dessous de la durée de vie (TTL) du verrou.
• La file d'attente des images grandit sans diminuer. Confirmez que wp-cron.php est en cours d'exécution (en mode cron du serveur, cela nécessite la deuxième entrée cron présentée ci-dessus), vérifiez le répertoire des journaux pour détecter d'éventuelles erreurs du worker de file d'attente, et vérifiez le HTTPS sortant vers les hébergeurs d'images (voir API, Network and SSL Requirements).
• Les données d'analyse ou de tarification ne sont pas actualisées. Celles-ci s'exécutent quotidiennement via WP-Cron ; si DISABLE_WP_CRON est défini sur true et qu'il n'y a pas de deuxième entrée cron appelant wp-cron.php, les tâches quotidiennes ne se déclencheront jamais.
• L'onglet System & Help indique que le jeton cron n'est pas configuré. Ouvrez l'onglet Import & Limits, passez en mode cron du serveur et laissez l'extension générer automatiquement un jeton ou collez le vôtre, puis enregistrez.
• Jeton divulgué ou renouvelé. Cliquez sur Regenerate Token dans l'onglet Import & Limits. Mettez à jour immédiatement chaque planificateur externe, car le jeton précédent cesse de fonctionner dès que le nouveau est enregistré.
• Les exécutions de cron sur l'environnement de staging affectent les données de production. Utilisez un jeton cron différent par environnement et envisagez d'utiliser un client AutoScout24 différent lorsque cela est possible (voir Configuration requise pour l'hébergement).

Documents connexes

• Configuration requise pour le système technique
• Configuration requise pour WordPress
• Configuration requise pour l'hébergement
• Configuration requise pour PHP et la base de données
• API, Network and SSL Requirements
• Liste de contrôle de pré-installation