Documentación · Documentación técnica

Esquema de la base de datos

Este documento describe las tablas personalizadas de la base de datos creadas por el plugin ADP Car Market Hub. Todas las tablas se gestionan con el asistente dbDelta() de WordPress y se crean al activar el plugin. Las versiones de sus esquemas se registran en wp_options para que dbDelta pueda aplicar cambios de columnas de forma segura durante las actualizaciones.

Cuándo utilizar este documento

Lea este documento si necesita:

Planificar copias de seguridad, retención o tareas de cumplimiento para los datos del plugin.
Crear informes personalizados basados en las tablas del plugin.
Diagnosticar actualizaciones de esquema fallidas o columnas faltantes.
Comprender qué tablas se eliminan al desinstalar y cuáles no.

Para conocer el modelo de entidad lógico que utiliza estas tablas, consulte el Data Model.

Descripción general

El plugin crea cinco tablas personalizadas:

Sufijo de la tabla	Propósito	Opción de versión de esquema
`as24_vehicles`	Datos de campos de vehículos, reemplazando la mayor parte del uso de `wp_postmeta`.	`as24ci_vehicles_db_version`
`as24ci_analytics`	Eventos de Analytics para páginas de vehículos y acciones de filtros globales.	`as24ci_analytics_db_version`
`as24ci_search_agents`	Suscripciones de alertas de búsqueda de visitantes (Smart Stock Alerts).	`as24ci_search_agent_db_version`
`as24ci_content_studio_jobs`	Trabajos de generación de Content Studio (una fila por trabajo).	`as24ci_content_studio_db_version`
`as24ci_content_studio_assets`	Recursos generados por Content Studio, vinculados a un trabajo mediante `job_id`.	`as24ci_content_studio_db_version`

Los nombres reales de las tablas utilizan el prefijo {$wpdb->prefix} de WordPress (normalmente wp_). La versión del esquema de la tabla de analytics se almacena en as24ci_analytics_db_version (constante AS24CI\Analytics::DB_VERSION_KEY). Las dos tablas de Content Studio comparten una única opción de versión de esquema (as24ci_content_studio_db_version, valor actual 1.3.0) definida en AS24CI\Content_Studio_Options::DB_VERSION y gestionada por AS24CI\Content_Studio_Repository::maybe_create_tables().

El plugin también depende de las tablas principales de WordPress wp_posts, wp_postmeta, wp_term_relationships, wp_term_taxonomy y wp_terms para los tipos de contenido personalizados as24ci_car y as24ci_lead y las 15 taxonomías de vehículos. Esas tablas siguen el esquema estándar de WordPress y no son redefinidas por el plugin.

Las cinco tablas personalizadas se eliminan automáticamente al desinstalar (consulte la sección Comportamiento de desinstalación más abajo), independientemente del ajuste as24ci_delete_data_on_uninstall.

Tabla: `{$wpdb->prefix}as24_vehicles`

Propietario: AS24CI\Vehicle_Repository. Creada a través de Vehicle_Repository::maybe_create_table() en la activación y vuelta a comprobar en ejecuciones posteriores. La constante de versión de esquema actual es 1.1, almacenada en la opción as24ci_vehicles_db_version.

La tabla contiene una fila por vehículo, vinculada a su entrada de as24ci_car mediante la columna post_id. La columna as24_id contiene el identificador de anuncio de AutoScout24. Ambas columnas tienen índices únicos.

Columnas

