Cron y procesamiento en segundo plano

Propósito

ADP Car Market Hub depende de tareas programadas en segundo plano para casi todo lo que no sea una acción directa del usuario: importa vehículos desde AutoScout24, procesa imágenes de forma asíncrona, limpia datos de analítica, actualiza el análisis de precios y ejecuta análisis diarios de calidad de datos. Este documento explica los mecanismos de cron que utiliza el plugin, las diferencias entre el programador integrado de WordPress y un cron de servidor real, las tareas recurrentes que programa el plugin y las señales operativas que se deben monitorizar.

Cuándo usar este documento

Utilice este documento cuando necesite:

• Decidir entre WP-Cron y un cron de servidor externo para un nuevo sitio de concesionario.
• Configurar el modo de cron, la frecuencia y el token secreto en la pestaña Referencia de importación y límites.
• Conectar un programador externo (cron de Linux, interfaz de cron del hosting o un pinger remoto) al endpoint REST de cron del plugin.
• Investigar por qué las importaciones no se ejecutan según lo programado o por qué se retrasa el procesamiento de imágenes.
• Auditar qué tareas recurrentes registra el plugin y cuánto tiempo se conservan sus datos.

Descripción general

El modelo de procesamiento en segundo plano del plugin consta de tres capas:

1. Una capa de activación (trigger) que decide cuándo debe comenzar el trabajo. Puede ser el pseudo-cron de WordPress (impulsado por las visitas de los usuarios a wp-cron.php) o un cron de servidor externo que llame directamente a wp-cron.php o al endpoint REST protegido por token del plugin en /wp-json/as24ci/v1/cron-import.
2. Una capa de programación (scheduler) que posee las tareas recurrentes. El plugin registra intervalos personalizados (cada 5 minutos, cada 6 horas, además de un intervalo configurable de "cada N minutos" con un mínimo de 15 minutos) y un pequeño conjunto de hooks de WP-Cron para las importaciones, la cola de imágenes, la cola de generación de IA, la limpieza de analítica, el análisis de precios y el escaneo diario de taxonomías.
3. Una capa de ejecución (worker) que realiza el trabajo real. Cada hook de WP-Cron está vinculado a un método de clase (importador, cola de imágenes, limpieza de analítica, etc.) que utiliza bloqueos basados en transients para evitar ejecuciones duplicadas y escribe opciones de estado/latido (heartbeat) que luego leen la pestaña de salud en Soporte y ayuda y el widget del escritorio.

Las tres rutas de importación (el hook programado de WP-Cron, el endpoint REST de cron y el botón de administración "Ejecutar ahora") llaman al mismo ejecutor compartido, por lo que el comportamiento y el bloqueo son idénticos independientemente del activador.

WP-Cron frente a cron de servidor

La pestaña Referencia de importación y límites expone dos modos de activación; ambos son compatibles, pero tienen perfiles de fiabilidad muy diferentes.

WP-Cron (por defecto)

• Impulsado por el tráfico de visitas. Cada solicitud a una página de WordPress puede generar wp-cron.php en segundo plano.
• Funciona en cualquier hosting sin necesidad de acceso al servidor.
• Se vuelve poco fiable en sitios con poco tráfico: si no hay visitas, no hay ejecuciones de cron.
• El plugin sigue instalando todos sus hooks; las ejecuciones omitidas simplemente se acumulan hasta la siguiente visita.

Cron de servidor (recomendado para producción)

• Impulsado por el sistema operativo o el programador del panel de control del hosting.
• Independiente del tráfico del sitio web, predecible y requerido por las comprobaciones de salud del plugin para obtener un estado de producción "totalmente listo".
• Configuración recomendada: 1. Definir define( 'DISABLE_WP_CRON', true ); en wp-config.php para que se desactive el cron impulsado por visitas. 2. Añadir una entrada de cron de servidor que llame al endpoint REST del plugin con el token secreto. 3. Añadir una segunda entrada que ejecute el propio wp-cron.php, de modo que las tareas recurrentes que no sean de importación (cola de imágenes, limpieza de analítica, precios, etc.) se sigan ejecutando.

Al cambiar a Cron de servidor en la pestaña Referencia de importación y límites, se ocultan los campos de programación de WP-Cron y se muestran la URL de activación REST, el token secreto y ejemplos de comandos listos para copiar.

Tareas recurrentes registradas por el plugin

El plugin programa los siguientes hooks de WP-Cron (algunos solo cuando la función relacionada está configurada). La pestaña Soporte y ayuda muestra su próxima hora de ejecución programada para que puedan ser inspeccionados en cualquier momento.

