E-commerce od zera: Analiza architektury niestandardowego sklepu internetowego

Typowy scenariusz:

1. Przeglądarka pobiera HTML aplikacji (app-shell).
2. Ładuje pliki JS/CSS (z hashem, co umożliwia długie cache'owanie).
3. React inicjalizuje się w #root, a router odczytuje location.pathname.
4. Komponent strony pobiera dane – albo z window.__INITIAL_DATA__ (dane z bootstrapu), albo przez wywołanie REST API.
5. React buduje DOM i dodaje nasłuchiwanie zdarzeń.
6. Kolejne zmiany stron odbywają się w trybie SPA (szybko, bez przeładowania całej strony).

Kluczowy problem SEO: Aplikacja działa w trybie Client-Side Rendering (CSR). Chociaż Google potrafi indeksować JavaScript, to proces ten jest opóźniony, a błędy w API mogą sprawić, że robot zobaczy pustą stronę. Ponadto, app-shell jest zwracany dla każdej ścieżki, nawet jeśli produkt nie istnieje – to prowadzi do tzw. „soft 404” (strona zwraca kod 200, ale nie ma treści). Google wyraźnie odradza takie podejście .

3. Katalog produktów: prosty, ale nieidealny

API katalogu jest sensownie zaprojektowane:

GET /api/products

GET /api/products/<slug>

Jednak są problemy:

• Limit 500 produktów w jednym żądaniu – działa dla 16 produktów, ale dla większego katalogu będzie nieefektywne. Lepiej zastosować paginację kursorem.
• Model danych zorientowany na produkt, a nie na wariant – pole stock jest na poziomie produktu, ale istnieją też variants. To prowadzi do niespójności: stan magazynowy powinien być przypisany do konkretnego wariantu (np. rozmiar M, kolor czarny), a nie do całego produktu.
• Niespójne dane – występują zarówno XXL, jak i 2XL, a także

  ink navy

  i

  Ink Navy

  . Utrudnia to filtrowanie, analitykę i mapowanie zdjęć.

Wniosek: Nowy system powinien mieć scentralizowany model danych z wariantami, SKU i stanem magazynowym na poziomie wariantu.

4. Budowniczy strony głównej i layoutu

Aplikacja wykorzystuje własny CMS do zarządzania stroną główną (/api/homepage) i layoutem (/api/layout). section_order i obiekty włącz/wyłącz wskazują, że strona główna jest kompozycją bloków (hero, trustbar, promocje, produkty), którą można zmieniać bez publikacji nowej wersji frontendu.

Zalety: Duża elastyczność dla marketingu.

Wady: Istnieją aliasy kluczy (np. ann i announcement), a struktura danych (kolejność, przełączniki, payload) może być niespójna. Nowy system powinien używać jednej, spójnej listy bloków z unikalnym ID, typem, stanem i danymi.

5. Ustawienia sklepu: wygoda vs. bezpieczeństwo

Endpoint /api/public/settings zwraca szeroki zakres konfiguracji: od kolorów marki po dane kontaktowe, progi darmowej wysyłki, a nawet tax_id. To wygodne, ale niebezpieczne. Nie wszystkie dane powinny być dostępne publicznie. tax_id, adres prawny czy wewnętrzne e-maile nie powinny trafiać do odpowiedzi API, którą każdy może odczytać. PayPal client_id może być publiczny, ale

client secret

6. Płatności PayPal i logika biznesowa

Przepływ płatności jest prawidłowo zaprojektowany: klient wysyła koszyk i kod rabatowy, serwer samodzielnie oblicza wartości, tworzy zamówienie w PayPal, a następnie je przechwytuje. To jedyna słuszna droga. Serwer nie może ufać danym z przeglądarki (cena, rabat, wysyłka).

Potencjalne problemy wymagające uwagi:

• Idempotencja (zabezpieczenie przed podwójnym kliknięciem).
• Transakcje bazodanowe (uniknięcie oversellingu).
• Weryfikacja webhooków PayPal.
• Mechanizm uzgadniania (reconciliation) dla przypadków, gdy PayPal potwierdzi płatność, ale odpowiedź nie dotrze do sklepu.

7. Pozostałe endpointy: recenzje, newsletter, kontakt, śledzenie

Sklep oferuje pełen zakres funkcji e-commerce. Warto zwrócić uwagę na:

• Recenzje: Potrzebują stanu (oczekujące/zaakceptowane), ochrony przed spamem i weryfikacji zakupu. Nazwa endpointu

  POST /api/reviews/<id>

  jest myląca – nowy system powinien używać RESTful resource naming.
• Newsletter: Wymaga normalizacji e-maili, unikalności, double opt-in i mechanizmu rezygnacji.
• Kontakt: Niezbędny jest CAPTCHA lub inna ochrona przed botami.
• Śledzenie zamówień: Publiczny endpoint może być podatny na ataki typu „enumeration” (przeglądanie zamówień po numerze). Należy użyć tokena lub dodatkowych danych uwierzytelniających.

8. Porównanie: Custom vs. WooCommerce – co jest lepsze?

Wniosek: Custom daje pełną kontrolę, ale wymaga zespołu i budowy wszystkiego od zera. WooCommerce jest prostszy i szybszy we wdrożeniu, ale ogranicza elastyczność. Nie ma jednoznacznej odpowiedzi – wybór zależy od priorytetów (szybkość wdrożenia vs. unikalne UX).

9. Plan przepisania: od SPA do hybrydy

Zamiast przepisywać aplikację na WooCommerce, zalecamy przepisanie jej od nowa, zachowując koncepcję customowego backendu, ale zmieniając strategię renderowania i model danych.

Zalecany stos technologiczny:

• Frontend: Next.js (App Router) z React i TypeScript. Umożliwia SSR, ISR i statyczne generowanie stron, co rozwiązuje problemy SEO kosztem nieco większej złożoności.
• Backend: NestJS (z Fastify) lub modułowy Fastify z TypeScript. Zapewnia strukturę, walidację i typowanie.
• Baza danych: PostgreSQL jako źródło prawdy. Drizzle ORM lub Prisma do migracji i bezpiecznych zapytań.
• Cache: Redis (tylko w razie potrzeby).
• Kolejki: BullMQ do zadań asynchronicznych (e-maile, webhooki).
• Storage: S3-compatible object storage dla multimediów.
• Obserwowalność: OpenTelemetry + strukturalne logi.

Kluczowe zmiany w projekcie:

1. Renderowanie hybrydowe: Użyj Next.js do generowania statycznych stron produktów i kategorii (ISR). Strony dynamiczne (koszyk, konto) mogą być renderowane po stronie serwera. Zmniejszy to zależność od JavaScript i poprawi SEO.
2. Model danych: Zastąp płaską strukturę produktu modelem z wariantami (rozmiar, kolor, stan magazynowy). Ujednolić wartości opcji (usunąć duplikaty).
3. Builder strony głównej: Zastąp rozproszoną konfigurację (section_order + toggles + payload) jedną, spójną listą bloków z własnym schematem.
4. Ustawienia: Podziel konfigurację na publiczną i prywatną. Nie udostępniaj danych wrażliwych przez publiczne API.
5. Checkout: Dodaj idempotencję, transakcje bazodanowe i mechanizm uzgadniania płatności.
6. Bezpieczeństwo: Wprowadź walidację dla wszystkich endpointów (CAPTCHA, rate limiting, ochrona przed enumeracją).

10. Podsumowanie

Obecna platforma jest solidna, ale ma poważne wady: model CSR jest problematyczny dla SEO, a model danych wymaga normalizacji. Przepisanie jej na Next.js z renderowaniem hybrydowym i solidniejszym backendem to inwestycja, która się opłaci, jeśli priorytetem jest unikalne doświadczenie marki i skalowalność. Dla małego sklepu z 16 produktami warto rozważyć, czy prostsze i tańsze w utrzymaniu WooCommerce nie będzie lepszym rozwiązaniem. Ostateczna decyzja należy do właściciela, ale kluczowe jest, aby podjąć ją świadomie, rozumiejąc kompromisy.