Struktura kodu i standardy backendu WiseB2B

Przeznaczenie dokumentu

Dokument ten opisuje strukturę katalogów, standardy kodowania oraz architekturę backendu WiseB2B. Jego celem jest ułatwienie wdrożeniowcom i deweloperom szybkiego odnalezienia się w projekcie oraz efektywnego rozwijania nowych funkcjonalności.

WiseB2B - UI API - założenia i wytyczne

Przeznaczenie UI API

UI API to warstwa komunikacji pomiędzy backendem a aplikacjami frontendowymi (np. sklepy internetowe, panele B2B, aplikacje mobilne). Umożliwia budowę nowoczesnych, wydajnych i skalowalnych aplikacji headless, zapewniając elastyczność, bezpieczeństwo i szybkie wdrożenia.

Typowe zastosowania

• Sklepy internetowe, panele klienta, aplikacje mobilne, portale B2B/B2C
• Integracja z zewnętrznymi systemami (ERP, CRM, płatności, logistyka)
• Dynamiczne interfejsy użytkownika (SPA)

Przykładowa aplikacja Reactowa

Przykładowa aplikacja Reactowa dołączona do WiseB2B to frontend typu headless, który komunikuje się z backendem wyłącznie przez UI API. Cała logika prezentacji, obsługa widoków i interakcje użytkownika realizowane są po stronie przeglądarki, a dane pobierane są dynamicznie z API. Dzięki temu wdrożeniowiec może szybko wdrożyć nowy projekt, dostosować wygląd i funkcjonalność oraz korzystać z nowoczesnych technologii frontendowych.

Uwaga: Aplikacja nie korzysta z szablonów serwerowych ani renderowania po stronie backendu, co zapewnia pełną niezależność warstwy frontendowej.

Główne założenia UI API

Główne założenia UI API określają sposób projektowania endpointów, model autoryzacji, standardy przekazywania danych i obsługi błędów. Dzięki nim UI API jest elastyczne, łatwe do integracji z różnymi technologiami frontendowymi, a jednocześnie zapewnia spójność, bezpieczeństwo i wysoką wydajność.

Kluczowe zasady

• Endpointy UI API są dedykowane poszczególnym widokom i komponentom interfejsu, a nie pojęciom biznesowym backendu.
• Wszystkie metody są dostępne z prefiksem /ui-api/.
• W headerze każdego zapytania przekazywany jest klucz autoryzacyjny oraz język (language).

Standardy zapytań i odpowiedzi

Sekcja opisuje standardowe parametry zapytań, strukturę odpowiedzi oraz obsługiwane kody HTTP.

GET – pobieranie zbiorów danych

Parametry requestu:

• page, limit, search_keyword

Przykład requestu:

GET /ui-api/products?page=1&limit=20&search_keyword=laptop HTTP/1.1
Authorization: Bearer {token}
Language: PL

Przykład response:

{
  "page": 1,
  "total_pages": 5,
  "total_count": 100,
  "items": [
    { "id": 1, "name": "Laptop X" },
    { "id": 2, "name": "Laptop Y" }
  ]
}

Tabela pól odpowiedzi:

Pole	Typ	Opis
page	int	Aktualna strona
total_pages	int	Liczba wszystkich stron
total_count	int	Liczba wszystkich elementów
items	array	Tablica zwracanych obiektów

GET – pobieranie szczegółów obiektu

• Identyfikator obiektu przekazywany w route, np. /ui-api/products/1

POST/PUT/DELETE – modyfikacja danych

Przykład response:

{
  "status": 1,
  "message": "Produkt został zapisany.",
  "message_style": "NOTICE",
  "show_message": true,
  "data": { "id": 123 },
  "error_fields": []
}

Tabela pól odpowiedzi:

Pole	Typ	Opis
status	int	0 – błąd, 1 – OK, 2 – potwierdzenie, 3+ – kody specyficzne
message	string	Komunikat dla użytkownika
message_style	string	Styl komunikatu (ERROR, WARNING, NOTICE)
show_message	bool	Czy pokazać komunikat użytkownikowi
data	mixed	Dodatkowe dane (np. ID utworzonych obiektów)
error_fields	array	Lista błędów walidacji formularza

Kody odpowiedzi HTTP

Kod	Znaczenie
200	OK – zapytanie przetworzone poprawnie
400	Błąd składni zapytania (np. niepoprawny JSON)
401	Brak autoryzacji
404	Obiekt nie znaleziony
422	Błąd logiki biznesowej (np. walidacja)
500	Błąd serwera lub infrastruktury

Uwaga: Szczegółowe obsługi wyjątków i statusów opisane są w kodzie abstrakcji i listenerów.

Komendy (endpointy akcji użytkownika)

Komendy to endpointy realizujące akcje użytkownika w procesie (np. kolejny krok checkoutu, potwierdzenie zamówienia). Są realizowane za pomocą POST i zwracają response zgodny ze standardem odpowiedzi.

Standardy nazywania atrybutów

W tej sekcji znajdziesz zasady nazewnictwa atrybutów związanych z datami oraz danymi użytkownika.

Nazwa atrybutu	Opis
creation_date	Data utworzenia (bez godziny)
creation_datetime	Data i godzina utworzenia
payment_date	Data płatności
user_name	Imię i nazwisko użytkownika
first_name	Imię użytkownika
last_name	Nazwisko użytkownika

Struktura katalogów kodu backend WiseB2B

Przeznaczenie sekcji

Ta sekcja opisuje strukturę katalogów i modułów backendu WiseB2B, aby ułatwić orientację w projekcie.

Struktura projektu standardowego backendu WiseB2B

