Documentazione · Documentazione tecnica

Schema del database

Questo documento descrive le tabelle personalizzate del database create dal plugin ADP Car Market Hub. Tutte le tabelle sono gestite con l'helper dbDelta() di WordPress e vengono create all'attivazione del plugin. Le versioni dei loro schemi sono tracciate in wp_options in modo che dbDelta possa applicare le modifiche alle colonne in modo sicuro durante l'aggiornamento.

Quando utilizzare questo documento

Leggere questo documento se è necessario:

Pianificare backup, conservazione o attività di conformità per i dati del plugin.
Creare report personalizzati basati sulle tabelle del plugin.
Diagnosticare aggiornamenti dello schema non riusciti o colonne mancanti.
Comprendere quali tabelle vengono eliminate al momento della disinstallazione e quali no.

Per il modello logico delle entità che utilizza queste tabelle, consultare il Modello dei dati.

Panoramica

Il plugin crea cinque tabelle personalizzate:

Suffisso tabella	Scopo	Opzione versione schema
`as24_vehicles`	Dati dei campi del veicolo, in sostituzione della maggior parte dell'uso di `wp_postmeta`.	`as24ci_vehicles_db_version`
`as24ci_analytics`	Eventi di Analytics per le pagine dei veicoli e le azioni dei filtri globali.	`as24ci_analytics_db_version`
`as24ci_search_agents`	Iscrizioni degli utenti agli avvisi di ricerca (Smart Stock Alerts).	`as24ci_search_agent_db_version`
`as24ci_content_studio_jobs`	Processi di generazione di Content Studio (una riga per processo).	`as24ci_content_studio_db_version`
`as24ci_content_studio_assets`	Asset generati da Content Studio, collegati a un processo tramite `job_id`.	`as24ci_content_studio_db_version`

I nomi reali delle tabelle utilizzano il prefisso {$wpdb->prefix} di WordPress (in genere wp_). La versione dello schema della tabella analytics è memorizzata in as24ci_analytics_db_version (costante AS24CI\Analytics::DB_VERSION_KEY). Le due tabelle di Content Studio condividono una singola opzione per la versione dello schema (as24ci_content_studio_db_version, valore corrente 1.3.0) definita su AS24CI\Content_Studio_Options::DB_VERSION e gestita da AS24CI\Content_Studio_Repository::maybe_create_tables().

Il plugin si affida anche alle tabelle core di WordPress wp_posts, wp_postmeta, wp_term_relationships, wp_term_taxonomy e wp_terms per i custom post type as24ci_car e as24ci_lead e per le 15 tassonomie dei veicoli. Tali tabelle seguono lo schema standard di WordPress e non vengono ridefinite dal plugin.

Tutte e cinque le tabelle personalizzate vengono eliminate automaticamente al momento della disinstallazione (vedere la sezione Comportamento di disinstallazione di seguito), indipendentemente dall'impostazione di as24ci_delete_data_on_uninstall.

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

Proprietario: AS24CI\Vehicle_Repository. Creata tramite Vehicle_Repository::maybe_create_table() all'attivazione e ricontrollata nei passaggi successivi. La costante della versione corrente dello schema è 1.1, memorizzata nell'opzione as24ci_vehicles_db_version.

La tabella contiene una riga per veicolo, collegata al suo articolo as24ci_car tramite la colonna post_id. La colonna as24_id contiene l'identificatore dell'annuncio AutoScout24. Entrambe le colonne hanno indici univoci.

Colonne

