Marketplace na Medusa.js: produkcyjne platformy sprzedażowe

Sam prowadzę marketplace, znam to od podszewki

Aktywnie rozwijam i utrzymuję produkcyjny marketplace na Medusa.js. Nie demo. Nie projekt poboczny. Żywa platforma z prawdziwymi sprzedawcami, prawdziwymi kupującymi i prawdziwymi transakcjami.

Oznacza to, że zetknąłem się z problemami, które nie pojawiają się w tutorialach ani dokumentacji:

• Prawdziwi sprzedawcy, którzy nie podążają za zaprojektowanym przepływem onboardingu, i przypadki poza scenariuszem, które to tworzy
• Prawdziwe zamówienia, które ujawniają luki w logice prowizji, którą uważałeś za kompletną
• Prawdziwe błędy użytkowników, które psują przepływy, które wydawały się oczywiste
• Prawdziwe decyzje biznesowe podejmowane w trakcie developmentu, i jak wymusiły zmiany architektoniczne
• Utrzymanie i rozwijanie żywego systemu przez wiele miesięcy, nie tylko wdrożenie i odejście

Zaprojektowałem architekturę. Podjąłem decyzje produktowe. Napisałem kod. Zajmuję się utrzymaniem. Wiem co się psuje i dlaczego, bo już to sam zepsułem.

Zatrudniając mnie do budowy Twojego marketplace, nie płacisz za kogoś, kto uczy się na Twoim projekcie. Dostajesz kogoś, kto już zapłacił to czesne.

Efekty tego podejścia opisuje także studium przypadku opublikowane przez Mercur.

Najtrudniejsza część to nie technologia

Platformy marketplace nie upadają przez zły kod. Upadają przez nierozwiązane decyzje biznesowe, które trafiają do architektury w złym momencie. Technologia jest do rozwiązania. Projekt procesów to miejsce, gdzie większość projektów się zatrzymuje.

Decyzje, które trzeba podjąć zanim rozpocznie się budowę

To nie są pytania techniczne. To pytania biznesowe i prawne, które bezpośrednio determinują sposób budowy systemu. Błędne odpowiedzi na wczesnym etapie oznaczają przebudowę później.

• Kto jest prawnym sprzedawcą, platforma czy vendor? To determinuje VAT, fakturowanie i odpowiedzialność.
• Kto wystawia fakturę kupującemu? Kto wystawia fakturę platformie?
• Kto obsługuje zwroty i reklamacje, i jak wygląda ten proces technicznie?
• Jak naliczana jest prowizja, stała kwota, procent, progi, per kategoria, czy dynamicznie?
• Kiedy następują wypłaty dla sprzedawców, natychmiast, tygodniowo, po okresie blokady, po potwierdzeniu przez kupującego?
• Jak wygląda onboarding sprzedawców, samorejestracja, ręczna akceptacja, weryfikacja tożsamości, upload dokumentów?
• Czy sprzedawcy są weryfikowani przed publikacją ofert? Co obejmuje weryfikacja?
• Jak publikowane są oferty, natychmiast, po moderacji, po akceptacji admina?
• Jakie role użytkowników istnieją, kupujący, sprzedawca, admin, moderator, support? Co może każda rola?
• Co się dzieje, gdy pojawia się spór między kupującym a sprzedawcą? Kto arbitruje?

Przechodzę przez te pytania razem z Tobą zanim zaproponuję jakąkolwiek architekturę. Odpowiedzi kształtują system. Przewodnik po decyzjach operacyjnych w marketplace oraz przegląd regulacji prawnych znajdziecie na stronie “Praktyczny przewodnik operacyjny dla marketplace”.

Najczęstsze błędy przy budowie marketplace

To nie są hipotezy. To wzorce, które widziałem wielokrotnie, i niektóre, które sam popełniłem.

• Budowanie wszystkiego przed walidacją rynku. Pełna platforma, której nikt nie używa, to droga lekcja. Zacznij od minimum, które pozwoli sprawdzić, czy kupujący i sprzedawcy w ogóle się pojawią.
• Źle zaprojektowany model prowizji. Zmiana logiki prowizji po uruchomieniu jest bolesna, dotyka płatności, fakturowania, umów ze sprzedawcami i raportowania. Zrób to dobrze zanim to zbudujesz.
• Brak strategii wypłat. Kiedy sprzedawcy dostają pieniądze? Co się dzieje, gdy kupujący żąda zwrotu po wypłacie? Te pytania muszą mieć odpowiedzi zanim zostanie zbudowana integracja płatności.
• Niedoszacowanie moderacji. Każdy marketplace w końcu ma złych aktorów, fałszywe oferty, oszukańczych sprzedawców, naruszenia regulaminu. Narzędzia moderacyjne to nie dodatek. To infrastruktura.
• Ignorowanie aspektów prawnych do momentu, gdy jest za późno. Kto jest prawnym sprzedawcą? Kto obsługuje VAT? Te decyzje wpływają na architekturę płatności. Odkrycie ich po uruchomieniu oznacza przebudowę kluczowych przepływów.
• Wybór technologii trudnej w rozwoju. Marketplace ewoluuje nieustannie. Jeśli baza kodu nie może być zmieniana bez psucia wszystkiego, wzrost staje się przepisaniem od zera.

Co projektuję i buduję

Nie lista funkcji. To obszary odpowiedzialności, każdy wymagający własnych decyzji projektowych.

Płatności i rozliczenia

