Ewolucja architektury i log modernizacji

Ten dokument przedstawia szczegółowy, techniczny przebieg modernizacji Comers, platformy commerce opartej o Yii2 i dostępnej pod adresem comers.app.

Opis obejmuje rzeczywiste zmiany wdrożone na systemie produkcyjnym.

To nie jest koncepcja ani redesign —
to realna transformacja działającego systemu, prowadzona iteracyjnie.

Overview

Pierwotny system stojący za Comers był monolitem opartym o Yii2, odpowiedzialnym za:

• zarządzanie zamówieniami
• integracje marketplace (eBay, Amazon, WooCommerce, Baselinker)
• listingi
• shipping
• faktury i raporty
• przetwarzanie w tle (joby)

Strategia modernizacji zakłada:

• wprowadzanie jawnych granic domenowych
• przebudowę do modularnej architektury
• zastępowanie implicit zależności kontraktami (porty)
• przygotowanie pod stopniową ekstrakcję do mikroserwisów

Faza: 2026-02

1. Wydzielenie nowych modułów domenowych

W systemie zostały zaimplementowane i zarejestrowane nowe moduły:

• ebay
• messages
• listings
• shipping
• notifications

Każdy moduł posiada:

• warstwę aplikacyjną (use case’y)
• warstwę integracyjną
• repozytoria infrastrukturalne
• adaptery
• jasno określony zakres odpowiedzialności

To oznacza przejście z:

„płaskiego monolitu”

do:

„modularnego monolitu z wyraźnymi boundary”

2. Przebudowa integracji eBay

Powstał nowy moduł integracyjny eBay obsługujący:

• eBay Trading API (legacy)
• eBay REST API (nowe)

Wdrożone elementy:

• EbayIntegrationPort (kontrakt aplikacyjny)
• LocalEbayIntegrationAdapter
• HttpEbayIntegrationAdapter
• flow autoryzacji OAuth
• use case’y wymiany tokenów
• use case’y importu listingów
• use case’y integracji wiadomości

Dodatkowo:

• obsługa podłączania i odłączania kont
• obsługa callbacków
• webhook / endpoint account deletion

Efekt:

• logika integracyjna nie jest już osadzona bezpośrednio w modelach domenowych
• wyraźna separacja pomiędzy systemem a zewnętrznym providerem
• gotowość do wydzielenia jako osobny serwis

3. Moduł wiadomości (warstwa konwersacyjna)

Nowy moduł messages wprowadza:

• model wątków (threads)
• obsługę konwersacji
• dedykowany UI
• endpointy REST API

Funkcjonalności:

• lista wątków
• pobieranie wiadomości w wątku
• wysyłanie odpowiedzi
• oznaczanie jako przeczytane
• archiwizacja / przywracanie
• resync i reprocess

Architektura:

• MessagesChannelPort
• adapter eBay dla wiadomości
• repozytorium raw payloadów
• repozytorium domenowe
• use case’y dla sync, read, reply i reprocess

Efekt:

• komunikacja staje się pełnoprawnym obszarem domenowym
• koniec rozproszonej logiki wiadomości
• przygotowanie pod obsługę multi-channel

4. Moduł listingów

Nowy moduł listings obejmuje:

• dedykowaną warstwę API
• endpointy importu / upsert / reprocess
• linkowanie produktów
• przepływ ingestii danych zewnętrznych

Elementy architektury:

• registry providerów źródeł
• repozytorium payloadów zewnętrznych
• serwisy ingestii
• separację danych źródłowych od modelu domenowego

Efekt:

• listingi nie są już ściśle sprzężone z integracjami
• jasna ścieżka do wydzielenia logiki marketplace
• lepsza kontrola nad cyklem życia ingestii danych

5. Moduł shipping (DPD, DHL)

Nowy moduł shipping zawiera:

• ShippingIntegrationPort
• adaptery lokalne i HTTP
• dispatcher tworzenia etykiet
• architekturę opartą o providerów

Obsługiwani providerzy:

• DPD
• DHL

Efekt:

• spójna warstwa integracji kurierskich
• uproszczone dodawanie nowych providerów
• eliminacja rozproszonej logiki shippingowej

