Sembot — Dokumentacja

Appearance

MarketerAI — Tworzenie Reguł z Filtrami Analitycznymi ​

Spis Treści ​

  1. Przegląd
  2. Aktualny Przepływ Tworzenia Reguły
  3. Struktura Danych Filtra Analitycznego
  4. Dostępne Kolumny Analityczne
  5. Jak Filtr Jest Wyświetlany w UI
  6. Oczekiwane Zachowanie Systemu
  7. Znane Problemy i Wymagane Poprawki

Przegląd ​

Marketer AI pozwala użytkownikom tworzyć reguły produktowe na podstawie danych analitycznych z platform reklamowych — m.in. Google Ads, Google Analytics 4 i Microsoft Ads. Użytkownik może np. powiedzieć:

„Dla produktów, w których konwersje Google Ads były większe niż 5 w ciągu ostatnich 30 dni, ustaw w etykiecie niestandardowej 0 wartość 'Marketer'"

System powinien przetłumaczyć tę komendę na kompletną regułę z poprawnie ustawionym filtrem analitycznym — włącznie z zakresem czasowym.

Aktualny Przepływ Tworzenia Reguły ​

Ścieżka end-to-end ​

Użytkownik (chat)
    ↓
Marketer AI (LLM + MCP tools — repo: sembot_public-mcp)
    ↓  wywołuje tool create_product_rule
POST /api/public/v1/projects/{project}/product-rules
    ↓  App\Http\Controllers\Api\PublicApi\Rules\ProductRulesController
    ↓  walidacja: App\Http\Requests\Api\Google\Merchant\Rules\StoreRuleRequest
    ↓              → App\Http\Requests\Api\FilteredRequest (walidacja filtrów)
    ↓  zapis do DB: Rule (kolumna `filters` — JSON)
    ↓  dispatch: BulkMassAction (kolejka products_mass_actions)
        ↓  przy wykonaniu reguły:
        App\Services\Products\AdditionalDataSource\AdditionalDataSourceService::processFilters()
            ↓  dla filtrów analitycznych pobiera dane z zewnętrznej platformy
            ↓  zamienia filtr analityczny na filtr po ID produktów

Komponenty zaangażowane w przetwarzanie filtrów analitycznych ​

KomponentPlikOdpowiedzialność
AdditionalDataSourceServiceapp/Services/Products/AdditionalDataSource/AdditionalDataSourceService.phpRozpoznaje filtry analityczne, wywołuje zewnętrzne API
GoogleAdsProductsDataSourceapp/Services/Products/AdditionalDataSource/GoogleAdsProductsDataSource.phpPobiera dane z Google Ads API dla filtrowanego zakresu dat
GoogleAnalytics4ProductsDataSourceapp/Services/Products/AdditionalDataSource/GoogleAnalytics4ProductsDataSource.phpPobiera dane z GA4 API
MicrosoftAdvertisingProductsDataSourceapp/Services/Products/AdditionalDataSource/MicrosoftAdvertisingProductsDataSource.phpPobiera dane z Microsoft Ads API
FilteredRequestapp/Http/Requests/Api/FilteredRequest.phpWaliduje strukturę filtrów — wymaga project_connection_id dla filtrów analitycznych

Jak filtr analityczny jest przetwarzany przy wykonaniu reguły ​

Przy przetwarzaniu BulkMassAction AdditionalDataSourceService::processFilters() dla każdego filtra analitycznego:

  1. Rozpoznaje, że param pochodzi z zewnętrznego źródła (np. google_ads_conversions)
  2. Tworzy konektor (GoogleAdsProductsDataSource) z połączeniem project_connection_id
  3. Używa sub_days lub start_date/end_date do określenia okna czasowego zapytania do platformy
  4. Pobiera z platformy listę identyfikatorów produktów spełniających warunek
  5. Zastępuje filtr analityczny filtrem param: google_product_id, symbol: in, value: [id1, id2, ...]
  6. Dalsze przetwarzanie reguły odbywa się już tylko na lokalnej bazie produktów

Struktura Danych Filtra Analitycznego ​

JSON zapisywany w bazie danych (kolumna filters tabeli rules) ​

json
{
  "filterGroups": [
    {
      "filters": [
        {
          "param": "google_ads_conversions",
          "symbol": ">",
          "value": 5,
          "project_connection_id": 123,
          "sub_days": 30,
          "translate_key": "connection_period"
        }
      ]
    }
  ]
}

Opis pól filtra analitycznego ​

