Sembot — Dokumentacja

Appearance

Najczęstsze błędy Marketera AI ​

Spis treści

1. Brak UUID w filtrach reguł produktowych ​

Na czym polega problem ​

Przy tworzeniu reguł produktowych przez Marketer AI (via narzędzie MCP/API), każda grupa filtrów i każdy pojedynczy filtr muszą posiadać pole id z unikalnym identyfikatorem UUID (format xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx).

Jeśli pole id jest pominięte, reguła zostaje zapisana w bazie danych ze strukturą niekompletną. Reguła działa pozornie poprawnie (produkty są filtrowane), ale wyświetla błąd w zakładce „Ustawienia reguł" interfejsu użytkownika.

Porównanie — struktura poprawna vs błędna ​

Struktura POPRAWNA (jak generuje UI):

json
{
  "filterGroups": [
    {
      "id": "ffc3b8d4-1a2b-4c3d-8e9f-000000000001",
      "operator": "and",
      "filters": [
        {
          "id": "e393d113-1a2b-4c3d-8e9f-000000000002",
          "param": "cost",
          "symbol": "greaterThanOrEqual",
          "value": "2",
          "operator": "and"
        }
      ]
    }
  ]
}

Struktura BŁĘDNA (jak generuje AI bez UUID):

json
{
  "filterGroups": [
    {
      "operator": "and",
      "filters": [
        {
          "param": "cost",
          "symbol": "greaterThanOrEqual",
          "value": "2",
          "operator": "and"
        }
      ]
    }
  ]
}

Kroki, które Marketer AI musi podjąć samodzielnie ​

Krok 1 — Zawsze generuj UUID dla każdej grupy filtrów

Dla każdego obiektu w tablicy filterGroups ustaw pole id jako UUID v4. Generuj UUID samodzielnie przy budowaniu struktury reguły, przed wywołaniem narzędzia MCP.

Format UUID v4: xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx, gdzie x to losowa cyfra hex, a y to jedna z cyfr 8, 9, a, b.

Przykład prawidłowo wygenerowanego UUID: a3f7c21e-59d0-4b18-9e6a-1d2e3f4a5b6c

Krok 2 — Zawsze generuj UUID dla każdego filtra wewnątrz grupy

Każdy obiekt w tablicy filters (wewnątrz każdej grupy) musi mieć własne, odrębne pole id z innym UUID niż grupa nadrzędna.

Krok 3 — Weryfikuj strukturę przed wywołaniem narzędzia

Przed wywołaniem narzędzia MCP do zapisu reguły sprawdź wewnętrznie:

  • Czy każdy element filterGroups ma pole id? → jeśli nie, wygeneruj UUID
  • Czy każdy element filters wewnątrz grupy ma pole id? → jeśli nie, wygeneruj UUID
  • Czy żadne dwa elementy nie mają tego samego UUID? → każdy musi być unikalny

Krok 4 — Nigdy nie kopiuj UUID między regułami

Jeśli tworzysz wiele reguł jednocześnie (np. przez batch), każda reguła, każda grupa i każdy filtr muszą mieć nowy, unikalny UUID. Nie wolno ponownie użyć UUID z innej reguły w tej samej operacji.

Szablon struktury do wypełnienia ​

json
{
  "filterGroups": [
    {
      "id": "<NOWY_UUID>",
      "operator": "and",
      "filters": [
        {
          "id": "<NOWY_UUID>",
          "param": "<parametr>",
          "symbol": "<operator_porownania>",
          "value": "<wartosc>",
          "operator": "and"
        }
      ]
    }
  ]
}

Dlaczego to ważne ​

UI Sembot automatycznie generuje UUID przy każdym kliknięciu „dodaj filtr". Narzędzie MCP nie robi tego automatycznie — odpowiedzialność za wygenerowanie UUID spoczywa na Marketer AI w momencie budowania żądania. Backend zapisze strukturę taką, jaką dostanie — bez UUID lub z UUID, bez weryfikacji kompletności.