Jak zacząć?

System automatycznie analizuje ceny i opłacalność produktów na Allegro na podstawie kodów EAN. Aby rozpocząć:

1. Dodaj kategorię - przejdź do zakładki Dane rynkowe, kliknij "Dodaj kategorię". Ustaw nazwę (np. "Perfumy"), mnożnik opłacalności (np. 1.25 = min 25% marży) i prowizję Allegro (np. 10%).
2. Wgraj listę proxy - przejdź do zakładki Warstwa sieciowa, wgraj plik z listą proxy (format: 1 URL na linię, np. http://user:pass@host:port).
3. Przygotuj plik Excel - utwórz arkusz z kolumnami: EAN (kod kreskowy), cena zakupu, opcjonalnie nazwa i waluta.
4. Uruchom analizę - przejdź do Nowa analiza, wybierz plik i kategorię, kliknij Start.
5. Śledź postęp - na dashboardzie widać aktywne analizy. Po zakończeniu pobierz wyniki jako Excel.

Format pliku wejściowego

Obsługiwane formaty: .xlsx, .xls, .csv. Maksymalny rozmiar: 50 MB.

Wskazówki:

• System automatycznie rozpoznaje nagłówki w różnych językach
• Duplikaty EAN w jednym pliku są automatycznie usuwane
• Ceny w walutach obcych są przeliczane po kursach z ustawień
• Wiersze bez EAN lub z ceną ≤ 0 są pomijane

Jak czytać wyniki analizy?

Algorytm opłacalności sprawdza 5 kryteriów (w kolejności):

1. Cena zakupu > 0 i istnieje cena Allegro
2. Mnożnik marży ≥ mnożnik kategorii (np. 1.25)
3. Zysk absolutny ≥ minimum (domyślnie 5 PLN)
4. Liczba sprzedanych ≥ minimum (domyślnie 10 szt.)
5. Liczba ofert ≤ maksimum konkurencji (domyślnie 50)

Metryki i koszty analizy

Po zakończeniu analizy dostępne są szczegółowe metryki:

Eksport metryk: CSV (przycisk "CSV") lub Excel (przycisk "XLSX") w podglądzie runu.

Mechanizm zabezpieczający (stop-loss)

System automatycznie zatrzymuje analizę gdy jakość pobierania danych spada poniżej akceptowalnych progów. Chroni to przed przepaleniem budżetu w sytuacji problemów sieciowych.

6 progów ochronnych:

Co się dzieje po zatrzymaniu:

• Analiza otrzymuje status "Zatrzymana"
• Pozostałe pozycje otrzymują status "stopped_by_guardrail"
• Raport przyczyny jest widoczny w podglądzie runu
• Wyniki przetworzone przed zatrzymaniem są zachowane - można je pobrać
• Jeśli skonfigurowany jest webhook, wysyłany jest alert

Progi można dostosować w zakładce Ustawienia.

Warstwa dostępu sieciowego (proxy)

System korzysta z puli serwerów pośredniczących (proxy) do pobierania danych. Zarządzanie pulą:

Import proxy:

• Format pliku: .txt, .csv lub .list - jeden URL na linię
• Format URL: http://user:pass@host:port lub socks5://host:port
• Duplikaty są automatycznie pomijane
• Maksymalny rozmiar pliku: 5 MB

System scoringu:

• Health score - ocena 0-100% (0 = martwy, 100 = idealny)
• Każdy sukces: +2% do wyniku
• Każdy błąd: -5% od wyniku
• System automatycznie wybiera proxy z najwyższym wynikiem

Auto-kwarantanna:

• Po 5 kolejnych błędach proxy jest automatycznie izolowany
• Czas kwarantanny: 24 godziny (konfigurowalne)
• Co 5 minut system sprawdza czy kwarantanna wygasła
• Można ręcznie kwarantannować/przywracać proxy w tabeli

Kategorie produktów

Każda analiza wymaga przypisania do kategorii. Kategorie definiują parametry oceny opłacalności.

Dodawanie kategorii: zakładka Dane rynkowe → "Dodaj kategorię".

API i eksport danych

Eksport wyników:

• Excel (.xlsx) - pełne wyniki z opłacalnością, cenami, metrykami
• CSV metryk - podsumowanie kosztowe runu
• Excel metryk - sformatowany arkusz z metrykami

REST API:

• GET /api/v1/analysis/active - aktywne analizy
• GET /api/v1/analysis/{id}/metrics - metryki runu
• GET /api/v1/analysis/{id}/results - wyniki analizy
• POST /api/v1/analysis/upload - upload pliku
• GET /api/v1/proxy-pool/health - stan proxy
• GET /api/v1/metrics/prometheus - metryki Prometheus

Klucze API: Twórz klucze z zakresami (read/write/admin) w zakładce Klucze API. Używaj nagłówka Authorization: Bearer jj_xxx...

Rozwiązywanie problemów

Poniżej znajdziesz najczęstsze problemy i sposoby ich rozwiązania.

Problem: Nie mogę wgrać pliku

• Błąd "Nieobsługiwany format" - upewnij się, że plik ma rozszerzenie .xlsx, .xls lub .csv
• Błąd "Plik za duży" - maksymalny rozmiar to 50 MB. Podziel plik na mniejsze części.
• Błąd "Brak wymaganych kolumn" - plik musi mieć kolumnę EAN i cenę zakupu. Sprawdź nagłówki.
• Plik się wgrywa ale 0 produktów - wszystkie wiersze zostały odrzucone. Sprawdź czy EAN to cyfry (8-13 znaków) i czy cena > 0.

Problem: Analiza nie startuje (status: oczekująca)

• Limit równoczesnych analiz - domyślnie max 3 na użytkownika. Poczekaj na zakończenie poprzedniej lub anuluj ją.
• Worker nie działa - sprawdź czy serwis "worker" jest uruchomiony (docker compose ps).
• Redis niedostępny - kolejka zadań wymaga Redis. Sprawdź połączenie.

Problem: Analiza została zatrzymana (stop-loss)

System automatycznie przerwał analizę z powodu problemów jakościowych. Sprawdź raport:

• error_rate - zbyt wiele błędów. Sprawdź jakość proxy (zakładka Warstwa sieciowa). Wymień słabe proxy.
• captcha_rate - zbyt wiele weryfikacji. Oznacza wykrycie automatycznego dostępu - zmień proxy lub poczekaj.
• consecutive_errors - seria błędów. Moduł pobierania danych może być niedostępny - sprawdź jego status na dashboardzie.
• retry_rate - zbyt wiele ponownych prób. Sieć jest niestabilna - sprawdź proxy.
• blocked_rate - zablokowane zapytania. IP proxy mogą być na czarnej liście - wymień je.
• cost_per_1000 - zbyt drogo. Zbyt wiele CAPTCHA lub retries. Popraw jakość proxy.

Co zrobić:

1. Sprawdź raport przyczyny w podglądzie runu
2. Popraw problem (zwykle wymiana proxy)
3. Dostosuj progi w Ustawieniach jeśli są zbyt czułe
4. Uruchom analizę ponownie

Problem: "Brak proxy w puli"

• Przejdź do zakładki Warstwa sieciowa
• Kliknij "Importuj" i wgraj plik z listą proxy
• Format: jeden URL na linię, np. http://user:pass@1.2.3.4:8080
• Obsługiwane protokoły: http, https, socks4, socks5
• Po imporcie sprawdź czy proxy mają status "Aktywny"

Problem: "Brak kategorii"

• Przejdź do zakładki Dane rynkowe
• Kliknij "Dodaj kategorię"
• Wpisz nazwę, mnożnik opłacalności i prowizję
• Kategoria pojawi się w liście przy tworzeniu nowej analizy

Problem: Dużo zablokowanych zapytań (blocked)

• Przyczyna: IP proxy zostały wykryte i zablokowane przez platformę docelową
• Rozwiązanie 1: Wymień proxy na świeże - wgraj nową listę w zakładce Warstwa sieciowa
• Rozwiązanie 2: Sprawdź health score proxy - te z wynikiem < 50% usuń lub kwarantannuj
• Rozwiązanie 3: Zmniejsz współbieżność (CONCURRENCY_PER_USER) żeby zmniejszyć obciążenie
• Rozwiązanie 4: Poczekaj 24h - kwarantanna automatycznie wygaśnie

Problem: Dużo produktów "nie znaleziono"

• Przyczyna 1: Produkt nie istnieje na Allegro - to normalne dla niszowych produktów
• Przyczyna 2: Błędny EAN - sprawdź czy kody mają 8-13 cyfr i poprawną sumę kontrolną
• Przyczyna 3: Produkt jest na Allegro pod innym kodem - zweryfikuj ręcznie
• Status "nie znaleziono" jest poprawny i nie oznacza błędu systemu

Problem: Błędy sieciowe (network_error / timeout)

• Przyczyna 1: Proxy nie odpowiada - sprawdź health score w zakładce Warstwa sieciowa
• Przyczyna 2: Serwer docelowy przeciążony - zmniejsz współbieżność lub poczekaj
• Przyczyna 3: Timeout zbyt krótki - domyślnie 90s, zwiększ ALLEGRO_SCRAPER_TIMEOUT_SECONDS
• Przyczyna 4: Firewall blokuje połączenia wychodzące - sprawdź regułki sieciowe

Problem: HTTP 429 - "Zbyt wiele zapytań"

• Na loginie: Przekroczono limit 5 prób na minutę. Poczekaj 60 sekund.
• Na uploadzie: Limit 10 uploadów na minutę. Poczekaj chwilę.
• Na analizie: Limit równoczesnych analiz (domyślnie 3 globalnie, 12 globalnie). Poczekaj na zakończenie.
• Na API: Globalny limit 200 zapytań na minutę. Zwolnij częstotliwość.

Problem: Nie mogę się zalogować

• Błędne hasło - upewnij się, że wpisujesz prawidłowe hasło (ustawione w UI_PASSWORD)
• Konto zablokowane - po 5 nieudanych próbach konto jest blokowane. Poczekaj 5 minut.
• CSRF failed - wyczyść cookies przeglądarki i spróbuj ponownie
• Hasło domyślne - jeśli nie zmieniono, domyślne hasło to wartość UI_PASSWORD z konfiguracji

Problem: Nie mogę pobrać wyników

• Analiza w toku - poczekaj na zakończenie (status: zakończona)
• Brak wyników - jeśli wszystkie pozycje to "nie znaleziono", eksport może być pusty
• Błąd 404 - analiza została usunięta lub nie istnieje
• Duży plik - eksport dużych analiz (10k+ EAN) może trwać kilka sekund

Tryb buforowany (cache)

System przechowuje pobrane dane rynkowe w bazie danych. Tryb cache pozwala na analizę bez ponownego pobierania:

• Cache TTL - czas ważności danych (domyślnie 30 dni, konfigurowalny w Ustawieniach)
• Analiza z bazy - zakładka Nowa analiza → "Start z bazy" - używa tylko danych z cache
• Oszczędność - tryb cache nie generuje kosztów sieciowych (koszt = 0)
• Kiedy używać - do ponownej analizy tych samych produktów lub testów z innymi parametrami

Alerty i monitoring

Monitoring EAN:

• Dodaj kody EAN do cyklicznego monitorowania (zakładka Monitoring)
• System automatycznie pobiera dane w wybranym interwale (15 min - 24h)
• Zmiany cen i dostępności są rejestrowane

Reguły alertów:

• Cena spadła poniżej X - powiadomienie gdy cena spadnie poniżej progu
• Cena wzrosła powyżej X - powiadomienie gdy cena wzrośnie ponad próg
• Spadek ceny o X% - powiadomienie przy procentowym spadku
• Produkt niedostępny - powiadomienie gdy produkt zniknie z oferty

Webhook: Skonfiguruj ALERT_WEBHOOK_URL w ustawieniach serwera żeby otrzymywać alerty na Slacka, Discorda lub email.