Colonna	Tipo	Note
`id`	`bigint(20) unsigned`	Chiave primaria, auto-incremento.
`post_id`	`bigint(20) unsigned`	ID dell'articolo WordPress per il `as24ci_car` collegato. Univoco.
`as24_id`	`varchar(64)`	Identificatore dell'annuncio AutoScout24. Univoco. Il valore predefinito è una stringa vuota.
`seller_id`	`varchar(64)`	Identificatore del venditore AutoScout24.
`make`	`varchar(100)`
`model`	`varchar(100)`
`version_full_name`	`varchar(255)`	Denominazione completa dell'allestimento/versione così come fornita dall'API.
`condition_type`	`varchar(50)`	Ad es. `new`, `used`, `demo` (i valori rispecchiano l'API di origine).
`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`	Il valore predefinito è `0`.
`seats`	`tinyint(3) unsigned`	Il valore predefinito è `0`.
`mileage`	`int(10) unsigned`	Il valore predefinito è `0`.
`cubic_capacity`	`int(10) unsigned`	Cilindrata del motore.
`range_km`	`int(10) unsigned`	Autonomia elettrica in chilometri.
`first_registration`	`date`	Ammette valori nulli.
`first_reg_year`	`smallint(5) unsigned`	Componente anno di `first_registration`. Il valore predefinito è `0`.
`power_kw`	`smallint(5) unsigned`
`power_hp`	`smallint(5) unsigned`
`co2_emission`	`smallint(5) unsigned`	g/km.
`price`	`decimal(10,2)`	Prezzo di vendita.
`list_price`	`decimal(10,2)`	Prezzo di listino/MSRP (se fornito).
`currency`	`char(3)`	Codice ISO 4217; il valore predefinito è `EUR`.
`emission_standard`	`varchar(20)`	Ad es. Euro 6.
`energy_label`	`char(5)`	Classe energetica A-G.
`battery_capacity`	`decimal(6,2)`	kWh.
`vin`	`varchar(20)`	Numero di telaio (VIN) del veicolo.
`status`	`varchar(30)`	Stato dell'annuncio così come fornito dall'API.
`is_live`	`tinyint(1)`	`1` se l'annuncio è attualmente online, altrimenti `0`.
`had_accident`	`tinyint(1)`
`equipment_codes`	`longtext`	Array JSON di codici equipaggiamento. Ammette valori nulli.
`equipment_standard`	`longtext`	Elenco JSON di elementi di equipaggiamento di serie. Ammette valori nulli.
`equipment_optional`	`longtext`	Elenco JSON di elementi di equipaggiamento opzionali. Ammette valori nulli.
`images`	`longtext`	Elenco JSON di URL delle immagini così come fornite dall'API.
`raw_data`	`longtext`	Payload sorgente completo conservato per scopi diagnostici.
`manual_overrides`	`longtext`	Oggetto JSON dei campi modificati dall'amministratore che sovrascrivono i valori importati.
`content_hash`	`varchar(64)`	Hash utilizzato per saltare le re-importazioni di annunci non modificati.
`imported_at`	`datetime`	Il valore predefinito è `CURRENT_TIMESTAMP`.
`updated_at`	`datetime`	Il valore predefinito è `CURRENT_TIMESTAMP`. Vedere la nota di implementazione di seguito.

Nota di implementazione: updated_at viene creato con solo DEFAULT CURRENT_TIMESTAMP all'interno dell'SQL di dbDelta poiché l'aggiunta diretta di ON UPDATE CURRENT_TIMESTAMP causa la riemissione da parte di dbDelta di un ALTER a ogni caricamento del plugin. La semantica di ON UPDATE viene applicata tramite un ALTER eseguito una sola volta dopo l'esecuzione di dbDelta.

Indici

Indice	Tipo	Colonne	Scopo
`PRIMARY`	Primary	`id`	Chiave primaria surrogata.
`uk_as24_id`	Unique	`as24_id`	Una riga per annuncio AutoScout24.
`uk_post_id`	Unique	`post_id`	Una riga per articolo veicolo WordPress.
`idx_make_model`	Index	`make`, `model`	Gestisce i filtri dell'archivio marca/modello.
`idx_price`	Index	`price`	Ordinamento dei prezzi/filtraggio per intervallo.
`idx_mileage`	Index	`mileage`	Ordinamento del chilometraggio/filtraggio per intervallo.
`idx_first_reg_year`	Index	`first_reg_year`	Ordinamento dell'anno/filtraggio per intervallo.
`idx_fuel_condition`	Index	`fuel_type`, `condition_type`	Filtro combinato comune.
`idx_status_live`	Index	`status`, `is_live`	Query per annunci online.
`idx_content_hash`	Index	`content_hash`	Ricerche durante il rilevamento delle modifiche.

Rete di sicurezza per `manual_overrides`

Dopo l'esecuzione di dbDelta, il repository esegue un controllo SHOW COLUMNS ... LIKE 'manual_overrides' e, se la colonna risulta mancante, emette un ALTER TABLE ... ADD COLUMN manual_overrides longtext DEFAULT NULL AFTER raw_data esplicito. Ciò compensa occasionali problemi di rilevamento delle colonne in alcune combinazioni di MySQL/MariaDB e garantisce che il livello di sovrascrittura manuale disponga sempre di uno spazio per memorizzare i dati.

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

Proprietario: AS24CI\Analytics. Creata tramite Analytics::maybe_create_table() durante l'attivazione e ricontrollata a ogni caricamento della pagina di amministrazione (il metodo è anche collegato a admin_init in modo che le installazioni esistenti rilevino le nuove colonne senza una riattivazione manuale).

Colonne

Colonna	Tipo	Note
`id`	`bigint(20) unsigned`	Chiave primaria, auto-incremento.
`post_id`	`bigint(20) unsigned`	ID dell'articolo veicolo. `0` per eventi globali come le ricerche con filtri.
`event_type`	`varchar(20)`	Identificatore dell'evento; il valore predefinito è `view`. Validato rispetto a `ALLOWED_EVENTS`.
`extra_data`	`longtext`	Payload opzionale codificato in JSON. Ammette valori nulli.
`created_at`	`datetime`	Il valore predefinito è `CURRENT_TIMESTAMP`.

Indici

Indice	Tipo	Colonne
`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`

Conservazione dei dati

Gli inserimenti avvengono solo quando Options::ANALYTICS_ENABLED è 1. Un processo di conservazione giornaliero viene eseguito tramite l'hook cron as24ci_daily_cleanup (pianificato all'attivazione, rimosso alla disattivazione). La finestra di conservazione viene configurata tramite la scheda di amministrazione di Analytics.

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

