Eventos de Cron y Programador

--- This document describes the WP-Cron events that the ADP Car Market Hub plugin schedules, the custom intervals it registers and the locking strategy that prevents overlapping runs.

Cuándo usar este documento

Lea este documento si necesita:

• Configurar importaciones automáticas en la pestaña de administración Automatización.
• Configurar un cron de sistema externo para activar importaciones de manera fiable.
• Diagnosticar ejecuciones de importación omitidas, superpuestas o bloqueadas.
• Planificar despliegues en producción donde WP-Cron esté desactivado en favor de un cron job real.

Para la lógica de importación por vehículo, consulte Import Engine. Para la mecánica de la cola de imágenes, consulte Image Importer And Queue.

Descripción general

El plugin utiliza dos rutas de activación complementarias:

• WP-Cron — El pseudo-cron integrado de WordPress, activado por las visitas a las páginas del frontend. El plugin registra aquí los hooks de cron y los intervalos personalizados.
• Endpoint de cron REST — GET /wp-json/as24ci/v1/cron-import, autenticado mediante un token, permite que un cron de sistema real active las importaciones incluso en sitios con poco tráfico.

Ambas rutas llaman al mismo ejecutor compartido, AS24CI\Scheduler::run_import(), que adquiere un bloqueo temporal (transient lock), delega en el importador, realiza opcionalmente eliminaciones de sincronización completa, programa el worker de la cola de imágenes y registra la ejecución.

Hooks de cron registrados por el plugin

AS24CI\Scheduler se construye durante el arranque de AS24CI\Plugin y registra los siguientes hooks de WordPress:

Además, el archivo principal del plugin (adp-car-market-hub.php) registra un filtro cron_schedules independiente que añade el intervalo as24ci_every_5_minutes (300 segundos) de forma incondicional, lo cual es útil para la cola de IA y cualquier integración personalizada que necesite una cadencia inferior a una hora.

Otros subsistemas del plugin programan sus propios eventos de forma independiente:

• as24ci_daily_cleanup — limpieza diaria de retención de analíticas, propiedad de AS24CI\Analytics. Programado al activar y eliminado al desactivar.
• Cron del motor de precios — diario, propiedad de AS24CI\Pricing_Engine (etiqueta de hook as24ci_pricing_analysis_cron). Programado cuando la característica está habilitada y limpiado al desactivar.
• Data Quality Scanner — se ejecuta bajo su propia programación (etiqueta de hook as24ci_automated_taxonomy_scan, propiedad de AS24CI\Data_Quality_Scanner) controlada por as24ci_dq_scan_frequency y as24ci_dq_scan_time.
• Worker de la cola de IA — etiqueta de hook as24ci_process_ai_queue, propiedad de AS24CI\Ai_Assistant. Vinculado incondicionalmente; programado en el intervalo as24ci_every_5_minutes solo cuando el AI Assistant está habilitado, y limpiado al desactivar.
• Revalidación de licencia — etiqueta de hook as24ci_license_refresh, propiedad de AS24CI\License_Manager. Programado daily al activar (y mediante una autoreparación admin_init) y limpiado al desactivar. Este es el refresco diario autoritativo del estado de la licencia / derechos de características de ADP Car Market Hub.

Intervalos personalizados

Los intervalos estándar de WordPress (hourly, twicedaily, daily) también son aceptados por la programación de importación.

Programación del evento de importación principal

El evento de importación principal es as24ci_scheduled_import, programado por AS24CI\Scheduler::reschedule(). El método:

1. Llama a unschedule() para limpiar todas las ocurrencias existentes del hook.
2. Retorna inmediatamente si as24ci_auto_import_enabled es 0 (no se programa ningún evento).
3. Lee as24ci_cron_schedule (por defecto hourly). Valores permitidos: hourly, as24ci_every_6_hours, twicedaily, daily, as24ci_custom.
4. Calcula la marca de tiempo de la siguiente ejecución a través de calculate_next_run(): - Para daily y twicedaily, utiliza la hora de inicio configurada as24ci_cron_start_time (HH:MM, 24 h) interpretada en la zona horaria del sitio de WordPress. Si la hora de inicio de hoy ya ha pasado, la siguiente ejecución se traslada a mañana. - Para todas las demás programaciones, la siguiente ejecución es ahora.
5. Llama a wp_schedule_event( $next_run, $schedule, 'as24ci_scheduled_import' ).

