Documentatie · Technische documentatie

Datamodel

Dit document beschrijft het logische datamodel dat wordt gebruikt door de ADP Car Market Hub-plugin: welke entiteiten er bestaan, hoe ze worden toegewezen aan WordPress-opslag en hoe de verschillende opslaglagen (aangepaste databasetabellen, berichten, postmeta en opties) samenwerken.

Wanneer u dit document moet gebruiken

Lees dit document als u het volgende moet doen:

Begrijpen welke entiteit (voertuig, lead, zoekagent, analytics-gebeurtenis) in welke tabel of welk berichttype leeft.
Beslissen waar u gegevens moet lezen of schrijven bij het bouwen van een aangepaste integratie of rapportage.
Begrijpen hoe voertuigveldgegevens zijn verdeeld tussen de speciale as24_vehicles-tabel en de legacy postmeta-sleutels.

Zie Database Schema voor onbewerkte kolomlijsten. Voor de postmeta-sleutels die worden weergegeven in de metabox-UI van de beheerder, raadpleegt u de import- en templatedocumenten in deze sectie.

Overzicht

De plugin maakt onderscheid tussen vier primaire entiteiten:

Voertuig — een enkele voertuigadvertentie geïmporteerd uit AutoScout24.
Lead — een contactformulier- of aanvraaginzending die (optioneel) gekoppeld is aan een voertuig.
Zoekagent — de opgeslagen zoekcriteria van een bezoeker met e-mailmeldingen.
Analytics-gebeurtenis — een enkele bijgehouden gebeurtenis op de openbare site (paginaweergave, filtergebruik, contact-openen, enz.).

