Docs Sync: Update from com_kickbannerstats commit 88833d2451e597b72a92ce871428b87ff346c49e

Author: Kicktemp Bot

src/components/com_kickbannerstats/api-integration.md

@@ -1,72 +1,114 @@
-# API & Looker Studio Integration
+# API & Looker Studio
 
-KickBannerStats stellt eine JSON-API über den Joomla API Wrapper bereit. Diese wird primär genutzt, um Daten an **Google Looker Studio** zu übergeben.
+Die größte Stärke von KickBannerStats liegt in der **Entkopplung**: Während Joomla die Daten sammelt, können externe Tools wie **Google Looker Studio** diese visualisieren – ohne die Performance Ihrer Webseite zu belasten.
 
-## API Endpoint
+## Das Ergebnis
 
-Der Zugriff erfolgt über den `StatisticsController`.
+Mit der Integration können Sie interaktive Dashboards erstellen, die Sie direkt mit Ihren Werbekunden teilen können.
 
-**Basis-URL:**
+![Looker Studio Report](./assets/lookerstudio.png)
+
+### Vorteile dieser Lösung
+* 🚀 **Performance:** Der Report lädt blitzschnell, da er auf die aggregierte API zugreift und nicht Millionen von Datenbankzeilen durchsucht.
+* 🔒 **Sicherheit:** Kunden erhalten Zugriff auf den Report, aber niemals direkten Zugriff auf Ihr Joomla-Backend.
+* 🎨 **White-Label:** Gestalten Sie den Report in Ihrem Corporate Design (oder dem des Kunden).
+
+---
+
+## Die API Schnittstelle
+
+KickBannerStats stellt einen nativen Joomla Webservice (API) Endpunkt bereit.
+
+### Endpoint
+
+```http
+GET /api/index.php/v1/kickbannerstats/statistics
+
+```
 
 ### Authentifizierung
-Die API nutzt die Standard Joomla API Token Authentifizierung (`Bearer Token` oder `X-Joomla-Token`).
 
-### Filter-Parameter
-Die API unterstützt folgende GET-Parameter zur Filterung:
+Der Zugriff erfolgt über einen **Joomla API Token**. Erstellen Sie diesen im Backend unter **Benutzer** > **Verwalten** > (User auswählen) > **Joomla API Token**.
+
+Der Token muss im Header der Anfrage gesendet werden:
+
+```http
+X-Joomla-Token: c2h...I6
+
+```
+
+### Filter Parameter
+
+Sie können die Daten serverseitig filtern, um die Payload klein zu halten:
 
 | Parameter | Typ | Beschreibung |
-| :--- | :--- | :--- |
-| `filter[begin]` | String (Y-m-d) | Startdatum (inklusiv) |
-| `filter[end]` | String (Y-m-d) | Enddatum (inklusiv) |
-| `filter[client_id]` | Int | Nur spezifischer Kunde |
-| `filter[banner_id]` | Int | Nur spezifisches Banner |
+| --- | --- | --- |
+| `filter[begin]` | `YYYY-MM-DD` | Startdatum (inklusiv) |
+| `filter[end]` | `YYYY-MM-DD` | Enddatum (inklusiv) |
+| `filter[client_id]` | `INT` | Nur Daten für einen spezifischen Kunden |
+| `filter[banner_id]` | `INT` | Nur Daten für ein spezifisches Banner |
 
-## Beispiel Response
-https://ihre-domain.de/api/index.php/v1/kickbannerstats/statistics
+### Beispiel Response (JSON)
 
 ```json
 [
     {
-        "date": "2026-01-20",
+        "date": "2026-02-12",
         "banner_id": 422,
         "client_id": 13,
         "impressions": 1319,
         "clicks": 3,
         "banner_name": "Musical Kids Amulett",
         "client_name": "besser-im-blick",
-        "updated_at": "2026-02-12 13:37:39"
+        "updated_at": "2026-02-13 03:00:00"
     },
     {
-        "date": "2026-01-19",
+        "date": "2026-02-11",
         "banner_id": 422,
         "client_id": 13,
         "impressions": 41324,
         "clicks": 38,
         "banner_name": "Musical Kids Amulett",
         "client_name": "besser-im-blick",
-        "updated_at": "2026-02-12 13:37:39"
+        "updated_at": "2026-02-13 03:00:00"
     }
 ]
+
 ```
 