Columna	Tipo	Notas
`id`	`bigint(20) unsigned`	Clave primaria, autoincremental.
`post_id`	`bigint(20) unsigned`	ID de la entrada de WordPress para el `as24ci_car` vinculado. Único.
`as24_id`	`varchar(64)`	Identificador de anuncio de AutoScout24. Único. Por defecto es una cadena vacía.
`seller_id`	`varchar(64)`	Identificador de vendedor de AutoScout24.
`make`	`varchar(100)`
`model`	`varchar(100)`
`version_full_name`	`varchar(255)`	Etiqueta completa de acabado/versión tal como la proporciona la API.
`condition_type`	`varchar(50)`	P. ej. `new`, `used`, `demo` (los valores reflejan la API de origen).
`body_type`	`varchar(50)`
`fuel_type`	`varchar(50)`
`transmission_type`	`varchar(50)`
`drive_type`	`varchar(50)`
`color_exterior`	`varchar(100)`
`color_interior`	`varchar(100)`
`doors`	`tinyint(3) unsigned`	Por defecto es `0`.
`seats`	`tinyint(3) unsigned`	Por defecto es `0`.
`mileage`	`int(10) unsigned`	Por defecto es `0`.
`cubic_capacity`	`int(10) unsigned`	Cilindrada del motor.
`range_km`	`int(10) unsigned`	Autonomía eléctrica en kilómetros.
`first_registration`	`date`	Admite valores nulos.
`first_reg_year`	`smallint(5) unsigned`	Componente de año de `first_registration`. Por defecto es `0`.
`power_kw`	`smallint(5) unsigned`
`power_hp`	`smallint(5) unsigned`
`co2_emission`	`smallint(5) unsigned`	g/km.
`price`	`decimal(10,2)`	Precio de venta.
`list_price`	`decimal(10,2)`	Precio de lista/MSRP (si se proporciona).
`currency`	`char(3)`	Código ISO 4217; por defecto es `EUR`.
`emission_standard`	`varchar(20)`	P. ej. Euro 6.
`energy_label`	`char(5)`	Etiqueta energética A-G.
`battery_capacity`	`decimal(6,2)`	kWh.
`vin`	`varchar(20)`	Número de identificación del vehículo (VIN).
`status`	`varchar(30)`	Estado del anuncio tal como lo proporciona la API.
`is_live`	`tinyint(1)`	`1` si el anuncio está activo actualmente, `0` en caso contrario.
`had_accident`	`tinyint(1)`
`equipment_codes`	`longtext`	Matriz JSON de códigos de equipamiento. Admite valores nulos.
`equipment_standard`	`longtext`	Lista JSON de elementos de equipamiento de serie. Admite valores nulos.
`equipment_optional`	`longtext`	Lista JSON de elementos de equipamiento opcional. Admite valores nulos.
`images`	`longtext`	Lista JSON de URL de imágenes tal como las proporciona la API.
`raw_data`	`longtext`	Carga útil de origen completa conservada para diagnóstico.
`manual_overrides`	`longtext`	Objeto JSON de campos editados por el administrador que sobrescriben los valores importados.
`content_hash`	`varchar(64)`	Hash utilizado para omitir reimportaciones de anuncios sin cambios.
`imported_at`	`datetime`	Por defecto es `CURRENT_TIMESTAMP`.
`updated_at`	`datetime`	Por defecto es `CURRENT_TIMESTAMP`. Véase la nota de implementación más abajo.

Nota de implementación: updated_at se crea únicamente con DEFAULT CURRENT_TIMESTAMP dentro del SQL de dbDelta porque añadir ON UPDATE CURRENT_TIMESTAMP directamente hace que dbDelta vuelva a emitir un ALTER en cada carga del plugin. La semántica de ON UPDATE se aplica mediante un ALTER de un solo uso después de que se ejecute dbDelta.

Índices

Índice	Tipo	Columnas	Propósito
`PRIMARY`	Primary	`id`	Clave primaria subrogada.
`uk_as24_id`	Unique	`as24_id`	Una fila por anuncio de AutoScout24.
`uk_post_id`	Unique	`post_id`	Una fila por entrada de vehículo de WordPress.
`idx_make_model`	Index	`make`, `model`	Controla los filtros de archivo de marca/modelo.
`idx_price`	Index	`price`	Ordenación por precio/filtrado por rango.
`idx_mileage`	Index	`mileage`	Ordenación por kilometraje/filtrado por rango.
`idx_first_reg_year`	Index	`first_reg_year`	Ordenación por año/filtrado por rango.
`idx_fuel_condition`	Index	`fuel_type`, `condition_type`	Filtro combinado común.
`idx_status_live`	Index	`status`, `is_live`	Consultas de anuncios activos.
`idx_content_hash`	Index	`content_hash`	Búsquedas durante la detección de cambios.

Red de seguridad para `manual_overrides`

Después de que se ejecute dbDelta, el repositorio realiza una comprobación de SHOW COLUMNS ... LIKE 'manual_overrides' y, si falta la columna, emite un ALTER TABLE ... ADD COLUMN manual_overrides longtext DEFAULT NULL AFTER raw_data explícito. Esto compensa los problemas ocasionales de detección de columnas en algunas combinaciones de MySQL/MariaDB y garantiza que la capa de sobrescritura manual siempre tenga un lugar donde almacenar los datos.

