edee.oneDocs
EdeeShop · Implementace

Fulltext pro e-shop entity (produkty, značky, kategorie, skupiny)

Upraveno

Tento dokument shrnuje možnosti nastavení fulltextu pro e‑shop entity.

Co fulltext dělá

  • Vyhledává v publikovaných e‑shop datech: produkty, značky, kategorie a skupiny.
  • Standardně indexuje základní pole (název, popisy, katalogové číslo, EAN apod.), ale řídí se konfigurací.
  • Podporuje vícejazyčné a víceregionální e-shopy (indexace podle regionů).
  • Výsledky se zobrazují v našeptávači i na výsledkové stránce, podporují stránkování, filtrování i třídění.
  • Výchozí minimum délky hledaného výrazu je 3 znaky (pokud je kratší, dotaz se neprovede).

Kde se fulltext nastavuje

  1. Globální fulltext modul
    Konfigurace v edee/config/module-fulltext/module-fulltext.xml definuje nastavení modulu. Podrobnosti zde.

  2. Konfigurace e‑shop entit
    Konfigurace v edee/config/module-edeeshop/features/catalog/*.xml (product.xml, brand.xml, category.xml, group.xml):

  • fulltextConfig/providers = definice zdrojů dat (co se indexuje),
  • fulltextConfig/sections = definice sekcí (kde a pro jaké regiony se indexuje).
  1. Frontend API
    Vyhledávání je dostupné přes FulltextController: GET /api/eshop/{catalogCode}/fulltext (více kapitola API pro FE).

Minimální postup nastavení

  1. Nastav fulltext modul

Z pohledu e-shopu není potřeba nic měnit, ale modul musí být zapnutý a správně nastavený.

  1. Definuj providery pro entity
    V edee/config/module-edeeshop/features/catalog/*.xml nastav fulltextConfig/providers/provider. Důležité body:
  • type musí být unikátní napříč všemi providery v aplikaci (např. products, brands).
  • builder/indexedProperties určuje, co se indexuje.
  • builder/variables a builder/dataList ukládají data do výsledků (např. pro grouping a filtrování).
  • query může omezit výběr entit (např. jen aktivní).
  • visibleForStockOnly (produkty) omezí indexaci na položky dostupné na skladu.
  1. Vytvoř sekce (sections)
    fulltextConfig/sections/section určuje fragment, providers, regions a sitemapId.
    Pokud je sections prázdné, entity se neindexují.

Pozn.: název sekce se skládá jako catalog_region_fragment (např. demo_czcsczk_products).
fragment se pak používá v API parametru sectionFragment. Seznam všech sekcí je dostupný v admin modulu.

Podrobnosti o konfiguraci fulltextConfig/providers/provider a fulltextConfig/sections/section k jednotlivým entitám:

  1. Spusť indexaci
    Fulltext hledá až po úspěšné indexaci (viz "Úlohy na pozadí" a skupina "Fulltextové vyhledávání").

Ukázková konfigurace

Níže je zkrácený výpis z demo konfigurace.

Produkty

xml
<fulltextConfig>  <providers>    <provider>      <type>products</type>      <query>        <referencedEntities>          <!-- Chceme indexovat i značku produktu, musíme ji načíst -->          <referencedEntity>brand</referencedEntity>        </referencedEntities>      </query>      <visibleForStockOnly>true</visibleForStockOnly>      <builder>        <gallery>hlavni-motiv</gallery>        <indexedProperties>          <indexedProperty>name</indexedProperty>          <indexedProperty>titleOrName</indexedProperty>          <indexedProperty>description</indexedProperty>          <indexedProperty>descriptionShort</indexedProperty>          <indexedProperty>getLocalizedTextByCode('metaDescription')</indexedProperty>          <indexedProperty>catalogNumber</indexedProperty>          <indexedProperty>ean</indexedProperty>          <indexedProperty>brand?.brand?.name</indexedProperty>        </indexedProperties>        <variantId>eshop-product-detail-microdata-1x1</variantId>        <variables>          <variable>productType.name</variable>        </variables>      </builder>    </provider>  </providers>  <sections>    <section>      <fragment>products</fragment>      <providers>        <provider>products</provider>      </providers>      <regions>        <region>          <country>cz</country>          <locale>cs</locale>          <currency>CZK</currency>        </region>      </regions>      <sitemapId>csDemoSitemap</sitemapId>      <fieldAnalyzers>        <fieldAnalyzer>          <field>title</field>          <analyzer>czech-edee-summon</analyzer>        </fieldAnalyzer>        <fieldAnalyzer>          <field>content</field>          <analyzer>czech-edee</analyzer>        </fieldAnalyzer>      </fieldAnalyzers>    </section>  </sections></fulltextConfig>

Značky / kategorie / skupiny

xml
<fulltextConfig>  <providers>    <provider>      <type>brands</type>      <builder>        <gallery>hlavni-motiv</gallery>        <indexedProperties>          <indexedProperty>name</indexedProperty>          <indexedProperty>titleOrName</indexedProperty>          <indexedProperty>description</indexedProperty>          <indexedProperty>descriptionShort</indexedProperty>          <indexedProperty>getLocalizedTextByCode('metaDescription')</indexedProperty>        </indexedProperties>      </builder>    </provider>  </providers>  <sections>    <section>      <fragment>brands</fragment>      <providers>        <provider>brands</provider>      </providers>      <regions>        <region>          <country>cz</country>          <locale>cs</locale>          <currency>CZK</currency>        </region>      </regions>      <sitemapId>csDemoSitemap</sitemapId>      <fieldAnalyzers>        <fieldAnalyzer>          <field>title</field>          <analyzer>czech-edee-summon</analyzer>        </fieldAnalyzer>        <fieldAnalyzer>          <field>content</field>          <analyzer>czech-edee</analyzer>        </fieldAnalyzer>      </fieldAnalyzers>    </section>  </sections></fulltextConfig>

Stejný vzor platí pro categories a groups (liší se type/fragment).

Jak fulltext ladit

1) Analyzátory (sekce a pole)

  • section/analyzer nastaví výchozí analyzátor pro sekci.
  • section/fieldAnalyzers/fieldAnalyzer umožní rozlišit analyzátor pro title a content.
  • Doporučení: agresivnější analyzátor pro title (czech-edee-summon) a standardní pro content (czech-edee).

Podporované analyzátory: czech-edee, czech-edee-summon, universal, english, ... (viz dokumentace).

2) Profily vyhledávání (Search Profiles)

V module-fulltext.xml lze definovat profily:

xml
<profile name="defaultProfile">  <param name="titleBoost" value="3"/>  <param name="promoItems" value="3"/></profile>

Profil se předává query parametrem profile do FulltextController.
Pokud profile není uveden, použije se fallback logika popsaná níže v sekci API pro FE.

3) Indexace identifikátorů (EAN, katalogové číslo)

Pro ean a catalogNumber je použita strategie indexace s ořezáváním zprava (RecursiveRightTrimWithDigitsIndexBuilder), která umožní hledat i části kódu.

Konkrétní chování RecursiveRightTrimWithDigitsIndexBuilder:

  • generuje tokeny postupným ořezáváním zprava,
  • navíc extrahuje číslice a ty indexuje stejným způsobem,
  • výchozí minimální délka tokenu je 3.

Příklad pro ABC12345:

  • textová část: ABC12345, ABC1234, ABC123, ...
  • čísla: 12345, 1234, 123, ...

Vlastní index buildery

Pokud chcete jinou strategii pro další atributy, použijte vlastní implementaci IndexBuilder (com.fg.cps.eshop.catalog.cps.fulltext.service.builder.IndexBuilder) a zaregistrujte ji v AbstractFulltextResourceBuilder.registerIndexBuilder.

Kroky:

  1. Implementujte IndexBuilder – např. ořezávání zleva, normalizace prefixů, custom tokenizace:
java
public class MySkuIndexBuilder implements IndexBuilder {    @Override    public void indexString(IndexBuilderContext context, @Nullable String value) {        if (value == null) {            return;        }        context.indexValue(value.toUpperCase(Locale.ROOT));        // případně další tokeny...    }}
  1. Zaregistrujte builder pro konkrétní atribut
    Klíč musí odpovídat přesně výrazu v indexedProperties (např. catalogNumber, ean, nebo i složitější SpEL jako brand?.brand?.name).
java
public class CustomProductResourceBuilder extends ProductResourceBuilder {    public CustomProductResourceBuilder(/* dependencies */) {        super(/* dependencies */);        registerIndexBuilder("catalogNumber", new MySkuIndexBuilder());        registerIndexBuilder("ean", RecursiveRightTrimWithDigitsIndexBuilder.INSTANCE);    }}
  1. Zajistěte použití builderu v projektu
    V FulltextResourceBuilderProvider lze přeregistrovat builder pro entitu:
