Katalog części i akcesoriów

Katalog części i akcesoriów VW Polo 6R

Kompleksowy, wielojęzyczny katalog oryginalnych części OEM i akcesoriów do Volkswagena Polo 6R/6C, zbudowany w całkowicie odseparowanej architekturze headless. Statyczny frontend w Astro pobiera dane z Laravelowego REST API podczas budowania i generuje czyste strony HTML, które nie odpytują bazy danych w trakcie działania. To nie jest sklep internetowy, ale ma większość funkcji znanych z e-commerce — listy produktów, filtrowanie, wyszukiwanie i szczegółowe specyfikacje — brakuje tylko płatności.

Projekt przeszedł kilka iteracji: od wczesnego SPA w Vue 2, przez Vue 3, aż po obecną wersję opartą na Astro 6 (SSG) z wyspami Vue 3 dla interaktywnych komponentów.

Architektura: headless CMS + statyczny frontend

System jest podzielony na dwa niezależne repozytoria:

Frontend (catalog.polo.blue) — statyczny generator stron Astro 6 z komponentami Vue 3, stylami UnoCSS i własnym systemem projektowym. Wszystkie dane pobierane są z API wyłącznie na etapie budowania. Przeglądarka nigdy nie łączy się bezpośrednio z backendem — z wyjątkiem narzędzi działających po stronie klienta, takich jak dekoder kodów PR.

Backend — aplikacja Laravel 13 udostępniająca REST API oraz panel administracyjny Filament 5. Zarządza produktami, kategoriami, tłumaczeniami, mediami, danymi SEO i wdrożeniami strony. Stoi na MySQL, Redisie (kolejki obsługiwane przez Laravel Horizon dla zadań w tle: konwersji obrazów, tłumaczeń i budowania strony) oraz Cloudflare R2 jako magazynie plików dla CDN. Wdrożenie strony można uruchomić wprost z panelu.

Dzięki temu rozdzieleniu frontend pozostaje w pełni statyczny — szybki, bezpieczny i globalnie buforowany przez CDN Cloudflare.

Przetwarzanie obrazów i CDN

Sporym wyzwaniem była optymalizacja obrazów — katalog jest obszerny, a ruch w większości mobilny. Rozwiązanie ewoluowało: od kompresji na etapie budowania (Sharp/Astro) po przeniesienie całego procesu na backend:

1. Wgrywanie — obrazy trafiają na Cloudflare R2 (kompatybilne z S3) przez Spatie Media Library
2. Konwersja — kolejki Laravel Horizon generują miniatury w wielu rozmiarach, w formatach AVIF i WebP
3. Dostarczanie — pliki serwowane są z dedykowanej subdomeny CDN, a ich adresy — w postaci zdenormalizowanej — trafiają bezpośrednio do modeli Product/Category, co eliminuje zapytania JOIN na listach produktów
4. Monitoring — widget CDN Stats w panelu pokazuje łączne zużycie miejsca, podział na modele i odsetek produktów z kompletem wygenerowanych konwersji

WebP pełni rolę formatu zapasowego dla AVIF, którego Grafika Google wciąż indeksuje w ograniczonym zakresie.

Wielojęzyczność i automatyczne tłumaczenia

Katalog obsługuje trzy języki — angielski, polski i niemiecki. Cała treść podlegająca tłumaczeniu (produkty, kategorie, kolory, materiały, kody PR, wpisy FAQ i nie tylko) korzysta z jednego, wspólnego systemu tłumaczeń, więc dodanie kolejnego języka nie wymaga zmian w schemacie bazy.

• DeepL API automatycznie tłumaczy treść z angielskiego na polski i niemiecki w zadaniach kolejkowanych w tle
• Opisy generowane przez AI powstają w języku angielskim z użyciem łańcucha awaryjnego obejmującego wielu dostawców LLM, a następnie trafiają do tłumaczenia przez DeepL
• Osobna struktura adresów dla każdego języka (/ dla EN, /pl/ dla polskiego, /de/ dla niemieckiego) z poprawnie skonfigurowanymi tagami hreflang
• Statyczne napisy interfejsu ładowane są z plików JSON, a przetłumaczona treść trafia z API już zlokalizowana

