Importador de imágenes y cola

Este documento describe cómo el plugin ADP Car Market Hub descarga, desduplica y asocia las imágenes de los vehículos, y cómo la cola de imágenes asíncrona traslada el trabajo de procesamiento de imágenes de larga duración fuera de la ruta de importación síncrona.

Cuándo usar este documento

Lea este documento si necesita:

• Entender qué imágenes terminan en la Biblioteca de medios de WordPress y cuáles se reutilizan o se omiten.
• Diagnosticar imágenes de vehículos faltantes, desactualizadas o duplicadas.
• Planificar la conversión a WebP o la capacidad de almacenamiento para un catálogo grande.
• Ajustar el procesamiento de imágenes en modo cron para hostings lentos o restringidos.

Para conocer el flujo de importación general, consulte Import Engine. Para la programación del lado del cron, consulte Cron Events And Scheduler.

Descripción general

Dos clases comparten la responsabilidad del manejo de imágenes:

• AS24CI\Image_Importer — descarga una lista de URL de imágenes, opcionalmente las convierte a WebP, las asocia a una publicación de vehículo a través de media_handle_sideload() y registra la URL de origen en el postmeta del adjunto para su desduplicación.
• AS24CI\Scheduler — posee la cola de imágenes asíncrona. El hook del worker as24ci_image_queue_process procesa los elementos pendientes en lotes con su propio bloqueo transitorio y presupuesto de tiempo.

El importador (Import Engine) decide si importar las imágenes de forma síncrona o posponer la mayoría de ellas a la cola, según el modo cron de la ejecución actual.

Fuente de verdad para las imágenes

Para cualquier adjunto importado, el marcador canónico de "¿de dónde vino esto?" es el postmeta _as24ci_source_url en la publicación del adjunto (attachment). El plugin utiliza este marcador para:

• Desduplicar descargas: si ya existe un adjunto con la misma URL de origen, el plugin lo reutiliza en lugar de descargarlo de nuevo.
• Reconstruir la lista _as24ci_image_ids del vehículo de manera autoritativa después de que el worker de la cola termine, consultando los adjuntos secundarios con esta clave meta.

Dos claves postmeta en la publicación del vehículo realizan el seguimiento de las imágenes importadas:

• _as24ci_image_ids — array de IDs de adjuntos de WordPress que pertenecen a la galería del importador.
• _as24ci_images_hash — hash MD5 de la lista de imágenes de origen. Puede contener el centinela 'pending_queue' mientras los elementos aún estén en la cola. La siguiente importación trata 'pending_queue' como una discrepancia para que la lista de imágenes siempre se vuelva a evaluar hasta que se haya importado por completo.

Los adjuntos de la galería añadidos manualmente se registran por separado en _as24ci_manual_image_ids y el plugin nunca los elimina.

Importación síncrona de imágenes

Image_Importer::import_images( int $post_id, array $images, string $listing_id ) realiza el trabajo síncrono:

1. Incluye de forma diferida (lazy load) los archivos de administración de medios de WordPress (wp-admin/includes/media.php, file.php, image.php).
2. Vuelve a aplicar de forma defensiva la capacidad as24ci_max_images.
3. Obtiene previamente las URL de origen conocidas de la publicación una sola vez a través de prefetch_known_urls_for_post() para evitar N consultas a la base de datos por imagen.
4. Para cada imagen (URL en cadena de texto o array con las claves url / src / href / original / imageUrl): - Reutiliza un adjunto existente si la URL de origen ya es conocida (primero en el mapa en memoria, luego mediante una búsqueda en el postmeta _as24ci_source_url). - De lo contrario, llama a download_url( $url, 30 ) (tiempo de espera de 30 segundos), opcionalmente la convierte a WebP y llama a media_handle_sideload() para crear el adjunto. - Escribe _as24ci_source_url en el nuevo adjunto y lo añade al mapa de desduplicación en memoria. - Registra los fallos (errores de descarga, errores de sideload) en el log y continúa con la siguiente imagen.
5. Fusiona los nuevos IDs de adjuntos en _as24ci_image_ids (preservando los elementos importados anteriormente) y establece la imagen destacada en el primer adjunto si la publicación aún no tiene una.

Los IDs existentes se fusionan en lugar de sobrescribirse para que las llamadas del worker de la cola acumulen adjuntos para la misma publicación a lo largo de varias ejecuciones.

Conversión a WebP

Cuando as24ci_convert_to_webp es 1, el importador intenta convertir cada imagen descargada a WebP antes de realizar el sideload:

• La calidad se lee de as24ci_webp_quality (por defecto 80 si no está establecido) y se limita al rango 1–100. El filtro as24ci_webp_quality puede anular este valor.
• Se intenta primero con imagewebp() de GD; se utiliza Imagick como alternativa.
• Si ninguna de las extensiones está disponible, se omite la conversión y se realiza el sideload de la imagen original. Se emite una línea en el log.
• Si la conversión produce un archivo vacío o falla, se limpia el archivo temporal y se utiliza la imagen original.

El archivo convertido hereda el nombre de archivo original con la extensión reemplazada por .webp.

Importación en modo cron (encolada)

Cuando el programador ejecuta una importación (cron o REST), establece Importer::set_cron_image_queue( true ) si as24ci_cron_image_queue es 1 (el valor por defecto). Para cada vehículo con más de una imagen, el importador:

