Laravel jako backend dla portalu klienta B2B

Laravel dobrze sprawdza się jako backend portalu klienta B2B, bo porządkuje dokładnie te elementy, na których taki portal się opiera: konta firmowe z wieloma użytkownikami, role i polityki dostępu, izolację danych między klientami, bezpieczne udostępnianie dokumentów, powiadomienia oraz stabilne API dla frontendu. Kluczem nie jest sam framework, lecz decyzje architektoniczne podjęte na początku – zwłaszcza model konta i sposób rozdzielenia danych. Poniżej opisujemy, jak projektujemy te warstwy i jakich błędów unikać.

Listę funkcji, które warto uruchomić w portalu na start i później, omawiamy osobno we wpisie panel klienta B2B – co powinien zawierać. Tutaj skupiamy się na tym, co dzieje się pod spodem.

Model konta: firma, oddział, użytkownik

Najczęstszy błąd w portalach B2B to utożsamienie klienta z użytkownikiem. W B2B klientem jest firma, a z portalu korzysta kilka lub kilkanaście osób z tej firmy. Dlatego backend powinien rozróżniać co najmniej:

• konto firmowe – kontrahent z numerem NIP, warunkami handlowymi i powiązaniem z identyfikatorem w ERP,
• oddział lub lokalizację – adresy dostaw, osobne magazyny, czasem osobne budżety,
• użytkownika – konkretną osobę z loginem, przypisaną do konta i opcjonalnie do wybranych oddziałów,
• rolę w obrębie konta – np. administrator konta, zamawiający, osoba akceptująca, księgowość.

W Laravel oznacza to osobne modele i relacje zamiast jednej tabeli `users` z kolumną „nazwa firmy”. Taki podział na początku kosztuje kilka dni pracy więcej, ale bez niego późniejsze dodanie drugiego użytkownika do klienta albo zamówień per oddział wymaga przebudowy połowy systemu.

Uprawnienia: role, polityki i zakres danych

Uprawnienia w portalu klienta działają na dwóch poziomach. Pierwszy to co użytkownik może zrobić – składać zamówienia, akceptować je, pobierać faktury, zarządzać innymi użytkownikami. Drugi to na jakich danych – tylko swojego konta, tylko swojego oddziału, tylko własnych zamówień.

W Laravel pierwszy poziom obsługują bramki i polityki (`Gate`, `Policy`), często uzupełnione pakietem do ról i uprawnień. Drugi poziom warto zaszyć w zapytaniach, a nie tylko w kontrolerach. Praktyczne zasady:

1. Każde zapytanie o dane klienta przechodzi przez zakres (scope) filtrujący po koncie firmowym.
2. Polityka sprawdza nie tylko rolę, ale też przynależność zasobu do konta i oddziału.
3. Uprawnienia pracowników firmy (handlowiec, obsługa) są oddzielone od uprawnień użytkowników klienta – to inne typy kont, często z osobnym logowaniem.
4. Funkcja „zaloguj się jako klient” dla obsługi jest logowana i widoczna w historii konta.

Multi-tenant: wspólna baza czy osobne bazy

Każdy portal B2B jest w praktyce systemem wielodostępnym, bo przechowuje dane wielu firm. Pytanie brzmi, jak mocno je rozdzielić.

• Wspólna baza z identyfikatorem konta – każda tabela z danymi klienta ma kolumnę konta, a globalny scope w modelach dodaje warunek automatycznie. To najprostszy i najczęściej wystarczający wariant dla portali jednej firmy obsługującej wielu klientów.
• Osobne schematy lub bazy per klient – wybierane, gdy klient wymaga fizycznej separacji danych, różnych kopii zapasowych albo różnych lokalizacji przechowywania. Wymaga pakietu obsługującego przełączanie połączeń i dyscypliny przy migracjach.
• Model mieszany – wspólna baza dla katalogu i konfiguracji, osobne dane transakcyjne dla wybranych dużych klientów.

Dla większości portali klienta zaczynamy od wspólnej bazy z automatycznym filtrem i testami, które sprawdzają, że użytkownik jednego konta nigdy nie zobaczy danych drugiego. Taki test powinien być częścią każdego wdrożenia.

Dokumenty: przechowywanie i udostępnianie

Faktury, specyfikacje, certyfikaty, protokoły – dokumenty to często najczęściej używana część portalu. Backend powinien:

• trzymać pliki w prywatnym magazynie (dysk poza katalogiem publicznym albo magazyn obiektowy zgodny z S3),
• zapisywać w bazie metadane: typ, numer, datę, konto, oddział, źródło (ERP, system dokumentów, ręczny upload),
• udostępniać plik przez podpisany, krótkotrwały adres wygenerowany po sprawdzeniu polityki,
• rozróżniać dokumenty per klient (faktury) od dokumentów per produkt (karty techniczne), które mogą być wspólne dla wielu kont,
• rejestrować pobrania, jeśli klient lub dział prawny tego wymaga.

