Specyfikacja techniczna TellMyShop

1. Czym jest produkt

TellMyShop to moduł PrestaShop. Zainstalowany w sklepie wystawia go jako zdalny serwer MCP (Model Context Protocol). Właściciel dodaje go w aplikacji czatu jako własny konektor: w Claude albo w ChatGPT (własny konektor w trybie dewelopera). Od tej chwili asystent AI może czytać sklep, a po zatwierdzeniu podglądu przez właściciela także go zmieniać.

Z jednego kodu powstają dwie paczki (module/build/build.php):

Obie mają nazwę techniczną tellmyshop, więc wgranie ZIP-a Pro na Free jest zwykłą aktualizacją; ustawienia i historia zostają. Dla PrestaShop 1.7.8 ten sam kod jest przebudowywany na osobne paczki PHP 7.4 (module/build/build-ps17.php, ZIP tellmyshop-ps17-<wersja>.zip i tellmyshop-audyt-ps17-<wersja>.zip); ta specyfikacja opisuje paczkę dla PrestaShop 8.1+/9. W kodzie jest też trzeci wariant dla PrestaShop Addons (tylko Treści i SEO, Katalog i Handel; src/Edition.php, addons), nieużywany.

Zasady, których trzyma się kod:

1. Zapis działa jak kliknięcie „Zapisz” w panelu. Zmiany treści idą przez klasy ObjectModel PrestaShop (walidacja, hooki, indeks wyszukiwarki, cache). Bezpośredni zapis w bazie jest tylko w obszarze Serwis (ps_db_execute, z kopią wierszy, pkt 5.8) i w ps_update_element_field (jedno pole jednego wiersza, dla pól, których nie obsługują zwykłe narzędzia).
2. Zapis w dwóch krokach. Każde narzędzie zapisujące najpierw zwraca podgląd i change_token. Dopiero drugie wywołanie z confirm=true i tym tokenem cokolwiek zapisuje.
3. Wszystko jest logowane i, gdzie się da, odwracalne: historia zmian z nagraniem każdego wiersza bazy zmienionego przy zapisie, ps_revert_change dla danych, kopie i przywracanie dla plików, kopie wierszy dla SQL, codzienna kopia bazy, nowa zmiana adresu sprawdzona pod 301 dla URL. Wyjątki są nazwane w podglądzie.
4. Bezpieczny start. Konektor wyłączony, dane klientów wyłączone, przełączniki Handel, Motyw, Moduły i Serwis wyłączone. Bez aktywnej licencji narzędzia zapisu są ukryte. Z aktywną licencją Treści i SEO oraz Katalog zapisują po podglądzie i zgodzie właściciela. Sklep i panel działają dalej.
5. Asystent AI działa jako osobny, nieaktywny pracownik panelu tylko z jego uprawnieniami; SuperAdmin jest odrzucany.
6. Właściciel się dowiaduje. Każde poluzowanie zabezpieczeń wysyła e-mail; jest codzienne podsumowanie i kontrola integralności plików.
7. Dane idą ze sklepu do własnego konta czatu właściciela (Claude od Anthropic albo ChatGPT od OpenAI). Bez PrestaShop Account i Eventbus. Wywołania licencji nie niosą treści sklepu.
8. Blokady stałe (src/Security/Blocklist.php) działają niezależnie od przełączników i licencji: bez dostępu do kont pracowników, haseł, uprawnień, kluczy API, plików z danymi do bazy ani samego konektora; bez zapisu podatków, metod i modułów płatności, zamówień i ich statusów.

2. Architektura i uwierzytelnienie

2.1 Składniki

2.2 Przebieg żądania

sequenceDiagram
    actor U as Właściciel
    participant C as Asystent AI (Claude albo ChatGPT)
    participant M as Moduł TellMyShop (sklep)
    participant PS as Rdzeń PrestaShop
    U->>C: „Napisz meta description dla Sof”
    C->>M: tools/call ps_search_products (HTTPS, token)
    M->>M: włącznik, HTTPS, blokada IP, lista IP, Origin, token, licencja, limity, uprawnienia
    M->>PS: zapytanie o produkty
    M-->>C: wynik (dane klientów filtrowane według poziomu)
    C->>M: tools/call ps_update_product_content (confirm=false)
    M-->>C: podgląd + change_token (30 min, jednorazowy)
    C-->>U: pokazuje podgląd, prosi o zgodę
    U->>C: „Tak, zapisz”
    C->>M: te same argumenty + confirm=true + change_token
    M->>M: przełącznik obszaru (jeśli obszar go ma), sprawdzenie tokenu (HMAC narzędzia, argumentów, stanu „przed”), codzienna kopia bazy
    M->>PS: zapis ObjectModel (walidacja, hooki, indeks, cache), nagranie każdego zmienionego wiersza
    M->>M: dziennik PrestaShop + historia zmian (change_id, operation_id)
    M-->>C: wynik z operation_id i kontrolą zmian spoza podglądu

2.3 Adres i transport

• Adres: https://twoj-sklep.pl/module/tellmyshop/mcp. Krok 1 karty Start tworzy adres konektora i pokazuje go w całości raz.
• Token idzie w adresie (?token=…) albo w nagłówku Authorization: Bearer ….
• Transport: Streamable HTTP, JSON-RPC. Wersje protokołu: 2026-07-28 (nowa; _meta i nagłówek MCP-Protocol-Version muszą się zgadzać) oraz starsze 2025-11-25, 2025-06-18, 2025-03-26. Nieobsługiwana wersja: HTTP 400 z listą obsługiwanych.
• Od 2.7.2 teksty dla modelu są po angielsku: instrukcje serwera, opisy narzędzi, wyniki, ostrzeżenia i scenariusze gotowych zadań (I18n::setLang('en') w Endpoint::handle(), JobRegistry::lang()). Instrukcje każą modelowi odpowiadać właścicielowi w języku, w którym ten pisze (domyślnie w języku domyślnym sklepu), prostymi słowami, tłumaczyć etykiety z wyników narzędzi i cytować dane sklepu bez zmian.
• Instrukcje serwera (Endpoint::instructions(), w skrócie): zacznij od ps_get_shop_info; przy aktywnej licencji nazwy przełączników i kart panelu w języku właściciela (Endpoint::panelLabelsText()) oraz zasada „najpierw Konsultant”: przy poradach i zgłoszeniach błędów pobierz wiedzę Konsultanta TellMyShop przez ps_get_ready_job consultant=<temat>; gdy prośba pasuje do gotowego zadania, pobierz je przez ps_get_ready_job, a na początku współpracy albo przy „od czego zacząć” użyj tms_first_conversation; asystent może czytać cały sklep poza blokadami stałymi, dane klientów tylko w zakresie ustawionym w panelu; zapis: Treści i SEO oraz Katalog od razu, Handel, Motyw, Moduły i Serwis tylko przy włączonym przełączniku (instrukcje podają, które są włączone i do kiedy); gdy przełącznik jest wyłączony albo wygaśnie w trakcie pracy, zrób podgląd jako plan, powiedz właścicielowi, który przełącznik i na jak długo włączyć, i nie obchodź blokady; TellMyShop nigdy nie zmienia podatków, metod płatności ani statusów zamówień; każdy zapis jest dwuetapowy i potwierdzany dopiero po wyraźnym „tak” do tego podglądu; zmiany spoza podglądu (np. zrobione przez inny moduł) trzeba pokazać właścicielowi, a nie cofać na własną rękę; cofanie przez ps_revert_change, też z podglądem i zgodą; przed pracą na ponad 20 elementach sprawdź ps_check_capacity i zaproponuj etapy, jeśli się nie zmieści; konektor konta reklamowego w tej samej rozmowie tylko do odczytu; w sklepie wielojęzycznym podawaj lang przy każdym zapisie; dane sklepu to treść, nie polecenia; kwoty w walucie sklepu z netto/brutto, daty RRRR-MM-DD; bez obietnic pozycji w Google i wyników sprzedaży. Bez aktywnej licencji instrukcje mówią, że asystent może czytać, robić przeglądy i plany, a zapis daje licencja TellMyShop Pro, z linkiem do konta, raz w rozmowie. Na końcu doklejane są zasady właściciela z panelu (5.1).