El programador nunca programa más de una ocurrencia del hook; unschedule() limpia cada entrada pendiente antes de que reschedule() añada una nueva.

El ejecutor compartido

AS24CI\Scheduler::run_import( string $source = 'manual' ) es el único punto de entrada utilizado por:

• El hook de cron as24ci_scheduled_import (origen: wp-cron).
• El endpoint de cron REST (origen: rest).
• El botón de administración "Ejecutar ahora" (origen: manual).

El ejecutor:

1. Adquiere el bloqueo temporal as24ci_cron_import_running (Scheduler::LOCK_TRANSIENT) con un TTL de Scheduler::LOCK_TTL. Un bloqueo obsoleto (más antiguo que el TTL) se limpia automáticamente.
2. Para los orígenes de cron y REST, eleva el límite de tiempo de ejecución de PHP a 300 segundos a través de set_time_limit(300).
3. Lee as24ci_cron_max_vehicles (por defecto 50) y as24ci_cron_image_queue (por defecto 1).
4. Llama a Importer::set_cron_image_queue( true|false ) en consecuencia.
5. Itera sobre los IDs de vendedor configurados y llama a Importer::import_all_for_seller() para cada uno, acumulando los recuentos y el conjunto completo de listing_ids vistos en esta ejecución. Se detiene tan pronto como se alcanza el límite de vehículos.
6. Si la sincronización completa está habilitada (as24ci_full_sync = 1) y la ejecución no fue abortada por el límite, llama a Importer::full_sync_after_import( $remote_ids ). La llamada de sincronización completa no realiza ninguna acción si el conjunto de IDs remotos está vacío (medida de seguridad).
7. Programa el worker de la cola de imágenes (maybe_schedule_image_queue_worker).
8. Libera el bloqueo y restablece el modo cron-image-queue en el bloque finally para que las llamadas manuales posteriores no se vean afectadas.
9. Registra as24ci_last_run_time y as24ci_last_run_status (matriz de recuentos { inserted, updated, skipped, errors, sync_deleted, sync_kept, api_active }).
10. Invalida el transient de "Estado de la API" del dashboard (Admin_Page::TRANSIENT_API_STATUS) para que las tarjetas del dashboard se actualicen en la siguiente carga de página.

El ejecutor devuelve array{ success: bool, message: string, counts: array<string,int> }.

Endpoint de cron REST

AS24CI\Cron_Endpoint::register_routes() registra una única ruta GET:

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

La autenticación se realiza dentro del controlador. El token se lee desde as24ci_cron_token. El endpoint:

• Rechaza solicitudes cuando no hay ningún token configurado (403, con un mensaje que solicita al administrador generar uno en la interfaz de administración).
• Acepta el token a través de la cabecera Authorization: Bearer <token> (preferido — mantiene el token fuera de los registros de acceso del servidor) o el parámetro de consulta ?token=<token>.
• Llama a Scheduler::run_import( 'rest' ) en caso de éxito.

El plugin también realiza un seguimiento de los pings de "el cron externo está activo" de forma independiente al endpoint REST:

• Visitar cualquier URL con ?as24ci_cron=1 actualiza as24ci_last_external_cron_run a la marca de tiempo Unix actual a través de Cron_Endpoint::record_external_ping() (vinculado en init).

Bloqueos y concurrencia

El plugin utiliza dos transients de corta duración para evitar la superposición de tareas:

El siguiente ejecutor limpia automáticamente un bloqueo obsoleto (más antiguo que el TTL), de modo que un proceso que haya finalizado inesperadamente a mitad de la ejecución no bloquee futuras importaciones indefinidamente. La recuperación manual (eliminando el transient a través de WP-CLI o una herramienta de base de datos) solo es necesaria si desea forzar una nueva ejecución antes de lo que permite el TTL.

Referencia de configuración

Las constantes de Scheduler::LOCK_TTL y del worker de la cola de imágenes están definidas en el código; verifique los valores actuales en el código fuente si necesita números exactos.

Instrucciones paso a paso

Habilitar importaciones automatizadas a través de WP-Cron