Tabla: `{$wpdb->prefix}as24ci_analytics`

Propietario: AS24CI\Analytics. Creada a través de Analytics::maybe_create_table() durante la activación y vuelta a comprobar en cada carga de página de administración (el método también está conectado a admin_init para que las instalaciones existentes detecten las nuevas columnas sin necesidad de una reactivación manual).

Columnas

Columna	Tipo	Notas
`id`	`bigint(20) unsigned`	Clave primaria, autoincremental.
`post_id`	`bigint(20) unsigned`	ID de la entrada del vehículo. `0` para eventos globales como búsquedas de filtros.
`event_type`	`varchar(20)`	Identificador de evento; por defecto es `view`. Validado contra `ALLOWED_EVENTS`.
`extra_data`	`longtext`	Carga útil opcional codificada en JSON. Admite valores nulos.
`created_at`	`datetime`	Por defecto es `CURRENT_TIMESTAMP`.

Índices

Índice	Tipo	Columnas
`PRIMARY`	Primary	`id`
`post_event_date`	Index	`post_id`, `event_type`, `created_at`
`event_type`	Index	`event_type`, `created_at`
`created_at`	Index	`created_at`

Retención

Las inserciones solo ocurren cuando Options::ANALYTICS_ENABLED es 1. Se ejecuta una tarea diaria de retención a través del gancho de cron as24ci_daily_cleanup (programado en la activación, eliminado en la desactivación). El intervalo de retención se configura a través de la pestaña de administración de analytics.

Tabla: `{$wpdb->prefix}as24ci_search_agents`

Propietario: AS24CI\Search_Agent. Creada a través de Search_Agent::maybe_create_table() en init (prioridad 1) para que esté disponible tanto para los controladores AJAX de administración como de frontend. La versión actual del esquema es 1.1, almacenada en la opción as24ci_search_agent_db_version. La creación está condicionada por el conmutador Options::FEATURE_SEARCH_AGENT, pero el esquema se registra incondicionalmente cuando se carga la clase de la característica.

Columnas

Columna	Tipo	Notas
`id`	`BIGINT UNSIGNED`	Clave primaria, autoincremental.
`name`	`VARCHAR(255)`	Nombre visible del visitante; por defecto es una cadena vacía.
`email`	`VARCHAR(255)`	Dirección de correo electrónico del visitante.
`criteria`	`TEXT`	Criterios de búsqueda guardados (representación serializada).
`token`	`VARCHAR(64)`	Token para enlaces de confirmación y de baja de suscripción.
`frequency`	`VARCHAR(20)`	Frecuencia de notificación; por defecto `daily`.
`status`	`VARCHAR(20)`	Uno de `pending`, `active`, `inactive`, `paused`. Por defecto `pending`.
`created_at`	`DATETIME`	Por defecto `CURRENT_TIMESTAMP`.
`confirmed_at`	`DATETIME`	Admite valores nulos; se establece cuando el visitante confirma mediante Double-Opt-In.

Índices

Índice	Tipo	Columnas
`PRIMARY`	Primary	`id`
`idx_status`	Index	`status`
`idx_token`	Index	`token`

Privacidad

Debido a que la tabla contiene datos personales (nombre, correo electrónico, preferencias de búsqueda), se elimina durante la desinstalación independientemente de la configuración de as24ci_delete_data_on_uninstall. Los operadores del sitio son responsables de las herramientas adicionales de retención o exportación requeridas por las normativas de privacidad locales.

Tabla: `{$wpdb->prefix}as24ci_content_studio_jobs`

Propietario: AS24CI\Content_Studio_Repository. Creada a través de Content_Studio_Repository::maybe_create_tables() (registrado como su propio gancho de activación en el archivo principal del plugin y también llamado de forma diferida por la mayoría de los métodos del repositorio). Contiene una fila por cada trabajo de generación de Content Studio. Los valores de estado son draft, queued, processing, ready y failed.

Columnas

