Événements Cron et planificateur

Ce document décrit les événements WP-Cron que le plugin ADP Car Market Hub planifie, les intervalles personnalisés qu'il enregistre et la stratégie de verrouillage qui empêche les exécutions simultanées.

Quand utiliser ce document

Lisez ce document si vous devez :

• Configurer les importations automatiques dans l'onglet d'administration Automation.
• Configurer un cron système externe pour déclencher les importations de manière fiable.
• Diagnostiquer les exécutions d'importation manquées, superposées ou bloquées.
• Planifier des déploiements en production où WP-Cron est désactivé au profit d'une véritable tâche cron.

Pour la logique d'importation par annonce, voir Import Engine. Pour le fonctionnement de la file d'attente des images, voir Image Importer And Queue.

Aperçu

Le plugin utilise deux voies de déclenchement complémentaires :

• WP-Cron — Le pseudo-cron intégré de WordPress, déclenché par les visites des pages du frontend. Le plugin y enregistre des hooks cron et des intervalles personnalisés.
• Point de terminaison REST cron — GET /wp-json/as24ci/v1/cron-import, authentifié par un jeton, permet à un véritable cron système de déclencher les importations même sur les sites à faible trafic.

Les deux voies appellent le même exécuteur partagé, AS24CI\Scheduler::run_import(), qui acquiert un verrou temporaire (transient), délègue à l'importateur, effectue éventuellement des suppressions de synchronisation complète, planifie le worker de la file d'attente d'images et enregistre l'exécution.

Hooks cron enregistrés par le plugin

AS24CI\Scheduler est construit lors du bootstrap de AS24CI\Plugin et enregistre les hooks WordPress suivants :

De plus, le fichier principal du plugin (adp-car-market-hub.php) enregistre un filtre cron_schedules distinct qui ajoute l'intervalle as24ci_every_5_minutes (300 secondes) de manière inconditionnelle — utile pour la file d'attente de l'IA et toutes les intégrations personnalisées nécessitant une cadence inférieure à l'heure.

D'autres sous-systèmes du plugin planifient leurs propres événements de manière indépendante :

• as24ci_daily_cleanup — nettoyage quotidien de la rétention des analyses, géré par AS24CI\Analytics. Planifié lors de l'activation et supprimé lors de la désactivation.
• Cron du moteur de tarification — quotidien, géré par AS24CI\Pricing_Engine (balise de hook as24ci_pricing_analysis_cron). Planifié lorsque la fonctionnalité est activée et effacé lors de la désactivation.
• Scanner de qualité des données — s'exécute selon son propre calendrier (balise de hook as24ci_automated_taxonomy_scan, géré par AS24CI\Data_Quality_Scanner) contrôlé par as24ci_dq_scan_frequency et as24ci_dq_scan_time.
• Worker de la file d'attente de l'IA — balise de hook as24ci_process_ai_queue, géré par AS24CI\Ai_Assistant. Lié inconditionnellement ; planifié sur l'intervalle as24ci_every_5_minutes uniquement lorsque l'AI Assistant est activé, et effacé lors de la désactivation.
• Revalidation de licence — balise de hook as24ci_license_refresh, géré par AS24CI\License_Manager. Planifié daily lors de l'activation (et via une auto-correction admin_init) et effacé lors de la désactivation. Il s'agit de la mise à jour quotidienne faisant autorité de l'état de la licence / des droits de fonctionnalités de ADP Car Market Hub.

Intervalles personnalisés

Les intervalles standards de WordPress (hourly, twicedaily, daily) sont également acceptés par le calendrier d'importation.

Planification de l'événement d'importation principal

L'événement d'importation principal est as24ci_scheduled_import, planifié par AS24CI\Scheduler::reschedule(). La méthode :

