Documentazione · Documentazione tecnica

Panoramica dell'architettura

Questo documento descrive l'architettura di alto livello del plugin ADP Car Market Hub WordPress: come è organizzato l'albero dei sorgenti, quali classi hanno le responsabilità principali e come le funzionalità principali sono collegate tra loro a runtime.

Quando utilizzare questo documento

Leggere questo documento se si ha la necessità di:

Ottenere una panoramica della base di codice PHP del plugin prima di approfondire un sottosistema specifico.
Capire quale classe è responsabile di una determinata funzionalità.
Pianificare una personalizzazione, un'integrazione o una revisione del codice.

Per l'ordine di bootstrap passo-passo, consultare Plugin Bootstrap And Lifecycle. Per i dettagli sull'archiviazione, consultare Data Model e Database Schema.

Panoramica

Il plugin è implementato in PHP e segue le convenzioni standard dei plugin WordPress. Utilizza:

Un singolo file radice (adp-car-market-hub.php) che definisce le costanti del plugin, registra un autoloader e aggancia i callback di bootstrap.
Un namespace PHP AS24CI\ per tutte le classi.
Le API core di WordPress per custom post types, tassonomie, opzioni, WP-Cron, REST API, gestori AJAX e tabelle personalizzate gestite da dbDelta.
Un singleton centrale AS24CI\Plugin che collega ogni funzionalità sull'azione plugins_loaded.

Struttura delle directory di primo livello