Proprietario: AS24CI\Search_Agent. Creata tramite Search_Agent::maybe_create_table() su init (priorità 1) in modo che sia disponibile sia per i gestori AJAX dell'amministrazione che del frontend. La versione corrente dello schema è 1.1, memorizzata nell'opzione as24ci_search_agent_db_version. La creazione è vincolata dall'interruttore Options::FEATURE_SEARCH_AGENT, ma lo schema viene registrato incondizionatamente quando viene caricata la classe della funzionalità.

Colonne

Colonna	Tipo	Note
`id`	`BIGINT UNSIGNED`	Chiave primaria, incremento automatico.
`name`	`VARCHAR(255)`	Nome visualizzato del visitatore; il valore predefinito è una stringa vuota.
`email`	`VARCHAR(255)`	Indirizzo email del visitatore.
`criteria`	`TEXT`	Criteri di ricerca salvati (rappresentazione serializzata).
`token`	`VARCHAR(64)`	Token per i link di conferma e disiscrizione.
`frequency`	`VARCHAR(20)`	Frequenza delle notifiche; il valore predefinito è `daily`.
`status`	`VARCHAR(20)`	Uno tra `pending`, `active`, `inactive`, `paused`. Il valore predefinito è `pending`.
`created_at`	`DATETIME`	Il valore predefinito è `CURRENT_TIMESTAMP`.
`confirmed_at`	`DATETIME`	Ammette valori nulli; impostato quando il visitatore conferma tramite Double-Opt-In.

Indici

Indice	Tipo	Colonne
`PRIMARY`	Primario	`id`
`idx_status`	Indice	`status`
`idx_token`	Indice	`token`

Privacy

Poiché la tabella contiene dati personali (nome, email, preferenze di ricerca), viene eliminata durante la disinstallazione indipendentemente dall'impostazione as24ci_delete_data_on_uninstall. I gestori del sito sono responsabili di eventuali strumenti aggiuntivi di conservazione o esportazione richiesti dalle normative locali sulla privacy.

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

Proprietario: AS24CI\Content_Studio_Repository. Creata tramite Content_Studio_Repository::maybe_create_tables() (registrato come proprio hook di attivazione nel file principale del plugin e chiamato anche in modo lazy dalla maggior parte dei metodi del repository). Contiene una riga per ogni lavoro di generazione di Content Studio. I valori di stato sono draft, queued, processing, ready e failed.

Colonne