-Looker Studio Connector
-Um diese Daten in Looker Studio zu nutzen, benötigen Sie ein Google Apps Script (Community Connector), welches diese API konsumiert.
+---
+
+## Google Looker Studio Connector
+
+Um die JSON-Daten in Looker Studio zu nutzen, wird ein **Community Connector** (Google Apps Script) benötigt, der die Daten abruft und in das Looker-Format umwandelt.
+
+### Schema Konfiguration
 
-Schema Definition
-Im Connector mappen Sie die JSON-Felder wie folgt:
+Im Connector werden die JSON-Felder wie folgt gemappt:
 
-date -> Datum (YYYYMMDD)
+1. **Dimensionen (Grün):**
+* `Date` (Typ: YYYYMMDD)
+* `Banner Name` (Typ: Text)
+* `Client Name` (Typ: Text)
 
-banner_name -> Text
 
-client_name -> Text
+2. **Metriken (Blau):**
+* `Impressions` (Typ: Zahl)
+* `Clicks` (Typ: Zahl)
+
+
+3. **Berechnete Felder:**
+* **CTR:** Erstellen Sie im Looker Studio ein Feld mit der Formel:
+```sql
+SUM(Clicks) / SUM(Impressions)
+
+```
+
 
-impressions -> Zahl
+*(Formatieren Sie dieses Feld als Prozent)*
 
-clicks -> Zahl
 
-CTR -> Berechnetes Feld (clicks / impressions)
 
-::: tip Caching
-Da die Daten in #__kickbannerstats_daily nur einmal täglich aktualisiert werden, empfiehlt es sich, im Looker Studio Connector ein Caching von 12 bis 24 Stunden zu aktivieren.
-:::
+::: tip Caching Strategie
+Da die Daten in Joomla nur einmal täglich (per Task) aktualisiert werden, sollten Sie im Looker Studio Connector das Caching aktivieren (z.B. für 12 Stunden). Dies beschleunigt den Report für den Endkunden extrem.
+:::

src/components/com_kickbannerstats/architecture.md

@@ -1,10 +1,19 @@
-# Architektur & Datenbank
+# Architektur & Datenfluss
 
-Der Kern von KickBannerStats ist die Entkopplung von "Schreiben" (Joomla Core) und "Lesen" (KickBannerStats).
+KickBannerStats wurde entwickelt, um ein spezifisches Problem von High-Traffic-Webseiten zu lösen: **Performance bei der Auswertung**.
 
-## Datenbank-Schema
+Anstatt Millionen von Rohdaten-Zeilen bei jedem Seitenaufruf neu zu berechnen, nutzt die Komponente einen **Data-Warehouse-Ansatz** (ETL: Extract, Transform, Load).
 
-Die Komponente nutzt eine eigene, flache Tabelle zur Speicherung der Tageswerte pro Banner und Kunde.
+## 1. Das Datenbank-Schema
+
+Die Basis der Performance ist die Entkopplung von Schreib- und Lese-Operationen.
+
+* **Schreiben (Joomla Core):** Jeder View/Klick landet in `#__banner_tracks`. Diese Tabelle wächst extrem schnell.
+* **Lesen (KickBannerStats):** Wir nutzen eine flache, aggregierte Tabelle namens `#__kickbannerstats_daily`.
+
+### Tabellenstruktur
+
+Die Tabelle `#__kickbannerstats_daily` speichert **eine Zeile pro Banner, Kunde und Tag**.
 
 ```sql
 CREATE TABLE IF NOT EXISTS `#__kickbannerstats_daily`
@@ -20,6 +29,63 @@ CREATE TABLE IF NOT EXISTS `#__kickbannerstats_daily`
   PRIMARY KEY (`date`, `banner_id`, `client_id`),
   KEY `idx_banner_date` (`banner_id`, `date`),
   KEY `idx_client_date` (`client_id`, `date`)