Najbardziej złożona część każdego marketplace. Pieniądze wpływają od kupującego, a następnie dzielą się między platformę i wielu sprzedawców, z refundami, blokadami i potrąceniami prowizji po drodze.

• Split payment - środki kierowane do sprzedawców automatycznie, minus prowizja platformy
• Logika prowizji - stała, procentowa, progowa, per kategoria lub niestandardowe reguły
• Harmonogramy wypłat - natychmiastowe, tygodniowe, na żądanie lub po okresach blokady
• Refundy - kto inicjuje, kto ponosi koszt, jak przepływa z powrotem przez system

Sprzedawcy i onboarding

To, jak sprzedawcy dołączają, są weryfikowani i działają na platformie, determinuje jakość strony podażowej. Źle zaprojektowany onboarding to jedno z najczęstszych źródeł problemów operacyjnych.

• Przepływy onboardingu - rejestracja, upload dokumentów, weryfikacja tożsamości, akceptacja
• Zarządzanie statusami - oczekujący, aktywny, zawieszony, odrzucony
• Uprawnienia i role - co konto sprzedawcy może, a czego nie może robić
• Panel sprzedawcy - zarządzanie produktami, obsługa zamówień, zarobki, analityka

Zamówienia, prowizje i moderacja

Operacyjny rdzeń platformy, jak przepływają zamówienia, jak naliczane są prowizje i jak platforma utrzymuje kontrolę jakości.

• Split orders - jedno zamówienie kupującego dzielone na pod-zamówienia per sprzedawca
• Naliczanie prowizji - obliczana i rejestrowana na poziomie zamówienia
• Moderacja treści - przegląd ofert, kolejki akceptacji, flagowanie
• Obsługa sporów - narzędzia do zarządzania reklamacjami między kupującymi a sprzedawcami

Architektura techniczna - dla founderów i osób technicznych

Founderzy kupują skalowalność, niezawodność i utrzymywalność. Oto jak architektura to dostarcza, i jakie technologie to umożliwiają.

Wydajność

Storefront marketplace może mieć tysiące stron listingowych. Bez przemyślanej strategii cache każde wczytanie strony uderza w bazę danych. Redis obsługuje zarządzanie sesjami i strony o dużym ruchu. Static generation z rewalidacją utrzymuje strony szybkie bez utraty aktualności.

SEO

SEO marketplace to nie to samo co SEO sklepu. Strony kategorii, profile sprzedawców i strony listingów wymagają własnej strategii indeksowania, obsługi canonicali i danych strukturalnych. Next.js z SSR zapewnia, że każda strona jest indeksowalna. To nie jest afterthought, jest wbudowane w architekturę od początku.

Skalowanie

Operacje finansowe - wypłaty, obliczenia prowizji, wysyłka powiadomień - działają asynchronicznie przez kolejki zadań. Synchroniczne przetwarzanie pieniędzy to ryzyko niezawodności. PostgreSQL obsługuje relacyjną złożoność relacji sprzedawca-zamówienie-prowizja z transakcjami i constraintami, które mają znaczenie gdy w grę wchodzą prawdziwe pieniądze.

Architektura

Headless i API-first. Storefront, panel sprzedawcy i panel admina to osobne aplikacje korzystające z tego samego API Medusa.js. Każda część może być wymieniona lub rozszerzona niezależnie. Niestandardowa logika prowizji, konta sprzedawców i reguły wypłat są zbudowane jako natywne moduły, nie wtyczki doklejone na wierzch systemu, który nie był na nie zaprojektowany.

Stack: Medusa.js, Next.js, PostgreSQL, Redis, TypeScript.

Aspekty prawne i biznesowe

Nie udzielam porad prawnych. Ale zbudowałem marketplace i wiem, że architektura jest często determinowana przez decyzje prawne i biznesowe podjęte przed pierwszą linią kodu. To obszary, które trzeba rozwiązać, z prawnikiem i księgowym, zanim projekt systemu zostanie sfinalizowany.

• Regulamin - kto za co odpowiada i jak rozwiązywane są spory
• Wymogi UE względem e-commerce, GDPR, OMNIBUS, DAC7
• Polityka prowizji - jak jest naliczana, kiedy pobierana i jak ujawniana sprzedawcom
• Odpowiedzialność platformy - za co platforma odpowiada, a za co nie, w transakcjach między kupującymi a sprzedawcami
• Fakturowanie i VAT - kto wystawia dokumenty, w jakiej jurysdykcji i jak system to obsługuje
• Zwroty i reklamacje - proces musi być zdefiniowany zanim zostanie wbudowany w system
• RODO - dane zbierane od kupujących i sprzedawców, przepływy zgód, retencja danych i żądania usunięcia
• Weryfikacja sprzedawców - wymagania KYC, zbieranie dokumentów i co się dzieje gdy sprzedawca nie przejdzie weryfikacji

Architektura systemu często zależy bezpośrednio od tych decyzji. Marketplace, w którym platforma jest prawnym sprzedawcą, wymaga zupełnie innego przepływu płatności niż taki, w którym każdy vendor sprzedaje niezależnie. Projektuję system, który spełnia wszelkie wymagania prawne i oszczędzi Ci problemów prawnych.

Pracujesz bezpośrednio z osobą, która to buduje

AppCrates to nie agencja. Nie ma project managera między Tobą a developerem. Rozmawiasz bezpośrednio z osobą, która projektuje architekturę, pisze kod i podejmuje decyzje techniczne. Szybszy feedback, konkretniejsze odpowiedzi, żadnych informacji gubionych w tłumaczeniu.