Ustawienia — EO2SG

1. Domyślne dla "Aktualizuj wszystko"

Operacje do wykonania (w kolejności)

Aktualizacja: stan / zakup / EAN ? Co robi?
Dla każdego sparowanego produktu kopiuje z Mpfirma do sklepu wybrane pola (stan magazynowy, cena zakupu, EAN). Tylko produkty EasyOffice_*.

Bezpieczeństwo: najmniej ryzykowna operacja — pola łatwe do cofnięcia, każda zmiana zapisana w dzienniku zmian z numerem ID operacji.

Rytm: dobra do uruchamiania automatycznego co godzinę. Aktualizacja opisów produktów ? Co robi?
Kopiuje opis HTML z Mpfirma do products_description w sklepie (tabela osobno od products, język polski).

Wybór strategii poniżej decyduje o ryzyku:

bezpieczna — wpisuje tylko gdy sklep ma pusty opis
uzupełnij krótsze — także gdy sklep ma <50% długości
zawsze nadpisuj — może zniszczyć Twoje ulepszenia w sklepie!

Tworzenie nowych produktów w sklepie ? Co robi?
Tworzy w sklepie produkty z Mpfirma których jeszcze tam nie ma. INSERT do trzech tabel: products + products_description + products_to_categories. Po INSERT — automatycznie wgrywa zdjęcia z Mpfirma (galeria + WebP).

Wymaga: zatwierdzonego mapowania kategorii dla danej kategorii Mpfirma. Produkty bez mapowania są pomijane.

Cofalne: rollback usuwa z 3 tabel + sprząta zdjęcia z FTP. Dezaktywacja produktów których nie ma w Mpfirma ? Co robi?
Produkty EasyOffice_X które są w sklepie ale wypadły z Mpfirma (ukryte / bez EAN-u / skasowane) — ustawia products_status: 1 → 0. Klient ich nie zobaczy w sklepie, ale dane zostają.

Bezpiecznik: przed dezaktywacją sprawdza LIVE w Mpfirma czy produkt nie wrócił do filtra (np. ktoś uzupełnił EAN). Jeśli wrócił — pomijany.

Cofalne: rollback przywraca status=1. Przerwij przy pierwszym błędzie ? Gdy podczas wykonania jednej operacji wystąpi choć jeden błąd, kolejne zaplanowane operacje NIE zostaną uruchomione. Bezpieczniejsze — pozwala spokojnie sprawdzić co poszło nie tak zanim zrobi się więcej zmian.

Wyłączone = lecimy dalej mimo pojedynczych błędów.

Pola dla "Aktualizacja stan / zakup / EAN"

stan magazynowy ? Aktualizuje pole products_quantity w sklepie liczbą sztuk z Mpfirma. Stan ujemny w Mpfirma jest traktowany jako 0. cena zakupu ? Aktualizuje products_purchase_price netto. Używana do raportów marży w sklepie. Nie wpływa na cenę sprzedaży widzianą przez klienta. EAN (uzupełnij puste) ? Wpisuje EAN z Mpfirma tylko gdy sklep ma pusty EAN. Jeśli sklep ma już jakiś EAN (nawet inny) — pomijamy. Konflikty rozstrzyga się ręcznie w panelu Powiązania → Wymagają sprawdzenia. cena sprzedaży ? ⚠ Ostrożnie — to cena widoczna dla klienta w sklepie.
Wartość obliczana z reguł narzutu (kategoria → szablon w panelu Narzuty). Aplikuje atomowo 4 pola: netto + brutto + kwota VAT + klasa VAT.

Działa tylko dla produktów z zatwierdzonym mapowaniem kategorii (sprawdzaj w Audyt kategorii).

Bezpiecznik Omnibus: obniżki >30% są domyślnie pomijane — zaznacz "pozwól na duże obniżki" jeśli świadomie chcesz je zaaplikować. Tylko sparowane (EAN zgodny) ? Pomija pary "sparowane (sklep bez EAN)" — działa tylko na te, gdzie EAN sklepu = EAN Mpfirma. Bezpieczniejsze (wyższa pewność że to ten sam produkt), ale węższe. Pozwól na duże obniżki (Omnibus) ? Dyrektywa Omnibus (UE) wymaga, by przy obniżce ceny pokazywać najniższą cenę z 30 dni. Dla obniżek >30% nasz system domyślnie BLOKUJE aktualizację ceny — żeby nie wprowadzić niezgodnej ceny przed prawnikiem.