Optymalizacja wydajności

Podzielony proces budowania

Budowanie wszystkich trzech wersji językowych w jednym przebiegu Astro wyczerpywało pamięć (10–20 GB RAM). Rozwiązaniem jest własny skrypt dzielący build: przetwarza po jednej wersji językowej, dla każdej osobno uruchamia indeksowanie Pagefind, a na końcu scala wszystko w katalogu dist/. Łączny czas budowania to ~5–6 minut dla wszystkich wersji.

Ograniczenie liczby zapytań API

Wstępne buforowanie kategorii pobiera wszystkie produkty dla danej kategorii głównej w jednym zapytaniu do API, a potem filtruje je lokalnie. Dzięki temu ~60 pojedynczych zapytań zamieniło się w kilka wywołań zbiorczych w trakcie budowania.

Wydajność frontendu

• content-visibility: auto na kartach produktów poza ekranem, co obniża koszt renderowania
• Stan zwinięcia panelu bocznego odtwarzany z localStorage jeszcze przed pierwszym renderowaniem, co zapobiega przesunięciom układu (CLS)
• Wstępne ładowanie czcionek (firmowe fonty VW) oraz preconnect do CDN i domen analitycznych
• Ręcznie wydzielone chunki Vite oddzielające kod bibliotek (Vue, system projektowy) od kodu stron
• Pierwsze trzy zdjęcia produktów ładują się natychmiast (na pierwszym fetchpriority="high"), reszta — leniwie

SEO i widoczność w wyszukiwarkach

Mocne SEO to główne źródło ruchu, zwłaszcza z wyszukiwarek grafiki. Najważniejsze elementy:

• Dane strukturalne (JSON-LD) — rozbudowany @graph z IndividualProduct (zamiast Product, by zaznaczyć niehandlowy charakter katalogu), BreadcrumbList, ItemList na stronach kategorii oraz encją Organization
• Mapy witryny XML — generowane po stronie serwera dla każdej wersji językowej i typu (produkty, kategorie, strony), pobierane na etapie budowania; arkusze stylów XSL zapewniają czytelny podgląd w przeglądarce
• llms.txt — pliki ułatwiające modelom AI/LLM odnalezienie treści, zgodne ze specyfikacją llmstxt.org
• Linkowanie wewnętrzne — sekcje „Powiązane produkty”, „Podobne produkty” i przyciski nawigacji w obrębie kategorii (sprawdzone testami A/B) wzmacniają przepływ mocy linków i ułatwiają poruszanie się po katalogu
• Pagefind — wyszukiwarka pełnotekstowa działająca offline, indeksowana osobno dla każdej wersji językowej, bez zewnętrznych zależności
• Panel SEO — widgety w panelu sprawdzają zbyt krótkie i zbyt długie tytuły, brakujące opisy oraz kompletność danych we wszystkich trzech językach

Interaktywne narzędzia

Trzy działające po stronie klienta narzędzia Vue 3 zwiększają użyteczność katalogu:

• Kalkulator opon i felg — porównuje dwie konfiguracje opon i felg, liczy różnicę średnicy oraz odchyłkę wskazań prędkościomierza, z wizualizacją SVG
• Przelicznik mocy — przelicza KM, kW i PS, pokazując wynik na wykresie słupkowym
• Dekoder kodów PR — rozszyfrowuje fabryczne kody wyposażenia VW (trzyznakowe), odpytując API i buforując wyniki po stronie klienta

Narzędzia są odizolowane w osobnej trasie Astro, żeby ich CSS (~25 KB) nie obciążał głównych stron katalogu.

Backend i panel administracyjny

Backend oparty na Laravelu 13 i Filamencie 5 udostępnia REST API oraz rozbudowany panel administracyjny podzielony na funkcjonalne klastry:

Zarządzanie treścią

• Zarządzanie produktami ze szczegółowymi specyfikacjami, kodami PR, dopasowaniem do silników i obsługą wielu języków
• Hierarchiczne kategorie z obsługą ikon i obrazów OG
• Kreator stron CMS z 13 typami bloków (hero, jumbotron, karuzela, CTA, FAQ, statystyki itd.)
• Zarządzanie tłumaczeniami z wsadową automatyzacją DeepL i flagami chroniącymi kluczowe tłumaczenia przed nadpisaniem