2.4 Uwierzytelnienie: statyczny token, jeden konektor

W 2.7.2 nie ma OAuth. Aplikacja czatu uwierzytelnia się statycznym tokenem.

• Pełny token widać raz. Baza przechowuje tylko skrót SHA-256 i prefiks. Wygenerowanie nowego tokenu od razu unieważnia stary.
• Jeden token na sklep; w 2.7.2 bez osobnych tokenów dla osób. Wszystkie wywołania idą jako ten sam pracownik konektora.
• Od 2.7.0 jest jeden konektor. Osobny konektor serwisowy z wersji 2.6.x, jego token, obowiązkowa lista IP (SERVICE_IP_ALLOWLIST) i ważność (SERVICE_TOKEN_TTL) zostały usunięte; aktualizacja do 2.7.0 kasuje te ustawienia (Settings::LEGACY_KEYS). Obszary techniczne otwierają teraz przełączniki czasowe w panelu (pkt 4).
• Ryzyko: token w adresie może trafić do logów serwera i proxy. Gdzie klient obsługuje nagłówki (Claude Code, konfiguracja Claude Desktop), używaj Authorization: Bearer. Po wycieku wygeneruj nowy token.
• Plan rozwoju: logowanie OAuth, ważne też dla katalogu konektorów Claude.

2.5 Zabezpieczenia punktu dostępu

src/Endpoint.php i src/Mcp/Core.php wykonują przy każdym żądaniu, w tej kolejności:

Po tych kontrolach pierwszy zatwierdzony zapis danego dnia uruchamia kopię bazy (Access::dailyBackup()); nigdy nie blokuje zapisu w Treściach, Katalogu ani Handlu, a nieudana albo niedokończona kopia trafia jako uwaga do wyniku. Monitorowanie, które nigdy nie blokuje wywołania: kontrola integralności (najwyżej co 6 h) i podsumowanie dzienne, uruchamiane po poprawnym tokenie.

IP klienta: CF-Connecting-IP / X-Forwarded-For są brane pod uwagę tylko przy włączonym TRUST_PROXY i gdy REMOTE_ADDR jest w TRUSTED_PROXIES.

2.6 Dokąd płyną dane

• Wyniki narzędzi idą ze sklepu do konta czatu właściciela: Claude (Anthropic) albo ChatGPT (OpenAI). Treść rozmów podlega warunkom dostawcy.
• Dane osobowe klientów trafiają do czatu tylko na poziomie pseudo (zamaskowane) albo full (czasowo); zobacz pkt 6.5.
• Bez PrestaShop Account i Eventbus.
• Serwer licencji dostaje tylko to, co wysyła src/License/: przy aktywacji klucz licencji, produkt, znormalizowane domeny i adres sklepu, losowe ID instancji i wersje modułu, PrestaShop i PHP; przy odświeżeniu token licencji, ID instancji i wersje modułu i PrestaShop, a do tego statystyki uruchomienia, jeśli właściciel je włączył; przy zwolnieniu token i ID instancji (za każdym razem także IP wywołującego).
• Statystyki uruchomienia (src/License/Usage.php, ustawienie USAGE_STATS, panel „Wysyłaj statystyki uruchomienia (same liczby)”): domyślnie wyłączone, wysyłane dopiero po włączeniu przez właściciela (od 2.6.5; aktualizacja do 2.6.5 wyłączyła je wszystkim). Idą z codziennym odświeżeniem: daty pierwszego wywołania narzędzia, pierwszego zadania i pierwszego cofnięcia, liczba zapisów i cofnięć, uruchomienia każdego gotowego zadania i wywołania w każdym obszarze. Bez treści rozmów, produktów i danych klientów.
• Wiedza Konsultanta (src/License/ConsultantUpdate.php): gdy odświeżenie zgłasza nowszą paczkę wiedzy, moduł pobiera ją z POST /api/v1/konsultant z tokenem licencji, ID instancji i językiem, sprawdza podpis Ed25519 i zapisuje w var/tellmyshop/. Paczka to sam tekst, nigdy kod; nie zmienia narzędzi, uprawnień ani zasady podglądu. Przy każdym błędzie zostaje ostatnia dobra albo wbudowana wiedza.
• Inne połączenia wychodzące: HttpProbe do własnych stron sklepu (sprawdzanie adresów, ps_inspect_page), ImageFetcher dla adresów zdjęć podanych do ps_manage_product_images (z ochroną SSRF), adres ZIP podany do ps_install_module. Treść sklepu nie trafia nigdzie poza aplikację czatu.

3. Wymagania

4. Obszary i przełączniki

4.1 Obszary w kodzie

Od 2.7.0 Pro z aktywną licencją czyta cały sklep: widoczne są wszystkie grupy narzędzi, z wyjątkiem danych objętych blokadami stałymi (src/Security/Blocklist.php). Obszary różnią się zapisem. Grupy narzędzi są zdefiniowane w src/Settings.php (GROUPS), ich obszary zapisu w src/Access.php (AREA_OF_GROUP), przełączniki w Settings::BLOCKS. Numery bloków 0–5 zostają jako stałe klucze (docs/data/tools.json, pole block).

Razem w 2.7.2: 71 narzędzi = 3 w rdzeniu + 41 + 9 + 9 + 5 + 4. 30 odczyt, 41 zapis. TellMyShop Free ma 24 z nich (same odczyty). Z aktywną licencją asystent widzi zaraz po instalacji 66; 5 narzędzi bloga wymaga SmartBloga. Liczba narzędzi wzrosła z 67 w 2.6.0 do 69 w 2.6.11 (ps_get_bought_together, ps_set_related_products) i do 71 w 2.7.0 (ps_get_element_full, ps_update_element_field). Wewnętrzna wersja 2.5.1 miała 63.

• Odczyt działa w każdym obszarze bez przełącznika, także pliki motywu, ps_db_query i lista kopii plików.
• Przełącznik jest sprawdzany dopiero przy zatwierdzeniu (confirm=true). Podgląd działa zawsze, więc asystent może zaplanować zmianę i powiedzieć właścicielowi, który przełącznik włączyć.
• Obsługa klienta (support, obszar „Customer service” w Access::AREA_NAMES) działa tylko na poziomie danych klientów pseudo albo full (6.5).
• ps_restore_file_backup wymaga przełącznika strefy przywracanego pliku: Motyw dla plików motywu, Moduły dla plików modułów, Serwis dla pozostałych plików sklepu (Settings::ZONE_BLOCK).
• ps_update_element_field zapisuje od razu, ale pola cen i stanów wymagają przełącznika Handel.
• ps_revert_change zapisuje od razu, ale cofnięcie zmiany z Handlu, Motywu, Modułów albo Serwisu wymaga przy zatwierdzeniu przełącznika tego obszaru; właściciel może cofnąć wszystko z panelu (karta Historia zmian).
• Włączenie Motywu, Modułów albo Serwisu wymaga zaznaczenia potwierdzenia i gotowej kopii bazy: moduł używa kopii z ostatniej godziny albo robi nową, co w dużym sklepie może wymagać kilku kliknięć; bez miejsca na kopię przełącznik się nie włączy (ConfigPage::toggleBlock(), DbBackup). Handel wymaga tylko potwierdzenia.
• Każde włączenie przełącznika trafia do dziennika audytu z nazwiskiem pracownika i wysyła e-mail do właściciela (block_on).

