Dokumentation · Technische Dokumentation
Datenbankschema
Dieses Dokument beschreibt die benutzerdefinierten Datenbanktabellen, die vom
ADP Car Market Hub-Plugin erstellt werden. Alle Tabellen werden mit dem Hilfsprogramm
dbDelta() von WordPress verwaltet und bei der Plugin-Aktivierung erstellt. Ihre Schema-Versionen
werden in wp_options nachverfolgt, sodass dbDelta bei Upgrades
Spaltenänderungen sicher anwenden kann.
Wann Sie dieses Dokument verwenden sollten
Lesen Sie dieses Dokument, wenn Sie:
- Backups, Aufbewahrungsfristen oder Compliance-Massnahmen für Plugin-Daten planen müssen.
- Benutzerdefinierte Berichte auf Basis der Plugin-Tabellen erstellen möchten.
- Fehlgeschlagene Schema-Upgrades oder fehlende Spalten diagnostizieren müssen.
- Verstehen möchten, welche Tabellen bei der Deinstallation gelöscht werden und welche nicht.
Für das logische Entitätsmodell, das diese Tabellen verwendet, siehe Datenmodell.
Übersicht
Das Plugin erstellt sechs benutzerdefinierte Tabellen:
| Tabellen-Suffix | Zweck | Schema-Version-Option |
|---|---|---|
as24_vehicles | Fahrzeugfelddaten, ersetzt den Grossteil der wp_postmeta-Nutzung. | as24ci_vehicles_db_version |
as24ci_analytics | Analytics-Ereignisse für Fahrzeugseiten und globale Filteraktionen. | as24ci_analytics_db_version |
as24ci_search_agents | Such-Abo-Anmeldungen von Besuchern (Smart Stock Alerts). | as24ci_search_agent_db_version |
as24ci_sync_state | Letzter Sync-Heartbeat pro Fahrzeug (post_id PK, last_sync). | as24ci_sync_state_db_version |
as24ci_content_studio_jobs | Content Studio-Generierungsaufträge (eine Zeile pro Auftrag). | as24ci_content_studio_db_version |
as24ci_content_studio_assets | Generierte Content Studio-Assets, verknüpft mit einem Auftrag über job_id. | as24ci_content_studio_db_version |
Die tatsächlichen Tabellennamen verwenden das WordPress-Präfix {$wpdb->prefix} (normalerweise
wp_). Die Schema-Version der Analytics-Tabelle wird in
as24ci_analytics_db_version (Konstante
AS24CI\Analytics::DB_VERSION_KEY) gespeichert. Die beiden Content Studio-Tabellen
teilen sich eine einzige Schema-Version-Option
(as24ci_content_studio_db_version, aktueller Wert 1.3.0), die auf
AS24CI\Content_Studio_Options::DB_VERSION definiert ist und von
AS24CI\Content_Studio_Repository::maybe_create_tables() verwaltet wird.
Die Tabelle as24ci_sync_state wird verzögert auf admin_init über
AS24CI\Sync_State::maybe_create_table() erstellt (nicht während der
Plugin-Aktivierung) und verfolgt ihre Schema-Version in der
Option as24ci_sync_state_db_version (siehe
includes/class-as24ci-sync-state.php:60 für den Tabellennamen und
:69-91 für den CREATE TABLE). Sie enthält eine Zeile pro Fahrzeug mit
post_id als Primärschlüssel und einer last_sync-Zeitstempelspalte.
Das Plugin stützt sich auch auf die WordPress-Core-Tabellen wp_posts,
wp_postmeta, wp_term_relationships, wp_term_taxonomy und
wp_terms für die Post-Types as24ci_car und as24ci_lead sowie die
15 Fahrzeug-Taxonomien. Diese Tabellen folgen dem Standard-WordPress-Schema
und werden vom Plugin nicht neu definiert.
Alle sechs benutzerdefinierten Tabellen werden bei der Deinstallation automatisch gelöscht (siehe
den Abschnitt Deinstallationsverhalten unten), unabhängig von der
Einstellung as24ci_delete_data_on_uninstall.
Tabelle: {$wpdb->prefix}as24_vehicles
Inhaber: AS24CI\Vehicle_Repository. Erstellt via
Vehicle_Repository::maybe_create_table() bei der Aktivierung und bei nachfolgenden Durchläufen erneut überprüft.
Die aktuelle Schemaversionskonstante ist 1.1,
gespeichert in der Option as24ci_vehicles_db_version.
Die Tabelle enthält eine Zeile pro Fahrzeug, die mit ihrem as24ci_car-Beitrag durch
die Spalte post_id verknüpft ist. Die Spalte as24_id enthält die AutoScout24
Fahrzeug-ID. Beide Spalten verfügen über eindeutige Indizes.
Spalten
| Spalte | Typ | Hinweise |
|---|---|---|
id | bigint(20) unsigned | Primärschlüssel, Auto-Increment. |
post_id | bigint(20) unsigned | WordPress Beitrags-ID für das verknüpfte as24ci_car. Eindeutig. |
as24_id | varchar(64) | AutoScout24 Fahrzeug-ID. Eindeutig. Standardmässig eine leere Zeichenkette. |
seller_id | varchar(64) | AutoScout24 Händler-ID (Seller ID). |
make | varchar(100) | |
model | varchar(100) | |
version_full_name | varchar(255) | Vollständige Modellbezeichnung/Version, wie von der API geliefert. |
condition_type | varchar(50) | Z. B. new, used, demo (Werte spiegeln die Quell-API wider). |
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 | Standardmässig 0. |
seats | tinyint(3) unsigned | Standardmässig 0. |
mileage | int(10) unsigned | Standardmässig 0. |
cubic_capacity | int(10) unsigned | Hubraum. |
range_km | int(10) unsigned | Elektrische Reichweite in Kilometern. |
first_registration | date | Nullwert zulässig (Nullable). |
first_reg_year | smallint(5) unsigned | Jahreskomponente von first_registration. Standardmässig 0. |
power_kw | smallint(5) unsigned | |
power_hp | smallint(5) unsigned | |
co2_emission | smallint(5) unsigned | g/km. |
price | decimal(10,2) | Verkaufspreis. |
list_price | decimal(10,2) | Listenpreis/UVP (falls angegeben). |
currency | char(3) | ISO 4217-Code; standardmässig EUR. |
emission_standard | varchar(20) | Z. B. Euro 6. |
energy_label | char(5) | A-G Energieetikette. |
battery_capacity | decimal(6,2) | kWh. |
vin | varchar(20) | Fahrgestellnummer (VIN). |
status | varchar(30) | Fahrzeugstatus, wie von der API geliefert. |
is_live | tinyint(1) | 1, wenn das Fahrzeug aktuell live ist, andernfalls 0. |
had_accident | tinyint(1) | |
equipment_codes | longtext | JSON-Array mit Ausstattungscodes. Nullwert zulässig. |
equipment_standard | longtext | JSON-Liste der Serienausstattung. Nullwert zulässig. |
equipment_optional | longtext | JSON-Liste der Sonderausstattung. Nullwert zulässig. |
images | longtext | JSON-Liste von Bild-URLs, wie von der API geliefert. |
raw_data | longtext | Vollständige Quell-Payload, die für Diagnosezwecke aufbewahrt wird. |
manual_overrides | longtext | JSON-Objekt mit vom Administrator bearbeiteten Feldern, die importierte Werte überschreiben. |
content_hash | varchar(64) | Hash, der verwendet wird, um Re-Importe von unveränderten Fahrzeugen zu überspringen. |
imported_at | datetime | Standardmässig CURRENT_TIMESTAMP. |
updated_at | datetime | Standardmässig CURRENT_TIMESTAMP. Siehe den Implementierungshinweis unten. |
Implementierungshinweis:
updated_atwird nur mitDEFAULT CURRENT_TIMESTAMPinnerhalb desdbDelta-SQL erstellt, da das direkte Hinzufügen vonON UPDATE CURRENT_TIMESTAMPdazu führt, dassdbDeltabei jedem Laden des Plugins einALTERneu ausgibt. DieON UPDATE-Semantik wird durch ein einmaligesALTERnach der Ausführung vondbDeltaangewendet.
Indizes
| Index | Typ | Spalten | Zweck |
|---|---|---|---|
PRIMARY | Primary | id | Surrogat-Primärschlüssel. |
uk_as24_id | Unique | as24_id | Eine Zeile pro AutoScout24 Fahrzeug. |
uk_post_id | Unique | post_id | Eine Zeile pro WordPress Fahrzeug-Beitrag. |
idx_make_model | Index | make, model | Steuert die Archivfilter für Marke/Modell. |
idx_price | Index | price | Preissortierung und Bereichsfilterung. |
idx_mileage | Index | mileage | Kilometersortierung und Bereichsfilterung. |
idx_first_reg_year | Index | first_reg_year | Jahressortierung und Bereichsfilterung. |
idx_fuel_condition | Index | fuel_type, condition_type | Häufiger kombinierter Filter. |
idx_status_live | Index | status, is_live | Abfragen für Live-Fahrzeuge. |
idx_content_hash | Index | content_hash | Suchen während der Änderungserkennung. |
Sicherheitsnetz für manual_overrides
Nach der Ausführung von dbDelta führt das Repository eine SHOW COLUMNS ... LIKE
'manual_overrides'-Prüfung durch und gibt, falls die Spalte fehlt, ein
explizites ALTER TABLE ... ADD COLUMN manual_overrides longtext DEFAULT
NULL AFTER raw_data aus. Dies kompensiert gelegentliche Probleme bei der Spaltenerkennung
in einigen MySQL/MariaDB-Kombinationen und stellt sicher, dass die manuelle
Überschreibungsebene immer einen Ort zum Speichern von Daten hat.
Tabelle: {$wpdb->prefix}as24ci_analytics
Eigentümer: AS24CI\Analytics. Erstellt via Analytics::maybe_create_table()
während der Aktivierung und bei jedem Laden einer Admin-Seite erneut überprüft (die Methode
ist auch an admin_init gekoppelt, sodass bestehende Installationen neue
Spalten ohne manuelle Reaktivierung übernehmen).
Spalten
| Spalte | Typ | Hinweise |
|---|---|---|
id | bigint(20) unsigned | Primärschlüssel, Auto-Inkrement. |
post_id | bigint(20) unsigned | Fahrzeug-Post-ID. 0 für globale Ereignisse wie Filtersuchen. |
event_type | varchar(20) | Ereignis-ID; standardmässig view. Validiert gegen ALLOWED_EVENTS. |
extra_data | longtext | Optionale JSON-codierte Payload. Nullbar. |
created_at | datetime | Standardmässig CURRENT_TIMESTAMP. |
Indizes
| Index | Typ | Spalten |
|---|---|---|
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 |
Aufbewahrung
Einfügungen erfolgen nur, wenn Options::ANALYTICS_ENABLED auf 1 steht. Ein täglicher
Aufbewahrungs-Job läuft über den Cron-Hook as24ci_daily_cleanup
(geplant bei Aktivierung, entfernt bei Deaktivierung). Das Aufbewahrungsfenster
wird über den Admin-Tab für Analytics konfiguriert.
Tabelle: {$wpdb->prefix}as24ci_search_agents
Eigentümer: AS24CI\Search_Agent. Erstellt via
Search_Agent::maybe_create_table() auf init (Priorität 1), sodass sie
sowohl für Admin- als auch für Frontend-AJAX-Handler verfügbar ist. Die aktuelle
Schemaversion ist 1.1, gespeichert in der
Option as24ci_search_agent_db_version. Die Erstellung wird durch den
Schalter Options::FEATURE_SEARCH_AGENT gesteuert, aber das Schema wird
bedingungslos registriert, wenn die Feature-Klasse geladen wird.
Spalten
| Spalte | Typ | Hinweise |
|---|---|---|
id | BIGINT UNSIGNED | Primärschlüssel, Auto-Inkrement. |
name | VARCHAR(255) | Anzeigename des Besuchers; standardmässig eine leere Zeichenkette. |
email | VARCHAR(255) | E-Mail-Adresse des Besuchers. |
criteria | TEXT | Gespeicherte Suchkriterien (serialisierte Darstellung). |
token | VARCHAR(64) | Token für Bestätigungs- und Abmeldelinks. |
frequency | VARCHAR(20) | Benachrichtigungshäufigkeit; standardmässig daily. |
status | VARCHAR(20) | Einer von pending, active, inactive, paused. Standardmässig pending. |
created_at | DATETIME | Standardmässig CURRENT_TIMESTAMP. |
confirmed_at | DATETIME | Nullbar; wird gesetzt, wenn der Besucher über Double-Opt-In bestätigt. |
Indizes
| Index | Typ | Spalten |
|---|---|---|
PRIMARY | Primary | id |
idx_status | Index | status |
idx_token | Index | token |
Datenschutz
Da die Tabelle personenbezogene Daten enthält (Name, E-Mail, Suchpräferenzen),
wird sie bei der Deinstallation unabhängig von der Einstellung as24ci_delete_data_on_uninstall
gelöscht. Die Website-Betreiber sind für zusätzliche Aufbewahrungs- oder
Export-Tools verantwortlich, die durch lokale Datenschutzvorschriften vorgeschrieben sind.
Tabelle: {$wpdb->prefix}as24ci_sync_state
Eigentümer: AS24CI\Sync_State. Lazy erstellt via
Sync_State::maybe_create_table(), das an admin_init gekoppelt ist
(nicht an den Aktivierungs-Hook), sodass die Tabelle beim ersten Laden der Admin-Seite
nach der Installation/dem Upgrade erscheint. Die Schemaversion wird in der
Option as24ci_sync_state_db_version nachverfolgt. Enthält eine Zeile pro Fahrzeug,
die den Heartbeat der letzten Synchronisierung aufzeichnet; die Methode führt auch eine einmalige
Migration der alten Post-Meta _as24ci_last_sync in diese Tabelle durch.
Siehe includes/class-as24ci-sync-state.php:69-91.
Spalten
| Spalte | Typ | Hinweise |
|---|---|---|
post_id | bigint(20) unsigned | Primärschlüssel. Verknüpfte as24ci_car Post-ID. |
last_sync | bigint(20) unsigned | Unix-Timestamp der letzten Synchronisierung. Standardmässig 0. |
Indizes
| Index | Typ | Spalten |
|---|---|---|
PRIMARY | Primary | post_id |
Tabelle: {$wpdb->prefix}as24ci_content_studio_jobs
Eigentümer: AS24CI\Content_Studio_Repository. Erstellt über
Content_Studio_Repository::maybe_create_tables() (registriert als eigener Aktivierungs-Hook in der Haupt-Plugin-Datei und zudem von den meisten Repository-Methoden verzögert aufgerufen). Enthält eine Zeile pro Content Studio-Generierungsauftrag. Statuswerte sind draft, queued, processing, ready und
failed.
Spalten
| Spalte | Typ | Hinweise |
|---|---|---|
id | bigint(20) unsigned | Primärschlüssel, Auto-Increment. |
vehicle_post_id | bigint(20) unsigned | Quell-Fahrzeug-Post. Standardwert ist 0. |
vehicle_snapshot_hash | varchar(64) | Hash des für den Auftrag verwendeten Fahrzeug-Snapshots. |
content_type | varchar(40) | Angeforderter Inhaltstyp. |
platform_preset | varchar(40) | Zielplattform-Preset. |
output_format | varchar(20) | Ausgabeformat. |
preset_key | varchar(80) | Preset-Katalogschlüssel. |
status | varchar(20) | Standardwert ist draft. |
prompt_payload | longtext | JSON-Prompt-Payload. Nullbar. |
provider | varchar(40) | Standardwert ist google. |
model | varchar(80) | Provider-Modell. |
language | varchar(20) | Ausgabesprache. |
tone | varchar(40) | Tonalität (Tone of voice). |
attempts | smallint(5) unsigned | Verarbeitungsversuche. Standardwert ist 0. |
last_error | text | Letzte Fehlermeldung. Nullbar. |
created_by | bigint(20) unsigned | WordPress Benutzer-ID. Standardwert ist 0. |
created_at | datetime | Standardwert ist CURRENT_TIMESTAMP. |
updated_at | datetime | Standardwert ist CURRENT_TIMESTAMP. |
started_at | datetime | Nullbar. |
completed_at | datetime | Nullbar. |
Indizes: PRIMARY (id), vehicle_post_id, status_created (status, created_at),
platform_preset, content_type.
Tabelle: {$wpdb->prefix}as24ci_content_studio_assets
Eigentümer: AS24CI\Content_Studio_Repository. Enthält die generierten Assets
(Text, Bilder, Copy-Pakete), die zu einem Auftrag gehören, verknüpft über job_id.
Spalten
| Spalte | Typ | Hinweise |
|---|---|---|
id | bigint(20) unsigned | Primärschlüssel, Auto-Increment. |
job_id | bigint(20) unsigned | Übergeordneter Auftrag. Standardwert ist 0. |
vehicle_post_id | bigint(20) unsigned | Quell-Fahrzeug-Post. Standardwert ist 0. |
asset_type | varchar(40) | Asset-Typ. |
file_path | text | Lokaler Dateipfad. Nullbar. |
file_url | text | Öffentliche URL. Nullbar. |
mime_type | varchar(120) | MIME-Typ. |
file_size | bigint(20) unsigned | Bytes. Standardwert ist 0. |
width | int(10) unsigned | Bildbreite. Standardwert ist 0. |
height | int(10) unsigned | Bildhöhe. Standardwert ist 0. |
duration_seconds | decimal(8,2) | Mediendauer. Standardwert ist 0.00. |
caption | longtext | Nullbar. |
hashtags | longtext | Nullbar. |
alt_text | text | Nullbar. |
thumbnail_path | text | Nullbar. |
payload_json | longtext | Strukturierte Payload (z. B. Copy-Pakete). Nullbar. |
scheduled_at | datetime | Nullbar. |
schedule_status | varchar(32) | Standardwert ist unscheduled. |
created_at | datetime | Standardwert ist CURRENT_TIMESTAMP. |
Indizes: PRIMARY (id), job_id, vehicle_post_id, asset_type,
created_at, schedule_status, scheduled_at.
Vom Plugin verwendete WordPress-Core-Tabellen
Das Plugin verändert das Schema der WordPress-Core-Tabellen nicht. Es nutzt diese wie folgt:
wp_posts— speichert Posts füras24ci_car(Fahrzeuge) undas24ci_lead(Leads).wp_postmeta— speichert abwärtskompatible Postmeta-Daten für Fahrzeug-Posts (_as24ci_listing_id,_as24ci_content_hash,_as24ci_images_hash,_as24ci_image_ids,_as24ci_manual_image_ids) und den Lead-Status (_as24ci_lead_status).wp_terms,wp_term_taxonomy,wp_term_relationships— speichern die 15 Fahrzeug-Taxonomien, die durchAS24CI\Taxonomiesregistriert wurden.wp_options— speichert alle Plugin-Einstellungen (Schlüssel definiert als Konstanten inAS24CI\Options) sowie die Schema-Versionsmarker und die IDs der bei der Aktivierung erstellten Seiten.wp_usersundwp_usermeta— werden indirekt über WordPress-Capabilities verwendet; keine Plugin-spezifischen Schreibvorgänge.
Die vom Plugin erstellten benutzerdefinierten Rollen und Capabilities
(as24ci_editor, das as24ci_car/as24ci_cars-Capability-Set und
manage_as24_imports) werden über die standardmässige WordPress-Rollenoption
(wp_user_roles) gespeichert.
Deinstallationsverhalten
Das uninstall.php-Skript führt immer DROP TABLE IF EXISTS für
die sechs benutzerdefinierten Tabellen aus und entfernt die entsprechenden Schema-Versionsoptionen
(uninstall.php:320-330):
{$wpdb->prefix}as24_vehicles(undas24ci_vehicles_db_version){$wpdb->prefix}as24ci_analytics{$wpdb->prefix}as24ci_search_agents(undas24ci_search_agent_db_version){$wpdb->prefix}as24ci_sync_state(undas24ci_sync_state_db_version){$wpdb->prefix}as24ci_content_studio_assets{$wpdb->prefix}as24ci_content_studio_jobs(undas24ci_content_studio_db_version)
Bei Multisite-Installationen wechselt das Skript zu jeder Website und
wiederholt die Bereinigung. Posts, Anhänge und bei der Aktivierung erstellte Seiten
werden nur entfernt, wenn der Administrator
as24ci_delete_data_on_uninstall auf 1 festgelegt hat.
Betriebliche Hinweise
- Schema-Upgrades sind idempotent. Jede Besitzerklasse überprüft ihre Schema-Version-Option und bricht vorzeitig ab, wenn die Tabelle bereits der erwarteten Version entspricht. Das Vehicles-Repository prüft zusätzlich, ob die Tabelle physisch existiert, bevor es vorzeitig abbricht.
- Direkte
wpdb-Abfragen auf diese Tabellen existieren in den Code-Pfaden für Repository, Analytics, Suchaufträge (Search-Agent) und Deinstallation. Sie sind bei Bedarf mit PHPCS-Ignore-Kommentaren geschützt. Eigener Code, der das Repository umgeht, sollte das Schema als Teil des internen Vertrags des Plugins betrachten und auf Spaltenänderungen zwischen den Versionen vorbereitet sein. - Die Spalten
raw_data,equipment_*undimagesenthalten serialisierte Daten. Behandeln Sie diese als opake Blobs und greifen Sie nach Möglichkeit über die Repository-Hilfsmethoden darauf zu. - Die Spalte
manual_overridesist die einzige Stelle, an der vom Administrator gesteuerte und vom Importer gesteuerte Zustände gemischt werden. Vermeiden Sie es, direkt in diese Spalte zu schreiben, ohne die Override-Ebene zu nutzen.
Fehlerbehebung
maybe_create_table()hat die Vehicles-Tabelle nicht erstellt. Vergewissern Sie sich, dassdbDelta()keine Fehler gemeldet hat. Das Repository schreibt Fehler inerror_log(), da es ausgeführt wird, bevor der Plugin-Logger verfügbar ist. Ein erneutes Ausführen der Aktivierung (Deaktivieren, Aktivieren) führtmaybe_create_table()erneut aus.- Eine neue Spalte fehlt nach einem Plugin-Upgrade. Überprüfen Sie die Schema-Version-Option für die betroffene Tabelle. Wenn sie dem aktuellen Wert entspricht, die Spalte aber fehlt, löschen Sie die Option, um zu erzwingen, dass
dbDeltabeim nächsten Laden der Admin-Seite erneut ausgeführt wird. Die Vehicles-Tabelle verfügt für diesen Fall über ein explizitesmanual_overrides-Sicherheitsnetz. - Die Analytics-Tabelle wächst schnell. Reduzieren Sie das Aufbewahrungsfenster oder deaktivieren Sie Analytics über
Options::ANALYTICS_ENABLED. Der tägliche Bereinigungsjob ist erforderlich, um die Tabellengrösse zu begrenzen. - Search-Agent-Zeilen bleiben nach der Deinstallation bestehen. Stellen Sie sicher, dass WordPress
uninstall.phpausgeführt hat. Wenn nurdeactivate()ausgeführt wurde (beispielsweise weil das Plugin deaktiviert, aber nicht gelöscht wurde), bleibt die Tabelle absichtlich bis zur Deinstallation erhalten.