REST API

API korzysta z konfigurowalnych presetów odpowiedzi, które dla każdego endpointu określają, jak wiele danych dołączyć — listy pozostają lekkie, a widoki szczegółowe bogate. Nagłówki cache HTTP są dostrajane dla każdej trasy, by maksymalizować liczbę trafień w CDN.

Pulpity analityki i monitoringu

• Google Analytics 4 — odsłony, użytkownicy, sesje, urządzenia, najczęstsze źródła odesłań i dane geograficzne (14 widgetów)
• Google Search Console — kliknięcia, wyświetlenia, CTR, średnia pozycja oraz najpopularniejsze strony i zapytania
• Core Web Vitals — śledzenie CLS, LCP i INP w czasie
• Google AdSense — monitorowanie przychodów z wielu witryn wraz z alertami o spadkach

Operacje i utrzymanie

• Wdrożenie strony jednym kliknięciem, które uruchamia build Astro w kolejce zadań (osobna kolejka site-build, żeby nie blokować tłumaczeń i przetwarzania mediów)
• Czyszczenie cache Cloudflare według adresu URL, prefiksu lub typu modelu
• Narzędzia do kopii zapasowych i przywracania bazy danych
• Rejestrowanie aktywności i pełna ścieżka audytu
• Pulpit kompletności danych wykrywający braki w mediach, tłumaczeniach, opisach i ocenie jakości linków

Przekierowania i odzyskiwanie ruchu z 404

Autorski moduł przekierowań wbudowany w panel Filament zamienia obsługę błędów 404 z ręcznej roboty w proces oparty na danych:

• Import CSV z raportów GSC i Ahrefs — adresy są wrzucane hurtowo ze znacznikiem źródła na każdym wpisie (gsc_404, ahrefs_404, manual, import), więc redakcja priorytyzuje po realnym wpływie na ruch zamiast zgadywać
• Kontekst GSC zapisany przy każdym przekierowaniu — kliknięcia, wyświetlenia oraz daty pierwszego i ostatniego wykrycia są przypięte do wiersza i widoczne na liście — od razu widać, które 404 faktycznie kosztowały ruch organiczny
• Automatyczne rozwiązywanie błędów crawlowania — utworzenie przekierowania automatycznie oznacza pasujące nierozwiązane wpisy GscCrawlError jako rozwiązane i wiąże je z ID przekierowania, zapisując użytkownika i znacznik czasu
• Zabezpieczenie przed self-redirectami — model rzuca wyjątek przy zapisie, jeśli old_url === new_url po normalizacji ścieżki (wielkość liter jest zachowana, ponieważ URL-e typu /6R0601025AEZ49/ vs /6r0601025aez49/ są różnymi adresami) — nieskończone pętle są wyłapywane przed wejściem na produkcję
• Wzorce regex, soft deletes, pełen audit trail przez Spatie Activitylog, obsługa 301/302/307/308 oraz hit_count i last_hit_at wskazujące stare przekierowania bezpieczne do usunięcia

Zapytania klientów o produkt

Każdy produkt ma własny formularz zapytań, a wiadomości lądują w panelu jako pełne konwersacje — nie pojedyncze maile w skrzynce, które łatwo zgubić:

• Wątek konwersacji w jednym widoku — wymiana między klientem a adminem zapisana chronologicznie, z autorami, datami i wklejonymi linkami do śledzenia przesyłki (Poczta Polska, GLS) widocznymi obok wiadomości
• Metadane geo i lokalizacyjne dla każdego zapytania — IP, kraj, miasto, region, referrer (sale.polo.blue vs catalog.polo.blue) i User Agent zachowane przy każdym wpisie, co pozwala priorytetyzować rynki bez dodatkowego logowania do GA
• Powiązany produkt — panel boczny widoku pokazuje ID, nazwę i miniaturkę produktu, którego dotyczy zapytanie; z karty produktu można też przejść do historii wszystkich zapytań o ten konkretny SKU
• Notatki wewnętrzne — admini mogą dorzucić notatkę niewidoczną dla klienta (cena specjalna, status wysyłki, ostrzeżenie o ryzykownym rynku) z autorem i znacznikiem czasu
• Status pipeline — Replied / Pending / Closed śledzą, gdzie utknęło zapytanie, a język przeglądarki i locale pozwalają oszacować rynek docelowy, zanim wyjdzie pierwsza odpowiedź