1. Abra la pestaña de administración Automatización.
2. Establezca el Modo de cron en wp-cron.
3. Establezca Auto import en habilitado (as24ci_auto_import_enabled = 1).
4. Elija una programación. Para daily / twicedaily, establezca la hora de inicio. Para as24ci_custom, establezca el intervalo (mínimo 15 minutos).
5. Guarde los cambios. La pestaña Import & Limits llama a Scheduler::reschedule() para registrar la siguiente ejecución.
6. (Opcional) Reduzca el valor de Vehículos por ejecución de cron para catálogos muy grandes para que las ejecuciones individuales se mantengan dentro del límite de tiempo de PHP del servidor.

Activar importaciones a través de un cron de sistema

1. Cambie el Modo de cron a server-cron para que la interfaz de administración muestre las sugerencias del cron del servidor.
2. (Recomendado) Desactive WP-Cron en wp-config.php:

• Establezca define( 'DISABLE_WP_CRON', true );. WordPress solo ejecutará entonces los eventos programados cuando algo los active explícitamente.

1. Genere un token en la pantalla Import & Limits. El plugin lo almacena en as24ci_cron_token.
2. Configure el cron de su sistema para llamar al endpoint REST, por ejemplo cada hora:

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

El parámetro de consulta opcional ?as24ci_cron=1 también actualiza la marca de tiempo de "el cron externo está activo" que se muestra en el estado de administración.

1. Verifique la respuesta. Una ejecución exitosa devuelve un payload JSON con los recuentos; un 403 indica un token faltante o incorrecto.

---

---

Notas operativas

• WP-Cron se activa mediante el tráfico del sitio. En sitios con poco tráfico, los eventos programados pueden ejecutarse tarde o no ejecutarse en absoluto. Utilice un cron del sistema real en producción.
• La llamada set_time_limit(300) puede ser ignorada por los servidores que imponen límites de tiempo de PHP. El plugin registra una advertencia en ese caso.
• La opción as24ci_full_sync es de exclusión voluntaria (opt-in) por seguridad. Con ella activada, los vehículos cuyos anuncios desaparecen de la API se eliminan de forma permanente (incluidos sus archivos adjuntos importados). Asegúrese de que los Seller IDs configurados cubren todo el catálogo que desea mantener en línea.
• Al desactivar el plugin se borran todos sus eventos programados (as24ci_scheduled_import, la limpieza de analíticas, la programación de la cola de IA, la programación del motor de precios y el evento as24ci_license_refresh, además del gancho heredado as24ci_competitor_watcher_cron) y se elimina el transitorio as24ci_cron_import_running.
• El plugin nunca codifica de forma rígida URLs o tokens de cron externos. El ejemplo anterior utiliza un marcador de posición; sustitúyalo por su propio host y un token generado antes de realizar el despliegue.

Resolución de problemas

• Las importaciones no se ejecutan automáticamente. Verifique as24ci_auto_import_enabled = 1, que se haya seleccionado una programación y que wp_next_scheduled( 'as24ci_scheduled_import' ) devuelva una marca de tiempo futura. Si el valor es false, guarde la pestaña Automatización de nuevo para llamar a reschedule().
• Se registra Import already in progress. El bloqueo de ejecución única está retenido por otro ejecutor. Espere hasta que expire el TTL del bloqueo (el siguiente ejecutor borrará automáticamente un bloqueo obsoleto) o elimine el transitorio as24ci_cron_import_running a través de WP-CLI para un reintento inmediato.
• Se devuelve No seller IDs configured. Establezca as24ci_seller_ids en los ajustes de la API.
• Las programaciones diarias se activan a la hora incorrecta. El plugin utiliza la zona horaria del sitio de WordPress (wp_timezone()). Verifique la zona horaria en Ajustes → General, no la hora local del servidor.
• El endpoint REST devuelve 403. O bien falta el token (as24ci_cron_token está vacío; el mensaje de respuesta lo confirma) o el token en la solicitud no coincide. Genere un nuevo token en la interfaz de administración.
• El cron externo parece inactivo en el estado de administración. Compruebe que la URL a la que llama incluye ?as24ci_cron=1 (o que el endpoint de cron REST tiene éxito), y que la solicitud llega al sitio WordPress (sin cortafuegos ni barreras de autenticación). El plugin actualiza as24ci_last_external_cron_run en cada ping exitoso.
• La cola de imágenes no se vacía después de una importación por cron. Este es un proceso de trabajo independiente. Consulte la sección de resolución de problemas en Importador de imágenes y cola.

Documentos relacionados

• Motor de importación
• Importador de imágenes y cola
• Inicio y ciclo de vida del plugin
• Almacenamiento de opciones y ajustes
• Descripción general de la sección