La activación registra las tareas recurrentes que siempre deben existir (importaciones, limpieza de analítica, precios, cola de imágenes, cola de IA cuando corresponda). La desactivación elimina las entradas de WP-Cron del plugin mediante wp_clear_scheduled_hook() para cada uno de los hooks anteriores.

Importaciones recurrentes

El ejecutor de importación es compartido por las tres rutas de activación y se comporta de la siguiente manera:

• Bloqueo (Locking). Antes de realizar cualquier trabajo, el ejecutor establece un transient (as24ci_cron_import_running) con un TTL de aproximadamente 40 minutos. Las ejecuciones posteriores que lleguen mientras el bloqueo esté activo finalizan de forma limpia e informan de que ya se está ejecutando una importación. Esto evita que WP-Cron y un cron de servidor compitan entre sí.
• Procesamiento por vendedor. El ejecutor recorre cada Seller ID configurado y llama al importador para cada uno de ellos de forma consecutiva.
• Vehículos por ejecución. La pestaña Referencia de importación y límites expone un límite de "Vehículos por ejecución" (0 = sin límite). Reducir este valor es la principal palanca para la estabilidad en hostings compartidos e inventarios muy grandes; los valores recomendados son de 50 a 80 para catálogos grandes.
• Persistencia del estado. Después de cada ejecución, se actualizan las opciones con la marca de tiempo de la última ejecución, la fuente de activación (wp-cron, rest, manual) y los recuentos por vendedor. El widget del escritorio y la pestaña Soporte y ayuda leen estas opciones para mostrar la información de la última ejecución.
• Sincronización completa opcional. Cuando la opción de Sincronización completa está activada, el ejecutor puede marcar como eliminados los vehículos que falten en la última respuesta de la API; esto es permanente, por lo que se requiere una estrategia de copia de seguridad probada (consulte la Guía de instalación).

El Batch-Wizard en la interfaz de administración utiliza el mismo importador pero procesa un vehículo por paso a partir de una lista en cola (transient as24ci_batch_queue), lo cual es útil para importaciones iniciales muy grandes en servidores con recursos limitados.

Cola de imágenes y procesadores asíncronos

Cuando la opción Activar cola de imágenes está activada (recomendado para importaciones con muchas imágenes):

• Durante la importación, solo se descarga de forma síncrona la primera imagen de cada vehículo, por lo que la página responde rápidamente y la ejecución del cron finaliza dentro de los límites de tiempo de ejecución de PHP.
• Las URL de las imágenes restantes se añaden a la cola de imágenes (una opción de WordPress) y se procesan en lotes mediante el hook as24ci_image_queue_process cada 5 minutos.
• El procesador utiliza su propio bloqueo por transient (as24ci_image_queue_running, TTL de 10 minutos) y procesa un número fijo de imágenes por lote.
• Un límite de seguridad (la constante de límite de tamaño de la cola en Scheduler) limita el crecimiento de la cola antes de que el plugin registre una advertencia y elimine por la fuerza las entradas duplicadas.

La cola de generación de IA sigue un patrón similar: las llamadas de IA durante la importación se aplazan a una cola y se procesan mediante un ejecutor asíncrono para que las ejecuciones de importación no se vean bloqueadas por el endpoint gestionado de Gemini.

Rutinas de limpieza y retención

• Retención de analítica. Analytics::cleanup_old_data() (hook as24ci_daily_cleanup) elimina las filas de analítica más antiguas que el valor establecido en el ajuste Días de retención de analítica. El valor predeterminado es 180 días; el mínimo aplicado en el código es de 7 días.
• Rotación de logs. Los logs del plugin en wp-content/uploads/as24ci-logs/ se rotan cuando un solo archivo alcanza los 10 MB, y los archivos rotados se eliminan después de 7 días. Esto es independiente de WP-Cron y se ejecuta con cada escritura de log.
• Caché de tokens. Los tokens de acceso OAuth se almacenan en caché en un transient hasta poco antes de su expires_in anunciado. Existe una herramienta para "Borrar la caché de tokens" para tareas de diagnóstico.
• Eliminación de vehículos. Cuando el plugin elimina un vehículo (por Sincronización completa o eliminación manual), limpia los archivos multimedia adjuntos y los metadatos relacionados a través de una ruta de eliminación centralizada.

Endpoint REST de cron

El endpoint de activación protegido por token se registra mediante Cron_Endpoint:

