case study · integracja

Wyszukiwarka, która rozumie „kubke”

Szybka wyszukiwarka produktów oparta o Algolię dla sklepu na platformie Shoper, która nie ma gotowej integracji. Własna usługa synchronizacji, podpowiedzi podczas pisania i strona wyników z filtrami, osadzone w szablonie sklepu jednym plikiem.

Platforma
Shoper (szablon Storefront)
Wyszukiwanie
Algolia
Zakres
Specyfikacja, backend, frontend, wdrożenie
Metodyka
Spec-Driven Development, 6 faz
sklep / podpowiedzi
Nakładka wyszukiwania: zapytanie z literówką „kubke” zwraca kubki z miniaturami, cenami i ceną promocyjną
Zapytanie z literówką zwraca właściwe produkty, z miniaturą, ceną i przekreśloną ceną regularną przy promocji.

01 / wyzwanie

Natywna wyszukiwarka nie wystarczała, a gotowej integracji nie było

Sklep potrzebował wyszukiwania, które wybacza literówki, zna synonimy, pokazuje wyniki w trakcie pisania i pozwala filtrować jak w dużych sklepach. Shoper nie ma integracji z Algolią, więc całość trzeba było zbudować: od pobierania katalogu z REST API po komponent osadzony w szablonie. Do tego część zachowań API nie jest opisana w publicznej dokumentacji.

  • req.01Pełny katalog w indeksieNazwy, opisy, ceny z promocjami, dostępność, kategorie, producenci, zdjęcia, atrybuty i warianty.
  • req.02Podpowiedzi przy pisaniuMiniatura, nazwa i cena produktu oraz podpowiedzi kategorii.
  • req.03Strona wyników z filtramiKategorie, producent, cena, dostępność, atrybuty; sortowanie po trafności, cenie i nowościach.
  • req.04TrafnośćLiterówki, synonimy, polska odmiana; produkty dostępne wyżej niż niedostępne.
  • req.05Aktualne daneZmiany w sklepie i stanach po zamówieniach widoczne w wyszukiwarce automatycznie.
  • req.06Spójny wyglądDopasowanie do szablonu sklepu i pełna obsługa telefonów.

02 / założenia

Najpierw specyfikacja, potem kod. I żadnego zgadywania

Prace szły w podejściu Spec-Driven Development: specyfikacja zaakceptowana przed pierwszą linią kodu, a każda faza kończyła się podsumowaniem i commitem. Każde twierdzenie o API Shopera miało w specyfikacji status, a założenia zamieniały się w fakty dopiero po sprawdzeniu na prawdziwych odpowiedziach.

✓ zweryfikowane na API ? założenie do sprawdzenia 68 ustaleń przeszło ze statusu założenia do zweryfikowanych
Odporność

Webhook to tylko sygnał

Każde zdarzenie kończy się tą samą operacją: zbuduj rekord produktu z aktualnych danych API. Duplikaty i zła kolejność zdarzeń nie psują indeksu.

Bezpieczeństwo

Klucz admin nigdy w przeglądarce

Frontend dostaje wyłącznie klucz tylko do wyszukiwania. Build kończy się błędem, jeśli w pliku pojawi się coś, co wygląda na klucz admin.

Prywatność

Z zamówień tylko ID produktów

Webhooki zamówień niosą dane osobowe. Usługa zapisuje z nich wyłącznie identyfikatory, a analityka Algolii startuje dopiero po zgodzie klienta sklepu.

Ciągłość

Sklep zawsze ma działającą wyszukiwarkę

Atomowa podmiana indeksu, blokada przed jego wyczyszczeniem i powrót do natywnej wyszukiwarki Shopera przy awarii Algolii. Jedna flaga wyłącza integrację.

03 / architektura

Trzy drogi do aktualnego indeksu

Usługa synchronizacji w jednym kontenerze przyjmuje webhooki, kolejkuje je i odświeża produkty. Co 20 minut dociąga zmiany po dacie modyfikacji, a raz na dobę porównuje cały katalog z indeksem i naprawia różnice. Przeglądarka rozmawia z Algolią bezpośrednio.

04 / co wdrożono

Od REST API do komponentu w szablonie

Usługa synchronizacji

  • Klient REST Shopera z dławieniem według nagłówków limitów, ponawianiem 429/5xx i paginacją
  • Mapper produkt → rekord: cena jak na listingu sklepu, warianty jako filtry, kategorie na 3 poziomach, opis oczyszczony z HTML
  • Pełny import z atomową podmianą indeksu i blokadą przed zmniejszeniem go o więcej niż 20%
  • Webhooki produktów, zamówień i kategorii z weryfikacją sumy kontrolnej, kolejką, ponawianiem i dead-letter
  • Synchronizacja przyrostowa i dobowa kontrolna, która zapisuje tylko różnice

Wyszukiwarka w sklepie

  • Nakładka z podpowiedziami produktów i kategorii, przejmująca natywne pole Storefront na desktopie i telefonie
  • Strona wyników: filtry, 4 sortowania, paginacja, wysuwany panel filtrów na telefonie
  • Adresy z filtrami do udostępnienia i działający przycisk „wstecz”
  • Informacja o najniższej cenie z 30 dni przy promocji (Omnibus)
  • Analityka Algolia Insights dopiero po zgodzie z modułu zgód sklepu