Włączone = pozwala aplikować takie zmiany. Używaj świadomie — sklep musi pokazać przekreśloną cenę z 30 dni.

Pole min_price_30_day w sklepie jest aktualizowane automatycznie (nie ręcznie).

Strategia aktualizacji opisów ? Wpływa na to które opisy w sklepie zostaną nadpisane.

bezpieczna — sklep ma pusty opis → wpisuje z Mpfirma. Inne zostawia. (76 produktów obecnie)
uzupełnij krótsze — bezpieczna + dodatkowo gdy sklep ma opis <50% długości MPF.
zawsze nadpisuj — wszystko co różne. ⚠ Ryzyko: jeśli ktoś w sklepie ulepszył opis, zostanie cofnięty do wersji z Mpfirma.

Limit: aktualizacja stan/zakup/EAN Limit: aktualizacja opisów Limit: tworzenie nowych Limit: dezaktywacja sierot

0 = bez limitu (wszystkie pasujące rekordy)

2. Powiadomienia / monitoring

Email do alertów monitoringu ? Adres na który system wyśle wiadomość gdy:

operacja synchronizacji zakończy się błędem
lokalna kopia danych jest starsza niż próg poniżej
nie da się połączyć z Mpfirma / sklepem / FTP

Wszystkie alerty trafiają też do pliku storage/logs/alerts.log (panel Automatyzacja). Email to dodatkowy kanał. Adres powiadomień (Slack / Discord / Teams) ? Adres internetowy (webhook URL) do którego system wyśle alerty alternatywnie do emaila.

Skąd go wziąć?

Slack: Ustawienia kanału → Integracje → "Incoming Webhooks" → kopiuj URL
Discord: Edytuj kanał → Integracje → Webhooki → "Nowy webhook" → kopiuj URL
Teams: Kanał → "..." → Łączniki → "Webhook przychodzący"

Pozostaw puste żeby wyłączyć. Po ilu godzinach uznać dane za przestarzałe ? Jeśli "Pełne odświeżenie lokalnej kopii" nie uruchomiło się od X godzin, monitoring uzna dane za stare i wyśle alert.

Polecam: 2× częstotliwość crona (np. cron co 1h → próg 2h). Zostawia margines na chwilowe problemy z hostingiem / siecią.

Monitoring ZAWSZE zapisuje do pliku alertów (widoczne w panelu Automatyzacja). Email i adres powiadomień to dodatkowe kanały.

3. Automatyczne uruchamianie (cron)

PHP CLI path na hostingu ? Ścieżka do interpretera PHP w trybie konsolowym na Twoim hostingu. Używana w cronie do uruchamiania skryptów.

Typowe wartości:

zenbox / CloudLinux: /usr/local/bin/ea-php83
ogólny Linux: /usr/bin/php8.3 albo /usr/bin/php
cPanel "PHP Selector": sprawdź w "Aktualna wersja PHP"

Jak sprawdzić? SSH → which php83 lub php -v. Ścieżka projektu na hostingu ? Katalog gdzie wgrane są pliki EO2SG na serwerze (poza public_html ze względów bezpieczeństwa). Przykłady:

~/eo2sg — w katalogu domowym użytkownika SSH
/home/easyoffice/eo2sg — pełna ścieżka

Cron robi cd do tego katalogu zanim odpali skrypt. Pełne odświeżenie lokalnej kopii (co ile godzin) Aktualizacja stan/zakup/EAN (co ile godzin) Lokalna kopia zdjęć (codziennie o godzinie)

Dezaktywacja sierot — dzień tygodnia o godzinie

Wariant A — gotowy fragment do wklejenia w cPanel "Zadania cron" ? Kiedy używać?
Gdy masz dostęp do cPanela na hostingu (zenbox, home.pl, OVH itp.) z opcją "Zadania cron" / "Cron jobs".