6. Moduł notyfikacji

Moduł notifications zapewnia:

• listę notyfikacji
• liczniki
• read / read-all
• archive / unarchive
• usuwanie

Zawiera:

• własny UI
• endpointy REST API

Efekt:

• komunikacja systemowa została uporządkowana
• fundament pod alerty i sygnalizację operacyjną
• separacja od workflow biznesowych

7. Porty i adaptery (kluczowa zmiana)

W systemie wdrożono:

• porty aplikacyjne (interfejsy / kontrakty)
• adaptery infrastrukturalne (local / HTTP)
• orkiestrację opartą o use case’y
• abstrakcję repozytoriów

Przykłady:

• EbayIntegrationPort
• MessagesChannelPort
• ShippingIntegrationPort

Efekt:

• przejście z implicit architektury do jawnej
• mocny fundament pod ekstrakcję usług
• lepsza testowalność i utrzymywalność

8. Model raw-first ingestion

Wprowadzono podejście:

• zapisu danych zewnętrznych jako raw payloadów
• oddzielenia fetch od przetwarzania domenowego
• wdrożenia możliwości reprocessingu

Dotyczy:

• listings
• messages

Efekt:

• większa odporność na błędy integracji
• możliwość replay i debugowania przepływów danych
• brak zależności od jednorazowego przetwarzania

9. Stateless + object storage

System przeszedł częściowo na model stateless:

• etykiety kurierskie → object storage (zgodne z S3)
• raporty → artefakty pobierane przez signed URL
• lokalny filesystem → wyłącznie tymczasowy workspace

Efekt:

• usunięcie zależności od trwałego storage lokalnego
• gotowość na środowiska kontenerowe / rozproszone
• zgodność z nowoczesnym, cloud-native modelem storage

10. Stabilizacja jobów i runtime

Nowy model jobów:

• kontenery jobowe oparte o Dockera
• współdzielony wrapper runtime
• MySQL advisory locks (distributed locking)
• timeouty
• structured logging
• jitter (przy starcie i iteracji)

Efekt:

• eliminacja duplikacji wykonań
• mniej race conditions
• większa obserwowalność
• bezpieczniejsze przetwarzanie wsadowe

11. Cleanup technologiczny

Środowisko runtime zostało zaktualizowane i ustabilizowane:

• upgrade do PHP 8.1 (z przygotowaniem pod nowsze wersje)
• konfiguracja oparta o .env
• usunięcie hardcoded credentials / danych konfiguracyjnych
• uporządkowanie zależności

Efekt:

• nowocześniejsze środowisko wykonawcze
• mniej długu technicznego
• większa spójność procesu deploymentu

12. UI

Nowe UI zostało wdrożone dla:

• modułu messages
• modułu notifications

Dodatkowo:

• uproszczono wybrane legacy widoki
• częściowo uporządkowano strukturę frontendową

Efekt:

• lepsza użyteczność dla użytkowników operacyjnych
• bardziej spójne wzorce interakcji
• przygotowanie gruntu pod przyszłą architekturę SPA / BFF

13. CI/CD i delivery

Proces delivery został usprawniony przez:

• pipeline’y CI
• wersjonowane release’y
• buildy obrazów kontenerowych
• uporządkowane środowiska runtime

Efekt:

• powtarzalne deploymenty
• lepszą kontrolę nad release’ami
• przygotowanie pod skalowalne środowiska

14. Dokumentacja

Modernizacja jest wspierana przez:

• dokumentacja techniczna
• notatki architektoniczne
• specyfikacje runtime
• planowanie migracji

Ten log będzie rozszerzany o kolejne fazy.

Kolejne fazy

Planowane obszary dalszej transformacji:

• ekstrakcja wybranych modułów do usług
• dalsza separacja integracji
• zastąpienie części legacy modelu jobów architekturą event-driven
• głębsza separacja frontendu (SPA / BFF)

Powiązane

• Główne case study (Comers / comers.app): /case-studies/commerce-platform-modernization
• Architecture showcase (GitHub):
  https://github.com/rocketdeploy-dev/showcase-commerce-platform-modernization

To dokumentuje realną ewolucję Comers, a nie teoretyczny redesign.