• Ruta: GET /wp-json/as24ci/v1/cron-import
• Autenticación: un secreto aleatorio de 32 caracteres almacenado en la opción as24ci_cron_token. El endpoint acepta el token de dos maneras:
• Preferida: cabecera HTTP Authorization: Bearer <token> (mantiene el token fuera de los logs de acceso).
• Alternativa: parámetro de consulta ?token=<token>.
• Códigos de respuesta: 200 en caso de éxito, 429 cuando el bloqueo ya está activo (ya se está ejecutando una importación), 403 para tokens faltantes o no válidos, 500 para excepciones no controladas.
• Efecto secundario: cada llamada exitosa actualiza la opción as24ci_last_external_cron_run, que la pestaña Soporte y ayuda utiliza para confirmar que el cron externo está activo.
• Se registra un latido (heartbeat) independiente y sin autenticación cada vez que se accede a cualquier URL de WordPress con ?as24ci_cron=1, lo cual es útil para pingers externos sencillos que solo necesitan confirmar la accesibilidad.

La pestaña Referencia de importación y límites genera ejemplos de comandos listos para copiar como:

*/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 primera entrada activa las importaciones; la segunda mantiene en funcionamiento los hooks de WP-Cron que no son de importación (cola de imágenes, limpieza de analítica, precios, etc.) cuando DISABLE_WP_CRON es true.

Monitorización operativa

El plugin expone las señales que los operadores necesitan monitorizar sin necesidad de herramientas adicionales:

• Pestaña de salud en Soporte y ayuda. Muestra cada hook de cron del plugin, su próxima ejecución programada y si la programación está a cargo de WP-Cron o de un cron de servidor externo. Incluye una tarjeta que señala DISABLE_WP_CRON como recomendado en el modo de cron de servidor.
• Widget del escritorio. Muestra la importación más reciente, la siguiente importación programada (cuando se utiliza WP-Cron), el tamaño de la cola de imágenes y la siguiente ejecución de la cola.
• Logs del plugin. wp-content/uploads/as24ci-logs/ registra cada ejecución de cron, la adquisición/liberación de bloqueos, la actividad de la cola de imágenes y cualquier error HTTP. Los logs se rotan a los 10 MB con una retención de 7 días.
• Opciones de última ejecución. as24ci_last_external_cron_run y las opciones internas correspondientes se pueden consultar directamente a través de WP-CLI para configurar alertas mediante scripts.

Una configuración de producción sencilla consiste en:

• Comprobación de disponibilidad (uptime) en la URL pública del archivo (disponibilidad del frontend).
• Comprobación de disponibilidad en /wp-json/as24ci/v1/cron-import?token=… devolviendo un estado 2xx/429 (ruta de cron accesible y autenticando correctamente).
• Alerta de espacio en disco en el volumen wp-content/uploads/ (crecimiento de imágenes y logs).
• Envío de logs opcional o revisión periódica del directorio de logs del plugin.

---

Resolución de problemas

• Las importaciones nunca se ejecutan automáticamente. Confirme el modo de cron en la pestaña Importación y límites. Si se selecciona WP-Cron, es posible que los sitios con poco tráfico no activen el cron en absoluto; cambie a cron del servidor. Si se selecciona el cron del servidor, verifique que el comando curl/wget realmente llegue al endpoint REST (se espera HTTP 200 o 429).
• Respuestas "Ya se está ejecutando una importación" (HTTP 429). El transient de bloqueo todavía se mantiene de una ejecución anterior. Espere a que finalice la ejecución o borre el transient as24ci_cron_import_running si un proceso PHP anterior falló sin liberar el bloqueo. Reduzca Vehículos por ejecución para mantener las ejecuciones individuales cómodamente por debajo del TTL de bloqueo.
• La cola de imágenes crece sin disminuir. Confirme que se está ejecutando wp-cron.php (en el modo de cron del servidor, esto requiere la segunda entrada de cron que se muestra arriba), verifique el directorio de logs para ver si hay errores del queue-worker y verifique el HTTPS saliente hacia los hosts de imágenes (consulte Requisitos de API, red y SSL).
• Los datos de análisis o precios no se actualizan. Estos se ejecutan a través de WP-Cron diariamente; si DISABLE_WP_CRON es true y no hay una segunda entrada de cron que llame a wp-cron.php, las tareas diarias nunca se activarán.
• La pestaña Sistema y ayuda muestra que el token de cron no está configurado. Abra la pestaña Importación y límites, cambie al modo de cron del servidor y deje que el plugin genere automáticamente un token o pegue el suyo propio y guarde.
• Token filtrado o rotado. Haga clic en Regenerar token en la pestaña Importación y límites. Actualice cada programador externo de inmediato, ya que el token anterior dejará de funcionar tan pronto como se guarde el nuevo.
• Las ejecuciones de cron en staging afectan a los datos de producción. Utilice un token de cron diferente por entorno y considere un cliente AutoScout24 diferente cuando sea posible (consulte Requisitos de hosting).

Documentos relacionados

• Requisitos técnicos del sistema
• Requisitos de WordPress
• Requisitos de hosting
• Requisitos de PHP y base de datos
• Requisitos de API, red y SSL
• Lista de comprobación previa a la instalación