1. Appelle unschedule() pour effacer toutes les occurrences existantes du hook.
2. Retourne immédiatement si as24ci_auto_import_enabled est 0 (aucun événement n'est planifié).
3. Lit as24ci_cron_schedule (par défaut hourly). Valeurs autorisées : hourly, as24ci_every_6_hours, twicedaily, daily, as24ci_custom.
4. Calcule l'horodatage de la prochaine exécution via calculate_next_run() : - Pour daily et twicedaily, utilise l'heure de début configurée as24ci_cron_start_time (HH:MM, 24 h) interprétée dans le fuseau horaire du site WordPress. Si l'heure de début d'aujourd'hui est déjà dépassée, la prochaine exécution est reportée à demain. - Pour tous les autres calendriers, la prochaine exécution est immédiate.
5. Appelle wp_schedule_event( $next_run, $schedule, 'as24ci_scheduled_import' ).

Le planificateur ne planifie jamais plus d'une occurrence du hook ; unschedule() efface chaque entrée en attente avant que reschedule() n'en ajoute une nouvelle.

L'exécuteur partagé

AS24CI\Scheduler::run_import( string $source = 'manual' ) est le point d'entrée unique utilisé par :

• Le hook cron as24ci_scheduled_import (source : wp-cron).
• Le point de terminaison REST cron (source : rest).
• Le bouton d'administration « Exécuter maintenant » (source : manual).

L'exécuteur :

1. Acquiert le verrou temporaire as24ci_cron_import_running (Scheduler::LOCK_TRANSIENT) avec une durée de vie (TTL) de Scheduler::LOCK_TTL. Un verrou obsolète (plus ancien que la durée de vie) est automatiquement effacé.
2. Pour les sources cron et REST, augmente la limite de temps d'exécution PHP à 300 secondes via set_time_limit(300).
3. Lit as24ci_cron_max_vehicles (par défaut 50) et as24ci_cron_image_queue (par défaut 1).
4. Appelle Importer::set_cron_image_queue( true|false ) en conséquence.
5. Boucle sur les Seller ID configurés et appelle Importer::import_all_for_seller() pour chacun, en cumulant les totaux et l'ensemble complet de listing_ids vus lors de cette exécution. S'arrête dès que la limite de véhicules est atteinte.
6. Si la synchronisation complète est activée (as24ci_full_sync = 1) et que l'exécution n'a pas été interrompue par la limite, appelle Importer::full_sync_after_import( $remote_ids ). L'appel de synchronisation complète n'effectue aucune action si l'ensemble d'identifiants distants est vide (mesure de sécurité).
7. Planifie le worker de la file d'attente d'images (maybe_schedule_image_queue_worker).
8. Libère le verrou et réinitialise le mode cron-image-queue dans le bloc finally afin que les appels manuels ultérieurs ne soient pas affectés.
9. Enregistre as24ci_last_run_time et as24ci_last_run_status (tableau de comptage { inserted, updated, skipped, errors, sync_deleted, sync_kept, api_active }).
10. Invalide le transient « API status » du tableau de bord (Admin_Page::TRANSIENT_API_STATUS) afin que les cartes du tableau de bord se rafraîchissent lors du prochain chargement de page.

L'exécuteur retourne array{ success: bool, message: string, counts: array<string,int> }.

Point de terminaison REST cron

AS24CI\Cron_Endpoint::register_routes() enregistre une seule route GET :

• GET /wp-json/as24ci/v1/cron-import

L'authentification est effectuée à l'intérieur du gestionnaire. Le jeton est lu depuis as24ci_cron_token. Le point de terminaison :

• Refuse les requêtes lorsqu'aucun jeton n'est configuré (403, avec un message demandant à l'administrateur d'en générer un dans l'interface d'administration).
• Accepte le jeton soit via l'en-tête Authorization: Bearer <token> (préféré — maintient le jeton hors des journaux d'accès du serveur), soit via le paramètre de requête ?token=<token>.
• Appelle Scheduler::run_import( 'rest' ) en cas de succès.

Le plugin suit également les pings « le cron externe est actif » indépendamment du point de terminaison REST :

• La visite de n'importe quelle URL avec ?as24ci_cron=1 met à jour as24ci_last_external_cron_run avec l'horodatage Unix actuel via Cron_Endpoint::record_external_ping() (lié à init).

Verrous et concurrence

Le plugin utilise deux transients à courte durée de vie pour empêcher les travaux simultanés :

Un verrou obsolète (plus ancien que la durée de vie) est automatiquement effacé par le prochain exécuteur, de sorte qu'un processus qui s'est arrêté en cours d'exécution ne bloque pas indéfiniment les futures importations. Une récupération manuelle (suppression du transient via WP-CLI ou un outil de base de données) n'est nécessaire que si vous souhaitez forcer une nouvelle exécution plus tôt que ne le permet la durée de vie.

Référence de configuration

Les constantes de Scheduler::LOCK_TTL et du worker de la file d'attente d'images sont définies dans le code ; vérifiez les valeurs actuelles dans le code source si vous avez besoin de chiffres exacts.

Instructions étape par étape

Activation des importations automatisées via WP-Cron

1. Ouvrez l'onglet d'administration Automation.
2. Réglez le Cron mode sur wp-cron.
3. Réglez Auto import sur activé (as24ci_auto_import_enabled = 1).
4. Choisissez un calendrier. Pour daily / twicedaily, définissez l'heure de début. Pour as24ci_custom, définissez l'intervalle (minimum 15 minutes).
5. Enregistrez. L'onglet Import & Limits appelle Scheduler::reschedule() pour enregistrer la prochaine exécution.
6. (Facultatif) Diminuez la valeur de Vehicles per cron run pour les très grands catalogues afin que les exécutions individuelles restent dans la limite de temps PHP de l'hébergeur.