Konfiguracja i utrzymanie

  • Ustawienia indeksu, repliki, synonimy i filtry w repozytorium, wgrywane jedną komendą
  • Filtry wyliczane z ustawień „pokaż w filtrach” w panelu Shopera
  • Obraz Docker bez uprawnień roota, system plików tylko do odczytu
  • CI: testy, lintery, audyt zależności, kontrola bundla
  • Runbook z procedurą rollbacku i checklista przed produkcją

05 / efekt

Zrzuty z prawdziwego sklepu na szablonie Storefront z katalogiem demonstracyjnym. Kliknij zrzut, aby go powiększyć.

06 / co pokazało prawdziwe API

Rzeczy, których nie było w dokumentacji

Weryfikacja na żywym sklepie i żywej Algolii wychwyciła zachowania, które przy pracy „z pamięci” skończyłyby się cichymi błędami na produkcji.

ObszarCo się okazałoRozwiązanie
Paginacja ShoperaStrona większa niż 50 pozycji po cichu wraca do 10.Klient zawsze pobiera maksymalnie 50.
Limity APIOdpowiedź 429 przychodzi jako HTML, bez Retry-After.Dławienie według nagłówków X-Shop-Api-* i własny backoff.
Filtry APINieznana składnia filtra jest ignorowana i zwraca cały katalog.Każdą składnię sprawdza test „data z przyszłości daje 0 wyników”.
WebhookiX-Webhook-Id to ID konfiguracji, nie dostawy; zdarzenia potrafią przyjść razem minutę później.Deduplikacja po treści i idempotentne odświeżanie z API.
Usunięte zamówieniePozycji nie da się już pobrać z API, a stan wraca bez zmiany daty modyfikacji.ID produktów brane z treści webhooka, awaryjnie dobowa synchronizacja kontrolna.
Podmiana indeksuAtomowa podmiana w SDK Algolii zawiesza się, gdy indeks jeszcze nie istnieje.Pierwszy import zapisuje wprost, kolejne podmieniają z limitem czasu.
Połączenie z AlgoliąSDK nie przełącza się na zapasowe hosty przy błędzie DNS.Własne ponawianie błędów połączenia.
Szablon StorefrontZgody obsługuje inne API niż w starszym szablonie, a sklep ma Service Workera.Integracja z modułem zgód Storefront i wersjonowanie adresu skryptu.

07 / wskaźniki

Liczby z wdrożenia testowego

~10s
od zmiany produktu w panelu do aktualnego wyniku w wyszukiwarce
3,6s
pełny import 82 produktów z wariantami
0
rozbieżności między sklepem a indeksem w synchronizacji kontrolnej
1,3KB
średni rekord; limit planu to 10 KB
139
testów automatycznych, w tym 6 na prawdziwym sklepie
68
założeń o API zweryfikowanych na żywym sklepie
0
znanych podatności w zależnościach (pip-audit, npm audit)
5,5KB
CSS po kompresji; JS 119 KB, ładowany z defer

Wskaźniki pochodzą ze środowiska testowego: sklep Shoper (Storefront) z katalogiem demonstracyjnym 80 produktów i aplikacja Algolia na planie darmowym. Nie są to dane biznesowe klienta. Wpływ na konwersję i liczbę wyszukiwań bez wyników mierzy się po uruchomieniu na produkcji w Algolia Analytics.

08 / proces

Sześć faz, każda zamknięta weryfikacją i commitem

  1. faza 0SpecyfikacjaZakres, model rekordu, przepływy, decyzje, otwarte pytania.
  2. faza 1Odkrywanie danychKlient API i zanonimizowane odpowiedzi jako fixtures.
  3. faza 2Mapper i importRekordy, konfiguracja Algolii jako kod, CLI.
  4. faza 3AktualizacjeWebhooki sprawdzone na prawdziwych dostawach, kolejka.
  5. faza 4FrontendPodpowiedzi, wyniki, testy e2e na sklepie.
  6. faza 5WdrożenieDocker, CI, dokumentacja, runbook.

technologie

  • Python 3.12
  • FastAPI
  • httpx
  • pydantic
  • SQLite
  • algoliasearch
  • Autocomplete.js
  • InstantSearch.js
  • esbuild
  • Playwright
  • pytest
  • Docker
  • GitHub Actions
  • Shoper REST API

co dalej

Gotowe do uruchomienia u klienta

Przed produkcją zostają decyzje biznesowe: plan Algolii, lista synonimów, zakres analityki i reguła dostępności. Architektura jest przygotowana na kolejne kroki: rekomendacje, personalizację, wyszukiwanie w treściach bloga i indeksy dla kolejnych języków.

następny krok

Masz podobne wyzwanie?

Opisz, co chcesz osiągnąć. Wrócę z konkretną propozycją, wyceną i planem wdrożenia.