O projekcie
Agent, który liczy wynik czterech sklepów firmy w jednym rachunku: sprzedaż, zwroty, prowizje platform i bramek, wysyłkę, pakowanie, wydatki na kampanie i koszty wspólne, których nie da się przypisać do jednego sklepu. Odpowiada na pytanie, które przy czterech kanałach naraz przestaje mieć oczywistą odpowiedź — ile z tego naprawdę zostaje.
Pierwsza rzecz, którą trzeba rozstrzygnąć, zanim cokolwiek się policzy: ZYSK NIE MA JEDNEGO MOMENTU. Sprzedaż jest dzisiaj, zwrot za trzydzieści dni, prowizja platformy rozlicza się na koniec miesiąca, a faktura za reklamę przychodzi jeszcze później. Marża „na dziś” i marża „po zamknięciu okresu” to dwie różne prawdy i obie są potrzebne — jedna do decyzji w tygodniu, druga do wiedzy, jak było naprawdę. Ten system liczy obie i nigdy ich nie miesza, bo mieszanie jest najczęstszym powodem, dla którego panele rentowności kłamią w dobrej wierze.
Druga trudność jest cicha i kosztuje najwięcej: CZTERY SKLEPY TO CZTERY RÓŻNE ZNACZENIA TEGO SAMEGO POLA. „Wartość zamówienia” bywa z podatkiem i bez, koszt wysyłki raz siedzi w przychodzie, a raz w koszcie, rabat raz jest osobną pozycją, a raz obniżoną ceną jednostkową. Zsumowanie takich czterech liczb daje wynik, który wygląda jak rachunek, a nie znaczy nic. Dlatego między źródłami a rachunkiem stoi słownik pojęć: każde pole ma jedną definicję, a każde źródło ma zapisane, jak się do niej sprowadza.
Trzecia sprawa to koszty, których nie da się przypisać do jednego sklepu: reklama na markę, magazyn, pakowanie, obsługa klienta, abonamenty narzędzi. Klucz podziału jest DECYZJĄ, a nie faktem — można dzielić po obrocie, po liczbie paczek albo po czasie obsługi i za każdym razem wyjdzie inna rentowność tego samego sklepu. System nie ukrywa tego za średnią: klucz jest jawny, zmienny, a każdy wynik niesie informację, jakim kluczem został policzony. Zmiana klucza przelicza historię, żeby dało się porównać jabłka z jabłkami.
Zwroty liczą się pełnym kosztem, nie utraconą marżą. Przy zwrocie wraca towar, ale zostaje transport w obie strony, czas na przyjęcie i sprawdzenie, przepakowanie, a czasem obniżona wartość produktu. Rachunek, który odejmuje tylko cenę sprzedaży, kłamie systematycznie w jedną stronę — i to tym bardziej, im więcej sklep sprzedaje w kategoriach o wysokiej zwrotności.
Kampanie są w tym rachunku po stronie kosztów i tylko po stronie kosztów. Wydatek jest faktem i jest liczony co do grosza; przypisanie sprzedaży do kampanii faktem nie jest. W kanale, w którym działa kilka źródeł ruchu naraz, atrybucja to model, a nie pomiar, więc raport mówi, ile wydano, co wpadło w oknie kampanii i ile z tego przyszło z oznaczonych odnośników — zamiast podawać jedną liczbę „zwrotu z kampanii”, której nikt nie potrafi obronić.
Rola modelu jest tu wąska i celowo taka została. Agent czyta dokumenty kosztowe, których nikt nie dostaje w ustandaryzowanej postaci — faktury za reklamę, spedycję, pakowanie, abonamenty — i zamienia je w pozycje przypisane do kategorii i sklepu. Wszystkie obliczenia robi kod, który da się przetestować. Do tego agent pilnuje anomalii: koszt pakowania rosnący przy tej samej liczbie paczek, prowizja odbiegająca od stawki umownej, sklep, który zjechał poniżej progu marży. Anomalia jest OSTRZEŻENIEM z pokazanym wyliczeniem, nie werdyktem.
Całość jest zbudowana tak, żeby każdą liczbę dało się rozłożyć z powrotem na części. Klikając w marżę miesiąca, dochodzi się do sklepu, do kategorii kosztu, do pojedynczego dokumentu i do momentu, w którym został wczytany. Rachunek, którego nie da się rozebrać, jest tylko opinią zapisaną cyframi — a na takich liczbach nikt nie powinien decydować o budżecie.
Problem
Przy czterech sklepach pytanie „ile na tym zarabiamy” przestaje mieć oczywistą odpowiedź. Każda platforma inaczej nazywa te same pola, prowizje i zwroty przychodzą z opóźnieniem, a koszty wspólne — reklama, magazyn, pakowanie — nie należą do żadnego sklepu z osobna. Arkusz sklejany raz w miesiącu odpowiada za późno i nie da się go rozebrać na części.
Rozwiązanie
Jedna definicja pola dla wszystkich czterech źródeł, dwa osobne wyniki — marża dzienna i marża po zamknięciu okresu — oraz koszty wspólne dzielone jawnym, zmiennym kluczem, który jest widoczny przy każdej liczbie. Agent czyta dokumenty kosztowe i zgłasza anomalie; liczy kod, a każdą wartość da się rozłożyć z powrotem na dokument źródłowy.
Funkcje
- marża dzienna i marża po zamknięciu okresu liczone osobno i nigdy nie mieszane
- jedna definicja pola dla czterech sklepów, z zapisem, jak każde źródło się do niej sprowadza
- koszty wspólne dzielone jawnym kluczem, widocznym przy każdym wyniku
- zmiana klucza podziału przelicza historię, żeby okresy dało się porównać
- zwrot liczony pełnym kosztem: transport w obie strony, przyjęcie, przepakowanie
- kampanie wyłącznie po stronie kosztów — wydatek jest faktem, atrybucja nie
- anomalie jako ostrzeżenia z pokazanym wyliczeniem, nie jako werdykt
- każda liczba rozkładalna do sklepu, kategorii kosztu i pojedynczego dokumentu
Moduły
agent-zbiorka
warstwa wejściaŚciąga zamówienia, zwroty, rozliczenia prowizji i dokumenty kosztowe z czterech sklepów.
- pobieranie z API platform i bramek płatności, z zapisem surowej odpowiedzi obok znormalizowanej
- dokumenty kosztowe czytane do pozycji — jedyne miejsce w systemie, w którym pracuje model
- rozliczenia prowizji wiązane z zamówieniami po identyfikatorze, nie po dacie i kwocie
- to samo zamówienie pobrane dwa razy nie tworzy drugiego wiersza w rachunku
- źródło niedostępne odnotowane jako luka w okresie, a nie pominięte po cichu
agent-slownik
warstwa ujednoliceniaSprowadza cztery różne znaczenia tego samego pola do jednej definicji.
- jedna definicja na pojęcie: wartość zamówienia, wysyłka, rabat, podatek, prowizja
- reguła sprowadzenia zapisana per źródło — widać, skąd bierze się każda wartość
- kwoty trzymane w groszach i w walucie źródła; przeliczenie po kursie z dnia zdarzenia
- nowe pole w API platformy zgłaszane jako brak definicji, a nie wpuszczane na wyczucie
- zmiana definicji wersjonowana, żeby stare okresy nie zmieniały się po cichu
agent-koszty
warstwa kosztówPrzypisuje koszty do sklepów i produktów, a koszty wspólne dzieli jawnym kluczem.
- koszty bezpośrednie wiązane z zamówieniem: wysyłka, pakowanie, prowizja, zwrot
- koszty wspólne — reklama na markę, magazyn, obsługa, abonamenty — dzielone kluczem
- klucz do wyboru: obrót, liczba paczek albo czas obsługi; wynik zawsze niesie wybrany klucz
- zmiana klucza przelicza historię, zamiast tworzyć dwie nieporównywalne epoki
- zwrot jako komplet kosztów, nie jako odjęta cena sprzedaży
agent-rachunek
warstwa wynikuSkłada wynik w dwóch horyzontach i pilnuje tego, co odbiega od normy.
- marża dzienna do decyzji w tygodniu i marża po zamknięciu okresu do wiedzy, jak było
- przekroje po sklepie, kategorii, marce i produkcie z tego samego zestawu danych
- kampania rozliczana jako koszt; obok niej okno sprzedaży i udział oznaczonych odnośników
- anomalie: koszt rosnący przy stałym wolumenie, prowizja poza stawką, sklep pod progiem marży
- każda liczba rozkładalna do dokumentu i momentu wczytania — rachunek da się rozebrać
Architektura
- Podstawa
- aplikacja TypeScript/Next.js z bazą PostgreSQL, wdrożona w infrastrukturze klienta
- Dwa horyzonty
- marża dzienna i marża po zamknięciu okresu są osobnymi wynikami; system nigdy ich nie sumuje
- Słownik pojęć
- jedna definicja pola dla czterech źródeł, z regułą sprowadzenia zapisaną per platforma
- Kwoty
- trzymane w groszach, w walucie źródła; przeliczenie po kursie z dnia zdarzenia, nie z dnia raportu
- Klucz podziału
- jawny i zmienny — obrót, paczki albo czas obsługi; każdy wynik niesie klucz, którym powstał
- Zwroty
- pełny koszt: transport w obie strony, przyjęcie, przepakowanie, obniżona wartość towaru
- Kampanie
- wyłącznie po stronie kosztów; raport podaje okno i udział oznaczonych odnośników zamiast zwrotu z kampanii
- Rola modelu
- odczyt dokumentów kosztowych do pozycji; wszystkie obliczenia w kodzie, który da się przetestować
- Anomalie
- ostrzeżenie z pokazanym wyliczeniem i progiem, nigdy samodzielna korekta liczb
- Rozkładalność
- od marży miesiąca do pojedynczego dokumentu i momentu wczytania — bez tego rachunek jest opinią
Technologie
- TypeScript
- Next.js
- PostgreSQL
- Claude
- REST API
Autor
Mariusz PerzyńskiClient Relations & Operations