Documentazione · Documentazione tecnica

Documentazione tecnica

Questo documento rappresenta il punto di partenza della documentazione tecnica per il plugin ADP Car Market Hub WordPress. Spiega cosa copre la sezione tecnica, a chi è rivolta e come i singoli documenti si relazionano tra loro.

Quando utilizzare questo documento

Leggi questo documento se sei:

  • Un developer che ha bisogno di capire come è strutturato il plugin prima di personalizzare template, hook o integrazioni.
  • Un amministratore di sito che desidera sapere quali tabelle di database, opzioni ed eventi pianificati utilizza il plugin su un'installazione WordPress.
  • Un integratore che deve pianificare una distribuzione, una revisione dell'ambiente o una revisione della sicurezza del plugin.

Gli utenti finali che desiderano solo gestire gli annunci di veicoli, i lead o le opzioni di design dovrebbero invece iniziare con le sezioni della documentazione rivolte agli utenti.

Panoramica

ADP Car Market Hub è un plugin WordPress che importa gli annunci di veicoli dall'API di AutoScout24 e li pubblica su un sito WordPress. Il plugin è implementato in PHP utilizzando le API core di WordPress (custom post type, tassonomie, opzioni, WP-Cron, REST API, AJAX, transient e tabelle personalizzate gestite da dbDelta).

La documentazione tecnica descrive:

  • L'architettura di alto livello e le responsabilità delle principali classi PHP sotto includes/.
  • La sequenza di bootstrap, i flussi di attivazione, disattivazione e disinstallazione.
  • Il modello dati alla base di veicoli, lead e funzionalità rivolte ai visitatori come i Search Alerts e Analytics.
  • Le tabelle di database personalizzate create tramite dbDelta e le chiavi postmeta che rimangono in wp_postmeta per compatibilità con le versioni precedenti.
  • Le superfici di integrazione (endpoint REST, azioni AJAX, webhook, shortcode, override dei template) su cui altri codici possono basarsi.

I documenti in questa sezione sono materiale di riferimento. Descrivono il comportamento visibile nel codice sorgente del plugin al momento della scrittura. Verifica il comportamento rispetto alla versione corrente del plugin prima di fare affidamento su di esso per il lavoro in produzione.

Requisiti o prerequisiti

Prima di leggere i documenti tecnici dovresti avere:

  • Un ambiente di sviluppo WordPress funzionante che soddisfi i requisiti dichiarati del plugin: WordPress 6.2 o successivo e PHP 8.1 o successivo (vedi l'header del plugin in adp-car-market-hub.php e readme.txt).
  • Una comprensione generale dello sviluppo di plugin WordPress (hook, custom post types, API delle opzioni, WP-Cron e REST API).
  • Familiarità di base con il livello di database di WordPress ($wpdb, dbDelta, postmeta e transient).
  • Accesso all'albero dei sorgenti del plugin se desideri fare riferimenti incrociati alle classi e alle costanti menzionate nella documentazione.

Non sono richiesti account esterni per leggere la documentazione. Per esercitare le funzionalità di importazione nella pratica, hai inoltre bisogno di credenziali API AutoScout24 valide e di almeno un venditore configurato. La configurazione di tali credenziali è trattata nella documentazione di configurazione rivolta agli utenti.

Come è organizzata questa sezione

La documentazione tecnica è suddivisa in documenti mirati. I punti di ingresso più importanti sono elencati di seguito; fai riferimento all'indice della sezione per l'elenco completo.

  1. Panoramica dell'architettura — mappa di alto livello delle classi principali, dei namespace e di come le funzionalità sono collegate tra loro a runtime.
  2. Bootstrap e ciclo di vita del plugin — ordine di esecuzione dal caricamento del plugin fino all'attivazione, alla normale gestione delle richieste e alla disattivazione.
  3. Modello dati — entità logiche (veicoli, lead, agenti di ricerca, eventi di analytics) e come si mappano sullo storage di WordPress.
  4. Schema del database — le tabelle personalizzate gestite da dbDelta create dal plugin, inclusi colonne e indici.

I documenti successivi approfondiscono sottosistemi specifici come l'importatore, la coda delle immagini, l'API REST, le azioni AJAX e il sistema di template.

Convenzioni utilizzate in questa sezione

  • I nomi delle classi sono scritti nella loro forma completamente qualificata utilizzando il namespace AS24CI\ (ad esempio AS24CI\Plugin, AS24CI\Vehicle_Repository).
  • Le chiavi delle opzioni sono racchiuse tra virgolette come stringhe (ad esempio as24ci_db_version) e, ove applicabile, viene fatto riferimento alla costante AS24CI\Options che le definisce.
  • Le tabelle del database sono scritte senza il prefisso della tabella WordPress (ad esempio as24_vehicles); il nome effettivo della tabella su un determinato sito è {$wpdb->prefix} seguito dal suffisso.
  • Gli hook sono indicati tramite il loro tag di azione o filtro (ad esempio as24ci_scheduled_import).

Quando un comportamento è configurabile, la documentazione indica l'opzione, il filtro o la costante che lo controlla. Quando qualcosa non può essere confermato dal codice sorgente, la documentazione lo dice esplicitamente. Verifica qualsiasi caso limite nella versione corrente del plugin prima di pubblicare linee guida per i clienti basate su di esso.

Note operative

  • La documentazione tecnica non include credenziali, dati dei clienti, URL interni, Seller ID o altri valori riservati. I valori di esempio mostrati negli estratti di codice sono presi direttamente dal sorgente del plugin e sono solo illustrativi.
  • Il plugin utilizza un autoloader in stile PSR-4 registrato in adp-car-market-hub.php. Le classi sotto il namespace AS24CI\ vengono caricate da includes/ e includes/admin/ su richiesta. Questo è rilevante quando si aggiungono integrazioni personalizzate che dipendono dalle classi del plugin.
  • Tutte le stringhe traducibili nel plugin utilizzano il text domain adp-car-market-hub. La documentazione tecnica stessa è solo in lingua inglese.

Risoluzione dei problemi

Questo documento introduttivo non descrive guasti specifici. Se stai esaminando un problema, inizia con il documento che copre il sottosistema interessato (ad esempio Eventi Cron e pianificatore per problemi di pianificazione dell'importazione, o Schema del database per errori relativi alle tabelle). Ciascun documento di sottosistema include le proprie note sulla risoluzione dei problemi, ove applicabile.

Documenti correlati