Konzepte

Diese Seite erklärt das Gedankenmodell hinter dem Erweiterten Analytics Dashboard — was die wichtigsten Begriffe bedeuten, wie die Teile zusammenpassen und warum bestimmte Designentscheidungen so getroffen wurden. Lesen Sie dies, bevor Sie in die Konfigurationsreferenz eintauchen, wenn Sie das "Warum" und nicht nur das "Was" verstehen möchten.

Die Kernidee: ein Chart-Builder statt vorgefertigter Berichte

Die meisten Analytics-Plugins liefern eine feste Auswahl an vorgefertigten Berichten. Das Erweiterte Analytics Dashboard verfolgt den entgegengesetzten Ansatz: Es bietet einen Chart-Builder mit einem visuellen Filtersystem. Sie wählen eine Datenquelle, konfigurieren Metrik und Filter, und der Chart wird sofort gerendert. So können Sie Fragen beantworten, die der Plugin-Entwickler nie vorhergesehen hat — "Wie viele Bestellungen verwendeten Zahlungsart X in Verkaufskanal Y im letzten Quartal?" — ohne auf ein Plugin-Update warten zu müssen.

Der Kompromiss: Sie investieren einige Minuten in die Konfiguration im Vorfeld. Die eingebetteten Demo-Charts sollen diesen Aufwand am ersten Tag so gering wie möglich halten.

Charts

Ein Chart ist die grundlegende Einheit. Er umfasst:

• Datenquelle — welche Shopware-Entität abgefragt wird (Bestellungen, Kunden, Produkte, Positionen).
• Metrik — was gemessen wird (Anzahl, Summe eines Felds, Durchschnitt eines Felds).
• Filter — Bedingungen, die die Abfrage einschränken (z. B. nur Bestellungen in einem bestimmten Verkaufskanal).
• Zeitraum — das Zeitfenster, das die Abfrage abdeckt.
• Zeitgranularität — wie Zeit unterteilt wird (Tag, Woche, Monat, Quartal, Jahr).
• Aufschlüsselung (optional) — eine Eigenschaft, nach der das Ergebnis in mehrere Datenreihen aufgeteilt wird.
• Visualisierungstyp — wie das Ergebnis dargestellt wird (Linie, Balken, Kreis, Donut, Zahl, Tabelle).

Charts werden unabhängig von Berichten gespeichert. Ein einzelner Chart kann gleichzeitig in mehreren Berichten erscheinen.

Chart-Übersetzungen

Chart-Titel und -Beschreibungen sind übersetzbar. Wenn Ihr Shop mehrere Sprachen unterstützt, können Sie für denselben Chart einen deutschen und einen englischen Titel eingeben. Die Admin-Benutzeroberfläche zeigt den Titel in der aktuell aktiven Sprache.

Berichte

Ein Bericht ist eine benannte Sammlung von Charts, die in einem Raster angezeigt werden. Er ist die Einheit, die Sie teilen, anzeigen und exportieren. Berichte sind ebenfalls übersetzbar — der Berichtsname kann je nach Sprache unterschiedlich sein.

Berichte haben zwei Konfigurationsbereiche:

• Welche Charts enthalten sind und in welcher Reihenfolge.
• Wie breit jeder Chart ist — die Spaltenbreite pro Chart, gespeichert im layout-Feld des Berichts als chartSpans.

Das Entfernen eines Charts aus einem Bericht löscht den Chart nicht aus der Bibliothek.

Der Übersichtsbericht

Ein Bericht kann in den Plugin-Einstellungen als Übersichtsbericht festgelegt werden. Dieser Bericht öffnet sich automatisch, wenn Sie zum Analytics-Modul navigieren. Er wird auch aus der regulären Berichtsliste ausgeblendet, damit er nicht doppelt erscheint. Dies ist der richtige Platz für Ihre wichtigsten täglichen Monitoring-Charts.

Datenquellen

Jede Datenquelle entspricht einer Shopware-Entität:

Datenquelle	Entität	Was gezählt/summiert/gemittelt wird
Bestellungen	order	Bestelldatensätze und ihre monetären Felder
Kunden	customer	Kundendatensätze
Produkte	product	Produktdatensätze und ihre Lager-/Preisfelder
Positionen	order_line_item	Einzelne Positionen innerhalb von Bestellungen