Columna	Tipo	Notas
`id`	`bigint(20) unsigned`	Clave primaria, autoincremental.
`vehicle_post_id`	`bigint(20) unsigned`	Entrada del vehículo de origen. Por defecto `0`.
`vehicle_snapshot_hash`	`varchar(64)`	Hash de la instantánea del vehículo utilizada para el trabajo.
`content_type`	`varchar(40)`	Tipo de contenido solicitado.
`platform_preset`	`varchar(40)`	Ajuste preestablecido de la plataforma de destino.
`output_format`	`varchar(20)`	Formato de salida.
`preset_key`	`varchar(80)`	Clave del catálogo preestablecido.
`status`	`varchar(20)`	Por defecto `draft`.
`prompt_payload`	`longtext`	Carga útil del prompt en JSON. Admite valores nulos.
`provider`	`varchar(40)`	Por defecto `google`.
`model`	`varchar(80)`	Modelo del proveedor.
`language`	`varchar(20)`	Idioma de salida.
`tone`	`varchar(40)`	Tono de voz.
`attempts`	`smallint(5) unsigned`	Intentos de procesamiento. Por defecto `0`.
`last_error`	`text`	Último mensaje de error. Admite valores nulos.
`created_by`	`bigint(20) unsigned`	ID de usuario de WordPress. Por defecto `0`.
`created_at`	`datetime`	Por defecto `CURRENT_TIMESTAMP`.
`updated_at`	`datetime`	Por defecto `CURRENT_TIMESTAMP`.
`started_at`	`datetime`	Admite valores nulos.
`completed_at`	`datetime`	Admite valores nulos.

Índices: PRIMARY (id), vehicle_post_id, status_created (status, created_at), platform_preset, content_type.

Tabla: `{$wpdb->prefix}as24ci_content_studio_assets`

Propietario: AS24CI\Content_Studio_Repository. Contiene los recursos generados (texto, imágenes, paquetes de copia) pertenecientes a un trabajo, vinculados por job_id.

Columnas

Columna	Tipo	Notas
`id`	`bigint(20) unsigned`	Clave primaria, autoincremental.
`job_id`	`bigint(20) unsigned`	Trabajo principal. Por defecto `0`.
`vehicle_post_id`	`bigint(20) unsigned`	Entrada del vehículo de origen. Por defecto `0`.
`asset_type`	`varchar(40)`	Tipo de recurso.
`file_path`	`text`	Ruta del archivo local. Admite valores nulos.
`file_url`	`text`	URL pública. Admite valores nulos.
`mime_type`	`varchar(120)`	Tipo MIME.
`file_size`	`bigint(20) unsigned`	Bytes. Por defecto `0`.
`width`	`int(10) unsigned`	Ancho de la imagen. Por defecto `0`.
`height`	`int(10) unsigned`	Alto de la imagen. Por defecto `0`.
`duration_seconds`	`decimal(8,2)`	Duración del medio. Por defecto `0.00`.
`caption`	`longtext`	Admite valores nulos.
`hashtags`	`longtext`	Admite valores nulos.
`alt_text`	`text`	Admite valores nulos.
`thumbnail_path`	`text`	Admite valores nulos.
`payload_json`	`longtext`	Carga útil estructurada (por ejemplo, paquetes de copia). Admite valores nulos.
`scheduled_at`	`datetime`	Admite valores nulos.
`schedule_status`	`varchar(32)`	Por defecto `unscheduled`.
`created_at`	`datetime`	Por defecto `CURRENT_TIMESTAMP`.

Índices: PRIMARY (id), job_id, vehicle_post_id, asset_type, created_at, schedule_status, scheduled_at.

Tablas principales de WordPress utilizadas por el plugin

El plugin no modifica el esquema de las tablas principales de WordPress. Depende de ellas de la siguiente manera:

wp_posts — almacena las entradas de as24ci_car (vehículos) y as24ci_lead (leads).
wp_postmeta — almacena postmeta de compatibilidad con versiones anteriores para las entradas de vehículos (_as24ci_listing_id, _as24ci_content_hash, _as24ci_images_hash, _as24ci_image_ids, _as24ci_manual_image_ids) y el estado del lead (_as24ci_lead_status).
wp_terms, wp_term_taxonomy, wp_term_relationships — almacenan las 15 taxonomías de vehículos registradas por AS24CI\Taxonomies.
wp_options — almacena todos los ajustes del plugin (claves definidas como constantes en AS24CI\Options) además de los marcadores de versión del esquema y los ID de las páginas creadas durante la activación.
wp_users y wp_usermeta — se utilizan indirectamente a través de las capacidades de WordPress; no hay escrituras específicas del plugin.