Dokumenty generowane przez portal, np. potwierdzenia zamówień w PDF, tworzy się w kolejce, żeby nie spowalniać odpowiedzi dla użytkownika.

Powiadomienia i zdarzenia

Portal żyje zdarzeniami: zamówienie przyjęte, zmiana statusu, nowa faktura, odpowiedź na reklamację. W Laravel naturalnym wzorcem jest zdarzenie domenowe plus powiadomienie wysyłane wybranymi kanałami (e-mail, powiadomienie w portalu, webhook do systemu klienta).

Dobre praktyki:

1. Użytkownik sam wybiera, które powiadomienia chce dostawać – administrator konta może ustawić domyślne dla całej firmy.
2. Powiadomienia wysyłane są z kolejki, z ponawianiem przy błędzie serwera pocztowego.
3. Każde powiadomienie ma odpowiednik w historii w portalu, żeby nie zależeć tylko od skrzynki mailowej.
4. Przy masowych zmianach (np. import stu faktur) system grupuje powiadomienia w jedno podsumowanie.

API dla frontendu

Frontend portalu może być renderowany serwerowo, zbudowany na Inertii albo działać jako osobna aplikacja SPA czy mobilna. W dwóch ostatnich przypadkach backend udostępnia API, które powinno:

• mieć stabilny kontrakt – zasoby (API Resources) oddzielają format odpowiedzi od struktury bazy,
• być wersjonowane, jeśli korzystają z niego aplikacje, których nie aktualizujesz jednocześnie z backendem,
• zwracać paginowane listy z filtrowaniem po stronie serwera, bo konta B2B mają tysiące dokumentów i pozycji,
• używać Sanctum do sesji SPA i tokenów dla prostych integracji,
• mieć ograniczenia liczby żądań (rate limiting) dla endpointów logowania i wyszukiwania.

Wymiana danych z ERP i CRM to osobna warstwa – kolejki, ponawianie, idempotencja i monitoring opisujemy szczegółowo w artykule integracje API Laravel z ERP i B2B. Ważne, żeby API dla frontu nigdy nie odpytywało ERP synchronicznie przy każdym wyświetleniu strony.

Historia działań i ślad audytowy

W relacji B2B spory dotyczą zwykle drobiazgów: kto zmienił adres dostawy, kto usunął pozycję z zamówienia, czy faktura była dostępna w dniu, w którym klient twierdzi, że jej nie widział. Backend powinien rejestrować takie zdarzenia w sposób, który da się pokazać obsłudze klienta bez sięgania do logów serwera:

• zmiany danych konta, adresów i użytkowników z informacją, kto ich dokonał,
• złożenie, edycję i anulowanie zamówień,
• nadanie i odebranie uprawnień,
• działania pracowników wykonane w imieniu klienta.

Historię warto zapisywać w osobnej tabeli zdarzeń, a nie przez nadpisywanie rekordów. Dzięki temu da się odtworzyć stan konta z dowolnego dnia.

Przykładowy przepływ: nowa faktura w portalu

Jak te warstwy współpracują, dobrze widać na prostym scenariuszu:

1. Warstwa integracyjna pobiera z ERP nową fakturę wraz z plikiem PDF i numerem kontrahenta.
2. Backend odnajduje konto firmowe po identyfikatorze z ERP, zapisuje metadane dokumentu i umieszcza plik w prywatnym magazynie.
3. Powstaje zdarzenie „nowa faktura”, które uruchamia powiadomienie dla użytkowników konta z rolą księgowości.
4. Użytkownik klika link w e-mailu, loguje się, a polityka sprawdza, czy dokument należy do jego konta.
5. Backend generuje podpisany adres ważny przez kilka minut i rejestruje pobranie.

Żaden krok nie wymaga ręcznej pracy zespołu, a każdy da się pokryć testem.

Typowe błędy w backendzie portalu

• jedna rola „klient” dla wszystkich użytkowników firmy,
• filtrowanie po koncie tylko w kontrolerach, bez zabezpieczenia w modelach,
• pliki faktur w katalogu publicznym z przewidywalnymi nazwami,
• powiadomienia wysyłane synchronicznie w trakcie żądania,
• brak historii działań użytkowników, przez co spory z klientem trudno wyjaśnić.

Następny krok

Zanim zaczniesz projektować ekrany, rozpisz strukturę swoich klientów: ile osób z jednej firmy korzysta z portalu, jakie mają role, czy działają w kilku oddziałach i jakie dokumenty muszą widzieć. To wystarczy, żeby zaprojektować model konta i uprawnień. Jeśli chcesz, przejdziemy przez to razem w ramach projektu platformy B2B i CRM – skontaktuj się z nami, a zaproponujemy architekturę backendu dopasowaną do Twojego portalu.