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 pełni oddzielonej architekturze headless. Statyczny frontend Astro pobiera dane z Laravel REST API w czasie budowania, generując czyste strony HTML bez zapytań do bazy danych w czasie działania. Choć nie jest to sklep internetowy, posiada wiele funkcji typowych dla e-commerce — listy produktów, filtrowanie, wyszukiwanie, szczegółowe specyfikacje — z wyjątkiem obsługi płatności.

Projekt przeszedł kilka iteracji: od wczesnego SPA w Vue 2, przez Vue 3, do obecnej konfiguracji 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 Astro 6 z komponentami Vue 3, stylowaniem UnoCSS i własnym systemem designu. Wszystkie dane są pobierane z API wyłącznie podczas kroku budowania. Przeglądarka nigdy nie kontaktuje się bezpośrednio z backendem (z wyjątkiem narzędzi po stronie klienta, jak dekoder kodów PR).

Backend — aplikacja Laravel 13 serwująca REST API i panel administracyjny Filament 5. Zarządza produktami, kategoriami, tłumaczeniami, mediami, danymi SEO i wdrożeniami strony. Oparty na MySQL, Redis (kolejki przez Laravel Horizon do zadań w tle jak konwersja obrazów, tłumaczenia i buildy strony) i Cloudflare R2 jako storage CDN. Wdrożenia strony można uruchamiać bezpośrednio z panelu administracyjnego.

Ta separacja oznacza, że frontend jest czysto statyczną stroną — szybką, bezpieczną i globalnie cache’owalną przez Cloudflare CDN.

Pipeline obrazów i CDN

Kluczowym wyzwaniem była optymalizacja obrazów przy rozbudowanym katalogu produktów i przewadze ruchu mobilnego. Rozwiązanie ewoluowało od kompresji w czasie budowania przez Sharp/Astro do pipeline’u po stronie backendu:

1. Upload — Obrazy są przechowywane na Cloudflare R2 (kompatybilnym z S3) przez Spatie Media Library
2. Konwersja — Kolejki Laravel Horizon generują miniaturki w wielu rozmiarach w formatach AVIF i WebP
3. Dostarczanie — Serwowane z dedykowanej subdomeny CDN ze zdenormalizowanymi URL-ami zapisanymi bezpośrednio na modelach Product/Category, eliminując zapytania JOIN w widokach list
4. Monitoring — Widget CDN Stats w panelu administracyjnym śledzi całkowity storage, rozkład per model i procent produktów z kompletem konwersji

WebP służy jako fallback dla AVIF ze względu na jego wciąż ograniczone indeksowanie w Google Image Search.

Wielojęzyczność i automatyczne tłumaczenia

Katalog obsługuje trzy języki — angielski, polski i niemiecki. Cała tłumaczalna treść (produkty, kategorie, kolory, materiały, kody PR, wpisy FAQ i więcej) współdzieli jeden zunifikowany system tłumaczeń, więc dodanie nowego języka nie wymaga zmian w schemacie bazy.

• DeepL API automatycznie tłumaczy treść z angielskiego na polski i niemiecki przez zadania kolejkowane w tle
• Opisy generowane przez AI używają łańcucha fallbacków na wielu dostawcach LLM do generowania angielskiej treści, która jest następnie tłumaczona przez DeepL
• Struktury URL per język (/ dla EN, /pl/ dla polskiego, /de/ dla niemieckiego) z prawidłowo skonfigurowanymi tagami hreflang
• Statyczne napisy UI ładowane z plików JSON, tłumaczenia treści serwowane już zlokalizowane przez API

Optymalizacja wydajności

System podzielonego budowania

Budowanie wszystkich trzech lokalizacji w jednym przebiegu Astro powodowało wyczerpanie pamięci (10-20 GB RAM). Rozwiązanie: własny skrypt split build przetwarzający jedną lokalizację na raz, uruchamiający indeksowanie Pagefind per lokalizacja, a następnie łączący wszystko w końcowy katalog dist/. Całkowity czas budowania: ~5-6 minut dla wszystkich lokalizacji.

Redukcja zapytań API

Cache prefetch kategorii pobiera wszystkie produkty per główna kategoria w pojedynczym zapytaniu API, następnie filtruje lokalnie. Zredukowało to ~60 indywidualnych zapytań API do kilku wywołań wsadowych podczas budowania.

Wydajność frontendu

• content-visibility: auto na elementach produktów poza ekranem, redukując koszt renderowania
• Stan zwinięcia sidebara przywracany z localStorage przed pierwszym renderowaniem, zapobiegając CLS
• Preloading czcionek (czcionki marki VW), preconnect do CDN i domen analitycznych
• Ręczne chunki Vite oddzielające kod vendora (Vue, design system) od kodu stron
• Pierwsze 3 obrazy produktów ładowane natychmiast, z fetchpriority="high" na pierwszym obrazie; reszta leniwie

SEO i odkrywalność

Silne SEO jest głównym źródłem ruchu, szczególnie z wyszukiwarek grafiki. Kluczowe strategie:

• Dane strukturalne (JSON-LD) — Rozbudowany markup @graph z IndividualProduct (nie Product, aby sygnalizować katalog nie-handlowy), BreadcrumbList, ItemList dla stron kategorii i encje Organization
• Mapy witryny XML — Generowane po stronie serwera per lokalizacja i typ (produkty, kategorie, strony), pobierane w czasie budowania z arkuszami stylów XSL do wyświetlania w przeglądarce
• llms.txt — Pliki odkrywalności AI/LLM zgodne ze specyfikacją llmstxt.org
• Linkowanie wewnętrzne — Powiązane produkty, podobne produkty i przyciski nawigacji w kategorii (zwalidowane testami A/B) poprawiają przepływ linków i użytkowników
• Pagefind — Offline’owe wyszukiwanie pełnotekstowe indeksowane per lokalizacja, bez zewnętrznych zależności
• Dashboard SEO — Widgety panelu administracyjnego audytują krótkie/długie tytuły, brakujące opisy i kompletność danych we wszystkich trzech językach

Interaktywne narzędzia

Trzy narzędzia Vue 3 po stronie klienta wzbogacają użyteczność katalogu:

• Kalkulator opon i felg — Porównuje dwie konfiguracje opon/felg, oblicza różnice średnicy i odchylenie prędkościomierza, z wizualizacją SVG
• Przelicznik mocy — Konwertuje między KM, kW i PS z wizualnym wykresem słupkowym
• Dekoder kodów PR — Dekoduje fabryczne kody opcji VW (3-znakowe) odpytując API, z cache’owaniem po stronie klienta

Narzędzia te są wyizolowane w osobnej trasie Astro, aby ich CSS (~25 KB) nie wpływał na główne strony katalogu.

Backend i panel administracyjny

Backend oparty na Laravel 13 i Filament 5 dostarcza REST API i zapewnia kompleksowy panel administracyjny zorganizowany w funkcjonalne klastry:

Zarządzanie treścią

• Zarządzanie produktami ze szczegółowymi specyfikacjami, kodami PR, kompatybilnością silników i obsługą wielu języków
• Hierarchiczna organizacja kategorii z zarządzaniem ikonami i obrazami OG
• Kreator stron CMS z 13 typami bloków (hero, jumbotron, karuzela, CTA, FAQ, statystyki itp.)
• Zarządzanie tłumaczeniami z automatyzacją wsadową DeepL i flagami ochrony dla krytycznych tłumaczeń

REST API

API używa konfigurowalnych presetów odpowiedzi kontrolujących głębokość dołączanych danych per endpoint — utrzymując lekkie odpowiedzi dla list i bogate dla widoków szczegółowych. Nagłówki cache HTTP są dostrajane per trasa, aby zmaksymalizować trafienia CDN.

Dashboardy analityki i monitoringu

• Google Analytics 4 — Odsłony, odwiedzający, sesje, urządzenia, top referrerzy, dane geograficzne (14 widgetów)
• Google Search Console — Kliknięcia, wyświetlenia, CTR, średnia pozycja, top strony i zapytania
• Core Web Vitals — Śledzenie szeregu czasowego CLS, LCP, INP
• Google AdSense — Śledzenie przychodów z wielu stron z alertami o spadkach

Operacje i utrzymanie

• Wdrażanie strony jednym kliknięciem uruchamiające buildy Astro przez zadania kolejkowane (osobna kolejka site-build, aby nie blokować zadań tłumaczeń/mediów)
• Czyszczenie cache Cloudflare według URL, prefiksu lub typu modelu
• Narzędzia backup/przywracania bazy danych
• Logowanie aktywności i pełna ścieżka audytu
• Dashboard kompletności danych audytujący brakujące media, tłumaczenia, opisy i jakość linków

Redirects i odzyskiwanie ruchu 404

Autorski moduł redirectów 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 zachowany per redirect — kliki, wyświetlenia oraz daty pierwszej i ostatniej detekcji są przypisane 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 redirectu automatycznie oznacza pasujące nierozwiązane wpisy GscCrawlError jako rozwiązane i linkuje je do ID redirectu, z zalogowanym userem i znacznikiem 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 redirecty bezpieczne do usunięcia

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ą notyfikację (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 zawiera zintegrowany system FAQ dostarczający specyfikacje techniczne i poradniki dla VW Polo 6R. Treść jest zorganizowana według kategorii produktów (opony, felgi, olej silnikowy, klimatyzacja, hamulce, zawieszenie, części karoserii) i obsługuje wielojęzyczne wyświetlanie z linkami do szczegółowych wpisów na blogu.

Wdrażanie

Frontend używa strategii wdrażania atomowego:

• Push do main uruchamia GitHub Actions
• Split build Astro wykonywany na serwerze hostingowym
• Każde wydanie trafia do katalogu ze znacznikiem czasu; public_html to symlink
• Rollback trwa poniżej 1 sekundy przez przepięcie symlinka na poprzednie wydanie

Wykorzystane technologie

Silne SEO, optymalizacja obrazów i dane strukturalne przyciągają znaczący ruch organiczny — szczególnie z wyszukiwarek grafiki — podczas gdy architektura headless utrzymuje stronę szybką, bezpieczną i łatwą w utrzymaniu.