# Katalog części i akcesoriów
> Katalog części OEM do VW Polo 6R oparty na headless CMS. Frontend Astro SSG, Vue 3, backend Laravel REST API, panel Filament, tłumaczenia DeepL i opisy AI.
- URL: https://spoko.space/pl/katalog-czesci-vw-polo-6r/
- Published: 2026-04-02
- Updated: 2026-06-17
- Tags: astro, vue3, unocss, laravel, filament, pwa, cloudflare, i18n, meilisearch, redis
---## 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](https://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](/pl/modern-car-blog/) 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.