Il repository è organizzato come segue (sono elencate solo le directory rilevanti per l'architettura di runtime):

adp-car-market-hub.php — file principale del plugin. Definisce le costanti, registra l'autoloader, carica il text domain, registra gli hook di attivazione/disattivazione, registra gli intervalli personalizzati di WP-Cron e avvia il singleton AS24CI\Plugin su plugins_loaded.
includes/ — classi PHP condivise e frontend, una classe per file. I nomi dei file seguono il pattern class-as24ci-<name>.php e si risolvono nella classe AS24CI\<Name> tramite l'autoloader.
includes/admin/ — classi PHP solo per l'amministrazione (schede delle impostazioni, helper per list-table, widget della bacheca). Risolte dallo stesso autoloader come fallback quando una classe non viene trovata in includes/.
src/Core/Helpers.php — helper procedurali condivisi caricati incondizionatamente dal file principale del plugin.
templates/ — template frontend e parti di template che possono essere sovrascritti dai temi.
assets/ — CSS, JavaScript e immagini per amministrazione e frontend.
languages/ — file di traduzione; il text domain è adp-car-market-hub.
uninstall.php — viene eseguito quando il plugin viene eliminato da WordPress e rimuove le opzioni del plugin e (opzionalmente) i contenuti importati.

Autoloader

adp-car-market-hub.php registra un piccolo autoloader compatibile con PSR-4 per il prefisso AS24CI\. I nomi delle classi vengono convertiti nella convenzione di denominazione dei file class-as24ci-<lower-case-name-with-dashes>.php. L'autoloader cerca prima in includes/ e poi in includes/admin/, il che consente alle classi condivise e a quelle solo per l'amministrazione di condividere un unico namespace.

Classi principali e loro responsabilità

Le seguenti classi costituiscono la spina dorsale del plugin. I nomi sono scritti nella loro forma completa (AS24CI\<Class>).

Bootstrap e servizi condivisi

AS24CI\Plugin — Punto di ingresso Singleton. Costruisce le istanze dei servizi condivisi (Logger, Client, Image_Importer, Vehicle_Repository, Importer, Scheduler), collega tutti gli hook di WordPress per il set di funzionalità attive ed espone i callback statici activate() / deactivate() / init().
AS24CI\Logger — Logger leggero utilizzato in tutto il plugin per i messaggi dell'importatore e dello scheduler.
AS24CI\Options — Registro centralizzato delle chiavi delle opzioni esposte come costanti di classe (es. Options::DB_VERSION, Options::DEFAULT_CURRENCY, Options::AUTO_IMPORT_ENABLED). Lo script uninstall.php utilizza Options::get_all_keys() per ripulire le opzioni alla rimozione del plugin.

Dati e archiviazione

AS24CI\CPT — Registra il custom post type as24ci_car con la mappatura delle capacità personalizzate (as24ci_car / as24ci_cars) e il metabox combinato "AutoScout24 API Import".
AS24CI\Taxonomies — Registra le 15 tassonomie degli attributi dei veicoli collegate a as24ci_car (marca, modello, tipo di carrozzeria, tipo di carburante, cambio, trazione, stato, colore esterno/interno, classe di emissione, etichetta energetica, categoria del veicolo, tipo di garanzia, dettagli della garanzia, disposizione dei cilindri).
AS24CI\Leads_CPT — Registra il custom post type as24ci_lead utilizzato per memorizzare gli invii dei moduli di contatto, con costanti di stato per new, contacted, closed e spam.
AS24CI\Vehicle_Repository — Repository per la tabella personalizzata dedicata {$wpdb->prefix}as24_vehicles che contiene i dati dei campi del veicolo (invece di wp_postmeta). Fornisce la gestione dello schema (maybe_create_table()), helper CRUD e whitelist di filtri/ordinamenti utilizzate da find().
AS24CI\Vehicle_Field_Resolver — Lettore centralizzato che risolve i campi del veicolo combinando i dati del repository con le sovrascritture manuali. Collegato durante la costruzione di Plugin tramite Vehicle_Field_Resolver::set_repository().
AS24CI\Vehicle_Deleter — Percorso di pulizia singolo e idempotente utilizzato ogni volta che un veicolo viene eliminato in modo permanente (eliminazione nativa di WP, eliminazione da sincronizzazione completa dell'importatore, azione di massa). Collegato durante la costruzione di Plugin.

Pipeline di importazione

AS24CI\Client — Client HTTP per l'API AutoScout24. Gestisce l'autenticazione e l'esecuzione delle richieste.
AS24CI\Mapper — Mappa i payload degli annunci AutoScout24 in entrata nella struttura dei campi interni utilizzata dal repository e scrive il postmeta _as24ci_listing_id per compatibilità con le versioni precedenti.
AS24CI\Importer — Coordina l'importazione per singolo annuncio: recupera i dati tramite Client, li trasforma tramite Mapper, persiste i veicoli tramite il repository e traccia il rilevamento delle modifiche attraverso le chiavi postmeta _as24ci_content_hash e _as24ci_images_hash.
AS24CI\Image_Importer — Scarica e allega le immagini dei veicoli, convertendole opzionalmente in WebP. Memorizza gli ID degli allegati nel postmeta _as24ci_image_ids.
AS24CI\Scheduler — Possiede gli hook WP-Cron as24ci_scheduled_import e as24ci_image_queue_process, i transient di blocco dell'esecuzione (as24ci_cron_import_running, as24ci_image_queue_running) e il transient della coda manuale del Batch-Wizard as24ci_batch_queue. Lo stesso flusso run_import() è utilizzato da WP-Cron, dall'endpoint cron REST e dal pulsante "Esegui ora" dell'amministratore.
AS24CI\Cron_Endpoint — Endpoint REST che consente ai server esterni di attivare le importazioni tramite un URL protetto da token.

Frontend, SEO e integrazioni

AS24CI\Templates — Instrada i template dell'archivio veicoli e del singolo veicolo attraverso il caricatore di template del plugin, abilitando le sovrascritture del tema.
AS24CI\Assets — Registra e accoda i bundle CSS e JavaScript per l'amministrazione e il frontend.
AS24CI\Archive_Filters — Visualizza l'interfaccia utente del filtro dell'archivio e applica le modifiche alla query in base alle selezioni dell'utente.
AS24CI\Schema — Aggiunge dati strutturati Schema.org e meta tag Open Graph / Twitter Card alle singole pagine dei veicoli. Opzionale, vincolato da Options::FEATURE_SCHEMA.
AS24CI\Sitemap — Integra i veicoli nella sitemap principale di WordPress ed è compatibile con Yoast e Rank Math. Opzionale, vincolato da Options::FEATURE_SITEMAP.
AS24CI\Social_Share, AS24CI\Pdf_Datasheet, AS24CI\Favorites, AS24CI\Compare, AS24CI\Export, AS24CI\Bulk_Actions, AS24CI\Financing_Calculator, AS24CI\Test_Drive, AS24CI\Search_Agent — Funzionalità opzionali che registrano ciascuna i propri hook. La maggior parte è vincolata da un interruttore Options::FEATURE_* (vedere seed_safe_defaults() in AS24CI\Plugin per i valori predefiniti forniti su una nuova installazione).
AS24CI\Webhooks — Webhook in uscita per casi d'uso di CRM e integrazione.
AS24CI\Rest_Api — API REST pubblica per gli annunci dei veicoli, vincolata da Options::REST_API_ENABLED.
AS24CI\Analytics — Tracciamento delle visualizzazioni di pagina, dei filtri e dei lead. Possiede la tabella {$wpdb->prefix}as24ci_analytics e il cron di conservazione as24ci_daily_cleanup.
AS24CI\Ai_Assistant — Genera descrizioni AI, metadati SEO ed evidenze degli equipaggiamenti utilizzando la configurazione gestita di Google Gemini esposta da AS24CI\Ai_Config. La chiave Gemini del cliente viene consegnata server-to-server dalla API Platform e memorizzata crittografata tramite AS24CI\Ai_Credential_Manager; nessun provider, modello o chiave API è selezionabile nell'interfaccia utente di amministrazione.
AS24CI\Data_Quality_Scanner — Rilevatore opzionale di refusi nelle tassonomie che utilizza l'integrazione AI.
AS24CI\Pricing_Engine — Analisi giornaliera dei prezzi eseguita sull'hook as24ci_pricing_analysis_cron.
AS24CI\Locations, AS24CI\Seller_Profile_Fields — Sedi della concessionaria, orari di apertura e metadati del profilo del venditore.
AS24CI\Team / AS24CI\Admin_Team — CMH Team: contatti di vendita della concessionaria che non richiedono account utente WordPress. L'archiviazione si basa sulle opzioni (nessuna tabella personalizzata o CPT); i contatti sono conservati in Options::TEAM_MEMBERS e nelle relative chiavi di opzione, rispecchiando il pattern Locations. Admin_Team registra un menu di amministrazione dedicato di primo livello.
AS24CI\License_Manager, AS24CI\License_Client, AS24CI\License_Refresh_Signal, AS24CI\License_Signal_Secret — Livello di licenza / accesso gestito della API Platform di ADP Car Market Hub. License_Manager possiede il cron di riconvalida giornaliera (as24ci_license_refresh), l'archiviazione dei diritti sulle funzionalità, il vincolo dei percorsi di scrittura operativi/AI e gli avvisi dell'amministratore. License_Refresh_Signal espone l'endpoint in entrata POST /as24ci/v1/license-refresh-signal.
AS24CI\Ai_Credential_Manager — Memorizza e decrittografa le credenziali Gemini del cliente fornite dalla API Platform.
Content Studio (AS24CI\Content_Studio_*, es. Content_Studio_Repository, Content_Studio_Options, Content_Studio_Admin_Worker, Admin_Tab_Content_Studio) — Un modulo ampiamente autonomo che genera contenuti di marketing a partire dai dati esistenti dei veicoli. Possiede le proprie tabelle (as24ci_content_studio_jobs, as24ci_content_studio_assets), le proprie opzioni as24ci_content_studio_* e un worker in background, ed è avviato dal file principale del plugin anziché dal router Admin. Legge i dati esistenti dei veicoli/importazioni in sola lettura.

Interfaccia utente di amministrazione

AS24CI\Admin — Controller di amministrazione di primo livello, istanziato solo quando is_admin() è vero. Compone internamente le classi delle schede da includes/admin/ (importatore, impostazioni, mappatura, design, layout manager, lead, AI Assistant, stato del sistema, ecc.).
AS24CI\Dashboard_Widget — Widget opzionale della bacheca di WordPress, vincolato da Options::FEATURE_DASHBOARD_WIDGET.

Interruttori delle funzionalità e "prima configurazione sicura"

La maggior parte delle funzionalità non essenziali è registrata in modo condizionale in AS24CI\Plugin::register_hooks() in base a opzioni le cui costanti sono definite su AS24CI\Options (ad esempio FEATURE_SCHEMA, FEATURE_SITEMAP, FEATURE_FAVORITES, FEATURE_COMPARE, FEATURE_PDF_DATASHEET, REST_API_ENABLED, AI_ASSISTANT_ENABLED, ANALYTICS_ENABLED, TEST_DRIVE_ENABLED).

Su una nuova installazione, il plugin inserisce valori predefiniti conservativi tramite AS24CI\Plugin::seed_safe_defaults(). Le funzionalità relative alla privacy, esterne o di elaborazione batch sono disattivate per impostazione predefinita; le funzionalità orientate al frontend (sitemap, schema, preferiti, confronto, calcolatore finanziario, widget della bacheca, esportazione, caricamento differito, layout manager) sono attive per impostazione predefinita. Le installazioni esistenti non vengono mai sovrascritte perché il seeder utilizza add_option().

Struttura di archiviazione (alto livello)

Il plugin utilizza tre livelli di archiviazione:

Tabelle di database personalizzate gestite tramite dbDelta: - {$wpdb->prefix}as24_vehicles — dati dei campi dei veicoli, di proprietà di AS24CI\Vehicle_Repository. - {$wpdb->prefix}as24ci_analytics — eventi di analytics, di proprietà di AS24CI\Analytics. - {$wpdb->prefix}as24ci_search_agents — iscrizioni agli avvisi di ricerca, di proprietà di AS24CI\Search_Agent. - {$wpdb->prefix}as24ci_content_studio_jobs e {$wpdb->prefix}as24ci_content_studio_assets — processi e asset generati di Content Studio, di proprietà di AS24CI\Content_Studio_Repository.
Post e postmeta di WordPress: - I post as24ci_car supportano i permalink, le tassonomie e i template di WordPress per ciascun veicolo. Un piccolo set di chiavi postmeta rimane in wp_postmeta per compatibilità con le versioni precedenti (ad esempio _as24ci_listing_id, _as24ci_content_hash, _as24ci_images_hash, _as24ci_image_ids, _as24ci_manual_image_ids). - I post as24ci_lead memorizzano gli invii dei moduli di contatto con lo stato memorizzato in _as24ci_lead_status.
wp_options — Tutte le impostazioni configurabili dall'utente. Le chiavi sono definite come costanti su AS24CI\Options (e, per Content Studio, su AS24CI\Content_Studio_Options). Le versioni dello schema per le tabelle personalizzate sono memorizzate anch'esse come opzioni (as24ci_db_version, as24ci_vehicles_db_version, as24ci_search_agent_db_version, as24ci_content_studio_db_version). I contatti di CMH Team sono memorizzati anch'essi nelle opzioni (as24ci_team_*).

Per i dettagli a livello di colonna, vedere Database Schema. Per il modello logico delle entità e come interagiscono i postmeta e la tabella personalizzata, vedere Data Model.

Flusso di runtime in sintesi

Una tipica richiesta attraversa le seguenti fasi (semplificate):

WordPress carica adp-car-market-hub.php, che definisce le costanti del plugin, registra l'autoloader e aggiunge intervalli WP-Cron personalizzati.
Su plugins_loaded (priorità 1) viene caricato il text domain.
Su plugins_loaded (priorità predefinita) viene eseguito AS24CI\Plugin::init(), che istanzia il singleton e registra tutti gli hook per le funzionalità attive.
Le classi delle funzionalità registrano i propri hook su init, rest_api_init, wp_ajax_*, wp_footer, ecc.
L'attività successiva (un'esecuzione di cron, una richiesta REST, la visualizzazione di una pagina frontend) viene gestita dagli hook registrati.

Note operative

Il plugin presuppone le versioni di WordPress e PHP dichiarate nell'intestazione del plugin (Requires at least: 6.2, Requires PHP: 8.1). Le versioni inferiori non sono supportate.
La maggior parte dei sottosistemi utilizza wpdb direttamente solo quando dbDelta non può esprimere lo schema o la query richiesti. Le query dirette sono limitate al codice di repository, analytics, search-agent e disinstallazione.
L'architettura mantiene deliberatamente separata la visualizzazione frontend dall'importazione dei dati. L'importatore non esegue mai il rendering dei template; i template non attivano mai richieste di rete verso AutoScout24.
Il plugin aggiunge un link "Impostazioni" alla sua riga nella schermata Plugin di WordPress tramite il filtro plugin_action_links_<basename>.

Risoluzione dei problemi

Una funzionalità non sembra registrarsi. Verificare il corrispondente interruttore Options::FEATURE_*. Il metodo register_hooks() in AS24CI\Plugin salta le funzionalità disabilitate.
Una classe non viene trovata. Verificare la convenzione di denominazione dei file (class-as24ci-<lower-dashed-name>.php) e che il file si trovi in includes/ o includes/admin/. L'autoloader cerca solo in queste due directory.
Si fa riferimento a una classe solo per amministratori dal frontend. Le classi di amministrazione vengono caricate su richiesta dall'autoloader, ma potrebbero fare affidamento su variabili globali o funzionalità riservate all'amministratore. Verificare il comportamento nella versione corrente del plugin prima di dipendere da esso.