Komentarze z WordPressa — powiadomienia i odpowiedzi

Blog polo.blue działa na headless WordPressie, ale jego komentarze są moderowane w całości z panelu Filament — administratorzy nie muszą już otwierać wp-admin, żeby obsłużyć codzienny strumień:

• Dwukierunkowa synchronizacja z WP REST API — WordPressCommentSync pobiera przyrostowo nowe oczekujące i zatwierdzone komentarze (cursor w cache’u z jednominutowym nakładaniem, żeby zabezpieczyć się przed różnicą zegarów między WP a panelem) i wypycha akcje moderacyjne z powrotem przez /wp-json/wp/v2/comments
• Pełna moderacja z poziomu panelu — zatwierdzanie, oznaczanie jako spam, wyrzucanie do kosza i odpowiadanie — wszystko bez opuszczania Filamenta. Odpowiedzi są publikowane z powrotem do WP jako komentarze dzieci, automatycznie zatwierdzane i przypięte do rodzica (wp_reply_id, replied_by_user_id, replied_at), więc zawsze widać, kto i kiedy odpowiedział
• Powiadomienia push przy nowych oczekujących komentarzach — administratorzy dostają powiadomienie (tytuł + autor + tytuł wpisu, z deep linkiem do /admin/blog-comments), więc żaden komentarz nie czeka na ręczne sprawdzenie wp-admin
• Świadomość wielojęzyczności — każdy komentarz dziedziczy język wpisu źródłowego (EN/PL — blog prowadzony jest w dwóch językach), dzięki czemu można go filtrować per locale w widoku listy
• Metadane wpisu cache’owane — tytuły i permalinki są rozwiązywane raz per batch i reużywane dla kolejnych komentarzy, eliminując zbędne zapytania do WP REST w trakcie synchronizacji
• Awaryjna furtka — każdy wiersz wystawia wpAdminUrl() jako bezpośredni skok do WP admin edit, na wypadek rzadkich sytuacji wymagających natywnego interfejsu

Baza wiedzy FAQ

Katalog ma zintegrowany system FAQ ze specyfikacjami technicznymi i poradnikami dla VW Polo 6R. Treść jest pogrupowana według kategorii produktów (opony, felgi, olej silnikowy, klimatyzacja, hamulce, zawieszenie, elementy karoserii), wyświetla się w wielu językach i linkuje do szczegółowych wpisów na blogu.

Wdrażanie

Frontend korzysta ze strategii wdrożeń atomowych:

• Push do main uruchamia GitHub Actions
• Dzielony build Astro wykonywany na serwerze hostingowym
• Każde wydanie trafia do katalogu oznaczonego znacznikiem czasu, a public_html jest dowiązaniem symbolicznym
• Wycofanie zmian (rollback) trwa poniżej sekundy — wystarczy przepiąć dowiązanie na poprzednie wydanie

Wyniki

Architektura headless, agresywna optymalizacja obrazów i dane strukturalne JSON-LD przekładają się na wymierny ruch organiczny — Google Analytics 4 pokazuje 14 tys. aktywnych użytkowników i 187 tys. zdarzeń w ostatnich 28 dniach, w większości z wyszukiwarki Google i Grafiki Google.

Zrzut raportów potwierdza, że ruch organiczny (Organic Search) jest głównym kanałem pozyskania, a rozkład zdarzeń (najczęściej product_view, ai_search_query, scroll, ad_impression) pokazuje, że użytkownicy faktycznie przeglądają katalog i korzystają z wbudowanej wyszukiwarki AI, a nie tylko odbijają się od strony głównej.

Wykorzystane technologie

Mocne SEO, optymalizacja obrazów i dane strukturalne przyciągają znaczący ruch organiczny — zwłaszcza z wyszukiwarek grafiki — a architektura headless utrzymuje stronę szybką, bezpieczną i łatwą w utrzymaniu.