Colonna	Tipo	Note
`id`	`bigint(20) unsigned`	Chiave primaria, incremento automatico.
`vehicle_post_id`	`bigint(20) unsigned`	Articolo del veicolo di origine. Il valore predefinito è `0`.
`vehicle_snapshot_hash`	`varchar(64)`	Hash dello snapshot del veicolo utilizzato per il lavoro.
`content_type`	`varchar(40)`	Tipo di contenuto richiesto.
`platform_preset`	`varchar(40)`	Preset della piattaforma di destinazione.
`output_format`	`varchar(20)`	Formato di output.
`preset_key`	`varchar(80)`	Chiave del catalogo dei preset.
`status`	`varchar(20)`	Il valore predefinito è `draft`.
`prompt_payload`	`longtext`	Payload JSON del prompt. Ammette valori nulli.
`provider`	`varchar(40)`	Il valore predefinito è `google`.
`model`	`varchar(80)`	Modello del fornitore.
`language`	`varchar(20)`	Lingua di output.
`tone`	`varchar(40)`	Tono di voce.
`attempts`	`smallint(5) unsigned`	Tentativi di elaborazione. Il valore predefinito è `0`.
`last_error`	`text`	Ultimo messaggio di errore. Ammette valori nulli.
`created_by`	`bigint(20) unsigned`	ID utente WordPress. Il valore predefinito è `0`.
`created_at`	`datetime`	Il valore predefinito è `CURRENT_TIMESTAMP`.
`updated_at`	`datetime`	Il valore predefinito è `CURRENT_TIMESTAMP`.
`started_at`	`datetime`	Ammette valori nulli.
`completed_at`	`datetime`	Ammette valori nulli.

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

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

Proprietario: AS24CI\Content_Studio_Repository. Contiene gli asset generati (testo, immagini, pacchetti di testi) appartenenti a un lavoro, collegati tramite job_id.

Colonne

Colonna	Tipo	Note
`id`	`bigint(20) unsigned`	Chiave primaria, incremento automatico.
`job_id`	`bigint(20) unsigned`	Lavoro principale. Il valore predefinito è `0`.
`vehicle_post_id`	`bigint(20) unsigned`	Articolo del veicolo di origine. Il valore predefinito è `0`.
`asset_type`	`varchar(40)`	Tipo di asset.
`file_path`	`text`	Percorso del file locale. Ammette valori nulli.
`file_url`	`text`	URL pubblico. Ammette valori nulli.
`mime_type`	`varchar(120)`	Tipo MIME.
`file_size`	`bigint(20) unsigned`	Byte. Il valore predefinito è `0`.
`width`	`int(10) unsigned`	Larghezza dell'immagine. Il valore predefinito è `0`.
`height`	`int(10) unsigned`	Altezza dell'immagine. Il valore predefinito è `0`.
`duration_seconds`	`decimal(8,2)`	Durata del media. Il valore predefinito è `0.00`.
`caption`	`longtext`	Ammette valori nulli.
`hashtags`	`longtext`	Ammette valori nulli.
`alt_text`	`text`	Ammette valori nulli.
`thumbnail_path`	`text`	Ammette valori nulli.
`payload_json`	`longtext`	Payload strutturato (es. pacchetti di testi). Ammette valori nulli.
`scheduled_at`	`datetime`	Ammette valori nulli.
`schedule_status`	`varchar(32)`	Il valore predefinito è `unscheduled`.
`created_at`	`datetime`	Il valore predefinito è `CURRENT_TIMESTAMP`.

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

Tabelle principali di WordPress utilizzate dal plugin

Il plugin non modifica lo schema delle tabelle principali di WordPress. Si affida ad esse come segue:

wp_posts — memorizza gli articoli di as24ci_car (veicoli) e as24ci_lead (lead).
wp_postmeta — memorizza i postmeta di retrocompatibilità per gli articoli dei veicoli (_as24ci_listing_id, _as24ci_content_hash, _as24ci_images_hash, _as24ci_image_ids, _as24ci_manual_image_ids) e lo stato del lead (_as24ci_lead_status).
wp_terms, wp_term_taxonomy, wp_term_relationships — memorizzano le 15 tassonomie dei veicoli registrate da AS24CI\Taxonomies.
wp_options — memorizza tutte le impostazioni del plugin (chiavi definite come costanti su AS24CI\Options) oltre ai marcatori della versione dello schema e agli ID delle pagine create all'attivazione.
wp_users e wp_usermeta — utilizzati indirettamente tramite le funzionalità di WordPress; nessuna scrittura specifica del plugin.