Déclenchement des importations via un cron système

1. Basculez le Cron mode sur server-cron afin que l'interface d'administration affiche les indications pour le cron du serveur.
2. (Recommandé) Désactivez WP-Cron dans wp-config.php :

• Définissez define( 'DISABLE_WP_CRON', true );. WordPress n'exécutera alors les événements planifiés que lorsque quelque chose les déclenchera explicitement.

1. Générez un jeton dans l'écran Import & Limits. Le plugin le stocke dans as24ci_cron_token.
2. Configurez votre cron système pour appeler le point de terminaison REST, par exemple toutes les heures :

   0 * * * * curl -fsS -H "Authorization: Bearer YOUR_TOKEN" \
     "https://example.com/wp-json/as24ci/v1/cron-import?as24ci_cron=1"

Le paramètre de requête facultatif ?as24ci_cron=1 met également à jour l'horodatage « le cron externe est actif » affiché dans l'état d'administration.

1. Vérifiez la réponse. Une exécution réussie renvoie une charge utile JSON contenant les totaux ; un code 403 indique un jeton manquant ou incorrect.

---

Notes opérationnelles

• WP-Cron est déclenché par le trafic du site. Sur les sites à faible trafic, les événements planifiés peuvent s'exécuter en retard ou pas du tout. Utilisez un véritable cron système en production.
• L'appel set_time_limit(300) peut être ignoré par les hébergeurs qui imposent des limites de temps PHP. Le plugin enregistre un avertissement dans ce cas.
• L'option as24ci_full_sync est activable sur option par mesure de sécurité. Lorsqu'elle est activée, les véhicules dont les annonces disparaissent de l'API sont définitivement supprimés (y compris leurs pièces jointes importées). Assurez-vous que les Seller IDs configurés couvrent l'intégralité du catalogue que vous avez l'intention de conserver en ligne.
• La désactivation du plugin efface tous ses événements planifiés (as24ci_scheduled_import, le nettoyage de l'analyse, la planification de la file d'attente de l'AI Assistant, la planification du moteur de tarification et l'événement as24ci_license_refresh — ainsi que le hook hérité as24ci_competitor_watcher_cron) et supprime le transient as24ci_cron_import_running.
• Le plugin ne code jamais en dur d'URL ou de jetons cron externes. L'exemple ci-dessus utilise un espace réservé ; remplacez-le par votre propre hôte et un jeton généré avant le déploiement.

Dépannage

• Les importations ne s'exécutent pas automatiquement. Vérifiez as24ci_auto_import_enabled = 1, qu'une planification est sélectionnée et que wp_next_scheduled( 'as24ci_scheduled_import' ) renvoie un horodatage futur. Si la valeur est false, enregistrez à nouveau l'onglet Automatisation pour appeler reschedule().
• Import already in progress est enregistré dans les journaux. Le verrou d'exécution unique est détenu par un autre exécuteur. Attendez que le TTL du verrou expire (le prochain exécuteur effacera automatiquement un verrou obsolète) ou supprimez le transient as24ci_cron_import_running via WP-CLI pour une tentative immédiate.
• No seller IDs configured est renvoyé. Définissez as24ci_seller_ids dans les réglages de l'API.
• Les planifications quotidiennes se déclenchent au mauvais moment. Le plugin utilise le fuseau horaire du site WordPress (wp_timezone()). Vérifiez le fuseau horaire dans Réglages → Général, et non l'heure locale du serveur.
• L'endpoint REST renvoie 403. Soit le jeton est manquant (as24ci_cron_token vide — le message de réponse le confirme), soit le jeton de la requête ne correspond pas. Générez un nouveau jeton dans l'interface d'administration.
• Le cron externe semble inactif dans l'état de l'administration. Vérifiez que l'URL que vous appelez inclut ?as24ci_cron=1 (ou que l'endpoint cron REST réussit), et que la requête atteint le site WordPress (pas de pare-feu, pas de barrière d'authentification). Le plugin met à jour as24ci_last_external_cron_run à chaque ping réussi.
• La file d'attente d'images ne se vide pas après une importation cron. Il s'agit d'un worker distinct. Consultez la section de dépannage dans Importateur d'images et file d'attente.

Documents connexes

• Moteur d'importation
• Importateur d'images et file d'attente
• Amorçage et cycle de vie du plugin
• Stockage des options et des réglages
• Aperçu de la section