Dokumentation · Technische Dokumentation
Datenbankschema
Dieses Dokument beschreibt die benutzerdefinierten Datenbanktabellen, die vom
ADP Car Market Hub-Plugin erstellt werden. Alle Tabellen werden mit dem
dbDelta()-Helper von WordPress verwaltet und bei der Plugin-Aktivierung erstellt. Ihre Schemaversionen
werden in wp_options nachverfolgt, sodass dbDelta Spaltenänderungen
bei Upgrades sicher anwenden kann.
Wann Sie dieses Dokument lesen sollten
Lesen Sie dieses Dokument, wenn Sie:
- Backups, Aufbewahrungsfristen oder Compliance-Arbeiten für Plugin-Daten planen müssen.
- Eigene 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 fünf benutzerdefinierte Tabellen:
| Tabellen-Suffix | Verwendungszweck | Schemaversion-Option |
|---|---|---|
as24_vehicles | Fahrzeug-Felddaten, 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 | Suchabo-Registrierungen von Besuchern (Smart Stock Alerts). | as24ci_search_agent_db_version |
as24ci_content_studio_jobs | Content Studio-Generierungsaufträge (eine Zeile pro Auftrag). | as24ci_content_studio_db_version |
as24ci_content_studio_assets | Im Content Studio generierte 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 Schemaversion der Analytics-Tabelle wird in
as24ci_analytics_db_version gespeichert (Konstante
AS24CI\Analytics::DB_VERSION_KEY). Die beiden Content Studio-Tabellen
teilen sich eine einzige Schemaversion-Option
(as24ci_content_studio_db_version, aktueller Wert 1.3.0), die in
AS24CI\Content_Studio_Options::DB_VERSION definiert ist und von
AS24CI\Content_Studio_Repository::maybe_create_tables() verwaltet wird.
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 Custom 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 fünf benutzerdefinierten Tabellen werden bei der Deinstallation automatisch gelöscht (siehe
den Abschnitt Verhalten bei Deinstallation unten), unabhängig von der
as24ci_delete_data_on_uninstall-Einstellung.
Tabelle: {$wpdb->prefix}as24_vehicles
Eigentümer: AS24CI\Vehicle_Repository. Erstellt via
Vehicle_Repository::maybe_create_table() bei der Aktivierung und bei nachfolgenden Durchläufen erneut überprüft.
Die aktuelle Schemaversions-Konstante ist 1.1,
gespeichert in der Option as24ci_vehicles_db_version.
Die Tabelle enthält eine Zeile pro Fahrzeug, die über die Spalte post_id mit ihrem as24ci_car-Post verknüpft ist.
Die Spalte as24_id enthält die AutoScout24-Inseratskennung.
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-Post-ID für das verknüpfte as24ci_car. Eindeutig. |
as24_id | varchar(64) | AutoScout24-Inseratskennung. Eindeutig. Standardmässig eine leere Zeichenkette. |
seller_id | varchar(64) | AutoScout24-Verkäuferkennung (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 des Motors. |
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) | Energieetikette A-G. |
battery_capacity | decimal(6,2) | kWh. |
vin | varchar(20) | Fahrgestellnummer (VIN). |
status | varchar(30) | Inseratsstatus, wie von der API geliefert. |
is_live | tinyint(1) | 1, wenn das Inserat 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 unveränderter Inserate 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 einALTERerneut ausgibt. DieON UPDATE-Semantik wird über 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-Inserat. |
uk_post_id | Unique | post_id | Eine Zeile pro WordPress-Fahrzeug-Post. |
idx_make_model | Index | make, model | Steuert die Archivfilter für Marke/Modell. |
idx_price | Index | price | Preissortierung / Preisspannen-Filterung. |
idx_mileage | Index | mileage | Kilometersortierung / Kilometerbereichs-Filterung. |
idx_first_reg_year | Index | first_reg_year | Jahressortierung / Jahresbereichs-Filterung. |
idx_fuel_condition | Index | fuel_type, condition_type | Häufiger kombinierter Filter. |
idx_status_live | Index | status, is_live | Abfragen für Live-Inserate. |
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 der 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-Increment. |
post_id | bigint(20) unsigned | Fahrzeug-Post-ID. 0 für globale Ereignisse wie Filtersuchen. |
event_type | varchar(20) | Ereigniskennung; standardmässig view. Validiert gegen ALLOWED_EVENTS. |
extra_data | longtext | Optionale JSON-codierte Payload. Nullwert zulässig. |
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 (Retention)
Einträge erfolgen nur, wenn Options::ANALYTICS_ENABLED auf 1 gesetzt ist. Ein täglicher
Bereinigungsjob läuft über den WP-Cron-Hook as24ci_daily_cleanup
(bei der Aktivierung geplant, bei der Deaktivierung entfernt). Das Aufbewahrungsfenster
wird über den Admin-Tab für Analytics konfiguriert.
Tabelle: {$wpdb->prefix}as24ci_search_agents
Eigentümer: AS24CI\Search_Agent. Erstellt über
Search_Agent::maybe_create_table() bei 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-Increment. |
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 (Name, E-Mail, Suchpräferenzen)
enthält, 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_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 auch verzögert von
den meisten Repository-Methoden aufgerufen). Enthält eine Zeile pro Content Studio-Generierungsjob.
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. Standardmässig 0. |
vehicle_snapshot_hash | varchar(64) | Hash des für den Job 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) | Standardmässig draft. |
prompt_payload | longtext | JSON-Prompt-Payload. Nullbar. |
provider | varchar(40) | Standardmässig google. |
model | varchar(80) | Provider-Modell. |
language | varchar(20) | Ausgabesprache. |
tone | varchar(40) | Tonalität (Tone of voice). |
attempts | smallint(5) unsigned | Verarbeitungsversuche. Standardmässig 0. |
last_error | text | Letzte Fehlermeldung. Nullbar. |
created_by | bigint(20) unsigned | WordPress-Benutzer-ID. Standardmässig 0. |
created_at | datetime | Standardmässig CURRENT_TIMESTAMP. |
updated_at | datetime | Standardmässig 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, Textpakete), die zu einem Job 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 Job. Standardmässig 0. |
vehicle_post_id | bigint(20) unsigned | Quell-Fahrzeug-Post. Standardmässig 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. Standardmässig 0. |
width | int(10) unsigned | Bildbreite. Standardmässig 0. |
height | int(10) unsigned | Bildhöhe. Standardmässig 0. |
duration_seconds | decimal(8,2) | Mediendauer. Standardmässig 0.00. |
caption | longtext | Nullbar. |
hashtags | longtext | Nullbar. |
alt_text | text | Nullbar. |
thumbnail_path | text | Nullbar. |
payload_json | longtext | Strukturierte Payload (z. B. Textpakete). Nullbar. |
scheduled_at | datetime | Nullbar. |
schedule_status | varchar(32) | Standardmässig unscheduled. |
created_at | datetime | Standardmässig 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 ändert das Schema der WordPress-Core-Tabellen nicht. Es verlässt sich wie folgt auf sie:
wp_posts— speichertas24ci_car(Fahrzeuge) undas24ci_lead(Leads) Posts.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 aufAS24CI\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 Capability-Set as24ci_car/as24ci_cars und
manage_as24_imports) werden über die standardmässige WordPress-Rollenoption
(wp_user_roles) gespeichert.
Deinstallationsverhalten
Das Skript uninstall.php führt immer DROP TABLE IF EXISTS für
die fünf benutzerdefinierten Tabellen aus und entfernt die entsprechenden Schema-Versionsoptionen:
{$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_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 gesetzt hat.
Betriebliche Hinweise
- Schema-Upgrades sind idempotent. Jede Eigentümerklasse überprüft ihre Schema-Versionsoption und bricht vorzeitig ab, wenn die Tabelle bereits der erwarteten Version entspricht. Das Fahrzeug-Repository prüft zusätzlich, ob die Tabelle physisch existiert, bevor es vorzeitig abbricht.
- Direkte
wpdb-Abfragen gegen diese Tabellen existieren im Repository-, Analytics-, Suchagenten- und Deinstallations-Codepfad. Sie sind gegebenenfalls mit PHPCS-Ignore-Kommentaren geschützt. Benutzerdefinierter Code, der das Repository umgeht, sollte das Schema als Teil des internen Vertrags des Plugins betrachten und auf Spaltenänderungen zwischen den Releases 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 Fahrzeugtabelle nicht erstellt. Stellen Sie sicher, 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-Versionsoption für die betroffene Tabelle. Wenn sie dem aktuellen Wert entspricht,
aber die Spalte fehlt, löschen Sie die Option, um zu erzwingen, dass
dbDeltabeim nächsten Laden der Admin-Seite erneut ausgeführt wird. Die Fahrzeugtabelle verfügt für diesen Fall über ein explizitesmanual_overrides-Sicherheitsnetz. - Die Analytics-Tabelle wächst schnell. Verringern Sie das Aufbewahrungsfenster
oder deaktivieren Sie Analytics über
Options::ANALYTICS_ENABLED. Der tägliche Bereinigungsjob ist erforderlich, um die Tabelle in Grenzen zu halten. - Suchagenten-Zeilen bleiben nach der Deinstallation bestehen. Überprüfen Sie, ob
WordPress die Methode
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.