Jak wkleić?

cPanel → "Zaawansowane" → "Zadania cron"
Skopiuj snippet poniżej (przycisk "Skopiuj")
Każdą linię wklej jako osobne zadanie (poza komentarzami zaczynającymi się od #)

Snippet odświeża się automatycznie gdy zmienisz pola powyżej.

Wariant B — uruchamianie zewnętrzną usługą (cron-job.org / EasyCron) ? Kiedy używać?
Gdy hosting nie ma cPanel cron lub wolisz konfigurację z poziomu przeglądarki (bez SSH/cPanel).

Jak skonfigurować?

Załóż konto na cron-job.org (darmowe) lub EasyCron
Dodaj nowe zadanie typu "URL" z adresem z listy poniżej
Ustaw harmonogram (np. co 1 godzinę dla "refresh", "apply_5A")

Bezpieczeństwo: klucz dostępu chroni przed obcymi pingami — jeśli ktoś go pozna, może zrobić DoS na panel. Trzymaj prywatnie, rotuj co kilka miesięcy lub natychmiast w razie wycieku.

Dla klientów bez dostępu do cPanel cron. Zewnętrzna usługa wywołuje nasz adres internetowy co X minut, my wykonujemy resztę. Klucz dostępu chroni przed obcymi wywołaniami.

Ładowanie...

? Wygeneruje nowy losowy klucz (32 znaki). STARE adresy w cron-job.org / EasyCron przestaną działać — trzeba je zaktualizować nowymi.

Rób to gdy podejrzewasz wyciek klucza lub po zmianie obsługującego klienta.

4. Obrazki — kompresja i upload

Jakość WebP (1-100) ? Im wyższa wartość, tym lepsza jakość ale większy plik.

60-70 — agresywna kompresja, widać artefakty na zdjęciach z gradientem
75-82 — sweet spot dla zdjęć produktowych (domyślne 82)
85-90 — bardzo bliskie oryginalnej JPG
95+ — sens tylko dla zdjęć przeznaczonych do druku

WebP 82 daje typowo 30-50% mniejsze pliki niż JPG przy nieodróżnialnej jakości na małych rozdzielczościach widzianych w sklepie. Max długość boku (px) ? Jeśli zdjęcie z Mpfirma jest większe niż ta wartość po dłuższej osi — zostanie zmniejszone (zachowując proporcje). Mniejsze zdjęcia zostają nietknięte.

1600px to standard dla sklepów (sklep i tak generuje miniatury z oryginału). Większe zdjęcia to marnowanie miejsca i transferu.

Nie kropujemy ani nie centrujemy — tylko proporcjonalne zmniejszenie. Pomiń konwersję dla < (bajty) ? Pliki mniejsze niż X bajtów wgrywamy do sklepu w oryginalnym formacie (bez konwersji do WebP).

Po co? Małe ikony / loga firmy nic nie zyskają na konwersji (czasem nawet pogorszenie). Próg 50 KB (51200) wyłącza je z procesu.

Wartość 0 = konwertuj wszystko do WebP. Kwarantanna zamiast usuwania ? Co robi kwarantanna?
Gdy nadpisujemy zdjęcia produktu nowymi z Mpfirma, stare pliki zamiast być skasowane z FTP — trafiają do folderu images/_eo2sg_trash/operacja_<ID>/. Dzięki temu rollback (cofnij operację) potrafi je przywrócić.

Wyłączone = stare pliki znikają od razu (oszczędność miejsca, ale rollback nie odzyska zdjęć).

Gdzie są pliki kwarantanny?
Na FTP sklepu w katalogu images/_eo2sg_trash/. Każde uruchomienie ma własny podkatalog operacja_<ID>.

Jak je usunąć (gdy już nie potrzebne)?
Klient FTP (FileZilla, WinSCP) → wejdź w images/_eo2sg_trash/ → usuń stare foldery operacja_*. Albo cPanel → "Menedżer plików" → ten sam katalog.

Kiedy bezpiecznie usuwać?
Po potwierdzeniu że nowe zdjęcia w sklepie są OK i nie planujesz cofania operacji. Stare runy (sprzed tygodnia) zwykle bezpieczne.

Te wartości są też w pliku konfiguracyjnym .env na serwerze. Panel zapisuje do bazy ustawień; właściwy moduł obróbki zdjęć korzysta z .env. Dla pełnej spójności zmień w obu miejscach (lub poproś administratora o synchronizację).

5. Dane firmy i sklepu

Nazwa firmy NIP Email firmy Publiczny URL sklepu (do linkowania) Strefa czasowa

6. Połączenia bazy i FTP ? Hasła zaszyfrowane w bazie (AES-256-GCM) — klucz szyfrowania (`APP_ENCRYPTION_KEY`) trzymamy w pliku `.env` na serwerze. Bez tego klucza danych w bazie nie da się odczytać.

Backup klucza: zachowaj `.env` w bezpiecznym miejscu — bez niego, jeśli baza zniknie lub klucz się zmieni, hasła trzeba wpisać od nowa.

Pierwszy raz? Klik "Skopiuj wartości z .env do bazy" — zaimportujemy z pliku konfiguracyjnego.

Ładowanie...

Po zmianie hasła użyj "Test połączenia" ZANIM zapiszesz — żeby się upewnić że nowe credentials działają. Pole hasła z kropkami •••••• oznacza "ustawione, niezmienione" — nadpisze tylko jeśli faktycznie wpiszesz nową wartość.

7. Polityka zdjęć

Sposób synchronizacji zdjęć dla sparowanych produktów ? Mpfirma jest źródłem prawdy (zalecane)
Każde zdjęcie sparowanego produktu nadpisujemy świeżym z Mpfirma — stare lądują w kwarantannie (sekcja 4). Spójne, ale dużo transferu na FTP przy pełnym apply.

Wgrywaj tylko gdy sklep nie ma zdjęć
Bezpieczne — jeśli sklep ma cokolwiek, zostawiamy. Wgrywamy tylko brakujące. Nie zaktualizuje zdjęć sparowanych produktów które się zmieniły w Mpfirma.

Porównuj zawartość (md5)
Pobieramy zdjęcie z Mpfirma + ze sklepu, porównujemy md5. Re-upload tylko jeśli różne. Najuczciwsze ale 2× pobranie per produkt = wolno przy 12k produktów.

Konwencja ścieżki w sklepie: bs_stockindex/<ID Mpfirma>/<plik> (zgodna z istniejącym integratorem XMLvat). Stare zdjęcia sparowanych produktów trafiają do _eo2sg_trash/operacja_<id>/... jeśli włączona kwarantanna (sekcja 4).

8. Backup sklepu ShopGold

⚠ Pamiętaj: przed pierwszym pełnym uruchomieniem "Aktualizuj wszystko" (a szczególnie przed tworzeniem nowych produktów lub dezaktywacją produktów których nie ma już w Mpfirma) — wykonaj kopię zapasową w panelu sklepu ShopGold (zwykle: cPanel → "Kreator backupu" albo wbudowany mechanizm sklepu). Magazyn Mpfirma jest tylko odczytywany — po naszej stronie nie ma ryzyka.

Pokazuj przypomnienie przed pełnym "Aktualizuj wszystko"

9. Synchronizacja Mpfirma — legacy vs nowy stack

⚠ Mpfirma żyje teraz w 2 warstwach:

Legacy (rdzeń aplikacji): Synchronizer z „Aktualizuj wszystko" pisze ceny/stany do sklepu bezpośrednio z mpfirma_products_snapshot.
Nowy stack (Źródła): MpfirmaAdapter czyta z tej samej tabeli, wpada do canonical layer i pisze przez SourceApplier.

Jeśli oba uruchomisz na tym samym produkcie — drugi nadpisze pierwszego. Wybierz ścieżkę poniżej:

Wyłącz legacy write — Synchronizer::applyPlan() będzie odrzucany bez błędu, write do ShopGold idzie WYŁĄCZNIE przez nowy stack (Źródła → Sklep).

Czytanie z Mpfirma zostaje aktywne (zasila mpfirma_products_snapshot, z którego nowy stack też korzysta). Możesz wrócić do legacy w każdej chwili — wystarczy odznaczyć.