-) ENGINE = InnoDB
-  DEFAULT CHARSET = utf8mb4
-  DEFAULT COLLATE = utf8mb4_unicode_ci;
+) ENGINE = InnoDB ...;
+
+```
+
+**Vorteile dieses Schemas:**
+
+* **Komprimierung:** Aus 1.000.000 Tracking-Events an einem Tag werden vielleicht nur 50 Zeilen (je nach Anzahl der aktiven Banner).
+* **Indexierung:** Der `PRIMARY KEY` über Datum und IDs ermöglicht extrem schnelle Range-Queries (z.B. "Letzte 30 Tage").
+
+---
+
+## 2. Der ETL-Prozess (Task Plugin)
+
+Die Daten gelangen nicht in Echtzeit in die Statistik-Tabelle, sondern über einen **Scheduled Task** (Geplante Aufgabe). Das Plugin `plg_task_kickbannerstats` übernimmt diese Arbeit.
+
+### Routine A: `create.stats` (Täglich)
+
+Dieser Task ist das Arbeitspferd und sollte **einmal täglich** laufen.
+
+1. **Zeitraum:** Er greift standardmäßig die letzten **3 Tage** ab (`backfillDays` Parameter).
+* *Warum 3 Tage?* Um sicherzustellen, dass Klicks kurz vor Mitternacht oder Zeitzonen-Differenzen korrekt erfasst werden, selbst wenn der Task mal einen Tag ausfällt.
+
+
+2. **Aggregation:** Er gruppiert die Rohdaten aus `#__banner_tracks` nach `DATE(track_date)`, `banner_id` und `cid`.
+3. **Upsert:** Die Daten werden mit `INSERT ... ON DUPLICATE KEY UPDATE` in die Zieltabelle geschrieben. Das bedeutet:
+* Existiert der Eintrag für diesen Tag/Banner schon? -> **Update** (Zahlen aktualisieren).
+* Existiert er noch nicht? -> **Insert** (Neu anlegen).
+
+
+
+### Routine B: `backfillStats` (Historisch)
+
+Dieser Task dient der initialen Befüllung oder Reparatur. Er ist für große Datenmengen optimiert.
+
+1. **Chunking:** Er verarbeitet den gewählten Zeitraum nicht am Stück, sondern in Blöcken (z.B. 30 Tage).
+2. **Memory Management:** Dies verhindert, dass PHP bei jahrelangen Historien in ein `Memory Limit` läuft.
+3. **Idempotenz:** Kann gefahrlos mehrfach ausgeführt werden, da er bestehende Werte einfach überschreibt.
+
+---
+
+## 3. Datenabruf (Read Path)
+
+Sobald die Daten in `#__kickbannerstats_daily` liegen, werden sie von der Komponente konsumiert.
+
+### Im Backend (MVC)
+
+* **DashboardModel:** Summiert die Werte für den Dashboard-Zeitraum (z.B. 30 Tage). Die **CTR** (Click-Through-Rate) wird dabei "on the fly" berechnet (`Klicks / Impressionen * 100`).
+* **StatisticsModel:** Listet die Tageswerte auf und ermöglicht Filterung nach Kunde/Banner.
+
+### Über die API (Headless)
+
+Der `StatisticsController` stellt die Daten als JSON bereit.
+
+* Er nutzt `Joomla\CMS\MVC\Controller\ApiController`.
+* Er unterstützt Filterung via `filter[begin]`, `filter[end]`, etc.
+* Er gibt die Daten direkt aus der aggregierten Tabelle zurück, was Antwortzeiten im Millisekunden-Bereich ermöglicht, selbst bei jahrelanger Historie.
+
+::: tip Zusammenfassung
+Die Architektur opfert **Echtzeit-Daten** (Daten sind max. 24h alt) zugunsten von massiver **Performance-Steigerung** und **Skalierbarkeit** für Reporting-Zwecke.
+:::