Daten werden immer aus der Live-Shopware-Datenbank über den DAL gelesen. Es gibt keine Datensynchronisierung oder Vorabaggregation — Charts spiegeln den aktuellen Zustand Ihrer Shop-Daten wider.

Das Filtersystem

Filter sind das leistungsstärkste Merkmal des Plugins. Sie verwenden dieselbe UND-Logik wie das eigene Regelsystem von Shopware: jede Bedingung in einer Filterliste muss erfüllt sein, damit ein Datensatz einbezogen wird.

Jede Filterzeile besteht aus drei Teilen:

1. Eigenschaft — welches Feld gefiltert werden soll (z. B. sales_channel_id, state_id, affiliate_code).
2. Operator — wie verglichen wird (gleich, ungleich, enthält, größer als usw.).
3. Wert — das Vergleichsziel (Entitätsauswahl, Boolean-Umschalter oder Freitext/Zahl, je nach Eigenschaftstyp).

Die verfügbaren Operatoren für eine Eigenschaft werden durch ihren Typ bestimmt. Entitätseigenschaften (wie Verkaufskanäle oder Währungen) verwenden gleich/ungleich/ist gesetzt/ist nicht gesetzt mit nativen Shopware-Entitätsauswahl-Komponenten.

Initialfilter

Einige Datenquellen stellen Initialfilter bereit — Admin-Bereich-Steuerelemente, die als Badges oberhalb des Charts erscheinen, getrennt von der gespeicherten Filterkonfiguration des Charts. Die aktuelle Implementierung enthält einen Verkaufskanal-Selektor auf dem Dashboard und in Berichtsansichten. Initialfilter werden bei der Abfrage mit den gespeicherten Filtern des Charts zusammengeführt; sie überschreiben die gespeicherte Konfiguration nicht.

Spaltenbreiten und der Ziehpunkt

Jeder Chart in einem Bericht oder auf dem Dashboard hat eine Spaltenbreite — wie viele Rasterspalten er einnimmt. Die Breite ist pro Chart unabhängig und wird separat von der Chart-Konfiguration gespeichert:

• In Berichten: Breiten werden in ssd_analytic.layout.chartSpans gespeichert (eine JSON-Map von chartId → Breite).
• Auf dem Dashboard: Breiten werden pro Admin-Benutzer in den Browser-Benutzereinstellungen gespeichert, sodass jeder Admin sein eigenes Layout hat.

Der Ziehpunkt am rechten Rand von Chart-Karten in der Bearbeitungsansicht rastet an Spaltengrenzen ein. Eine FLIP-Animation ordnet benachbarte Karten während des Ziehens fließend neu an.

Standardbreiten ohne gespeicherte Einstellung: Zahlenkarten → 1 Spalte; Tabellen → volle Breite; alle anderen Typen → 2 Spalten.

Zeitraum-Voreinstellungen und benutzerdefinierte Zeiträume

Voreinstellungen wie "Letzte 30 Tage" und "Diesen Monat" werden zum Abfragezeitpunkt auf dem Server zu konkreten {start, end}-Zeitstempeln aufgelöst. Benutzerdefinierte Zeiträume verwenden die expliziten Werte date_range_start / date_range_end, die in der Chart-Entität gespeichert sind.

Wenn Vorperiode vergleichen aktiviert ist, berechnet das Backend automatisch den passenden Vorperiodenzeitraum: "Letzte 30 Tage" vergleicht mit den 30 Tagen davor; "Dieser Monat" vergleicht mit dem letzten Monat; benutzerdefinierte Zeiträume verschieben sich um dieselbe Dauer zurück.

Vorperioden-Vergleich und der Delta-Badge

Bei Zahlenkarten treibt der Vorperiodenwert einen Delta-Badge an, der die Änderung von einer Periode zur nächsten anzeigt:

• Ein grüner Aufwärts-Badge für positive Änderungen.
• Ein roter Abwärts-Badge für negative Änderungen.
• Der Badge zeigt einen Prozentsatz (z. B. +12,3 %), wenn der Vorperiodenwert ungleich null ist. Wenn der Vorperiodenwert null ist, wird nur das absolute Delta angezeigt (Prozentdivision durch null wird unterdrückt).