java
builderProvider.registerFulltextResourceBuilder(CatalogEntityType.PRODUCT, customProductResourceBuilder);

API pro FE (FulltextController)

Endpoint:

kód
GET /api/eshop/{catalogCode}/fulltext

Parametry:

  • catalogRegion (např. cz_czk)
  • sectionFragment (např. products, brands, categories, groups)
  • query (hledaný výraz)
  • pageSize, pageNumber
  • variables (např. MASTER OR BASIC OR SET)
  • profile (volba search profilu)
  • promoItemCount (max promo výsledků)
  • fulltextGroupResultMapperName (volitelný mapper pro groupování)

Výsledky jsou seskupené (master + varianty). Pokud je nalezen master, varianty se ve výsledku nevypisují samostatně.

Parametr profile

Umožňuje klientovi zvolit konkrétní vyhledávací profil (Search Profile) definovaný v konfiguraci fulltextového modulu.

Pokud je parametr profile zadán, FulltextController jej předá do SearchParams. Na základě zvoleného profilu se následně aplikují příslušná nastavení, jako je například titleBoost.

Pokud profile není zadán (výchozí stav), použije se „ad-hoc“ logika, která zvýhodňuje titulek pomocí parametru titleBoost.

Dále platí, že pokud není profile definován, předává se hledaná hodnota také do searchParams.term. To zajistí, že se v polích title i content bude hledat přesně zadaný výraz bez vlivu analyzéru. Při přesné shodě tak fulltext najde záznam i v případech, kdy by to úprava slova analyzérem neumožnila.

Podrobnější popis dalších parametrů zde.

Diagnostika a ladění

Pro ladění analyzátorů a tokenizace lze použít diagnostické nástroje v sekci "Nastavení"/"Fulltext" v administraci.

Související dokumentace