Modelo de datos

Este documento describe el modelo de datos lógico utilizado por el plugin ADP Car Market Hub: qué entidades existen, cómo se mapean en el almacenamiento de WordPress y cómo funcionan juntas las diferentes capas de almacenamiento (tablas de bases de datos personalizadas, posts, postmeta y options).

Cuándo utilizar este documento

Lea este documento si necesita:

• Entender qué entidad (vehículo, lead, agente de búsqueda, evento de analytics) reside en qué tabla o tipo de post.
• Decidir dónde leer o escribir datos al crear una integración o informe personalizado.
• Entender cómo se dividen los datos de los campos de los vehículos entre la tabla dedicada as24_vehicles y las claves postmeta heredadas.

Para ver listas de columnas sin procesar, consulte Database Schema. Para las claves postmeta expuestas en la interfaz de usuario de metaboxes de administración, consulte los documentos de importación y plantillas en esta sección.

Descripción general

El plugin distingue entre cuatro entidades principales:

1. Vehículo — un único anuncio de coche importado de AutoScout24.
2. Lead — el envío de un formulario de contacto o consulta vinculado (opcionalmente) a un vehículo.
3. Agente de búsqueda — los criterios de búsqueda guardados de un visitante con notificaciones por correo electrónico.
4. Evento de Analytics — un único evento rastreado en el sitio público (vista de página, uso de filtros, apertura de contacto, etc.).

Cada entidad utiliza la capa de almacenamiento que mejor se adapta a su patrón de acceso. Los vehículos se dividen entre posts de WordPress (para enlaces permanentes, taxonomías, plantillas) y una tabla relacional dedicada (para columnas con tipo y consultas rápidas). Los leads son posts completos de WordPress. Los agentes de búsqueda y los eventos de analytics residen en sus propias tablas personalizadas.

Vehículo

Un vehículo es la entidad central del plugin. Está representado por dos registros estrechamente vinculados:

• Un post de WordPress con el tipo de post as24ci_car. El post proporciona el enlace permanente (/cars/<slug>/), el título y el extracto, la imagen destacada, el contenido del editor, los términos de taxonomía asignados y la superficie de capacidades de WordPress.
• Una fila en la tabla dedicada {$wpdb->prefix}as24_vehicles, propiedad de AS24CI\Vehicle_Repository. La fila contiene los datos tipados de los campos del vehículo (precio, kilometraje, año de matriculación, tipo de combustible, equipamiento, etc.), el payload crudo de la API y los metadatos utilizados para la detección de cambios.

Los dos registros están vinculados por la columna post_id, que tiene un índice único en la tabla. Cada fila también tiene una columna única as24_id que contiene el identificador de anuncio de AutoScout24.

Por qué una tabla dedicada

Los datos de los campos de los vehículos se almacenaban originalmente en wp_postmeta. El plugin trasladó estos datos a una tabla dedicada para que:

• Las columnas con tipo (decimales para precios, enteros para kilometraje, fechas para la primera matriculación) se puedan consultar y ordenar directamente sin el coste y la ambigüedad de los joins de meta_query.
• Los índices compuestos como idx_make_model, idx_fuel_condition y idx_status_live aceleren el filtrado de archivos.
• La detección de cambios (content_hash) resida junto a los datos que describe.

Por motivos de compatibilidad con versiones anteriores, el importador sigue escribiendo un pequeño conjunto de claves postmeta; consulte la siguiente sección.

Claves postmeta que aún se escriben para los vehículos

Incluso con la tabla personalizada en funcionamiento, las siguientes claves postmeta permanecen en los posts de as24ci_car. Se conservan intencionadamente para mantener el funcionamiento de las integraciones más antiguas y evitar regresiones en la interfaz de usuario de administración, la cola del AI Assistant y el flujo de eliminación.

Los adjuntos manuales de la galería de los que se realiza un seguimiento en _as24ci_manual_image_ids se tratan como propiedad del usuario y no se eliminan mediante el código de eliminación o desinstalación del plugin, incluso cuando se eliminan los adjuntos importados.

Sobrescrituras manuales

La tabla de vehículos incluye una columna JSON manual_overrides. Cuando un administrador edita un campo de vehículo que el importador gestiona normalmente, el cambio se almacena como una entrada clave/valor en esta columna. El AS24CI\Vehicle_Field_Resolver lee primero de la fila y luego aplica las sobrescrituras manuales para que las importaciones posteriores no borren las ediciones manuales. La red de seguridad dbDelta en Vehicle_Repository::maybe_create_table() añade esta columna en las tablas existentes si falta.

Taxonomías de vehículos

Los posts de as24ci_car están vinculados a 15 taxonomías no jerárquicas registradas por AS24CI\Taxonomies:

as24ci_brand, as24ci_model, as24ci_body_type, as24ci_condition, as24ci_fuel_type, as24ci_transmission, as24ci_drive, as24ci_ext_color, as24ci_int_color, as24ci_emission_std, as24ci_energy_label, as24ci_vehicle_cat, as24ci_warranty_type, as24ci_warranty_det, as24ci_cyl_arrange.

Los términos de las taxonomías alimentan los filtros de archivo y proporcionan URLs nativas de WordPress (por ejemplo, /as24ci_brand/<slug>/). Muchos de estos mismos valores también existen como columnas desnormalizadas en la tabla de vehículos (por ejemplo, make, fuel_type, transmission_type) para que las consultas de archivo puedan ejecutarse sin necesidad de realizar un join con wp_term_relationships.

Capacidades de vehículos

El tipo de post as24ci_car utiliza capacidades personalizadas con el formato as24ci_car / as24ci_cars (con map_meta_cap activado). Al activarse, el plugin otorga este conjunto de capacidades a los administradores y al rol personalizado as24ci_editor. Los administradores reciben adicionalmente la capacidad manage_as24_imports (Plugin::CAP_MANAGE), que restringe el acceso al importador, los ajustes, las herramientas y la interfaz de usuario de logs. Los usuarios con el rol "Editor" de WordPress no reciben capacidades de vehículos por defecto.

Lead

Un lead representa el envío de un formulario de contacto o consulta. Se almacena como un post de WordPress con el tipo de post as24ci_lead, registrado por AS24CI\Leads_CPT. El post almacena el mensaje del visitante en el contenido/extracto del post y los datos de contacto del remitente en postmeta.

El estado del lead se almacena en la clave postmeta _as24ci_lead_status y su valor por defecto es new. Los valores válidos se exponen como constantes en AS24CI\Leads_CPT:

• STATUS_NEW (new)
• STATUS_CONTACTED (contacted)
• STATUS_CLOSED (closed)
• STATUS_SPAM (spam)

Leads_CPT::get_lead_status() protege contra valores no válidos recurriendo a new. Leads_CPT::update_lead_status() valida el valor entrante antes de escribirlo.

Si un lead se envió desde la página de un vehículo, el vehículo relacionado se referencia en el postmeta del lead para que la pestaña de Leads de administración pueda mostrar el anuncio de origen.

Agente de búsqueda

Un agente de búsqueda representa los criterios de búsqueda guardados de un visitante con una suscripción por correo electrónico. Los agentes de búsqueda se almacenan en la tabla dedicada {$wpdb->prefix}as24ci_search_agents, propiedad de AS24CI\Search_Agent.

Cada fila contiene:

• name y email — identidad del visitante.
• criteria — los filtros de búsqueda guardados (almacenados como texto).
• token — token opaco utilizado para confirmar o cancelar la suscripción.
• frequency — frecuencia de notificación (por defecto es daily).
• status — uno de los valores pending, active, inactive o paused, expuestos como constantes en AS24CI\Search_Agent.
• created_at y confirmed_at — marcas de tiempo para el flujo de Doble Opt-In conforme al RGPD.

Debido a que los agentes de búsqueda contienen datos personales, la tabla siempre se elimina durante la desinstalación, independientemente del ajuste as24ci_delete_data_on_uninstall.

Evento de Analytics

Un evento de analytics registra una única interacción del visitante (vista de página, uso de filtros, apertura de contacto, etc.). Los eventos se almacenan en la tabla dedicada {$wpdb->prefix}as24ci_analytics, propiedad de AS24CI\Analytics.

Cada fila contiene:

• post_id — el ID del post del vehículo relacionado, o 0 para eventos globales como las búsquedas con filtros.
• event_type — el identificador del evento (los valores permitidos se validan contra la propia lista ALLOWED_EVENTS de la clase).
• extra_data — payload opcional codificado en JSON.
• created_at — marca de tiempo del evento.

Los eventos solo se registran cuando Options::ANALYTICS_ENABLED está establecido en 1. Una tarea diaria de limpieza de retención se ejecuta a través del hook de cron as24ci_daily_cleanup. Al igual que la tabla de agentes de búsqueda, la tabla de analytics siempre se elimina durante la desinstalación porque puede contener datos de seguimiento de visitantes.

Páginas gestionadas por la activación

Durante la activación, el plugin puede crear tres páginas de WordPress que albergan los shortcodes de cara al público:

• Cars ([as24ci_archive]) — la página principal del archivo de vehículos.
• Compare Cars ([as24ci_compare]) — la página de comparación.
• Favorites ([as24ci_favorites]) — la página de favoritos/lista de deseos.