Elke entiteit gebruikt de opslaglaag die het beste past bij het toegangspatroon. Voertuigen zijn verdeeld over WordPress-berichten (voor permalinks, taxonomieën, templates) en een speciale relationele tabel (voor getypeerde kolommen en snelle query's). Leads zijn volledige WordPress-berichten. Zoekagenten en analytics-gebeurtenissen leven in hun eigen aangepaste tabellen.

Voertuig

Een voertuig is de centrale entiteit van de plugin. Het wordt vertegenwoordigd door twee nauw gekoppelde records:

Een WordPress-bericht van het berichttype as24ci_car. Het bericht biedt de permalink (/cars/<slug>/), de titel en de samenvatting, de uitgelichte afbeelding, de editor-inhoud, de toegewezen taxonomietermen en de WordPress-rechtenstructuur.
Een rij in de speciale tabel {$wpdb->prefix}as24_vehicles, eigendom van AS24CI\Vehicle_Repository. De rij bevat de getypeerde voertuigveldgegevens (prijs, kilometerstand, registratiejaar, brandstoftype, uitrusting, enz.), de ruwe API-payload en metadata die worden gebruikt voor wijzigingsdetectie.

De twee records zijn gekoppeld via de post_id-kolom, die een unieke index op de tabel heeft. Elke rij heeft ook een unieke as24_id-kolom die de AutoScout24-advertentie-identificatie bevat.

Waarom een speciale tabel

Voertuigveldgegevens werden oorspronkelijk opgeslagen in wp_postmeta. De plugin heeft deze gegevens verplaatst naar een speciale tabel zodat:

Getypeerde kolommen (decimalen voor prijzen, gehele getallen voor kilometerstand, datums voor eerste registratie) rechtstreeks kunnen worden opgevraagd en gesorteerd zonder de kosten en ambiguïteit van meta_query-joins.
Samengestelde indexen zoals idx_make_model, idx_fuel_condition en idx_status_live de archieffiltering versnellen.
Wijzigingsdetectie (content_hash) zich bevindt naast de gegevens die het beschrijft.

Voor achterwaartse compatibiliteit blijft de importeur een kleine set postmeta-sleutels schrijven; zie de volgende sectie.

Postmeta-sleutels die nog steeds voor voertuigen worden geschreven

Zelfs met de aangepaste tabel op zijn plaats, blijven de volgende postmeta-sleutels bestaan op as24ci_car-berichten. Ze zijn bewust behouden om oudere integraties te laten werken en om regressies in de beheerders-UI, de AI Assistant-wachtrij en de verwijderingsstroom te voorkomen.

Postmeta-sleutel	Betekenis
`_as24ci_listing_id`	AutoScout24-advertentie-identificatie. Weerspiegelt de `as24_id`-kolom in de tabel.
`_as24ci_content_hash`	SHA-achtige hash van de importeerbare inhoud. Wordt gebruikt om ongewijzigde advertenties over te slaan bij herimport.
`_as24ci_images_hash`	Hash van de bronafbeeldingenset. Kan een "pending" sentinel bevatten zolang de afbeeldingenwachtrij nog actief is.
`_as24ci_image_ids`	Array van WordPress-bijlage-ID's voor afbeeldingen die door de plugin zijn geïmporteerd.
`_as24ci_manual_image_ids`	Array van bijlage-ID's die handmatig zijn toegevoegd via de galerijkiezer.
`_as24ci_lead_status`	(Alleen lead-berichten.) Lead-status: `new`, `contacted`, `closed` of `spam`.

Handmatige galerijbijlagen die worden bijgehouden in _as24ci_manual_image_ids worden beschouwd als eigendom van de gebruiker en worden niet verwijderd door de verwijderings- of de-installatiecode van de plugin, zelfs niet wanneer geïmporteerde bijlagen worden verwijderd.

Handmatige overschrijvingen

De voertuigentabel bevat een manual_overrides JSON-kolom. Wanneer een beheerder een voertuigveld bewerkt dat de importeur normaal gesproken beheert, wordt de wijziging opgeslagen als een sleutel/waarde-invoer in deze kolom. De AS24CI\Vehicle_Field_Resolver leest eerst uit de rij en legt daar vervolgens eventuele handmatige overschrijvingen overheen, zodat volgende importacties handmatige bewerkingen niet wissen. De dbDelta-veiligheid in Vehicle_Repository::maybe_create_table() voegt deze kolom toe aan bestaande tabellen als deze ontbreekt.

Voertuigtaxonomieën

as24ci_car-berichten zijn gekoppeld aan 15 niet-hiërarchische taxonomieën geregistreerd door 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.

Taxonomietermen sturen de archieffilters aan en bieden native WordPress -URL's (bijvoorbeeld /as24ci_brand/<slug>/). Veel van dezelfde waarden bestaan ook als gedenormaliseerde kolommen in de voertuigentabel (bijvoorbeeld make, fuel_type, transmission_type) zodat archiefquery's kunnen worden uitgevoerd zonder wp_term_relationships te joinen.

Voertuigrechten

Het berichttype as24ci_car gebruikt aangepaste rechten in de vorm van as24ci_car / as24ci_cars (map_meta_cap is ingeschakeld). Bij activering verleent de plugin deze rechtenset aan beheerders en aan de aangepaste rol as24ci_editor. Beheerders ontvangen daarnaast het recht manage_as24_imports (Plugin::CAP_MANAGE), dat de toegang regelt tot de importeur, instellingen, tools en de log-UI. WordPress "Redacteur"-gebruikers ontvangen standaard geen voertuigrechten.

Lead

Een lead vertegenwoordigt een contactformulier- of aanvraaginzending. Deze wordt opgeslagen als een WordPress-bericht van het berichttype as24ci_lead, geregistreerd door AS24CI\Leads_CPT. Het bericht slaat het bericht van de bezoeker op in de berichtinhoud/samenvatting en de contactgegevens van de afzender in postmeta.

De lead-status wordt opgeslagen in de postmeta-sleutel _as24ci_lead_status en is standaard new. De geldige waarden worden weergegeven als constanten op AS24CI\Leads_CPT:

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

Leads_CPT::get_lead_status() beschermt tegen ongeldige waarden door terug te vallen op new. Leads_CPT::update_lead_status() valideert de inkomende waarde voordat deze wordt geschreven.

Als een lead is verzonden vanaf een voertuigpagina, wordt naar het gerelateerde voertuig verwezen in de postmeta van de lead, zodat het tabblad Leads in het beheer de oorspronkelijke advertentie kan weergeven.

Zoekagent

Een zoekagent vertegenwoordigt de opgeslagen zoekcriteria van een bezoeker met een e-mailabonnement. Zoekagenten worden opgeslagen in de speciale tabel {$wpdb->prefix}as24ci_search_agents, eigendom van AS24CI\Search_Agent.

Elke rij bevat:

name en email — identiteit van de bezoeker.
criteria — de opgeslagen zoekfilters (opgeslagen als tekst).
token — ondoorzichtige token die wordt gebruikt om te bevestigen of af te melden.
frequency — meldingsfrequentie (standaard daily).
status — een van pending, active, inactive of paused, weergegeven als constanten op AS24CI\Search_Agent.
created_at en confirmed_at — tijdstempels voor de AVG-conforme Double-Opt-In-stroom.

Omdat zoekagenten persoonlijke gegevens bevatten, wordt de tabel altijd verwijderd tijdens de-installatie, ongeacht de instelling as24ci_delete_data_on_uninstall.

Analytics-gebeurtenis

Een analytics-gebeurtenis registreert een enkele interactie van een bezoeker (paginaweergave, filtergebruik, contact-openen, enz.). Gebeurtenissen worden opgeslagen in de speciale tabel {$wpdb->prefix}as24ci_analytics, eigendom van AS24CI\Analytics.

Elke rij bevat:

post_id — het gerelateerde voertuigbericht-ID, of 0 for globale gebeurtenissen zoals filterzoekopdrachten.
event_type — de gebeurtenis-identificatie (de toegestane waarden worden gevalideerd tegen de eigen ALLOWED_EVENTS-lijst van de klasse).
extra_data — optionele JSON-gecodeerde payload.
created_at — tijdstempel van de gebeurtenis.

Gebeurtenissen worden alleen geregistreerd wanneer Options::ANALYTICS_ENABLED is ingesteld op 1. Een dagelijkse opschoonactie voor retentie wordt uitgevoerd via de as24ci_daily_cleanup cron-hook. Net als de zoekagent-tabel wordt de analytics-tabel altijd verwijderd tijdens de-installatie omdat deze gegevens voor het volgen van bezoekers kan bevatten.

Door activering beheerde pagina's

Tijdens de activering kan de plugin drie WordPress-pagina's maken die de openbare shortcodes hosten:

Cars ([as24ci_archive]) — de hoofdarchiefpagina voor voertuigen.
Compare Cars ([as24ci_compare]) — de vergelijkingspagina.
Favorites ([as24ci_favorites]) — de favorieten-/verlanglijstpagina.

De ID's worden opgeslagen in de opties as24ci_page_archive_id, as24ci_page_compare_id en as24ci_page_favorites_id. Deze pagina's maken strikt genomen geen deel uit van het datamodel; ze zijn gemaakt zodat de shortcodes een standaardlocatie hebben, en het zijn de enige WordPress-pagina's die de plugin verwijdert tijdens een destructieve de-installatie.

Instellingen (opties)

Alle door de gebruiker configureerbare instellingen worden opgeslagen in wp_options. De sleutels zijn gedefinieerd als constanten op AS24CI\Options. Voorbeelden hiervan zijn:

API en authenticatie: as24ci_base_url, as24ci_token_url, as24ci_seller_ids, as24ci_client_id, as24ci_client_secret, as24ci_token_audience.
Gedrag van de importeur: as24ci_default_post_status, as24ci_default_post_author, as24ci_import_images, as24ci_max_images, as24ci_convert_to_webp, as24ci_webp_quality, as24ci_full_sync.
Planner: as24ci_auto_import_enabled, as24ci_cron_schedule, as24ci_cron_start_time, as24ci_cron_custom_minutes, as24ci_cron_max_vehicles, as24ci_cron_token.
Functieschakelaars: Options::FEATURE_*-constanten voor sitemap, schema, favorieten, vergelijken, sociaal delen, PDF-gegevensblad, zoekagent, analytics, AI Assistant, REST API, dashboardwidget, enz.
Schema-/versiemarkeringen: as24ci_db_version, as24ci_caps_version, as24ci_vehicles_db_version, as24ci_search_agent_db_version.

De volledige inventaris en het gedrag van deze opties is gedocumenteerd in het document Options And Settings Storage.

Transients

De plugin gebruikt een klein aantal transients voor kortstondige status. De meest relevante voor het datamodel zijn:

as24ci_access_token — gecachte AutoScout24 OAuth-toegangstoken.
as24ci_cron_import_running — run-lock die overlappende importacties voorkomt (Scheduler::LOCK_TRANSIENT, ~40 minuten TTL).
as24ci_image_queue_running — run-lock voor de verwerker van de afbeeldingenwachtrij.
as24ci_batch_queue — wachtrij-payload voor de handmatige Batch-Wizard.

Transients worden indien nodig verwijderd tijdens deactivering en de-installatie.

Configuration reference

Storage layer	Owner	Notes
`as24ci_car` post + custom table row	`AS24CI\CPT`, `AS24CI\Vehicle_Repository`	Gekoppeld door `post_id`; één-op-één.
`_as24ci_listing_id`, `_as24ci_content_hash`	`AS24CI\Importer`, `AS24CI\Mapper`	Backwards-compatibele postmeta op voertuigberichten.
`_as24ci_image_ids`, `_as24ci_manual_image_ids`	`AS24CI\Image_Importer`, `AS24CI\CPT`	Geïmporteerde vs handmatige galerij; handmatig wordt nooit verwijderd.
`as24ci_lead` post + postmeta	`AS24CI\Leads_CPT`, `AS24CI\Contact_Form`	Status in `_as24ci_lead_status`.
`{$wpdb->prefix}as24ci_search_agents`	`AS24CI\Search_Agent`	Persoonsgegevens; worden altijd verwijderd bij deinstallatie.
`{$wpdb->prefix}as24ci_analytics`	`AS24CI\Analytics`	Bezoekersgegevens; worden altijd verwijderd bij deinstallatie.
`wp_options` (`as24ci_*`)	`AS24CI\Options`	Instellingen; verwijdering afhankelijk van `as24ci_delete_data_on_uninstall`.
Transients (`as24ci_*`)	diverse	Kortstondige status; gewist bij deactivering/deinstallatie.

Operational notes

Een voertuig bestaat zolang zowel het bericht als de tabelrij bestaan. De AS24CI\Vehicle_Deleter opschoning is gekoppeld tijdens de opbouw van de plugin zodat elk permanent verwijderingstraject (native WP-verwijdering, volledige importersynchronisatie, bulkactie) via dezelfde idempotente stroom verloopt.
De repository houdt een kleine in-process cache bij (object cache-groep as24ci_vehicles, ~1 uur TTL) voor zoekopdrachten in een enkele rij. Directe schrijfacties naar de tabel vanuit aangepaste code omzeilen deze cache; overweeg om deze handmatig te invalideren wanneer u de repository uitbreidt.
De raw_data kolom in de voertuigentabel bewaart de bron-payload van de import. Dit is handig voor het debuggen van mapping-problemen, maar er mag niet op worden vertrouwd als een stabiel contract; de structuur van de payload wordt bepaald door de AutoScout24 API.
Handmatige galerijafbeeldingen worden bewust behandeld als het eigendom van de beheerder. Ze worden niet verwijderd wanneer geïmporteerde afbeeldingen worden verwijderd, en ze worden niet verwijderd tijdens de deinstallatie. Verwijder ze indien nodig handmatig uit de WordPress Mediabibliotheek.

Troubleshooting

**Een voertuig mist veldwaarden in de frontend maar bestaat wel in de berichtenlijst.** Controleer of de voertuigentabel een rij bevat met de overeenkomstige post_id. Als de rij ontbreekt, is de vermelding buiten de importer om aangemaakt of is de migratie naar de aangepaste tabel niet voltooid.
Bewerkingen in de metabox worden overschreven door de volgende import. Controleer of het getroffen veld wordt weggeschreven in de manual_overrides JSON-kolom. De overschrijvingslaag vereist dat de manual_overrides kolom bestaat; de schema-upgrade voegt deze indien nodig toe.
Een geïmporteerde afbeelding verdwijnt. De plugin verwijdert alleen bijlagen die worden bijgehouden in _as24ci_image_ids. Afbeeldingen die zijn toegevoegd via de handmatige galerij (_as24ci_manual_image_ids) blijven behouden. Controleer welke lijst de betreffende bijlage-ID bevat.
**Rijen voor de zoekagent of analytics verschijnen nog steeds na het verwijderen van de plugin.** Controleer of uninstall.php is uitgevoerd. De twee tabellen worden onvoorwaardelijk verwijderd bij deinstallatie. Als de deinstallatie niet is uitgevoerd (bijvoorbeeld omdat de plugin alleen is gedeactiveerd), blijven de rijen aanwezig.