1. Descarga solo la primera imagen inmediatamente a través de la ruta síncrona para que el vehículo tenga una imagen destacada.
2. Comprueba previamente si todas las imágenes restantes ya están asociadas (a través del mapa de desduplicación). En caso afirmativo, no se crea ninguna entrada en la cola y se escribe el _as24ci_images_hash final inmediatamente.
3. De lo contrario, llama a enqueue_remaining_images() para añadir elementos con el formato { post_id, listing_id, url, images_hash } a la opción as24ci_image_queue. El _as24ci_images_hash del vehículo se establece en el centinela 'pending_queue' para que las futuras importaciones sigan reevaluando hasta que se complete la cola.

La cola tiene un límite estricto de Scheduler::IMAGE_QUEUE_SIZE_LIMIT elementos. Las nuevas entradas se descartan cuando se alcanza el límite y se emite una línea en el log.

Worker de la cola

AS24CI\Scheduler::run_image_queue() está vinculado al hook de cron as24ci_image_queue_process y ejecuta las descargas diferidas reales:

1. Llama a set_time_limit(300) (sujeto a las restricciones del host).
2. Adquiere el bloqueo transitorio as24ci_image_queue_running con el TTL Scheduler::IMAGE_QUEUE_LOCK_TTL. Un bloqueo obsoleto (más antiguo que el TTL) se borra automáticamente.
3. Carga la cola desde la opción as24ci_image_queue.
4. Procesa los elementos en lotes de Scheduler::IMAGE_QUEUE_BATCH_SIZE mientras la cola no esté vacía y el presupuesto de tiempo (IMAGE_QUEUE_LOCK_TTL − 60s) no se haya agotado.
5. Para cada elemento, llama a Image_Importer::import_images() para la URL individual. Los errores se capturan y se registran en el log; el elemento se descarta para evitar un bucle infinito de errores.
6. Persiste la cola restante y escribe las estadísticas por ejecución en as24ci_image_queue_last_run ({ processed, failed, remaining, timestamp }).
7. Para cada publicación completamente vaciada de la cola en esta ejecución, reconstruye _as24ci_image_ids de manera autoritativa a partir de los adjuntos secundarios reales etiquetados con _as24ci_source_url y almacena el _as24ci_images_hash final. Esto garantiza que los metadatos estén completos y sean consistentes incluso si fallaron elementos individuales de la cola.
8. Programa la siguiente ejecución a través de maybe_schedule_image_queue_worker() si quedan elementos.

El valor images_hash del worker se valida para asegurar que sea una cadena MD5 en minúsculas de 32 caracteres antes de su uso. Las entradas corruptas se tratan como ausentes para que el hash de la publicación no se finalice con datos erróneos.

Referencia de configuración

Los valores exactos de IMAGE_QUEUE_LOCK_TTL, IMAGE_QUEUE_BATCH_SIZE y IMAGE_QUEUE_SIZE_LIMIT se definen como constantes en AS24CI\Scheduler y pueden cambiar entre versiones del plugin. Verifíquelos en el código fuente actual si necesita planificar para una carga específica.

Notas operativas

• WP-Cron es el activador por defecto. En sitios con poco tráfico, considere un cron del lado del servidor / cron del sistema que apunte a wp-cron.php (con DISABLE_WP_CRON establecido en true) para que la cola se vacíe de manera predecible.
• Las descargas de imágenes se realizan a través de download_url(), que utiliza la API HTTP de WordPress. Los servidores que bloqueen el tráfico HTTP saliente deben añadir a la lista blanca los servidores de imágenes de AutoScout24.
• La desduplicación de imágenes se basa en la URL de origen exacta. Las URL que difieran solo en la cadena de consulta (query string) o en los parámetros de firma se tratarán como fuentes distintas y se descargarán por separado.
• Los adjuntos manuales de la galería registrados en _as24ci_manual_image_ids nunca son sobrescritos ni eliminados por el importador o por el worker de la cola.
• El worker de la cola reconstruye _as24ci_image_ids a partir de los adjuntos secundarios reales al final de cada publicación completamente vaciada; si manipula los metadatos directamente entre ejecuciones del worker, es posible que sus cambios se reviertan.

Resolución de problemas

• Los vehículos aparecen sin ninguna imagen. Confirme que as24ci_import_images esté habilitado. Compruebe que as24ci_max_images no sea cero donde se pretenda. En el modo cron, la imagen principal se importa de forma síncrona; si no aparece ninguna imagen en absoluto, busque errores de descarga en el log del plugin.
• Solo la primera imagen está presente después de una importación por cron. Esto es lo esperado durante las importaciones en modo cron hasta que el worker as24ci_image_queue_process termine. Compruebe as24ci_image_queue_last_run para ver el progreso y el tamaño de la cola.
• La cola crece pero nunca se vacía. Verifique que WP-Cron se esté ejecutando (o que un cron del servidor active wp-cron.php). Compruebe si hay un transient as24ci_image_queue_running atascado que sea más antiguo que el TTL del worker. El worker borra automáticamente los bloqueos obsoletos en la siguiente ejecución.
• La conversión a WebP no se realiza. Asegúrese de que as24ci_convert_to_webp sea 1 y que esté instalado GD con soporte para WebP (imagewebp) o Imagick. El plugin registra en el log el motivo cuando se omite la conversión.
• Aparecen imágenes que parecen duplicadas en la galería. La clave de desduplicación es la URL de origen exacta. Las CDN que añaden parámetros de consulta únicos por solicitud anularán la desduplicación. Verifique las URL en la carga útil de la API mediante el registro detallado (verbose logging).
• Las imágenes desaparecieron después de eliminar un vehículo. El Vehicle_Deleter elimina los adjuntos registrados en _as24ci_image_ids. Los adjuntos manuales de la galería (_as24ci_manual_image_ids) se conservan. Verifique qué lista contenía el ID del adjunto afectado.

Documentos relacionados

• Import Engine
• Cron Events And Scheduler
• Data Model
• Database Schema
• Descripción general de la sección