Modello dei dati

Questo documento descrive il modello logico dei dati utilizzato dal plugin ADP Car Market Hub: quali entità esistono, come si mappano sullo spazio di archiviazione di WordPress e come i diversi livelli di archiviazione (tabelle di database personalizzate, post, postmeta e opzioni) lavorano insieme.

Quando usare questo documento

Leggere questo documento se si ha la necessità di:

• Comprendere quale entità (veicolo, lead, agente di ricerca, evento di analytics) risiede in quale tabella o tipo di post.
• Decidere dove leggere o scrivere i dati quando si crea un'integrazione personalizzata o un report.
• Comprendere come i dati dei campi del veicolo sono suddivisi tra la tabella dedicata as24_vehicles e le chiavi postmeta legacy.

Per gli elenchi delle colonne grezze, vedere Database Schema. Per le chiavi postmeta esposte nell'interfaccia utente dei metabox di amministrazione, vedere i documenti di importazione e template in questa sezione.

Panoramica

Il plugin distingue quattro entità primarie:

1. Veicolo — un singolo annuncio di auto importato da AutoScout24.
2. Lead — l'invio di un modulo di contatto o di una richiesta collegato (opzionalmente) a un veicolo.
3. Agente di ricerca — i criteri di ricerca salvati da un visitatore con notifiche e-mail.
4. Evento di Analytics — un singolo evento tracciato sul sito pubblico (visualizzazione pagina, uso dei filtri, apertura contatto, ecc.).

Ogni entità utilizza il livello di archiviazione che meglio si adatta al suo modello di accesso. I veicoli sono suddivisi tra i post di WordPress (per permalink, tassonomie, template) e una tabella relazionale dedicata (per colonne tipizzate e query rapide). I lead sono post completi di WordPress. Gli agenti di ricerca e gli eventi di analytics risiedono nelle proprie tabelle personalizzate.

Veicolo

Il veicolo è l'entità centrale del plugin. È rappresentato da due record strettamente accoppiati:

• Un post di WordPress con tipo di post as24ci_car. Il post fornisce il permalink (/cars/<slug>/), il titolo e l'estratto, l'immagine in evidenza, il contenuto dell'editor, i termini di tassonomia assegnati e la gestione delle funzionalità (WordPress capability surface).
• Una riga nella tabella dedicata {$wpdb->prefix}as24_vehicles, di proprietà di AS24CI\Vehicle_Repository. La riga contiene i dati tipizzati dei campi del veicolo (prezzo, chilometraggio, anno di immatricolazione, tipo di carburante, equipaggiamento, ecc.), il payload grezzo dell'API e i metadati utilizzati per il rilevamento delle modifiche.

I due record sono collegati dalla colonna post_id, che ha un indice unico sulla tabella. Ogni riga ha anche una colonna unica as24_id che contiene l'identificatore dell'annuncio di AutoScout24.

Perché una tabella dedicata

I dati dei campi del veicolo erano originariamente memorizzati in wp_postmeta. Il plugin ha spostato questi dati in una tabella dedicata in modo che:

• Le colonne tipizzate (decimali per i prezzi, interi per il chilometraggio, date per la prima immatricolazione) possano essere interrogate e ordinate direttamente senza il costo e l'ambiguità dei join di meta_query.
• Gli indici composti come idx_make_model, idx_fuel_condition e idx_status_live accelerino il filtraggio degli archivi.
• Il rilevamento delle modifiche (content_hash) risieda accanto ai dati che descrive.

Per compatibilità con le versioni precedenti, l'importatore continua a scrivere un piccolo set di chiavi postmeta; vedere la sezione successiva.

Chiavi postmeta ancora scritte per i veicoli

Anche con la tabella personalizzata attiva, le seguenti chiavi postmeta rimangono sui post di as24ci_car. Sono intenzionalmente preservate per mantenere funzionanti le integrazioni più vecchie ed evitare regressioni nell'interfaccia utente di amministrazione, nella coda di AI Assistant e nel flusso di eliminazione.

Gli allegati manuali della galleria tracciati in _as24ci_manual_image_ids sono trattati come di proprietà dell'utente e non vengono rimossi dal codice di eliminazione o disinstallazione del plugin, anche quando gli allegati importati vengono rimossi.

Sostituzioni manuali

La tabella dei veicoli include una colonna JSON manual_overrides. Quando un amministratore modifica un campo del veicolo che l'importatore normalmente gestisce, la modifica viene memorizzata come voce chiave/valore in questa colonna. Il AS24CI\Vehicle_Field_Resolver legge prima dalla riga e poi sovrappone eventuali sostituzioni manuali, in modo che le importazioni successive non cancellino le modifiche manuali. La protezione dbDelta in Vehicle_Repository::maybe_create_table() aggiunge questa colonna sulle tabelle esistenti se mancante.