Los IDs se almacenan en las opciones as24ci_page_archive_id, as24ci_page_compare_id y as24ci_page_favorites_id. Estas páginas no forman parte estrictamente del modelo de datos; se crean para que los shortcodes tengan una ubicación predeterminada, y son las únicas páginas de WordPress que el plugin elimina durante una desinstalación destructiva.

Ajustes (options)

Todos los ajustes configurables por el usuario se almacenan en wp_options. Las claves se definen como constantes en AS24CI\Options. Los ejemplos incluyen:

• API y autenticación: as24ci_base_url, as24ci_token_url, as24ci_seller_ids, as24ci_client_id, as24ci_client_secret, as24ci_token_audience.
• Comportamiento del importador: as24ci_default_post_status, as24ci_default_post_author, as24ci_import_images, as24ci_max_images, as24ci_convert_to_webp, as24ci_webp_quality, as24ci_full_sync.
• Programador: as24ci_auto_import_enabled, as24ci_cron_schedule, as24ci_cron_start_time, as24ci_cron_custom_minutes, as24ci_cron_max_vehicles, as24ci_cron_token.
• Interruptores de características: constantes de Options::FEATURE_* para sitemap, schema, favoritos, comparar, compartir en redes sociales, PDF datasheet, agente de búsqueda, analytics, AI Assistant, REST API, widget del escritorio, etc.
• Marcadores de esquema/versión: as24ci_db_version, as24ci_caps_version, as24ci_vehicles_db_version, as24ci_search_agent_db_version.

El inventario completo y el comportamiento de estas opciones se documentan en el documento Almacenamiento de opciones y ajustes.

Transients

El plugin utiliza un pequeño número de transients para estados de corta duración. Los más relevantes para el modelo de datos son:

• as24ci_access_token — token de acceso OAuth de AutoScout24 en caché.
• as24ci_cron_import_running — bloqueo de ejecución que evita la superposición de importaciones (Scheduler::LOCK_TRANSIENT, ~40 minutos de TTL).
• as24ci_image_queue_running — bloqueo de ejecución para el worker de la cola de imágenes.
• as24ci_batch_queue — payload de la cola para el asistente por lotes manual (Batch-Wizard).

Los transients se eliminan durante la desactivación y la desinstalación según corresponda.

---

Referencia de configuración

Notas operativas

• Un vehículo existe mientras existan tanto su entrada como su fila en la tabla. La limpieza de AS24CI\Vehicle_Deleter se conecta durante la construcción del plugin para que cada ruta de eliminación permanente (eliminación nativa de WP, sincronización completa del importador, acción en lote) pase por el mismo flujo idempotente.
• El repositorio mantiene una pequeña caché en proceso (grupo de caché de objetos as24ci_vehicles, ~1 hora de TTL) para búsquedas de una sola fila. Las escrituras directas en la tabla desde código personalizado omiten esta caché; considere invalidarla manualmente al extender el repositorio.
• La columna raw_data en la tabla de vehículos conserva la carga útil de origen de la importación. Esto es útil para depurar problemas de mapeo, pero no debe considerarse como un contrato estable; la estructura de la carga útil está determinada por la API de AutoScout24.
• Las imágenes de la galería manual se tratan deliberadamente como propiedad del administrador. No se eliminan cuando se borran las imágenes importadas, y tampoco se eliminan durante la desinstalación. Elimínelas manualmente de la biblioteca de medios de WordPress si es necesario.

Resolución de problemas

• A un vehículo le faltan valores de campos en el frontend pero existe en la lista de entradas. Compruebe que la tabla de vehículos contiene una fila con el post_id correspondiente. Si la fila no existe, el anuncio se creó fuera del importador o la migración a la tabla personalizada no se completó.
• Las ediciones en la metabox se sobrescriben con la siguiente importación. Verifique que el campo afectado se esté escribiendo en la columna JSON manual_overrides. La capa de anulación requiere que exista la columna manual_overrides; la actualización del esquema la añade si es necesario.
• Una imagen importada desaparece. El plugin solo elimina los archivos adjuntos de los que se realiza un seguimiento en _as24ci_image_ids. Las imágenes que se añadieron a través de la galería manual (_as24ci_manual_image_ids) se conservan. Verifique qué lista contiene el ID de archivo adjunto afectado.
• Las filas de agentes de búsqueda o de analítica siguen apareciendo después de eliminar el plugin. Confirme que se ejecutó uninstall.php. Las dos tablas se eliminan incondicionalmente al desinstalar. Si la desinstalación no se ejecutó (por ejemplo, porque el plugin solo se desactivó), las filas permanecen en su lugar.

Documentos relacionados

• Descripción general de la arquitectura
• Inicialización y ciclo de vida del plugin
• Esquema de la base de datos
• Descripción general de la sección