I ruoli e le funzionalità personalizzati creati dal plugin (as24ci_editor, il set di funzionalità as24ci_car/as24ci_cars e manage_as24_imports) sono memorizzati tramite l'opzione standard dei ruoli di WordPress (wp_user_roles).

Comportamento in caso di disinstallazione

Lo script uninstall.php esegue sempre DROP TABLE IF EXISTS per le cinque tabelle personalizzate e rimuove le opzioni corrispondenti alla versione dello schema:

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

Sulle installazioni multisito, lo script passa a ciascun sito e ripete la pulizia. Gli articoli, gli allegati e le pagine create all'attivazione vengono rimossi solo quando l'amministratore ha impostato as24ci_delete_data_on_uninstall su 1.

Note operative

Gli aggiornamenti dello schema sono idempotenti. Ogni classe proprietaria controlla la propria opzione di versione dello schema ed esce rapidamente quando la tabella corrisponde già alla versione prevista. Il repository dei veicoli controlla inoltre che la tabella esista fisicamente prima di uscire rapidamente.
Nel repository, nell'analytics, nel search-agent e nei percorsi del codice di disinstallazione sono presenti query wpdb dirette contro queste tabelle. Esse sono protette da commenti di ignoranza PHPCS dove appropriato. Il codice personalizzato che esclude il repository dovrebbe trattare lo schema come parte del contratto interno del plugin ed essere preparato a modifiche delle colonne tra i rilasci.
Le colonne raw_data, equipment_* e images contengono dati serializzati. Trattateli come blob opachi e accedetevi tramite gli helper del repository quando possibile.
La colonna manual_overrides è l'unico punto che unisce lo stato controllato dall'amministratore e quello controllato dall'importatore. Evitate di scrivervi direttamente senza passare attraverso il livello di override.

Risoluzione dei problemi

maybe_create_table() non ha creato la tabella dei veicoli. Verificare che dbDelta() non abbia segnalato errori. Il repository scrive gli errori su error_log() perché viene eseguito prima che il Logger del plugin sia disponibile. Eseguire nuovamente l'attivazione (disattiva, attiva) esegue nuovamente maybe_create_table().
Manca una nuova colonna dopo un aggiornamento del plugin. Controllare l'opzione della versione dello schema per la tabella interessata. Se è uguale al valore corrente ma la colonna manca, eliminare l'opzione per forzare la riedecuzione di dbDelta al successivo caricamento della pagina di amministrazione. La tabella dei veicoli ha una rete di sicurezza esplicita manual_overrides per questo caso.
La tabella analytics cresce rapidamente. Ridurre la finestra di conservazione o disabilitare l'analytics tramite Options::ANALYTICS_ENABLED. Il lavoro di pulizia giornaliero è necessario per mantenere la tabella entro i limiti.
Le righe di search-agent persistono dopo la disinstallazione. Verificare che WordPress abbia eseguito uninstall.php. Se è stato eseguito solo deactivate() (ad esempio perché il plugin è stato disattivato ma non eliminato), la tabella viene intenzionalmente conservata fino alla disinstallazione.

Quando utilizzare questo documento

Panoramica

Tabella: {$wpdb->prefix}as24_vehicles

Colonne

Indici

Rete di sicurezza per manual_overrides

Tabella: {$wpdb->prefix}as24ci_analytics

Colonne

Indici

Conservazione dei dati

Tabella: {$wpdb->prefix}as24ci_search_agents

Colonne

Indici

Privacy

Tabella: {$wpdb->prefix}as24ci_content_studio_jobs

Colonne

Tabella: {$wpdb->prefix}as24ci_content_studio_assets

Colonne

Tabelle principali di WordPress utilizzate dal plugin

Comportamento in caso di disinstallazione

Note operative

Risoluzione dei problemi

Documenti correlati

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

Rete di sicurezza per `manual_overrides`

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

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

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

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