PoleTypWymaganeOpis
paramstringtakNazwa metryki analitycznej (patrz sekcja niżej)
symbolstringtakOperator porównania: >, <, =, !=, >=, <=, is_empty, not_empty
valuenumber/stringtakWartość progowa do porównania
project_connection_idintegertakID połączenia projektu z platformą (np. konkretne konto Google Ads)
sub_daysintegerwarunkowe*Liczba dni wstecz dla daty względnej (np. 30 = ostatnie 30 dni)
start_datestring (YYYY-MM-DD)warunkowe*Data początku dla stałego zakresu dat
end_datestring (YYYY-MM-DD)warunkowe*Data końca dla stałego zakresu dat
translate_keystringtakTryb wyświetlania w UI: connection_period (data względna) lub connection_range (stały zakres)

* Albo sub_days, albo para start_date + end_date — jedno z nich jest wymagane. Gdy oba obecne, sub_days ma priorytet.

Dwa tryby zakresu czasowego ​

Tryb 1: Data względna (sub_days) ​

Użytkownik podaje liczbę dni wstecz od dziś. Zakres jest wyliczany dynamicznie przy każdym wykonaniu reguły.

json
{
  "sub_days": 30,
  "translate_key": "connection_period"
}

UI wyświetla: "Last 30 days"

Kiedy używać: zawsze gdy użytkownik mówi „ostatnie N dni", „za ostatni miesiąc", „w ciągu ostatnich 90 dni" itp.

Tryb 2: Stały zakres dat (start_date + end_date) ​

Użytkownik podaje konkretne daty — zakres jest stały i nie zmienia się z czasem.

json
{
  "start_date": "2025-01-01",
  "end_date": "2025-03-31",
  "translate_key": "connection_range"
}

UI wyświetla: "2025-01-01 – 2025-03-31"

Kiedy używać: gdy użytkownik podaje konkretne daty np. „od 1 stycznia do 31 marca 2025".

Dostępne Kolumny Analityczne ​

paramMetrykaDozwolone operatory
google_ads_impressionsWyświetlenia>, <, =, !=, >=, <=, is_empty, not_empty
google_ads_clicksKliknięcia>, <, =, !=, >=, <=, is_empty, not_empty
google_ads_costKoszt>, <, =, !=, >=, <=, is_empty, not_empty
google_ads_avg_cpcŚredni CPC>, <, =, !=, is_empty, not_empty
google_ads_conversionsKonwersje>, <, =, !=, is_empty, not_empty
google_ads_conv_rateWspółczynnik konwersji>, <, =, !=, is_empty, not_empty
google_ads_total_conv_valueŁączna wartość konwersji>, <, =, !=, is_empty, not_empty
google_ads_cost_per_conversionKoszt na konwersję>, <, =, !=, is_empty, not_empty
google_ads_roasROAS>, <, =, !=, is_empty, not_empty

Google Analytics 4 (project_connection_id → połączenie typu GOOGLE_ANALYTICS_4) ​

Dane dostępne z GA4: sesje, przychody, użytkownicy, koszyk, zamówienia i inne — zależnie od konfiguracji GA4 klienta.

Microsoft Ads (project_connection_id → połączenie typu BING_ADS) ​

Analogiczne metryki jak Google Ads: impressions, clicks, cost, conversions itp.

Jak Filtr Jest Wyświetlany w UI ​

Frontend (analytics-picker.component.ts) odczytuje sub_days, start_date, end_date z filtra i wyświetla:

sub_days ustawione   → "Last 30 days"          ← POPRAWNY widok
sub_days = null i brak start_date/end_date → "{{startDate}} - {{endDate}}"  ← BŁĘDNY widok (niezinterpretowane zmienne)
start_date + end_date ustawione → "2025-01-01 – 2025-03-31"

Gdy AI tworzy regułę bez sub_days i bez start_date/end_date — UI pokazuje surowe zmienne szablonu tłumaczenia, co sygnalizuje brak danych zakresu czasowego.

Oczekiwane Zachowanie Systemu ​

Krok 1 — Identyfikacja intencji ​

