Eventi Cron e pianificatore

Questo documento descrive gli eventi WP-Cron pianificati dal plugin ADP Car Market Hub, gli intervalli personalizzati che esso registra e la strategia di blocco che impedisce esecuzioni sovrapposte.

Quando utilizzare questo documento

Leggere questo documento se si desidera:

• Configurare le importazioni automatiche nella scheda di amministrazione Automation.
• Impostare un cron di sistema esterno per avviare le importazioni in modo affidabile.
• Diagnosticare esecuzioni di importazione saltate, sovrapposte o bloccate.
• Pianificare distribuzioni in produzione in cui WP-Cron è disabilitato a favore di un vero cron job.

Per la logica di importazione per singolo annuncio, vedere Import Engine. Per i meccanismi della coda delle immagini, vedere Image Importer And Queue.

Panoramica

Il plugin utilizza due percorsi di attivazione complementari:

• WP-Cron — lo pseudo-cron integrato di WordPress, attivato dalle visualizzazioni delle pagine del frontend. Il plugin registra qui gli hook cron e gli intervalli personalizzati.
• Endpoint REST cron — GET /wp-json/as24ci/v1/cron-import, autenticato tramite un token, consente a un vero cron di sistema di avviare le importazioni anche su siti a basso traffico.

Entrambi i percorsi chiamano lo stesso esecutore condiviso, AS24CI\Scheduler::run_import(), che acquisisce un blocco transitorio (transient lock), lo delega all'importatore, esegue facoltativamente le eliminazioni di sincronizzazione completa, pianifica il worker della coda delle immagini e registra l'esecuzione.

Hook cron registrati dal plugin

AS24CI\Scheduler viene costruito durante il bootstrap di AS24CI\Plugin e registra i seguenti hook di WordPress:

Inoltre, il file principale del plugin (adp-car-market-hub.php) registra un filtro cron_schedules separato che aggiunge l'intervallo as24ci_every_5_minutes (300 secondi) in modo incondizionato — utile per la coda AI e per qualsiasi integrazione personalizzata che necessiti di una cadenza inferiore all'ora.

Altri sottosistemi del plugin pianificano i propri eventi in modo indipendente:

• as24ci_daily_cleanup — pulizia giornaliera della conservazione dei dati di analytics, di proprietà di AS24CI\Analytics. Pianificato all'attivazione e rimosso alla disattivazione.
• Cron del motore di determinazione dei prezzi — giornaliero, di proprietà di AS24CI\Pricing_Engine (tag dell'hook as24ci_pricing_analysis_cron). Pianificato quando la funzionalità è abilitata e rimosso alla disattivazione.
• Data Quality Scanner — viene eseguito in base alla propria pianificazione (tag dell'hook as24ci_automated_taxonomy_scan, di proprietà di AS24CI\Data_Quality_Scanner) controllata da as24ci_dq_scan_frequency e as24ci_dq_scan_time.
• Worker della coda AI — tag dell'hook as24ci_process_ai_queue, di proprietà di AS24CI\Ai_Assistant. Associato in modo incondizionato; pianificato sull'intervallo as24ci_every_5_minutes solo quando AI Assistant è abilitato, e rimosso alla disattivazione.
• Nuova convalida della licenza — tag dell'hook as24ci_license_refresh, di proprietà di AS24CI\License_Manager. Pianificato daily all'attivazione (e tramite un ripristino automatico admin_init) e rimosso alla disattivazione. Questo è l'aggiornamento giornaliero autorevole dello stato della licenza / dei diritti delle funzionalità di ADP Car Market Hub.

Intervalli personalizzati

Anche gli intervalli standard di WordPress (hourly, twicedaily, daily) sono accettati dalla pianificazione dell'importazione.

Pianificazione dell'evento di importazione principale

L'evento di importazione principale è as24ci_scheduled_import, pianificato da AS24CI\Scheduler::reschedule(). Il metodo:

1. Chiama unschedule() per cancellare tutte le occorrenze esistenti dell'hook.
2. Ritorna immediatamente se as24ci_auto_import_enabled è 0 (nessun evento viene pianificato).
3. Legge as24ci_cron_schedule (predefinito hourly). Valori consentiti: hourly, as24ci_every_6_hours, twicedaily, daily, as24ci_custom.
4. Calcola il timestamp della prossima esecuzione tramite calculate_next_run(): - Per daily e twicedaily, utilizza l'orario configurato as24ci_cron_start_time (HH:MM, 24 h) interpretato nel fuso orario del sito WordPress. Se l'orario di inizio di oggi è già passato, la prossima esecuzione viene spostata a domani. - Per tutte le altre pianificazioni, la prossima esecuzione è immediata.
5. Chiama wp_schedule_event( $next_run, $schedule, 'as24ci_scheduled_import' ).

Lo scheduler non pianifica mai più di un'occorrenza dell'hook; unschedule() cancella ogni voce in sospeso prima che reschedule() ne aggiunga una nuova.

L'esecutore condiviso

AS24CI\Scheduler::run_import( string $source = 'manual' ) è il singolo punto di ingresso utilizzato da:

• L'hook cron as24ci_scheduled_import (origine: wp-cron).
• L'endpoint REST cron (origine: rest).
• Il pulsante "Esegui ora" dell'amministratore (origine: manual).

L'esecutore:

1. Acquisisce il blocco transitorio as24ci_cron_import_running (Scheduler::LOCK_TRANSIENT) con un TTL di Scheduler::LOCK_TTL. Un blocco obsoleto (più vecchio del TTL) viene automaticamente rimosso.
2. Per le origini cron e REST, aumenta il limite del tempo di esecuzione di PHP a 300 secondi tramite set_time_limit(300).
3. Legge as24ci_cron_max_vehicles (predefinito 50) e as24ci_cron_image_queue (predefinito 1).
4. Chiama Importer::set_cron_image_queue( true|false ) di conseguenza.
5. Itera sugli ID venditore configurati e chiama Importer::import_all_for_seller() per ciascuno, accumulando i conteggi e il set completo di listing_ids rilevati in questa esecuzione. Si ferma non appena viene raggiunto il limite di veicoli.
6. Se la sincronizzazione completa è abilitata (as24ci_full_sync = 1) e l'esecuzione non è stata interrotta dal limite, chiama Importer::full_sync_after_import( $remote_ids ). La chiamata di sincronizzazione completa non ha effetto se il set di ID remoti è vuoto (misura di sicurezza).
7. Pianifica il worker della coda delle immagini (maybe_schedule_image_queue_worker).
8. Rilascia il blocco e ripristina la modalità cron-image-queue nel blocco finally in modo che le successive chiamate manuali non ne risentano.
9. Registra as24ci_last_run_time e as24ci_last_run_status (array dei conteggi { inserted, updated, skipped, errors, sync_deleted, sync_kept, api_active }).
10. Invalida il transient "API status" della dashboard (Admin_Page::TRANSIENT_API_STATUS) in modo che le schede della dashboard si aggiornino al successivo caricamento della pagina.

L'esecutore restituisce array{ success: bool, message: string, counts: array<string,int> }.

Endpoint REST cron

AS24CI\Cron_Endpoint::register_routes() registra una singola rotta GET:

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

L'autenticazione viene eseguita all'interno del gestore. Il token viene letto da as24ci_cron_token. L'endpoint:

• Rifiuta le richieste quando non è configurato alcun token (403, con un messaggio che chiede all'amministratore di generarne uno nell'interfaccia di amministrazione).
• Accetta il token tramite l'intestazione Authorization: Bearer <token> (preferito — mantiene il token fuori dai log di accesso del server) o il parametro di query ?token=<token>.
• Chiama Scheduler::run_import( 'rest' ) in caso di successo.

Il plugin tiene traccia anche dei ping "il cron esterno è attivo" indipendentemente dall'endpoint REST:

• La visita a qualsiasi URL con ?as24ci_cron=1 aggiorna as24ci_last_external_cron_run al timestamp Unix corrente tramite Cron_Endpoint::record_external_ping() (collegato su init).

Blocchi e concorrenza

Il plugin utilizza due transient a breve durata per evitare la sovrapposizione dei lavori:

Un blocco obsoleto (più vecchio del TTL) viene rimosso automaticamente dal prossimo esecutore, in modo che un processo interrotto a metà esecuzione non blocchi le importazioni future a tempo indeterminato. Il ripristino manuale (eliminando il transient tramite WP-CLI o uno strumento di database) è necessario solo se si desidera forzare una nuova esecuzione prima di quanto consentito dal TTL.

Riferimento per la configurazione

Le costanti di Scheduler::LOCK_TTL e del worker della coda delle immagini sono definite nel codice; verificare i valori correnti nel codice sorgente se si necessita di numeri esatti.

Istruzioni passo dopo passo

Abilitare le importazioni automatiche tramite WP-Cron

1. Aprire la scheda di amministrazione Automation.
2. Impostare Cron mode su wp-cron.
3. Impostare Auto import su abilitato (as24ci_auto_import_enabled = 1).
4. Scegliere una pianificazione. Per daily / twicedaily, impostare l'orario di inizio. For as24ci_custom, impostare l'intervallo (minimo 15 minuti).
5. Salvare. La scheda Import & Limits chiama Scheduler::reschedule() per registrare la prossima esecuzione.
6. (Facoltativo) Ridurre Vehicles per cron run per cataloghi molto grandi in modo che le singole esecuzioni rimangano entro il limite di tempo PHP dell'host.

Attivare le importazioni tramite un cron di sistema

1. Impostare Cron mode su server-cron in modo che l'interfaccia utente di amministrazione mostri i suggerimenti per il cron del server.
2. (Consigliato) Disabilitare WP-Cron in wp-config.php:

• Impostare define( 'DISABLE_WP_CRON', true );. WordPress eseguirà quindi gli eventi pianificati solo quando qualcosa li attiva esplicitamente.

1. Generare un token nella schermata Import & Limits. Il plugin lo memorizza in as24ci_cron_token.
2. Configurare il cron di sistema per chiamare l'endpoint REST, ad esempio ogni ora:

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

Il parametro di query facoltativo ?as24ci_cron=1 aggiorna anche il timestamp "il cron esterno è attivo" mostrato nello stato dell'amministratore.

1. Verificare la risposta. Un'esecuzione riuscita restituisce un payload JSON con i conteggi; un codice 403 indica un token mancante o errato.

---

Note operative

• WP-Cron viene attivato dal traffico del sito. Sui siti a basso traffico, gli eventi pianificati potrebbero essere eseguiti in ritardo o non essere eseguiti affatto. Utilizzare un vero cron di sistema in produzione.
• La chiamata set_time_limit(300) potrebbe essere ignorata dagli host che impongono limiti di tempo PHP. In tal caso, il plugin registra un avviso nei log.
• L'opzione as24ci_full_sync è di tipo opt-in per sicurezza. Con questa opzione abilitata, i veicoli i cui annunci scompaiono dall'API vengono eliminati in modo permanente (inclusi i relativi allegati importati). Assicurarsi che i Seller ID configurati coprano l'intero catalogo che si intende mantenere online.
• La disattivazione del plugin cancella tutti i suoi eventi pianificati (as24ci_scheduled_import, la pulizia di Analytics, la pianificazione della coda AI, la pianificazione del motore di determinazione dei prezzi e l'evento as24ci_license_refresh — oltre all'hook legacy as24ci_competitor_watcher_cron) e rimuove il transient as24ci_cron_import_running.
• Il plugin non codifica mai in modo rigido URL cron esterni o token. L'esempio sopra utilizza un segnaposto; sostituirlo con il proprio host e un token generato prima della distribuzione.

Risoluzione dei problemi

• Le importazioni non vengono eseguite automaticamente. Verificare as24ci_auto_import_enabled = 1, che sia selezionata una pianificazione e che wp_next_scheduled( 'as24ci_scheduled_import' ) restituisca un timestamp futuro. Se il valore è false, salvare nuovamente la scheda Automazione per chiamare reschedule().
• Viene registrato Import already in progress. Il blocco di esecuzione singola è mantenuto da un altro esecutore. Attendere la scadenza del TTL del blocco (l'esecutore successivo cancellerà automaticamente un blocco obsoleto) o eliminare il transient as24ci_cron_import_running tramite WP-CLI per un tentativo immediato.
• Viene restituito No seller IDs configured. Impostare as24ci_seller_ids nelle impostazioni dell'API.
• Le pianificazioni giornaliere si attivano all'ora sbagliata. Il plugin utilizza il fuso orario del sito WordPress (wp_timezone()). Verificare il fuso orario in Impostazioni → Generale, non l'ora locale del server.
• L'endpoint REST restituisce 403. Il token è mancante (as24ci_cron_token vuoto — il messaggio di risposta lo conferma) oppure il token nella richiesta non corrisponde. Generare un nuovo token nell'interfaccia di amministrazione.
• Il cron esterno sembra inattivo nello stato dell'amministratore. Verificare che l'URL chiamato includa ?as24ci_cron=1 (o che l'endpoint cron REST abbia successo) e che la richiesta raggiunga il sito WordPress (nessun firewall, nessuna barriera di autenticazione). Il plugin aggiorna as24ci_last_external_cron_run a ogni ping andato a buon fine.
• La coda delle immagini non si svuota dopo un'importazione cron. Si tratta di un worker separato. Consultare la sezione sulla risoluzione dei problemi in Importatore immagini e coda.

Documenti correlati

• Motore di importazione
• Importatore immagini e coda
• Bootstrap e ciclo di vita del plugin
• Archiviazione di opzioni e impostazioni
• Panoramica della sezione