BAZARTY.COM (PAYLOAD + MONGODB)

Rozbudowa cudzej dojrzałej bazy to inna dyscyplina niż pisanie od zera: każda moja zmiana mogła po cichu złamać konwencję, o której istnieniu nie wiedziałem. Zanim dopisałem pierwszą linijkę, zrobiłem reverse-engineering bazy do .planning/codebase/* — ARCHITECTURE, CONVENTIONS, INTEGRATIONS — a wzorce (kolekcja Payload, router tRPC) zamknąłem we własnych skillach Claude, które generują nowy kod od razu w stylu zastanego. Konwencje przestały być wiedzą plemienną — stały się egzekwowalne.

Dla rękodzieła stock to często dokładnie 1 sztuka — a dwóch kupujących klikających „kup” w tej samej chwili nie może obaj jej dostać. Payload local API robi read-modify-write (find → sprawdź stan → update), czyli klasyczny wyścig TOCTOU: obie sesje czytają stock: 1, obie przechodzą walidację, obie dekrementują. Zamiast walczyć z frameworkiem, w tym jednym miejscu świadomie zszedłem poniżej ORM do surowego sterownika Mongo: warunkowy atomowy dekrement, w którym warunek $gte i $inc wykonują się w jednej niepodzielnej operacji — modifiedCount === 1 znaczy „zarezerwowane”, zero nadsprzedaży. Rezerwacja wpina się przed utworzeniem sesji Stripe, a rollback zwraca stan przy wygaśnięciu sesji. To jedyne miejsce w całej aplikacji omijające Payload — i jest opisane w kodzie, dlaczego.

Escrow zbudowałem dwa razy tego samego dnia. Pierwsza wersja używała stripe'owego delay_days — wstrzymania wypłaty liczonego od płatności. Działała, ale chroniła źle: okno liczy się od zapłaty, nie od realnego odbioru, więc przy wolnej dostawie środki mogły wyjść do sprzedawcy, zanim kupujący w ogóle zobaczył paczkę. Wyrzuciłem ją po kilku godzinach i przebudowałem model: konta sprzedawców przechodzą na payouts=manual, a wypłatę zwalnia mój własny sweeper — dokładnie 2 dni po potwierdzeniu odbioru przez kupującego, z guardem idempotencji po stripePayoutId i kwotą liczoną jako lustro matematyki checkoutu, żeby nie przekroczyć salda o grosz. Gotowość wyrzucenia działającego kodu, gdy model ryzyka jest błędny — i zapisanie w historii dlaczego — uważam za najcenniejszą lekcję tego projektu.

Integracja z Furgonetką (agregator kurierów) nauczyła mnie pokory wobec niedodokumentowanych API: tworzenie przesyłki łamało się na formacie adresu (ulica jednym polem vs rozbite street + building_number) i wersji API, a objawem dla użytkownika było „0 opcji dostawy” w checkoucie. Dwie kolejne poprawki tego samego dnia pogorszyły sprawę — obie złamały tworzenie paczki — więc trzeci commit był revertem do znanej-działającej wersji z maina, z jawnym uzasadnieniem w komunikacie. Dopiero potem przyszła właściwa naprawa: migracja na endpoint calculate-price, twarde limity wymiarów paczki i — najważniejsze — zamiana cichego zera na komunikat mówiący, czego konkretnie brakuje (np. dwuczłonowa nazwa odbiorcy, minimalne wymiary). Dyscyplina „revert do known-good zamiast nawarstwiania fixów” została mi z tego na stałe.