Tassonomie dei veicoli

I post di as24ci_car sono collegati a 15 tassonomie non gerarchiche registrate da 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.

I termini di tassonomia alimentano i filtri dell'archivio e forniscono URL nativi di WordPress (ad esempio /as24ci_brand/<slug>/). Molti degli stessi valori esistono anche come colonne denormalizzate nella tabella dei veicoli (ad esempio make, fuel_type, transmission_type) in modo che le query di archivio possano essere eseguite senza join su wp_term_relationships.

Funzionalità dei veicoli (Capabilities)

Il tipo di post as24ci_car utilizza funzionalità personalizzate nella forma as24ci_car / as24ci_cars (con map_meta_cap abilitato). All'attivazione il plugin concede questo set di funzionalità agli amministratori e al ruolo personalizzato as24ci_editor. Gli amministratori ricevono inoltre la funzionalità manage_as24_imports (Plugin::CAP_MANAGE), che controlla l'accesso all'importatore, alle impostazioni, agli strumenti e all'interfaccia utente dei log. Gli utenti "Editor" di WordPress non ricevono le funzionalità dei veicoli per impostazione predefinita.

Lead

Un lead rappresenta l'invio di un modulo di contatto o di una richiesta. Viene memorizzato come un post di WordPress con tipo di post as24ci_lead, registrato da AS24CI\Leads_CPT. Il post memorizza il messaggio del visitatore nel contenuto/estratto del post e i dettagli di contatto del mittente nei postmeta.

Lo stato del lead è memorizzato nella chiave postmeta _as24ci_lead_status e ha come valore predefinito new. I valori validi sono esposti come costanti su AS24CI\Leads_CPT:

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

Leads_CPT::get_lead_status() protegge da valori non validi ripristinando il valore predefinito new. Leads_CPT::update_lead_status() convalida il valore in entrata prima di scriverlo.

Se un lead è stato inviato da una pagina di un veicolo, il veicolo correlato viene indicato nei postmeta del lead in modo che la scheda Lead dell'amministratore possa mostrare l'annuncio di origine.

Agente di ricerca

Un agente di ricerca rappresenta i criteri di ricerca salvati da un visitatore con un abbonamento e-mail. Gli agenti di ricerca sono memorizzati nella tabella dedicata {$wpdb->prefix}as24ci_search_agents, di proprietà di AS24CI\Search_Agent.

Ogni riga contiene:

• name e email — identità del visitatore.
• criteria — i filtri di ricerca salvati (memorizzati come testo).
• token — token opaco utilizzato per confermare o annullare l'iscrizione.
• frequency — frequenza delle notifiche (predefinita su daily).
• status — uno tra pending, active, inactive o paused, esposti come costanti su AS24CI\Search_Agent.
• created_at e confirmed_at — timestamp per il flusso di Double-Opt-In conforme al GDPR.

Poiché gli agenti di ricerca contengono dati personali, la tabella viene sempre eliminata durante la disinstallazione, indipendentemente dall'impostazione di as24ci_delete_data_on_uninstall.

Evento di Analytics

Un evento di analytics registra una singola interazione del visitatore (visualizzazione pagina, uso dei filtri, apertura contatto, ecc.). Gli eventi sono memorizzati nella tabella dedicata {$wpdb->prefix}as24ci_analytics, di proprietà di AS24CI\Analytics.

Ogni riga contiene:

• post_id — l'ID del post del veicolo correlato, o 0 per eventi globali come le ricerche con filtri.
• event_type — l'identificatore dell'evento (i valori consentiti sono convalidati rispetto all'elenco ALLOWED_EVENTS della classe stessa).
• extra_data — payload opzionale codificato in JSON.
• created_at — timestamp dell'evento.

Gli eventi vengono registrati solo quando Options::ANALYTICS_ENABLED è impostato su 1. Una pulizia giornaliera per la conservazione dei dati viene eseguita tramite l'hook cron as24ci_daily_cleanup. Come la tabella degli agenti di ricerca, la tabella di analytics viene sempre eliminata durante la disinstallazione perché può contenere dati di tracciamento dei visitatori.

Pagine gestite all'attivazione

Durante l'attivazione, il plugin può creare tre pagine di WordPress che ospitano gli shortcode visibili al pubblico:

• Cars ([as24ci_archive]) — la pagina principale dell'archivio veicoli.
• Compare Cars ([as24ci_compare]) — la pagina di confronto.
• Favorites ([as24ci_favorites]) — la pagina dei preferiti/lista dei desideri.

Gli ID sono memorizzati nelle opzioni as24ci_page_archive_id, as24ci_page_compare_id e as24ci_page_favorites_id. Queste pagine non fanno strettamente parte del modello dei dati; vengono create in modo che gli shortcode abbiano una sede predefinita, e sono le uniche pagine di WordPress che il plugin rimuove durante una disinstallazione distruttiva.

Impostazioni (opzioni)

Tutte le impostazioni configurabili dall'utente sono memorizzate in wp_options. Le chiavi sono definite come costanti su AS24CI\Options. Gli esempi includono:

• API e autenticazione: as24ci_base_url, as24ci_token_url, as24ci_seller_ids, as24ci_client_id, as24ci_client_secret, as24ci_token_audience.
• Comportamento dell'importatore: as24ci_default_post_status, as24ci_default_post_author, as24ci_import_images, as24ci_max_images, as24ci_convert_to_webp, as24ci_webp_quality, as24ci_full_sync.
• Pianificatore (Scheduler): as24ci_auto_import_enabled, as24ci_cron_schedule, as24ci_cron_start_time, as24ci_cron_custom_minutes, as24ci_cron_max_vehicles, as24ci_cron_token.
• Attivazione funzionalità (Feature toggles): costanti Options::FEATURE_* per sitemap, schema, preferiti, confronto, condivisione social, PDF datasheet, agente di ricerca, analytics, AI Assistant, REST API, widget della bacheca, ecc.
• Indicatori di schema/versione: as24ci_db_version, as24ci_caps_version, as24ci_vehicles_db_version, as24ci_search_agent_db_version.

L'inventario completo e il comportamento di queste opzioni sono documentati nel documento Options And Settings Storage.

Transient

Il plugin utilizza un piccolo numero di transient per gli stati a breve termine. I più rilevanti per il modello dei dati sono:

• as24ci_access_token — token di accesso OAuth di AutoScout24 memorizzato in cache.
• as24ci_cron_import_running — blocco di esecuzione (run-lock) che impedisce importazioni sovrapposte (Scheduler::LOCK_TRANSIENT, TTL di circa 40 minuti).
• as24ci_image_queue_running — blocco di esecuzione per il worker della coda delle immagini.
• as24ci_batch_queue — payload della coda per la procedura guidata batch manuale (Batch-Wizard).

I transient vengono eliminati durante la disattivazione e la disinstallazione, a seconda dei casi.

---

Riferimento di configurazione

Note operative

• Un veicolo esiste finché esistono sia il suo post sia la riga della tabella. La pulizia di AS24CI\Vehicle_Deleter è collegata durante la costruzione del plugin in modo che ogni percorso di eliminazione permanente (eliminazione nativa di WP, sincronizzazione completa dell'importatore, azione di massa) passi attraverso lo stesso flusso idempotente.
• Il repository mantiene una piccola cache in-process (gruppo di cache degli oggetti as24ci_vehicles, TTL di circa 1 ora) per le ricerche su singola riga. Le scritture dirette sulla tabella da codice personalizzato bypassano questa cache; valutare di invalidarla manualmente quando si estende il repository.
• La colonna raw_data nella tabella dei veicoli conserva il payload sorgente dell'importazione. Questo è utile per il debug dei problemi di mappatura, ma non deve essere considerato come un contratto stabile; la struttura del payload è determinata dall'API AutoScout24.
• Le immagini della galleria manuale sono trattate deliberatamente come proprietà dell'amministratore. Non vengono rimosse quando vengono eliminate le immagini importate e non vengono rimosse durante la disinstallazione. Se necessario, rimuoverle manualmente dalla Libreria media di WordPress.

Risoluzione dei problemi

• Un veicolo non presenta i valori dei campi sul frontend ma esiste nell'elenco dei post. Verificare che la tabella dei veicoli contenga una riga con il corrispondente post_id. Se la riga è assente, l'annuncio è stato creato al di fuori dell'importatore o la migrazione alla tabella personalizzata non è stata completata.
• Le modifiche nel metabox vengono sovrascritte dall'importazione successiva. Verificare che il campo interessato venga scritto nella colonna JSON manual_overrides. Il livello di sovrascrittura richiede l'esistenza della colonna manual_overrides; l'aggiornamento dello schema la aggiunge se necessario.
• Un'immagine importata scompare. Il plugin elimina solo gli allegati tracciati in _as24ci_image_ids. Le immagini che sono state aggiunte tramite la galleria manuale (_as24ci_manual_image_ids) vengono conservate. Verificare quale elenco contiene l'ID dell'allegato interessato.
• Le righe degli agenti di ricerca o di analytics appaiono ancora dopo aver eliminato il plugin. Verificare che uninstall.php sia stato eseguito. Le due tabelle vengono rimosse incondizionatamente alla disinstallazione. Se la disinstallazione non è stata eseguita (ad esempio perché il plugin è stato solo disattivato), le righe rimangono al loro posto.

Documenti correlati

• Panoramica dell'architettura
• Bootstrap e ciclo di vita del plugin
• Schema del database
• Panoramica della sezione