Bei Linien- und Balken-Charts erscheint die Vorperiode als zweite gestrichelte Datenreihe, die über der aktuellen Periode überlagert wird.

Aufschlüsselung

Eine Aufschlüsselung teilt die Daten eines Charts nach einer Dimension auf und macht aus einem einfachen Linien-Chart mehrere Linien — eine pro Segment. Zum Beispiel zeigt ein Umsatz-Chart, der nach sales_channel_id aufgeschlüsselt wird, eine Linie pro Verkaufskanal.

In dieser Version wird nur eine Aufschlüsselung pro Chart unterstützt. Verfügbare Aufschlüsselungseigenschaften unterscheiden sich je nach Datenquelle.

Segmente mit einem null-Wert für die Aufschlüsselungseigenschaft werden unter einer konfigurierten Null-Bezeichnung zusammengefasst (z. B. "Direkt / Organisch" für campaign_code), sodass sie sichtbar bleiben, anstatt stillschweigend weggelassen zu werden.

ACL und Zugriffskontrolle

Das Plugin verwendet das eingebaute ACL-System von Shopware. Der Zugriff wird durch vier Rollen auf der ssd_analytic-Ressource gesteuert:

• Betrachter — erforderlich, um das Analytics-Menü zu sehen und Daten zu lesen. Jeder Benutzer ohne diese Rolle sieht den Analytics-Eintrag nicht.
• Bearbeiter — erforderlich, um bestehende Charts und Berichte zu aktualisieren (zu speichern).
• Ersteller — erforderlich, um neue Charts und Berichte zu erstellen.
• Löscher — erforderlich, um Charts und Berichte zu löschen.

Rollen sind kumulativ: Ein Ersteller benötigt Betrachter + Bearbeiter, und ein Löscher benötigt Betrachter. Die genauen Rollenschlüssel finden Sie in der Konfigurationsreferenz.

Erweiterungspunkte

Das Plugin stellt eine Reihe von Symfony-Events für Plugins von Drittanbietern oder eigenen Code bereit, um die Abfrage-Pipeline zu erweitern:

Event	Wann es ausgelöst wird	Verwendungszweck
BeforeAnalyticsQueryEvent	Bevor SQL aufgebaut wird	Zusätzliche Filter basierend auf Tenant, Rolle oder Kontext injizieren
BeforeAnalyticsQueryExecuteEvent	Nach SQL-Aufbau, vor DB-Ausführung	Rohe SQL/Parameter als letzten Ausweg mutieren
AnalyticsQueryResultEvent	Nach Rückgabe der Abfrage	Ergebnisdaten nachbearbeiten, Werte maskieren, berechnete Reihen anhängen
AnalyticsDataSourcesEvent	Wenn Datenquellen-Metadaten abgerufen werden	Verfügbare Datenquellen in der Chart-Builder-Benutzeroberfläche hinzufügen, entfernen oder ändern
RegisterAnalyticsOperatorsEvent	Einmalig bei erster Verwendung (gecacht)	Benutzerdefinierte Filter-Operatoren registrieren (z. B. between)
RegisterAnalyticsDateRangesEvent	Einmalig bei erster Verwendung (gecacht)	Benutzerdefinierte Zeitraum-Voreinstellungen registrieren (z. B. fiscal_year)

Diese Events folgen dem Standard-Symfony-EventSubscriberInterface-Muster. Codebeispiele finden Sie in planning/06-developer-notes.md im Plugin-Quellcode.

Was nicht im Umfang liegt

Das Plugin fragt die Shopware-Datenbank direkt über den DAL ab. Es bietet nicht:

• Tracking von Storefront-Besuchern, Seitenaufrufen oder Sitzungen (verwenden Sie dafür Shopware Analytics oder Google Analytics).
• Verbindungen zu externen Data Warehouses oder Datensynchronisierung mit externen Diensten.
• Multi-Shop-Aggregation über mehrere Instanzen hinweg.
• KI-gestützte Erkenntnisse oder Anomalieerkennung.
• Storefront-Events auf Positionsebene (In den Warenkorb legen, Wunschliste usw.).