Gdy użytkownik podaje komendę z filtrem analitycznym, AI musi wyodrębnić:

  • Metrykę → param (np. „konwersje Google Ads" → google_ads_conversions)
  • Operator → symbol (np. „większe niż" → >, „mniejsze niż" → <, „równe" → =)
  • Wartość progową → value (np. 5)
  • Zakres czasowy → sub_days lub start_date/end_date (np. „ostatnie 30 dni" → sub_days: 30)
  • Platformę → typ połączenia (np. „Google Ads" → GOOGLE_ADS)

Krok 2 — Dopytanie o brakujące dane ​

Jeśli użytkownik nie podał zakresu czasowego — AI MUSI zapytać przed stworzeniem reguły.

Przykładowe pytanie AI do użytkownika:

„Za jaki okres chcesz sprawdzić dane? Możesz podać:— liczbę dni wstecz (np. ostatnie 30 dni, 90 dni)— konkretny zakres dat (np. od 2025-01-01 do 2025-03-31)"

Nie wolno tworzyć reguły z domyślnym zakresem bez pytania — użytkownik musi świadomie podjąć tę decyzję, bo zakres czasowy bezpośrednio wpływa na to które produkty zostaną oznaczone.

Krok 3 — Identyfikacja połączenia projektu ​

AI musi znać project_connection_id — ID konkretnego konta reklamowego w projekcie.

Jeśli AI nie zna ID:

  1. Wywołuje narzędzie listujące dostępne połączenia projektu dla danej platformy
  2. Jeśli jest dokładnie jedno połączenie danego typu — używa go automatycznie
  3. Jeśli jest więcej połączeń — prezentuje listę i pyta użytkownika które wybrać

Krok 4 — Budowanie kompletnego filtra ​

AI wywołuje narzędzie create_product_rule z kompletnym filtrem:

json
{
  "filterGroups": [
    {
      "filters": [
        {
          "param": "google_ads_conversions",
          "symbol": ">",
          "value": 5,
          "project_connection_id": 123,
          "sub_days": 30,
          "translate_key": "connection_period"
        }
      ]
    }
  ],
  "action": {
    "action": "override",
    "param": "custom_label_0",
    "value": "Marketer"
  },
  "active": true
}

Reguła poprawności:

  • Dla daty względnej: sub_days (integer > 0) + translate_key: "connection_period"
  • Dla stałego zakresu: start_date + end_date (format YYYY-MM-DD) + translate_key: "connection_range"
  • Pole symbol musi zawierać jeden z dozwolonych operatorów — nigdy nie może być puste
  • Pole project_connection_id jest zawsze wymagane

Krok 5 — Potwierdzenie przed zapisem ​

Przed wysłaniem żądania do API AI prezentuje użytkownikowi podsumowanie tworzonej reguły i czeka na potwierdzenie:

„Tworzę regułę:— Warunek: konwersje Google Ads > 5 (ostatnie 30 dni, konto: Sklep PL)— Akcja: ustaw etykietę niestandardową 0 = 'Marketer'Czy potwierdzasz?"

Znane Problemy i Wymagane Poprawki ​

Problem 1 — Brak sub_days w tworzonym filtrze ​

Objaw: UI wyświetla - zamiast np. "Last 30 days".

Przyczyna: Narzędzie MCP (create_product_rule w sembot_public-mcp) nie przekazuje pola sub_days do API, nawet gdy użytkownik podał zakres względny.

Wymagana poprawka:

  • W schemacie narzędzia MCP dodać pole sub_days (integer) w definicji filtra
  • Dodać instrukcję: dla dat względnych używać sub_days + translate_key: "connection_period", nie start_date/end_date

Problem 2 — Brak translate_key w filtrze ​

Objaw: UI nie wie w jakim trybie wyświetlić przycisk zakresu dat.

Wymagana poprawka: Zawsze wysyłać translate_key przy filtrach analitycznych (connection_period lub connection_range).

Problem 3 — Brak operatora symbol ​

Objaw: Filtr tworzony bez operatora lub z niepoprawną nazwą pola.

Przyczyna: Pole operatora w API nazywa się symbol (nie operator). AI może używać błędnej nazwy.

Wymagana poprawka: W schemacie narzędzia MCP pole operatora filtra musi być nazwane symbol z enumem dozwolonych wartości: >, <, =, !=, >=, <=, is_empty, not_empty.

Problem 4 — AI nie pyta o zakres czasowy gdy brak danych ​

Objaw: AI tworzy regułę bez pytania o zakres, skutkując niekompletnym filtrem.

Wymagana poprawka: Dodać do system promptu agenta lub opisu narzędzia MCP instrukcję: przed wywołaniem create_product_rule z filtrem analitycznym zawsze upewnij się że masz zakres czasowy — jeśli użytkownik go nie podał, zapytaj.