Los roles y capacidades personalizados creados por el plugin (as24ci_editor, el conjunto de capacidades as24ci_car/as24ci_cars y manage_as24_imports) se almacenan a través de la opción de roles estándar de WordPress (wp_user_roles).

Comportamiento de desinstalación

El script uninstall.php siempre emite DROP TABLE IF EXISTS para las cinco tablas personalizadas y elimina las opciones de versión de esquema correspondientes:

{$wpdb->prefix}as24_vehicles (y as24ci_vehicles_db_version)
{$wpdb->prefix}as24ci_analytics
{$wpdb->prefix}as24ci_search_agents (y as24ci_search_agent_db_version)
{$wpdb->prefix}as24ci_content_studio_assets
{$wpdb->prefix}as24ci_content_studio_jobs (y as24ci_content_studio_db_version)

En instalaciones multisitio, el script cambia a cada sitio y repite la limpieza. Las entradas, los archivos adjuntos y las páginas creadas durante la activación solo se eliminan cuando el administrador ha establecido as24ci_delete_data_on_uninstall en 1.

Notas operativas

Las actualizaciones de esquema son idempotentes. Cada clase propietaria comprueba su opción de versión de esquema y sale rápidamente cuando la tabla ya coincide con la versión esperada. El repositorio de vehículos comprueba adicionalmente que la tabla exista físicamente antes de salir rápidamente.
Existen consultas directas de wpdb contra estas tablas en las rutas de código del repositorio, analytics, search-agent y desinstalación. Están protegidas con comentarios de ignorar de PHPCS donde corresponde. El código personalizado que omita el repositorio debe tratar el esquema como parte del contrato interno del plugin y estar preparado para cambios de columnas entre versiones.
Las columnas raw_data, equipment_* y images contienen datos serializados. Trátelas como blobs opacos y acceda a ellas a través de los asistentes del repositorio cuando sea posible.
La columna manual_overrides es el único lugar que mezcla el estado controlado por el administrador y el controlado por el importador. Evite escribir en ella directamente sin pasar por la capa de anulación.

Resolución de problemas

maybe_create_table() no creó la tabla de vehículos. Confirme que dbDelta() no informó de errores. El repositorio escribe los errores en error_log() porque se ejecuta antes de que el Logger del plugin esté disponible. Volver a ejecutar la activación (desactivar, activar) vuelve a ejecutar maybe_create_table().
Falta una nueva columna después de una actualización del plugin. Compruebe la opción de versión de esquema para la tabla afectada. Si es igual al valor actual pero falta la columna, elimine la opción para forzar la ejecución de dbDelta en la siguiente carga de página de administración. La tabla de vehículos tiene una red de seguridad explícita manual_overrides para este caso.
La tabla de analytics crece rápidamente. Reduzca la ventana de retención o desactive analytics a través de Options::ANALYTICS_ENABLED. El trabajo de limpieza diario es necesario para mantener la tabla acotada.
Las filas de search-agent persisten después de la desinstalación. Verifique que WordPress haya ejecutado uninstall.php. Si solo se ejecutó deactivate() (por ejemplo, porque el plugin se desactivó pero no se eliminó), la tabla se conserva intencionadamente hasta la desinstalación.

Cuándo utilizar este documento

Descripción general

Tabla: {$wpdb->prefix}as24_vehicles

Columnas

Índices

Red de seguridad para manual_overrides

Tabla: {$wpdb->prefix}as24ci_analytics

Columnas

Índices

Retención

Tabla: {$wpdb->prefix}as24ci_search_agents

Columnas

Índices

Privacidad

Tabla: {$wpdb->prefix}as24ci_content_studio_jobs

Columnas

Tabla: {$wpdb->prefix}as24ci_content_studio_assets

Columnas

Tablas principales de WordPress utilizadas por el plugin

Comportamiento de desinstalación

Notas operativas

Resolución de problemas

Documentos relacionados

Tabla: `{$wpdb->prefix}as24_vehicles`

Red de seguridad para `manual_overrides`

Tabla: `{$wpdb->prefix}as24ci_analytics`

Tabla: `{$wpdb->prefix}as24ci_search_agents`

Tabla: `{$wpdb->prefix}as24ci_content_studio_jobs`

Tabla: `{$wpdb->prefix}as24ci_content_studio_assets`