wiseb2b_backend/
├── Wise/                # Główny katalog z modułami biznesowymi
├── config/              # Konfiguracja aplikacji (konfiguracja symfony bo każdy moduł ma swoją konfiguracje)
├── public/              # Pliki publiczne - tutaj będą zdjęcia, dokumenty, i wszystkie pliki dostępne poprzez URL
├── migrations/          # Migracje czyli możliwosć aktualizacji bazy danych
├── tests/               # Testy automatyczne (należy testy pisać w module)
└── vendor/              # Zależności composer

Moduły backendowe WiseB2B (Wise/)

Wise/
├── Agreement/           # Zarządzanie umowami i kontraktami (zgody)
├── Cart/                # Obsługa koszyka zakupowego
├── Checkout/            # Proces finalizacji zamówienia (proces zakupowy)
├── Client/              # Zarządzanie klientami
├── ClientApi/           # API dla klientów
├── Cms/                 # System zarządzania treścią
├── Core/                # Podstawowe komponenty i funkcjonalności
├── Delivery/            # System zarządzania dostawami
├── Document/            # Zarządzanie dokumentami
├── DynamicUI/           # Dynamiczne interfejsy użytkownika
├── ExportCatalog/       # Eksport katalogów produktowych
├── File/                # System zarządzania plikami
├── Generator/           # Generator komponentów i kodu (deprecated)
├── GPSR/                # Moduł GPSR (Global Product Safety and Regulatory)
├── I18n/                # Internacjonalizacja i lokalizacja
├── Message/             # System komunikacji i powiadomień (m.in wysyłanie wiadomości e-mail)
├── MultiStore/          # Obsługa wielu sklepów
├── Offer/               # Zarządzanie ofertami
├── Order/               # Obsługa zamówień
├── OrderEdit/           # Edycja i modyfikacja zamówień
├── Payment/             # System płatności
├── Pricing/             # Zarządzanie cenami i rabatami
├── Product/             # Katalog i zarządzanie produktami (i elementami z nimi związanymi m.in kategorie, atrybuty itd)
├── Receiver/            # Obsługa odbiorców
├── SearchProduct/       # Wyszukiwarka produktów, Listing produktów
├── Security/            # Bezpieczeństwo i autoryzacja
├── Service/             # Usługi
├── ShoppingList/        # Listy zakupowe
├── Stock/               # Zarządzanie stanami magazynowymi
└── User/                # Zarządzanie użytkownikami

Struktura modułu

ModułPrzykładowy/
├── ApiAdmin/                        # Endpointy API ADMIN
│   ├── Controller/                  # Kontrolery
│   ├── Dto/                         # DTO do API
│   └── Service/                     # Serwisy prezentacji
├── ApiUi/                           # Endpointy API UI
│   ├── Controller/                  # Kontrolery
│   ├── Dto/                         # DTO do API
│   ├── DynamicPages/                # Providery DynamicUI
│   └── Service/                     # Serwisy prezentacji
│       └── Interfaces/              # Interfejsy serwisów
├── Command/                         # Komendy
├── Docs/                            # Dokumentacja
│   ├── Client/                      # Dokumentacja dla klientów
│   └── Developer/                   # Dokumentacja dla deweloperów
├── Domain/                          # Warstwa domeny
│   ├── EncjaPrzykładowa/            # Katalog encji
│   │   ├── Event/                   # Eventy encji
│   │   ├── Exception/               # Wyjątki encji
│   │   ├── Interfaces/              # Interfejsy domenowe
│   │   ├── Listener/                # Listenery encji
│   │   └── Service/                 # Serwisy domenowe
│   │       └── Interfaces/          # Interfejsy serwisów domenowych
├── Repository/                      # Repozytoria encji/modeli
│   ├── Doctrine/                    # Repozytoria Doctrine
│   ├── Config/                      # Repozytoria config.yaml
│   └── Json/                        # Repozytoria Json
├── Resources/                       # Zasoby modułu
│   ├── config/                      # Pliki konfiguracyjne
│   │   ├── config.yaml              # Konfiguracja modułu
│   │   ├── doctrine.yaml            # Schematy encji
│   │   ├── routes.yaml              # Routing
│   │   └── services.yaml            # Usługi, DI, providery
│   ├── entity/                      # Konfiguracja ORM
│   ├── json/                        # Pliki JSON
│   ├── template/                    # Szablony (np. twig)
│   └── translations/                # Translacje
├── Service/                         # Serwisy aplikacji
│   └── Interfaces/                  # Interfejsy serwisów aplikacji
└── Tests/                           # Testy
    ├── AdminApi/                    # Testy endpointów AdminApi
    ├── UiApi/                       # Testy endpointów UiApi
    └── Unit/                        # Testy jednostkowe

---

Podsumowanie

Dokumentacja przedstawia kluczowe założenia, strukturę oraz standardy projektowe backendu WiseB2B, ze szczególnym uwzględnieniem roli UI API. UI API stanowi nowoczesny, elastyczny i bezpieczny most pomiędzy backendem a dowolnymi aplikacjami frontendowymi, umożliwiając szybkie wdrożenia, łatwą personalizację oraz integrację z zewnętrznymi systemami. Przemyślana architektura katalogów i modułów, jasne standardy komunikacji oraz gotowe wzorce wdrożeniowe pozwalają wdrożeniowcom i klientom WiseB2B na efektywne rozwijanie własnych rozwiązań cyfrowych, niezależnie od skali projektu. Stosowanie opisanych tu zasad i struktur gwarantuje wysoką jakość, bezpieczeństwo oraz przewidywalność rozwoju systemu w długim okresie.

---