Licencja obejmuje wszystkie obszary; plany różnią się tylko liczbą domen produkcyjnych. Obszary sterują ryzykiem, nie ceną. Etykiety panelu pochodzą z i18n/*.php w 6 językach (pl, en, de, fr, es, it); angielski panel nazywa przełącznik Handel „Sales”.

4.2 Licencja, Pro bez licencji i TellMyShop Free

• Pro z aktywną licencją (tryb licencji full) = czyta cały sklep i zapisuje tak, jak opisuje pkt 4.1.
• Pro bez aktywnej licencji (brak klucza, klucz nieważny albo wygasły, inna domena lub instancja, albo token wersji darmowej; LicenseManager::effective() w trybie innym niż full) = czyta cały sklep, każde narzędzie zapisu jest ukryte, z gotowych zadań widać tylko grupę Free. Trybu tylko do odczytu jako ustawienia już nie ma (READ_ONLY usunięto w 2.7.0); decyduje sama licencja. W wewnętrznej wersji 2.5.1 bramka nie była wpięta (pkt 12).
• TellMyShop Free = paczka zbudowana bez narzędzi zapisu, bez narzędzi bloków 2–5 i ps_get_element_full oraz bez skryptu awaryjnego. Panel i asystent mówią, co daje TellMyShop Pro, z linkiem.
• ps_get_shop_info podaje wersję modułu, wariant (full, audit dla Pro bez aktywnej licencji, audit_free dla Free), tryb i stan licencji, obszary zapisu (write_areas: obszary zawsze włączone i każdy przełącznik z czasem działania i końcem), widoczne grupy i narzędzia, brakujące uprawnienia, poziom danych klientów i limity godzinowe, więc asystent wyjaśni, czemu zapis jest niedostępny.

4.3 Pozostałe ustawienia

Usunięte w 2.7.0 (Settings::LEGACY_KEYS, kasowane przy aktualizacji i odinstalowaniu): READ_ONLY, GROUPS, BLOCK_THEME, BLOCK_MODULES, SERVICE_TOKEN_*, SERVICE_IP_ALLOWLIST, SERVICE_TOKEN_TTL.

4.4 Zachowanie przy wyłączonym przełączniku

• Narzędzia za przełącznikiem zostają w tools/list i dalej czytają. Narzędzie zapisu zwraca podgląd z dopiskiem, że przełącznik jest wyłączony i że asystent ma pokazać podgląd jako plan i poprosić właściciela o włączenie przełącznika.
• Przy zatwierdzeniu przełącznik jest sprawdzany ponownie, więc zapis zatwierdzony po wygaśnięciu przełącznika jest odrzucany z komunikatem, który podaje kartę panelu („Zapis w obszarach”), przełącznik i jego czas działania. Nic się nie zapisuje.
• Przełączniki włącza tylko właściciel, w panelu. Ustawień konektora nie da się zmienić przez konektor.
• Od 2.7.0 profil pracownika konektora utworzony przez moduł dostaje od razu uprawnienia panelu wszystkich obszarów (EmployeeSetup::BLOCK_GRANTS); o zapisie decydują przełączniki, nie profil. Role konfiguracji i odinstalowania modułów idą za przełącznikiem Moduły, także gdy wygaśnie sam (EmployeeSetup::reconcileModuleRoles()). Obszar Serwis działa poza uprawnieniami PrestaShop.
• Blokady stałe, także przy wszystkich włączonych przełącznikach (Blocklist, w panelu „Zawsze zablokowane”): konta pracowników, hasła, sesje, uprawnienia i profile, konta API i webservice, tabele konektora, pliki z danymi do bazy (parameters.php, settings.inc.php, .env), katalog prywatny i sam moduł są niedostępne do odczytu i zapisu; podatki, moduły płatności z ich ustawieniami i plikami, zamówienia i ich statusy (w obsłudze klienta tylko prywatne notatki) oraz ustawienia wyglądające na sekrety nigdy nie są zapisywane.
• Narzędzia bloga pojawiają się tylko przy wykrytym SmartBlogu.

4.5 Przypisanie narzędzi do obszarów

Parametry wszystkich 71 narzędzi są sprawdzone ze schematami wejścia zwracanymi przez tools/list modułu 2.7.2 (docs/data/tools.json, params_status: "code_2.7.2"; narzędzia bloga z kodu, bo sklepy testowe nie mają SmartBloga). Uwagi do wybranych narzędzi:

• ps_check_capacity (odczyt, rdzeń, także bez licencji i we Free). items (wymagane, 0–100 000), batch_size (1–50, domyślnie 50), reads (0–100 000, domyślnie jedna lista na paczkę), files (0–1000). Kod: src/Tools/Shop/CheckCapacityTool.php na src/Write/Capacity.php (Capacity::plan()). Potrzebne wywołania to szacunek: odczyty + (paczki + pliki) × 3 (podgląd, zapis, sprawdzenie); potrzebne zapisy są dokładne: paczki + pliki. Zwraca limit, użyte, zostało i potrzeba dla wywołań, zapisów i zapisów plików, fits, items_now, frees_from (GG:MM) i suggest_limit (zaokrąglone w górę do dziesiątek); przy włączonym przełączniku Serwis także godzinę, o której sam się wyłączy (service_until).
• ps_get_ready_job (odczyt, rdzeń, także bez licencji). Parametry job, args (obiekt z wartościami tekstowymi) i consultant. Bez job wypisuje zadania dostępne w tym sklepie, z oznaczeniem [switch off] tam, gdzie zadanie czyta i planuje, dopóki właściciel nie włączy przełącznika obszaru, z argumentami wymaganymi oznaczonymi *; z job zwraca scenariusz krok po kroku. Każda wartość argumentu jest obcinana do 200 znaków; brak wymaganego argumentu zwraca błąd. We Free i w Pro bez licencji lista obejmuje tylko grupę Free; zadanie Pro wywołane po nazwie zwraca jedno neutralne zdanie. Z consultant (bez job) zwraca wiedzę Konsultanta TellMyShop na jeden albo kilka tematów rozdzielonych przecinkami (approach, seo, ai_search, product_page, copy, pricing, categories, design, commerce, developer, ads; list wypisuje tematy), tylko przy aktywnej licencji. Scenariusze i wiedza są po angielsku (JobRegistry::lang()).
• ps_get_element_full (odczyt, catalog, tylko Pro, 2.7.0). type (product | category | cms), id, lang, shop_id, table, max_chars (20–20 000; domyślnie 200, z table 2000), limit (domyślnie 20, maks. 200), offset. Wiersze każdej tabeli powiązanej z elementem (id_product, id_category, id_cms), także tabel innych modułów, oznaczone nazwą modułu; bez tabel z danymi klientów, zamówień i koszyków.
• ps_update_element_field (zapis, catalog, 2.7.0). type, id, table, column, value (tekst albo null, maks. 1 000 000 znaków), where (pozostałe kolumny klucza; pasować musi dokładnie jeden wiersz), confirm, change_token. Bezpośredni zapis w bazie: inne moduły nie reagują, a PrestaShop niczego nie przelicza poza indeksem wyszukiwarki produktów. Nigdy nie zmienia kolumn klucza. Pola cen i stanów wymagają przełącznika Handel; tabele objęte blokadami stałymi są odrzucane. Nagrywane i odwracalne jak każda zmiana.
• ps_list_redirects (odczyt, grupa seo, także bez licencji). search (maks. 200 znaków), active, sort = date | hits | last_hit (domyślnie date), shop_id, limit domyślnie 50, maks. 200, offset. Pokazuje tylko przekierowania dodane przez ps_manage_redirects; przekierowań produktów (ps_set_product_redirect) i reguł .htaccess w niej nie ma.
• ps_manage_redirects (zapis, grupa seo, przy aktywnej licencji zapisuje od razu). action = add | disable | enable. items dla add, do 100: source (wymagane, maks. 1024 znaki), target (maks. 2048) albo target_type (product | category | cms) z target_id, code 301 (domyślnie) albo 302. redirect_ids dla disable i enable, do 100. Do tego lang, shop_id, confirm, change_token. Podgląd sprawdza na żywo: źródło musi teraz zwracać 404 albo 410 (aktywne przekierowanie tego samego źródła oznacza zmianę celu), cel 200 w domenie sklepu; łańcuchy i pętle są odrzucane, także w obrębie jednego wywołania; nie da się przekierować strony głównej ani adresów modułu i panelu. Po zapisie narzędzie sprawdza każdy stary adres. Bez akcji usuwania; ps_revert_change cofa dodanie albo włączenie przez wyłączenie przekierowania, a zmianę celu przez przywrócenie poprzedniego celu. Przekierowania obsługuje moduł; zostają po odinstalowaniu, chyba że odznaczono „Przy odinstalowaniu zachowaj historię, kopie i przekierowania”.
• ps_get_404_report i ps_get_product_sales przyjmują days (ostatnie N dni zamiast date_from; 1–365 i 1–366).

Narzędzia z parametrem action (ps_manage_*, ps_customer_service, ps_server_file, ps_module_file, ps_module_config, ps_config) są liczone jako zapisujące; bez aktywnej licencji ich akcje listy i odczytu znikają razem z nimi.

4.6 Ekran konfiguracji (panel)

Panel w 6 językach (pl, en, de, fr, es, it; i18n/*.php; język pracownika, rezerwowo en). Nad kartami: etykieta wariantu (TellMyShop Free, TellMyShop Free (bez licencji), TellMyShop Pro, TellMyShop Pro (sprawdź licencję)) i jedno zdanie o stanie zapisu; po aktualizacji do 2.7.0 jednorazowa informacja o nowym modelu. Bez aktywnej licencji ramka mówi, co daje TellMyShop Pro. Karty w 2.7.2, w tej kolejności (views/templates/admin/configure.tpl):

4.7 Gotowe zadania

Zdefiniowane w src/Jobs/JobRegistry.php (GROUPS, JOBS), podawane jako prompty MCP (prompts/list, prompts/get) w menu konektora w aplikacji czatu, oraz narzędzie rdzenia tylko do odczytu ps_get_ready_job, które w aplikacjach bez menu promptów (np. w ChatGPT) zwraca ten sam scenariusz. Argumenty promptów są obcinane do 200 znaków i wstawiane do scenariusza jako dane w cudzysłowie, nigdy jako polecenia. Gotowe zadania doszły w 2.6.0; od 2.7.1 są podzielone na grupy. Projekt: produkt/gotowe-zadania-2.7.1.md.

• tms_help nie ma karty w panelu; tms_features_cleanup nie ma ani karty, ani pozycji w menu promptów. Oba wypisuje ps_get_ready_job (tms_features_cleanup tylko przy aktywnej licencji).
• Free (i Pro bez aktywnej licencji) pokazuje tylko grupę Free; scenariusze tylko czytają i kończą się linkiem do TellMyShop Pro. Pro z aktywną licencją pokazuje wszystkie grupy. Gdy przełącznik obszaru zadania jest wyłączony, zadanie działa w trybie switch: czyta, planuje i prosi właściciela o włączenie przełącznika przed jakimkolwiek zapisem.
• Zadania Motywu, Modułów i Serwisu zaczynają się wspólnym scenariuszem obszaru (np. najpierw motyw potomny i custom.css, wyłączenie zamiast odinstalowania, odczyt i diagnoza przed bezpośrednią zmianą w bazie albo w plikach). Przy aktywnej licencji każdy scenariusz zawiera też pasującą wiedzę Konsultanta TellMyShop (Consultant::forJob()).
• Każde zadanie: odczyt → plan dla właściciela → podgląd → zgoda → confirm → raport z ID operacji do cofnięcia; paczki do 50; bez obietnic efektów SEO i sprzedaży.
• Karty w panelu są w języku panelu (6 języków); scenariusze dla modelu od 2.7.2 są po angielsku.

5. Ścieżka zapisu

5.1 Kroki (src/Write/WriteFlow.php)

1. Wywołanie bez confirm (albo confirm=false). Narzędzie sprawdza argumenty, wczytuje stan i buduje podgląd: różnice per pole, liczby, przykładowe ceny, ostrzeżenia, skutki uboczne, warunki blokujące i informację, czy zmianę da się cofnąć. Moduły podpięte pod zapis tego obiektu są wymienione w ostrzeżeniu (Recorder::hookWarnings()). Gdy przełącznik obszaru jest wyłączony, podgląd o tym mówi. Nic się nie zapisuje.
2. Token. Odpowiedź zawiera change_token = HMAC nazwy narzędzia, argumentów i skrótu stanu „przed”, podpisany kluczem modułu. Ważny 30 minut, jednorazowy (użyte tokeny są zapisywane).
3. Zgoda. Asystent pokazuje podgląd i czeka na wyraźne „tak”. Instrukcje serwera zabraniają mu potwierdzania na własną rękę.
4. Wywołanie z confirm=true, change_token i identycznymi argumentami. Odrzucane, gdy przełącznik obszaru jest wyłączony, licencja wygasła, tokenu brak, wygasł, był użyty albo wydano go dla innych argumentów, albo gdy stan „przed” zmienił się od podglądu. Dla ps_install_module token wiąże też SHA-256 pobranego ZIP-a. Pierwszy zatwierdzony zapis danego dnia uruchamia codzienną kopię bazy (5.6).
5. Zapis przez ObjectWriter (5.2) albo wyspecjalizowane klasy zapisu (5.3). W trakcie zapisu Recorder nagrywa każdy wiersz bazy zmieniony przez narzędzie, przez PrestaShop i przez hooki innych modułów (5.4).
6. Log: wpis w dzienniku PrestaShop z ID pracownika konektora, wpis historii per zmienione pole i jeden wpis z nagranymi wierszami (5.4). Operacje zbiorcze mają wspólny operation_id.
7. Wynik z change_id / operation_id, kontrolą po zapisie („poza zmianami z podglądu nic innego w bazie się nie zmieniło” albo lista pozostałych zmian) i kontrolami, gdzie narzędzie je ma (301 po zmianie adresu, kompilacja Smarty, składnia PHP).
8. Cofnięcie na prośbę: ps_revert_change, ps_restore_file_backup albo nowy ps_change_url.

Standard TellMyShop (rozmowa o zmianach). WriteFlow::risk() ocenia każdy podgląd jako low / medium / high (niskie, średnie, wysokie): obszary Motyw, Moduły i Serwis oraz grupa Handel to ryzyko wysokie (poza ps_set_related_products, które jest niskie); ps_change_url, ps_manage_redirects, ps_set_product_redirect, ps_manage_categories i ps_set_product_categories to średnie; cofnięcie, które usuwa obiekt utworzony przez konektor, to średnie; reszta niskie. Ponad 20 elementów podnosi poziom o jeden (maks. wysokie) i każe najpierw zrobić 2–3 próbki; ostrzeżenia podnoszą go co najmniej do średniego. WriteFlow::standard() dokleja do każdego podglądu blok „TellMyShop standard”: ile mówić na danym poziomie (wysokie = karta ryzyka do 5 linii), że zgodą jest tylko wyraźne „tak” do tego podglądu i że przy niepewności proponuje się próbę na jednym elemencie. Po confirm=true wynik każe asystentowi sprawdzić efekt, podać wynik z liczbami i powiedzieć, jak cofnąć (albo że cofnąć się nie da). Każdy podgląd i zapis kończy się też linią o pozostałych limitach godzinowych. Poziom to wskazówka dla rozmowy, nie blokada; blokują przełączniki, licencja i change_token. Standard jest też streszczony w instrukcjach serwera przy każdym initialize (Endpoint::instructions()).

Zasady właściciela. Ustawienie OWNER_RULES (panel: karta Ustawienia, pole „Zasady Twojego sklepu dla asystenta AI”, jedna zasada w linii, maks. 1000 znaków) jest doklejane do instrukcji serwera przez Endpoint::ownerRulesText() i widoczne w ps_get_shop_info. Zasady właściciela obowiązują, o ile nie łamią zasad bezpieczeństwa; podgląd i zgoda zostają zawsze.

5.2 „Jak Zapisz w panelu” (src/Write/ObjectWriter.php)

Dla każdego obiektu: wczytuje ObjectModel ze wszystkimi językami i id_shop_list; sprawdza każde zmienione pole regułami klasy (validateField, isCleanHtml, limity długości); wywołuje setFieldsToUpdate(), więc zapisuje tylko zmienione pola; wywołuje update(), które odpala actionObject<Klasa>UpdateBefore/After (dla produktów też actionProductSave, actionProductUpdate); zapisuje wpis w dzienniku PrestaShop przypisany do pracownika konektora i wpis historii zmian.

5.3 Kroki zależne od typu obiektu

ps_check_shop_health wykrywa moduły podpięte pod zapisy i moduły reagujące tylko na formularz panelu. Warto go uruchomić przed większymi zmianami.

5.4 Historia zmian

Nagrywanie wierszy (src/Write/Recorder.php, od 2.7.0). Podczas zatwierdzonego zapisu warstwa nagrywająca (RecordingDb, ta sama sesja MySQL) odczytuje przed zapytaniem i po nim każdy wiersz dotknięty przez INSERT, REPLACE, UPDATE i DELETE, niezależnie od tego, czy zmieniło go narzędzie, PrestaShop czy hook innego modułu. Wynik trafia do jednego zaszyfrowanego wpisu historii typu recorded_rows. Tabele ulotne (połączenia, statystyki, logi, cache) są pomijane; zapytania, których nie da się rozłożyć (UPDATE z JOIN, INSERT…SELECT, DDL), są wymieniane jako nienagrane; błąd nagrywania nigdy nie zatrzymuje zapisu. Wynik zapisu wymienia każdą zmianę spoza podglądu, a asystent pokazuje je właścicielowi zamiast samemu je cofać.

Zapis: tabela ps_tellmyshop_change. Retencja HISTORY_RETENTION, domyślnie 180 dni. Usunięcie w psgdpr kasuje wpisy klienta; eksport je wymienia bez wartości. ps_list_changes zawsze maskuje dane klientów w wartościach przed i po, niezależnie od bieżącego poziomu dostępu: historia to podsumowanie, a nie sposób odczytu danych klientów. Wewnętrzna wersja 2.5.1 pokazywała odszyfrowane wartości bez maskowania.

5.5 Cofanie

• ps_revert_change po change_id albo operation_id. Dwuetapowe jak każdy zapis. Obejmuje Treści i SEO, Katalog, Handel, Moduły (włączanie, ustawienia) i Serwis (ps_config, ps_db_execute z kopią wierszy).
• Operacja z nagranymi wierszami jest cofana przez nagranie: wiersze wracają dokładnie do stanu sprzed zapisu, bez ponownego zapisu obiektów i bez odpalania hooków innych modułów (RecordedRows::undo()).
• Cofnięcie zmiany z obszaru Handel, Motyw, Moduły albo Serwis wymaga przełącznika tego obszaru w chwili zatwierdzenia (Reverter::blockFor()); podgląd cofnięcia działa zawsze. Karta Historia zmian w panelu pozwala zalogowanemu pracownikowi cofnąć każdą operację z jego własnymi uprawnieniami.
• Jeśli obecna wartość różni się od zapisanej „po”, podgląd o tym mówi; cofnięcie nadpisze późniejszą edycję.
• Samo cofnięcie jest logowane, więc też da się je cofnąć.
• Nieodwracalne według typu obiektu (Reverter::NOT_REVERTABLE w src/Write/Reverter.php): theme (utworzenie motywu potomnego), db_ddl (ALTER, CREATE, DROP, TRUNCATE), module_install (instalacja, aktualizacja albo odinstalowanie modułu), image_file (usunięte zdjęcie). Podgląd podaje powód i co zrobić zamiast tego. Nieodwracalne są też: zmiany adresów (link_rewrite: nowy ps_change_url), edycje plików (kopie), czyszczenie cache, utworzony produkt, który jest już w zamówieniu, odtworzony kod rabatowy już użyty w zamówieniu. Zaszyfrowane wpisy wymagają pliku klucza.
• Przekierowania (ps_manage_redirects): cofnięcie dodania albo włączenia wyłącza przekierowanie; cofnięcie zmiany celu przywraca poprzedni cel.
• Reguły koszyka nie mają usuwania: kod się wyłącza, nigdy nie usuwa.

5.6 Kopie plików

• Każdy zapis pliku w obszarach Motyw, Moduły i Serwis i każde przywrócenie najpierw kopiuje bieżący plik (albo zapisuje, że go nie było). ps_restore_file_backup kopiuje bieżącą wersję przed przywróceniem.
• Miejsce: var/tellmyshop/backups/RRRR/MM/ i tabela tellmyshop_backup; katalogi modułów przed aktualizacją w backups/modules/. Wszystkie kopie szyfrowane. Retencja 90 dni, zawsze co najmniej 5 ostatnich kopii pliku.
• Przywrócenie przez konektor wymaga przełącznika strefy pliku: Motyw dla plików motywu, Moduły dla plików modułów, Serwis dla pozostałych plików sklepu (Settings::ZONE_BLOCK). Przywrócenie w panelu wymaga uprawnienia pracownika do edycji motywów.
• Motyw: .tpl, .css, .js, .json w aktywnym motywie; motyw nadrzędny tylko do odczytu (prefiks parent:); search musi wystąpić dokładnie raz. Moduły i pliki sklepu: rozszerzenia tekstowe (php, tpl, twig, css, js, json, yml, xml, txt, md, html, htaccess, scss, svg…), odczyt maks. 1 MB, treść maks. 500 000 znaków.
• Kopie bazy (src/Storage/DbBackup.php, od 2.7.0, tylko Pro): pełny zrzut SQL tabel sklepu, zapisywany w częściach, które można wznowić, skompresowany gzip i zaszyfrowany (var/tellmyshop/db-backups/<id>.tmsdb, metadane w index.json, bez dodatkowej tabeli). Tabele ulotne (połączenia, statystyki, logi, cache) zachowują tylko strukturę. Kopia powstaje przy włączeniu konektora, raz dziennie przed pierwszą zatwierdzoną zmianą, przed włączeniem Motywu, Modułów albo Serwisu i po kliknięciu Zrób kopię teraz. Zostają 2 ostatnie; Pobierz odszyfrowuje kopię do pliku .sql.gz. Wszystkie kopie bazy są usuwane przy wyłączeniu konektora i przy odinstalowaniu. Zrzut nie jest migawką transakcyjną: duży sklep jest kopiowany w kilku żądaniach, a w tym czasie działa dalej.

5.7 Zmiana adresu URL

1. Podgląd pokazuje stary i nowy adres w każdym języku, adresy zmienione przy okazji i to, czy stary adres przekieruje 301.
2. Blokada, gdy przekierowanie kanoniczne to 302, włączony jest tryb deweloperski albo moduł nadpisuje trasy (src/Url/UrlGuard.php).
3. Po zapisie narzędzie wywołuje stary adres, oczekuje 301 na nowy i podaje wynik.
4. Cofnięcie = nowy ps_change_url na stary slug.
5. Format sluga: ^[a-z0-9]+(?:-[a-z0-9]+)*$, maks. 128 znaków, SmartBlog maks. 45.
6. Przekierowania z dowolnego starego adresu (do naprawy 404): ps_list_redirects je wyświetla, ps_manage_redirects je dodaje (301 albo 302), wyłącza i włącza; bez usuwania, cofanie przez historię zmian; źródło musi zwracać 404/410, cel 200 w domenie sklepu, bez łańcuchów i pętli (4.5).

5.8 SQL w obszarze Serwis (src/Server/)

• ps_db_query (odczyt bez przełącznika): SELECT, SHOW, DESCRIBE, EXPLAIN w transakcji READ ONLY, maks. 200 wierszy, e-maile, telefony i adresy IP maskowane.
• ps_db_execute (przełącznik Serwis): jedno polecenie INSERT, UPDATE, DELETE albo REPLACE. UPDATE/DELETE jednej tabeli: najpierw kopia pasujących wierszy (maks. 1000), cofnięcie = REPLACE tych wierszy; bez WHERE tylko z all_rows=true. INSERT jednego wiersza z autoinkrementacją: cofnięcie = usunięcie. Wykonanie w transakcji; więcej zmienionych wierszy niż zadeklarowano (max_rows) = ROLLBACK. DDL (ALTER, CREATE, DROP, TRUNCATE) tylko z allow_ddl=true: bez kopii, bez cofania, wyraźne ostrzeżenie w podglądzie.
• SqlGuard: jedno polecenie, bez komentarzy ukrywających treść; tabele zawsze niedostępne (Blocklist::NO_ACCESS_TABLES): employee*, access, module_access, profile*, configuration*, webservice_*, api_client, api_access, authorized_application, authorization_role, customer_session, admin_filter i tabele konektora; tabele nigdy niezapisywalne (Blocklist::NO_WRITE_TABLES): podatki, powiązania modułów płatności, zamówienia i ich szczegóły, statusy, płatności, faktury, noty i zwroty; zablokowane operacje na plikach i użytkownikach MySQL. Tabele z danymi osobowymi (6.5) tylko na poziomie pseudo (z maskowaniem) albo full.
• Uczciwie: filtr opiera się na wzorcach i chroni przed pomyłką, nie przed celowym obejściem. Obszar Serwis to pełne zaufanie, dlatego przełącznik działa 3 godziny, przed jego włączeniem powstaje kopia bazy, a właściciel dostaje alarm.
• Nie ma narzędzia do uruchamiania dowolnego kodu PHP. Pliki PHP można zapisywać (pliki modułów z przełącznikiem Moduły, pliki sklepu z przełącznikiem Serwis) po sprawdzeniu składni.

6. Zabezpieczenia

6.1 Pracownik konektora i uprawnienia

Krok 1 karty Start („Utwórz adres konektora”) zakłada profil „Claude TellMyShop” i nieaktywnego pracownika „Claude TellMyShop” (nikt się na niego nie zaloguje), gdy ich nie ma, i od razu go wybiera (src/Admin/EmployeeSetup.php). Od 2.7.0 profil dostaje od razu uprawnienia panelu do wszystkich obszarów; o tym, co się zapisuje, decydują przełączniki. ExecutionContext::requirePermissions sprawdza zakładki i akcje panelu per narzędzie. Uprawnienia konfiguracji i odinstalowania modułów idą za przełącznikiem Moduły. SuperAdmin jest odrzucany. Wpisy w dzienniku są przypisane do tego pracownika, więc ps_get_logs(employee_only=true) pokazuje, co zrobił asystent. Odinstalowanie usuwa pracownika i profil utworzone przez moduł.

6.2 Limity

• Do zmiany, na godzinę: 300 wywołań, 150 zapisów, 20 zapisów plików (pliki motywu, modułów i sklepu).
• Limity operacji zbiorczych: pkt 11.1.

6.3 Zabezpieczenia handlu

• Zapis każdej zmiany z obszaru Handel wymaga przełącznika Handel (działa do wyłączenia; włączenie wymaga zaznaczonego potwierdzenia i jest logowane z nazwiskiem pracownika).
• ps_update_prices: cena 0 odrzucana; zmiana powyżej 30% wymaga allow_big_change.
• ps_manage_specific_prices, ps_manage_catalog_price_rules: ostrzeżenie powyżej 50% rabatu; powyżej 90% wymagane allow_big_change; brak daty końca daje ostrzeżenie. Podgląd reguły katalogowej pokazuje liczbę produktów i przykładowe ceny.
• ps_manage_cart_rules: nowe kody nieaktywne; brak akcji usuwania; reguła bez kodu wymaga auto_apply.
• ps_update_stock: maks. 100 pozycji; zapis ruchu magazynowego.
• ps_update_shipping: tylko istniejący przewoźnicy i przedziały.
• Podatki, metody płatności i statusy zamówień nigdy nie są zmieniane (4.4).
• Kwoty w podglądach są w walucie domyślnej sklepu (Text::money()). Wewnętrzna wersja 2.5.1 pokazywała „zł” w podglądzie ceny sklepów z inną walutą.

6.4 Zabezpieczenia motywu, modułów i plików

• Kontrola Smarty przed zapisem: biała lista znaczników i modyfikatorów, potem próbna kompilacja. {php}, {include_php} i statyczne wywołania klas są odrzucane.
• Sprawdzenie składni JSON; ostrzeżenia o nowych <script> i domenach zewnętrznych.
• Nadpisania w motywie (ps_override_module_template) mają pierwszeństwo przed edycją plików modułu; zmiany w plikach modułu znikają przy jego aktualizacji i narzędzie to mówi.
• ps_uninstall_module wymaga powtórzenia nazwy modułu w confirm_name; opis kieruje najpierw do wyłączenia.
• Strefy plików: bez .., realpath() w obrębie strefy, dowiązania poza strefę odrzucane, lista zakazów (6.5), sam moduł nigdy do zapisu.
• Motyw, Moduły i Serwis wyłączają się same po 24, 24 i 3 godzinach, a ich włączenie wymaga kopii bazy (4.1).
• Klucz awaryjny przed włączeniem Modułów albo Serwisu (6.8).

6.5 Dane klientów (src/Privacy/PersonalData.php)

• Rozpoznawanie. Stała lista KNOWN_TABLES (customer, address, guest, connections, orders i order_*, message, cart, newsletter i zapisy e-mail, powiadomienia o dostępności, dziennik maili, referrer cache, psgdpr, wishlist, opinie o produktach…) plus każda tabela z kolumną pasującą do wzorców e-mail, imię/nazwisko, telefon, adres, kod pocztowy, IP, data urodzenia, PESEL/NIP albo sekret, odczytana z information_schema, także w tabelach modułów innych firm. Tabele firmowe (contact, store, supplier, manufacturer, warehouse, shop, carrier) wyłączone.
• Maskowanie (PersonalData::mask()). E-mail, telefon, adres i numery identyfikacyjne → pseudonim Klient-xxxxxx, ten sam przez jeden dzień (klucz pseudonimów zmienia się codziennie); imię i nazwisko → inicjały i pseudonim (J*** K*** (Klient-xxxxxx)); IPv4 → a.b.*.*, IPv6 → IPv6 ***, IP zapisane jako liczba → ***; data urodzenia → rok; sekrety → ***. W wolnym tekście (logi, wiadomości, pliki): e-maile j***@g***.com, telefony → 3 ostatnie cyfry, adresy IP oraz tokeny i klucze w postaci klucz=wartość i Bearer. W obsłudze klienta klient wątku to „Klient #ID” albo inicjały.
• Stałe pseudonimy. HMAC-SHA256 z kluczem dziennym (HMAC daty z 32-bajtowym kluczem głównym w var/tellmyshop/keys/pseudonym.key): ta sama wartość ma to samo oznaczenie w ciągu doby, a następnego dnia inne, więc zestawień z różnych dni nie da się połączyć. Bez klucza wartość zmienia się w ***, nigdy nie jest jawna.
• Pliki. Zawsze zablokowane (Files\Zone::DENY = Blocklist::NO_ACCESS_FILES, plus wzorzec): app/config/parameters.php|yml, config/settings*.inc.php, .env*, .htpasswd, *.key|pem|p12|crt|sql|gz|zip|tar|…|dump|bak, .git, .svn, var/logs, app/logs, log, logs, upload, download, katalog prywatny, kopie, moduł i jego skrypt awaryjny.
• Szyfrowanie. Pkt 6.9.
• psgdpr. actionDeleteGDPRCustomer usuwa klienta z zaszyfrowanej historii; actionExportGDPRData wymienia operacje konektora dotyczące klienta, bez wartości.
• Obowiązki właściciela. Panel mówi wprost, że podstawa prawna, polityka prywatności, rejestr czynności, umowa powierzenia z dostawcą czatu i przekazywanie danych poza EOG należą do właściciela sklepu; daje teksty pomocnicze do sprawdzenia przez prawnika.
• Nie piszemy „zgodny z RODO”. Dane pseudonimizowane to nadal dane osobowe (motyw 26 RODO); administratorem pozostaje sklep.
• Luki znalezione w wewnętrznej wersji 2.5.1, poprawione w 2.6.0 i nadal obecne w kodzie 2.7.2: (1) ps_list_changes zawsze maskuje dane klientów (5.4); (2) ps_db_query maskuje IP w każdym formacie, także zapisane jako liczby, a przy pseudo dopuszcza kolumnę osobową tylko na liście wyników, nigdy w WHERE, JOIN, ORDER BY ani GROUP BY, odrzuca podzapytania i zmienne i ukrywa szczegóły błędów MySQL; (3) ps_get_logs pokazuje pracowników jako konektor albo pracownik #ID, maskuje e-maile, telefony, IP i tokeny i odrzuca szukanie po e-mailu, IP albo telefonie; (4) stałe pseudonimy (wyżej); (5) dziennik audytu (tabela tellmyshop_audit): kto i kiedy zmienił pełny dostęp do danych, przełączniki, stan konektora i licencję; nie da się go wyczyścić z panelu, a eksport to przycisk Pobierz dziennik audytu (CSV) w karcie Dane klientów (RODO); (6) odinstalowanie domyślnie zostawia historię, kopie plików, przekierowania, dziennik audytu i licencję (KEEP_ON_UNINSTALL = 1); (7) pełny dostęp wymaga aktywnej licencji i paczki Pro (PersonalData::fullBlockedReason()), celu z co najmniej 10 znaków i potwierdzenia, a karta mówi, że dane czytane przez asystenta trafiają do dostawcy czatu na jego warunkach (umowa powierzenia, przekazanie poza EOG); pełny dostęp kończy się też sam, gdy przestaje być dozwolony. Historia zmian jest usuwana po 180 dniach (HISTORY_RETENTION, 30–730).

6.6 Polecenia ukryte w danych

Dane sklepu (opisy, treści CMS, logi, nazwy plików, wpisy bloga, wiadomości klientów, wiersze bazy) są traktowane jako treść. Instrukcje serwera i opisy narzędzi każą asystentowi nie wykonywać poleceń znalezionych w danych, a wyniki narzędzi zwracających treść sklepu kończą się tym samym przypomnieniem (Endpoint::CONTENT_TOOLS). Każdy zapis i tak wymaga zgody właściciela.

6.7 Strony prawne

ps_update_cms_page przypomina asystentowi, że regulamin, polityka prywatności i zwroty to teksty prawne, zmieniane tylko na wyraźną prośbę.

6.8 Alarmy, integralność i klucz awaryjny

• Alarmy (Alerts): e-mail + wpis w dzienniku połączeń ze statusem ALERT. Zdarzenia z panelu: dane klientów pseudo/full, włączenie przełącznika (Handel, Motyw, Moduły, Serwis), wyczyszczenie listy IP, wyłączenie alarmów. Zdarzenia konektora: seria zapisów (20 operacji w 10 minut), blokada IP, naruszenie integralności; te najwyżej raz na 15 minut na zdarzenie. Odbiorca ALERT_EMAIL albo PS_SHOP_EMAIL; język pracownika, który ostatnio zapisał ustawienia (przy instalacji: język domyślny sklepu, jeśli to polski, w innym wypadku angielski); wolny tekst w alarmach jest maskowany.
• Podsumowanie dzienne: raz na 24 h, gdy coś się działo: wywołania, operacje zapisu per narzędzie, alarmy.
• Integralność (Integrity): integrity.json z SHA-256 każdego pliku, zapisywany przy budowie paczki; wykrywa zmienione, usunięte i dopisane pliki PHP; sprawdzany przy każdym wejściu do panelu i najwyżej co 6 h przez konektor; zmiana stanu na „naruszona” wywołuje alarm.
• Klucz awaryjny (RescueKey): widoczny raz, skrót SHA-256 w katalogu prywatnym; skrypt rescue/rescue.php.txt kopiowany do katalogu głównego sklepu pod losową nazwą (PrestaShop blokuje bezpośrednie wywołania PHP w modules/). Działa bez uruchamiania PrestaShop: przywraca pliki zmienione przez konektor, wyłącza obszar Serwis; zmian w bazie nie cofa (do tego służą kopie bazy z pkt 5.6). Usuwany przy odinstalowaniu. Nie ma go w TellMyShop Free.

6.9 Szyfrowanie (src/Security/Crypto.php)

libsodium secretbox (XSalsa20-Poly1305). Klucz 32 B w var/tellmyshop/keys/history.key, poza bazą danych. Format enc:v1: + base64(nonce + szyfrogram). Szyfrowane: historia zmian wierszy bazy, nagrane wiersze, ustawienia PrestaShop i modułów, wątki i wiadomości klientów, warunki reguł koszyka, wszystkie kopie plików i wszystkie kopie bazy. Gdy klucza nie da się utworzyć, nic nie jest zapisywane jawnie. Utrata klucza = zaszyfrowanych zmian nie da się cofnąć, a kopii bazy odczytać. Chroni przed wyciekiem samej bazy, nie przed przejęciem całego serwera.

7. Integracja licencji

7.1 Zasady (handlowe)

7.2 Wdrożenie w 2.7.2

8. Języki i multistore

8.1 Języki

• Narzędzia odczytu przyjmują lang (kod ISO). Bez niego listy używają języka domyślnego, a narzędzia „get” zwracają wszystkie aktywne języki.
• Narzędzia zapisu zapisują jeden język na wywołanie; lang jest wymagany, gdy sklep ma więcej niż jeden aktywny język. ps_create_product i ps_create_cms_page przy tworzeniu wypełniają wszystkie języki; tłumaczenia dochodzą narzędziami aktualizacji.
• Slugi są per język; ps_change_url zmienia jeden język.
• Panel: pl, en, de, fr, es, it. Teksty dla modelu: angielski (2.3); asystent odpowiada w języku właściciela.

8.2 Multistore

• Większość narzędzi przyjmuje shop_id; ObjectWriter wczytuje obiekty z id_shop_list.
• Ustawienia modułu są globalne (getGlobalValue): jeden token, jeden zestaw przełączników i limitów dla wszystkich sklepów. Instalacja działa w CONTEXT_ALL.
• Kontekst sklepu i trasy per sklep nie są sprawdzone. Dokumentacja mówi, że multistore nie jest obsługiwane.

9. Logi

10. Kody błędów

2.7.2 nie ma własnych tekstowych kodów błędów. Błędy mają dwie postacie (src/Mcp/Core.php, src/Endpoint.php). Od 2.7.2 komunikaty są po angielsku; asystent tłumaczy je właścicielowi w jego języku. Sekrety (tokeny, klucze) są wycinane z każdego komunikatu (mcp_redact()).

1. Odrzucone żądanie (błąd JSON-RPC). Ustawiony jest status HTTP, a treść to {"jsonrpc": "2.0", "id": …, "error": {"code": …, "message": "…"}}, z data tam, gdzie zaznaczono. Odmowy z Endpoint::deny() nie mają id i trafiają do dziennika połączeń.

2. Błąd narzędzia (wynik MCP z isError: true). Samo wywołanie się udaje; wynik to {"content": [{"type": "text", "text": "Error: …"}], "isError": true}. Asystent czyta tekst i może poprawić wywołanie. Każdy błąd narzędzia trafia do dziennika połączeń ze statusem ERR.

11. Wymagania niefunkcjonalne

11.1 Limity narzędzi

Limity narzędzi bloga i ps_list_carriers: zobacz tools.json.

11.2 Czas i wydajność

• Wywołania licencji: krótkie limity czasu (odświeżanie w tle 3 s), nigdy nie blokują narzędzia.
• ps_inspect_page, kontrola adresów po zmianie i pobieranie zdjęć/ZIP używają limitów HttpProbe / ImageFetcher.
• Rozpoznawanie tabel osobowych raz na żądanie HTTP (cache).
• Limit czasu: set_time_limit(120) na żądanie (mcp_run()), więc wywołanie może trwać do 120 sekund, jeśli hosting na to pozwala.
• Kopie bazy są zapisywane w częściach (około 15 sekund na kliknięcie w panelu, wznawiane przy kolejnych żądaniach); kopia niedokończona przez 6 godzin zaczyna się od nowa.
• Bez częściowego sukcesu: każdy błąd znaleziony przy budowie podglądu zatrzymuje całe wywołanie z listą problemów (WriteFlow), więc nic się nie zapisuje, dopóki wszystkie pozycje nie przejdą. Część narzędzi pomija pozycje, które nie wymagają zmiany, z ostrzeżeniem w podglądzie.

11.3 Formaty

• UTF-8. Daty RRRR-MM-DD (strefa sklepu). Kwoty w walucie sklepu z oznaczeniem netto/brutto.
• Identyfikatory produktu: id:123, ref:ABC-1, ean:5901234123457, adres w sklepie, samo ID (1-7 cyfr), EAN (8/12/13 cyfr) albo indeks.

11.4 Zgodność, aktualizacja i odinstalowanie

• PrestaShop 8.1+ i 9.x, PHP 8.1+ (PrestaShop 1.7.8: osobna paczka PHP 7.4). Bez PrestaShop Account. Bez zmian w plikach rdzenia i bez nadpisań klas.
• Aktualizacja zachowuje historię, kopie plików, token, przełączniki i licencję. Settings::installDefaults() dodaje tylko brakujące ustawienia z wartościami domyślnymi. Skrypty aktualizacji w upgrade/: upgrade-2.6.5.php wyłącza statystyki uruchomienia u wszystkich (od tej pory tylko za zgodą); upgrade-2.7.0.php przenosi na model obszarów: jeśli był włączony tryb tylko do odczytu, wszystkie przełączniki zostają wyłączone; w przeciwnym razie Handel zostaje włączony, włączone wcześniej Motyw i Moduły dostają świeże 24 h, a Serwis najwyżej 3 h; limity godzinowe rosną do co najmniej 300 wywołań i 150 zapisów; konektor serwisowy, lista grup i tryb tylko do odczytu są usuwane (Settings::LEGACY_KEYS); profil konektora dostaje uprawnienia wszystkich obszarów; panel pokazuje jednorazową informację.
• Odinstalowanie (tellmyshop.php, sql/uninstall.php): zawsze usuwa pracownika i profil utworzone przez moduł, skrypt awaryjny i jego klucz, wszystkie kopie bazy, pobraną wiedzę Konsultanta, token konektora, klucz podpisu i ustawienie pracownika oraz tabele tellmyshop_log i tellmyshop_token_used. Przy włączonym KEEP_ON_UNINSTALL (domyślnie) reszta zostaje: tabele tellmyshop_change, tellmyshop_backup, tellmyshop_redirect, tellmyshop_audit, katalog prywatny var/tellmyshop/ z kluczami i pozostałe ustawienia, w tym licencja. Przy wyłączonym usuwane jest także to wszystko. Zatwierdzone zmiany zostają w sklepie.
• Z wewnętrznych wersji claudemcp na tellmyshop (2.6.0 i nowsze) nie ma aktualizacji w miejscu ani migracji danych (inna nazwa techniczna; kod niczego nie czyta z claudemcp): trzeba odinstalować stary moduł i zainstalować tellmyshop.

12. Znane problemy w 2.5.1 (historia)

Problemy znalezione w wewnętrznej wersji 2.5.1 w testach na PrestaShop 9.0.0 (PHP 8.4), 2026-10-05. Ostatnia kolumna mówi, co z nimi zrobił kod 2.6.0; późniejsze zmiany są w nawiasach.

Potwierdzone na 9.0.0 z 2.5.1: instalacja, utworzenie konta Claude, wygenerowanie adresu i połączenie; wszystkie 17 narzędzi odczytu widocznych po instalacji; zapis w dwóch krokach dla opisu produktu i ceny. 2.6.0: kod sprawdzony, test zapisu i cofnięcia zaliczony na PrestaShop 9.2.0 (sklep testowy), 2026-10-05. 2.7.2: tools/list sprawdzone na PrestaShop 8.1.7 i 8.2.3, test zapisu i cofnięcia z nagrywaniem wierszy zaliczony na 8.2.3 (sklepy testowe), 2026-10-10.

13. Plan rozwoju

Poza 2.7.2. Nigdy nie opisujemy jako dostępnego.

14. Pytania rozstrzygnięte w 2.6.0 i 2.7.2

Pytania otwarte do paczki 2.6.0 rozstrzygnięto na podstawie kodu 2.6.0 (2026-10-05); odpowiedzi poniżej są zaktualizowane do kodu 2.7.2 (2026-10-11). Wcześniej rozstrzygnięte przez kod 2.5.1: transport i wersje protokołu, Origin bez nagłówka, domyślna lista IP (pusta), czas blokady (okno 10 minut), limity do zmiany, wymiana tokenu (od razu), przełącznik danych klientów (trzy poziomy), retencja historii, retencja kopii.

1. Etykiety panelu: w 6 językach w i18n/ (pl, en, de, fr, es, it); nazwy kart w pkt 4.6.
2. Lista narzędzi: 71 narzędzi w 2.7.2 (67 w 2.6.0, 69 od 2.6.11, 71 od 2.7.0), bez zmian nazw; parametry każdego narzędzia sprawdzone z tools/list 2.7.2 (params_status: "code_2.7.2" w tools.json).
3. Gotowe zadania: src/Jobs/JobRegistry.php, sześć grup, jako prompty MCP i przez ps_get_ready_job; karty w panelu w 6 językach, scenariusze dla modelu od 2.7.2 po angielsku.
4. Bramka licencji: wpięta w src/Endpoint.php; bez trybu full narzędzia zapisu są ukryte; klucz publiczny k1; odinstalowanie nie zwalnia domeny.
5. TellMyShop Free: nie wymaga klucza (Edition::usesLicense() zwraca false dla darmowej paczki).
6. Dane klientów: wszystkie 7 poprawek jest w kodzie (6.5); stałe pseudonimy to HMAC z kluczem dziennym; historia jest usuwana po 180 dniach.
7. Katalog i klucz: var/tellmyshop/; klucz szyfrowania var/tellmyshop/keys/history.key; kopie bazy w var/tellmyshop/db-backups/.
8. Tabele i ustawienia: tellmyshop_log, tellmyshop_change, tellmyshop_backup, tellmyshop_token_used, tellmyshop_redirect, tellmyshop_audit (sql/install.php); prefiks ustawień TELLMYSHOP_.
9. Pracownik i profil: pracownik „Claude TellMyShop”, profil „Claude TellMyShop” (src/Admin/EmployeeSetup.php).
10. Kody błędów i format: pkt 10.
11. Limit czasu i częściowy sukces: pkt 11.2.
12. Nieodwracalne: Reverter::NOT_REVERTABLE w src/Write/Reverter.php (pkt 5.5).
13. Liczniki użycia: statystyki uruchomienia są w kodzie (src/License/Usage.php); od 2.6.5 są wysyłane dopiero po włączeniu przez właściciela w Ustawieniach (pkt 2.6).
14. ChatGPT: ten sam konektor działa w ChatGPT (własny konektor w trybie dewelopera); od 2.7.2 jego adresy Origin są akceptowane.

Nadal otwarte (kod na to nie odpowie):

1. Pełna lista testów PrestaShop/PHP: 2.7.2 jest przetestowane na PrestaShop 8.1.7 i 8.2.3 (PHP 8.1) oraz na paczce 1.7.8. Jeszcze nie testowane z 2.7.2: PrestaShop 9.x; PHP 8.2–8.4.
2. Jak gotowe zadania (prompty MCP) wyglądają w aplikacjach Claude na telefon.

---

PrestaShop jest zastrzeżonym znakiem towarowym PrestaShop SA. Claude jest znakiem towarowym Anthropic. ChatGPT jest znakiem towarowym OpenAI. TellMyShop nie jest powiązany z żadną z tych firm.