Cron e elaborazione in background

Scopo

ADP Car Market Hub dipende da attività pianificate in background per quasi tutto ciò che non è un'azione diretta dell'utente: importa i veicoli da AutoScout24, elabora le immagini in modo asincrono, pulisce i dati analitici, aggiorna l'analisi dei prezzi ed esegue scansioni giornaliere sulla qualità dei dati. Questo documento spiega i meccanismi di cron utilizzati dal plugin, le differenze tra lo scheduler integrato di WordPress e un vero cron del server, i job ricorrenti pianificati dal plugin e i segnali operativi da monitorare.

Quando utilizzare questo documento

Utilizza questo documento quando desideri:

• Decidere tra WP-Cron e un cron server esterno per un nuovo sito di concessionaria.
• Configurare la modalità cron, la frequenza e il token segreto nella scheda Importazione e limiti.
• Collegare uno scheduler esterno (cron di Linux, interfaccia utente cron dell'hosting o un pinger remoto) all'endpoint REST cron del plugin.
• Investigare sul perché le importazioni non vengano eseguite come pianificato o perché l'elaborazione delle immagini sia ritardata.
• Verificare quali job ricorrenti registra il plugin e per quanto tempo vengono conservati i relativi dati.

Panoramica

Il modello di elaborazione in background del plugin si articola su tre livelli:

1. Un livello di attivazione (trigger) che decide quando il lavoro deve iniziare. Questo può essere il pseudo-cron di WordPress (guidato dalle visite degli utenti al sito su wp-cron.php) o un cron server esterno che chiama direttamente wp-cron.php o l'endpoint REST del plugin protetto da token all'indirizzo /wp-json/as24ci/v1/cron-import.
2. Un livello di pianificazione (scheduler) che gestisce i job ricorrenti. Il plugin registra intervalli personalizzati (ogni 5 minuti, ogni 6 ore, oltre a un intervallo configurabile "ogni N minuti" con un limite minimo di 15 minuti) e un piccolo set di hook WP-Cron per le importazioni, la coda delle immagini, la coda di generazione AI, la pulizia dei dati analitici, l'analisi dei prezzi e la scansione giornaliera delle tassonomie.
3. Un livello di esecuzione (worker) che svolge il lavoro effettivo. Ogni hook WP-Cron è associato a un metodo di classe (importatore, coda immagini, pulizia dati analitici, ecc.) che utilizza blocchi (lock) basati su transient per prevenire esecuzioni sovrapposte e scrive opzioni di stato/heartbeat lette dalla scheda Stato e salute / Salute e dal widget della bacheca.

Tutti e tre i percorsi di importazione — l'hook WP-Cron pianificato, l'endpoint REST cron e il pulsante di amministrazione "Avvia ora" — chiamano lo stesso esecutore (runner) condiviso, pertanto il comportamento e il meccanismo di blocco sono identici indipendentemente dal trigger.

Cron di WordPress vs. cron del server

La scheda Importazione e limiti espone due modalità di attivazione; entrambe sono supportate, ma presentano profili di affidabilità molto diversi.

Cron di WordPress (predefinito)

• Guidato dal traffico dei visitatori. Ogni richiesta a una pagina WordPress può avviare wp-cron.php in background.
• Funziona su qualsiasi host senza necessità di accesso al server.
• Diventa inaffidabile sui siti a basso traffico: senza visitatori non ci sono esecuzioni cron.
• Il plugin installa comunque tutti i suoi hook; le esecuzioni saltate si accumulano semplicemente fino alla visita successiva.

Cron del server (consigliato per la produzione)

• Guidato dal sistema operativo o dallo scheduler del pannello di controllo dell'hosting.
• Indipendente dal traffico del sito web, prevedibile e richiesto dai controlli di Salute del plugin per uno stato di produzione "completamente pronto".
• Configurazione consigliata: 1. Impostare define( 'DISABLE_WP_CRON', true ); in wp-config.php in modo da disattivare il cron guidato dalle visite. 2. Aggiungere una voce cron nel server che chiami l'endpoint REST del plugin con il token segreto. 3. Aggiungere una seconda voce che esegua direttamente wp-cron.php, in modo che i job ricorrenti diversi dall'importazione (coda immagini, pulizia dati analitici, prezzi, ecc.) continuino a essere eseguiti.

Passando a Cron del server nella scheda Importazione e limiti, i campi di pianificazione di WP-Cron vengono nascosti e vengono mostrati l'URL del trigger REST, il token segreto e i comandi di esempio pronti da copiare.

Job ricorrenti registrati dal plugin

I seguenti hook WP-Cron sono pianificati dal plugin (alcuni solo quando la relativa funzionalità è configurata). La scheda Stato e salute elenca il loro prossimo orario di esecuzione pianificato in modo che possano essere ispezionati in qualsiasi momento.

L'attivazione registra i job ricorrenti che dovrebbero sempre esistere (importazioni, pulizia dati analitici, prezzi, coda immagini, coda AI se applicabile). La disattivazione rimuove le voci WP-Cron del plugin tramite wp_clear_scheduled_hook() per ciascuno degli hook sopra indicati.

Importazioni ricorrenti

L'esecutore dell'importazione è condiviso da tutti e tre i percorsi di attivazione e si comporta come segue:

• Blocco (Locking). Prima di eseguire qualsiasi lavoro, l'esecutore imposta un transient (as24ci_cron_import_running) con un TTL di circa 40 minuti. Le esecuzioni successive che arrivano mentre il blocco è attivo terminano in modo pulito e segnalano che un'importazione è già in corso. Ciò impedisce a WP-Cron e a un cron del server di entrare in conflitto tra loro.
• Elaborazione per venditore. L'esecutore scorre ogni Seller ID configurato e chiama l'importatore per ciascuno di essi a turno.
• Veicoli per esecuzione. La scheda Importazione e limiti espone un limite di "Veicoli per esecuzione" (0 = nessun limite). Ridurre questo valore è la leva principale per la stabilità su hosting condivisi e inventari molto grandi; i valori consigliati sono 50–80 per cataloghi di grandi dimensioni.
• Persistenza dello stato. Dopo ogni esecuzione, le opzioni vengono aggiornate con il timestamp dell'ultima esecuzione, la sorgente del trigger (wp-cron, rest, manuale) e i conteggi per venditore. Il widget della bacheca e la scheda Stato e salute leggono queste opzioni per mostrare le informazioni sull'ultima esecuzione.
• Sincronizzazione completa opzionale. Quando l'opzione Sincronizzazione completa è abilitata, l'esecutore può contrassegnare come eliminati i veicoli mancanti dall'ultima risposta API; questa operazione è permanente, pertanto è richiesta una strategia di backup testata (vedere Requisiti di hosting).

La procedura guidata Batch-Wizard nell'interfaccia di amministrazione utilizza lo stesso importatore ma elabora un veicolo per passaggio da un elenco in coda (transient as24ci_batch_queue), il che è utile per importazioni iniziali molto grandi su host con risorse limitate.

Coda immagini e worker asincroni

Quando l'opzione Abilita coda immagini è attiva (consigliata per importazioni con molte immagini):

• Durante l'importazione, solo la prima immagine di ciascun veicolo viene scaricata in modo sincrono, in modo che la pagina risponda rapidamente e l'esecuzione del cron si completi ampiamente entro i limiti del tempo di esecuzione di PHP.
• Gli URL delle immagini rimanenti vengono aggiunti alla coda delle immagini (un'opzione di WordPress) e elaborati in lotti dall'hook as24ci_image_queue_process ogni 5 minuti.
• Il worker utilizza il proprio blocco transient (as24ci_image_queue_running, TTL di 10 minuti) e elabora un numero fisso di immagini per lotto.
• Un limite di sicurezza (la costante del limite di dimensione della coda in Scheduler) limita la crescita della coda prima che il plugin registri un avviso e rimuova forzatamente i duplicati.

La coda di generazione AI segue un modello simile: le chiamate AI durante l'importazione vengono differite a una coda e elaborate da un worker asincrono in modo che le esecuzioni di importazione non siano bloccate dall'endpoint gestito di Gemini.

Routine di pulizia e conservazione

• Conservazione dei dati analitici. Analytics::cleanup_old_data() (hook as24ci_daily_cleanup) elimina le righe di dati analitici più vecchie del valore impostato in Giorni di conservazione dei dati analitici. Il valore predefinito è 180 giorni; il minimo imposto nel codice è 7 giorni.
• Rotazione dei log. I log del plugin in wp-content/uploads/as24ci-logs/ vengono ruotati quando un singolo file raggiunge i 10 MB, e i file ruotati vengono eliminati dopo 7 giorni. Questo processo è indipendente da WP-Cron e viene eseguito a ogni scrittura di log.
• Cache dei token. I token di accesso OAuth vengono memorizzati nella cache in un transient fino a poco prima della loro scadenza dichiarata in expires_in. È disponibile uno strumento "Svuota cache token" per scopi diagnostici.
• Eliminazione dei veicoli. Quando il plugin rimuove un veicolo (Sincronizzazione completa o eliminazione manuale), pulisce i relativi allegati multimediali e i metadati attraverso un percorso di eliminazione centralizzato.

Endpoint REST cron

L'endpoint di attivazione protetto da token è registrato da Cron_Endpoint:

• Rotta: GET /wp-json/as24ci/v1/cron-import
• Autenticazione: un segreto casuale di 32 caratteri memorizzato nell'opzione as24ci_cron_token. L'endpoint accetta il token in due modi:
• Preferito: intestazione HTTP Authorization: Bearer <token> (mantiene il token fuori dai log di accesso).
• Alternativo: parametro di query ?token=<token>.
• Codici di risposta: 200 in caso di successo, 429 quando il blocco è già attivo (un'importazione è già in corso), 403 per token mancanti o non validi, 500 per eccezioni non gestite.
• Effetto collaterale: ogni chiamata andata a buon fine aggiorna l'opzione as24ci_last_external_cron_run, che la scheda Stato e salute utilizza per confermare che il cron esterno è attivo.
• Un heartbeat separato e non autenticato viene registrato ogni volta che un URL di WordPress viene colpito con ?as24ci_cron=1, il che è utile per pinger esterni economici che devono solo confermare la raggiungibilità.

La scheda Importazione e limiti genera comandi di esempio pronti da copiare come:

*/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 prima voce attiva le importazioni; la seconda mantiene in esecuzione gli hook WP-Cron diversi dall'importazione (coda immagini, pulizia dati analitici, prezzi, ecc.) quando DISABLE_WP_CRON è impostato su true.

Monitoraggio operativo

Il plugin espone i segnali necessari agli operatori per il monitoraggio senza bisogno di strumenti aggiuntivi:

• Scheda Stato e salute / Salute. Elenca ogni hook cron del plugin, la sua prossima esecuzione pianificata e se la pianificazione è attualmente gestita da WP-Cron o da un cron server esterno. Include una scheda che segnala DISABLE_WP_CRON come consigliato in modalità cron del server.
• Widget della bacheca. Mostra l'esecuzione dell'importazione più recente, la prossima importazione pianificata (quando WP-Cron è in uso), la profondità della coda delle immagini e la prossima esecuzione della coda.
• Log del plugin. wp-content/uploads/as24ci-logs/ registra ogni esecuzione del cron, l'acquisizione/rilascio dei blocchi, l'attività della coda delle immagini e qualsiasi errore HTTP. I log ruotano a 10 MB con una conservazione di 7 giorni.
• Opzioni dell'ultima esecuzione. as24ci_last_external_cron_run e le corrispondenti opzioni interne possono essere verificate direttamente tramite WP-CLI per l'invio di avvisi tramite script.

Una configurazione di produzione semplice prevede:

• Controllo dell'uptime sull'URL dell'archivio pubblico (disponibilità del front-end).
• Controllo dell'uptime su /wp-json/as24ci/v1/cron-import?token=… che restituisce uno stato 2xx/429 (percorso cron raggiungibile e autenticato).
• Avviso sullo spazio su disco per il volume wp-content/uploads/ (crescita delle immagini e log).
• Invio opzionale dei log o revisione periodica della directory dei log del plugin.

---

Risoluzione dei problemi

• Le importazioni non si avviano mai automaticamente. Verificare la modalità cron nella scheda Import & Limits. Se è selezionato WP-Cron, i siti a basso traffico potrebbero non attivare affatto il cron — passare al cron del server. Se è selezionato il cron del server, verificare che il comando curl/wget raggiunga effettivamente l'endpoint REST (è previsto HTTP 200 o 429).
• Risposte "An import is already running" (HTTP 429). Il transient di blocco è ancora attivo da un'esecuzione precedente. Attendere il completamento dell'esecuzione o cancellare il transient as24ci_cron_import_running se un processo PHP precedente si è interrotto bruscamente senza rilasciare il blocco. Ridurre il valore di Vehicles per Run per mantenere le singole esecuzioni ampiamente al di sotto del TTL di blocco.
• La coda delle immagini cresce senza ridursi. Verificare che wp-cron.php venga eseguito (in modalità cron del server ciò richiede la seconda voce cron mostrata sopra), controllare la directory dei log per eventuali errori del queue-worker e verificare la connessione HTTPS in uscita verso gli host delle immagini (vedere Requisiti di API, rete e SSL).
• I dati di Analytics o dei prezzi non si aggiornano. Questi vengono eseguiti quotidianamente tramite WP-Cron; se DISABLE_WP_CRON è impostato su true e non è presente una seconda voce cron che chiama wp-cron.php, i job giornalieri non si attiveranno mai.
• La scheda System & Help mostra che il token cron non è configurato. Aprire la scheda Import & Limits, passare alla modalità cron del server e lasciare che il plugin generi automaticamente un token oppure incollarne uno proprio e salvare.
• Token trapelato o ruotato. Fare clic su Regenerate Token nella scheda Import & Limits. Aggiornare immediatamente ogni pianificatore esterno, poiché il token precedente smette di funzionare non appena viene salvato quello nuovo.
• Le esecuzioni cron su staging influiscono sui dati di produzione. Utilizzare un token cron diverso per ogni ambiente e considerare l'uso di un client AutoScout24 differente quando possibile (vedere Requisiti di hosting).

Documenti correlati

• Requisiti tecnici di sistema
• Requisiti di WordPress
• Requisiti di hosting
• Requisiti di PHP e database
• Requisiti di API, rete e SSL
• Lista di controllo pre-installazione