Przejdź do głównej zawartości

Klienci (customers)

Logika biznesowa cyklu życia klienta, zbudowana na module danych customer_accounts. Każdy klient należy do organizacji — firmowej w przypadku B2B albo jednoosobowej organizacji osobistej w przypadku osoby fizycznej — a customer_accounts.organization_id ma ograniczenie NOT NULL. „Samodzielny” oznacza w tym dokumencie poza organizacją firmową, a nigdy bez organizacji: taki klient jest osobnym tenantem, a funkcje związane z organizacją, które oferuje firma (zaproszenia, limit kredytowy, przypisanie handlowca), po prostu w jego przypadku nie występują, zamiast być wyłączane jako przypadek szczególny.

Możliwości​

Storefront (samoobsługa)

  • Samodzielna rejestracja, dostępna zależnie od ustawienia customers.allow_registration_without_organization w danym kanale sprzedaży: obowiązuje wartość ustawiona dla kanału, do którego należy żądanie, a w jej braku wartość dla wszystkich kanałów. Po udanej rejestracji konto i jego organizacja osobista są zapisywane w jednej transakcji, a nowe konto jest automatycznie logowane. Gdy ustawienie jest wyłączone, strona /register-customer w sklepie zamiast formularza pokazuje komunikat z linkiem do rejestracji organizacji, więc odwiedzający nie wypełnia formularza, który zostałby odrzucony.
  • Pierwsze logowanie przez zewnętrznego dostawcę tożsamości (np. Google) zakłada konto według tego samego ustawienia, odczytanego dla kanału sprzedaży, w którym logowanie rozpoczęto. Gdy w tym kanale ustawienie jest wyłączone, konto nie powstaje, a odwiedzający wraca na stronę logowania z prośbą o wcześniejsze założenie konta.
  • Jedna książka adresowa dla każdego klienta: książka jego organizacji. Klient indywidualny widzi ją jako Moje adresy (/addresses), członek firmy jako Adresy organizacji (/organization/addresses). Kasa proponuje adresy z tej samej książki i do niej zapisuje nowe. Obsługuje ją moduł organizations na bazie addresses, nie ten moduł, więc działa także wtedy, gdy ten moduł jest wyłączony.
  • Domyślna metoda płatności i metoda dostawy. Adresy domyślne są odczytywane z książki organizacji, w której się je ustawia.
  • Zmiana hasła; historia własnych zamówień i zapytań ofertowych tylko do odczytu.
  • Język wiadomości e-mail. Strona konta (/account) pokazuje, pod Weryfikacją dwuetapową, język, w którym piszemy e-maile do klienta — jako listę języków sklepu nazwanych we własnym języku, z przyciskiem Zapisz. Konto samo zapisuje język przy utworzeniu oraz, jeśli jeszcze go nie ma, przy następnym logowaniu (zob. customer_accounts); tutaj klient go zmienia i tylko to go zastępuje. Język, którego sklep nie oferuje, jest odrzucany (422 PREFERRED_LANGUAGE_NOT_OFFERED). Jeśli zapisanego języka sklep już nie oferuje, strona o tym informuje i wstępnie wybiera język, w którym wysyłamy e-maile. W sklepie z jednym językiem, a także gdy ten moduł jest wyłączony, wiersz tylko podaje język i nie oferuje wyboru.

Panel administracyjny (nadzór)

  • Lista klientów (wyszukiwanie oraz filtry statusu, organizacji i grupy) i widok szczegółów z datą utworzenia, grupą klientów, organizacją, stanem blokady, ostatnim logowaniem i językiem wiadomości e-mail klienta — tylko do odczytu, a gdy konto go nie ma: Nie ustawiono — używany jest domyślny język sklepu. Widzą go pracownicy z customers:read; zmienić go może tylko klient.
  • Blokowanie i odblokowanie oraz usunięcie miękkie i przywrócenie, z uprawnieniami zależnymi od roli: administrator platformy może działać na każdym kliencie; poza nim uprawniony jest handlowiec przypisany do organizacji klienta. Organizacja osobista nigdy nie ma przypisanego handlowca, więc reguła dla nieprzypisanych organizacji sprawia, że samodzielnym klientem może zająć się dowolny handlowiec — na liście klientów, na ekranie klienta i przy każdym odczycie objętym izolacją, a nie tylko przy tych akcjach, bo reguła zasięgu jest jedna na wszystkich ekranach (zgłoszenie #305). Zabezpieczenie odmawia zablokowania, usunięcia lub odłączenia ostatniego aktywnego członka z rolą Administrator organizacji firmowej (409 ORG_OWNER_DEPLETION); zablokowani administratorzy się nie liczą. Nie dotyczy organizacji osobistej, której jedyny członek ma rolę Administrator: zablokowanie lub usunięcie takiego klienta jest dozwolone.
  • Logowanie jako klient; audytowane jako impersonation.start / impersonation.end. Odpowiedź podaje organizationRole klienta, a logowanie jako klient działa dokładnie z jego uprawnieniami w organizacji.
  • Reset hasła z poziomu panelu (e-mail z linkiem do ustawienia hasła).
  • Walidacja NIP/VAT (VIES, port Białej listy).
  • Przypisanie do organizacji i odłączenie od organizacji, które przenosi klienta do jego własnej organizacji osobistej, zamiast zostawiać go bez organizacji. Bezpośrednie przypisanie grupy klientów (zastępuje grupę organizacji przy wyznaczaniu cen i promocji).
  • Panele zamówień, zapytań ofertowych i koszyków (bieżących i porzuconych), tylko do odczytu.
  • Widok „klienci online” oparty na ostatniej aktywności sesji.

Jeden przycisk Zapisz na ekranie klienta. Ekran klienta (/customers/:id) ma jeden przycisk Zapisz w nagłówku (na wąskim ekranie zostaje pod ręką u dołu). Obejmuje pola niestandardowe klienta i panele dodawane przez inne moduły, każdy, gdy jego moduł jest włączony: domyślne ustawienia zamówień (Szybkie zamówienia) i nadpisanie negocjacji cen (Zapytania ofertowe). Żadne z nich nie zapisuje się już samo. Gdy jest coś do zapisania, przycisk pokazuje „Zapisz 2 zmiany”.

  • Najpierw wszystko jest sprawdzane; jeśli którakolwiek część zostanie odrzucona, nic nie jest zapisywane.
  • Najpierw zapisywane są pola niestandardowe. Jeśli zostaną odrzucone, żaden panel nie jest zapisywany, a powód widać przy polu.
  • Jeśli pola niestandardowe zostaną zapisane, a panel nie, podsumowanie pod nagłówkiem mówi, co zapisano, a czego nie („Zapisano: Klient. Nie zapisano: Domyślne ustawienia zamówień — powód”); kolejne Zapisz zapisuje tylko panel.
  • Gdy zmiana negocjacji cen czeka na zapis, panel ukrywa wiersz „Obowiązuje: …”, który opisuje zapisaną wartość; wraca on po zapisaniu zmiany.
  • Opuszczenie strony — link w inne miejsce panelu albo zamknięcie lub odświeżenie karty przeglądarki — z niezapisanymi zmianami wymaga potwierdzenia.

Zapisz widzi operator z customers:manage albo taki, który może zmienić któryś z paneli. Akcje (blokada / odblokowanie, reset hasła, reset weryfikacji dwuetapowej, logowanie jako klient, usunięcie / przywrócenie), przypisanie do organizacji i Grupa klientów nie są częścią zapisu: działają w chwili użycia, a każda z tych sekcji ma etykietę Działa od razu.

Usuwanie i anonimizacja​

Usunięcie to miękkie wyłączenie konta: logowanie jest odrzucane, konto ukryte, sesje unieważnione, a zamówienia, zapytania ofertowe i historia audytu zachowane. W konfigurowalnym okresie (customers.deletion_retention_days, domyślnie 365 dni) uprawniona osoba może przywrócić konto. Po jego upływie zadanie anonimizacji (AnonymizationSweepWorker) nieodwracalnie usuwa dane osobowe i przywrócenie nie jest już możliwe: od chwili upływu okresu przywrócenie kończy się odpowiedzią 409 CUSTOMER_RESTORE_WINDOW_ELAPSED, nawet jeśli zadanie nie dotarło jeszcze do tego konta. Konto traci adres e-mail, imię i nazwisko, hasło oraz wszystkie wartości pól niestandardowych. W przypadku klienta indywidualnego zadanie anonimizuje też jego organizację osobistą: czyści jej nazwę, adres rejestrowy, nazwę prawną, adresy e-mail do potwierdzeń zamówień i wszystkie wartości pól niestandardowych, a wszystkie jej zapisane adresy, także te, które klient wcześniej usunął, są czyszczone (-, bez telefonu, kraj zostaje) i miękko usuwane (usunięty adres zachowuje datę usunięcia), każdy z wpisem audytu address.anonymized. Dzieje się tak również wtedy, gdy operator usunął już tę organizację. Złożone zamówienia zachowują swoje kopie adresów. Wpisy audytu anonimizacji odnotowują, że dane usunięto, ale nie przechowują samych danych.

Usuwane są też uzasadnienia, które operatorzy zapisali o kliencie: powód zablokowania konta, a w przypadku klienta indywidualnego także powody zablokowania i odrzucenia jego organizacji osobistej. Organizacja firmowa zachowuje swoje powody. Sama blokada lub odrzucenie zostaje, więc ekrany klienta nadal pokazują status i jego datę, ale bez powodu. Wpisy audytu anonimizacji odnotowują jedynie, że powód istniał.

Wcześniejsza historia audytu dotycząca klienta również jest usuwana w miejscu. Obejmuje to wpis samej blokady wraz z powodem, zmiany profilu i zmiany adresów. Dotyczy to wpisów o koncie, a w przypadku klienta indywidualnego także o jego organizacji osobistej, adresach tej organizacji (w tym tych, które klient wcześniej usunął) oraz o jego wycofanych adresach osobistych. Każdy wpis zachowuje akcję, wykonawców, czas i obiekt, a każde zapisane pole zachowuje swoją nazwę. Imiona i nazwiska, adresy e-mail, adresy, dowolny tekst i każda wartość pola niestandardowego zmieniają się w [erased], co przeglądarka audytu pokazuje jako Usunięto. We wpisach, które klient zapisał sam, usuwane są też adres IP i identyfikator przeglądarki (user agent). Wpisy o innych rekordach, na przykład o zamówieniach klienta, zachowują własną historię. Każdy zanonimizowany klient otrzymuje jeden wpis audit.redacted, zapisany przez system, zawierający wyłącznie liczby i identyfikatory. Samą regułę opisuje dokumentacja modułu dziennika audytu, w sekcji Usuwanie danych przy anonimizacji. Historia jest usuwana przed samym kontem, więc konto uznaje się za zanonimizowane dopiero wtedy, gdy jego historia też została usunięta.

Zadanie usuwa też uzasadnienia, które operatorzy i osoby akceptujące podali, odrzucając koszyki tego konta; każdy koszyk zachowuje swój status. Co jest usuwane, a co zostaje, opisuje moduł koszyków (Przechowywanie historii zmian).

Zadanie czyści też zapis, który platforma prowadzi o każdym e-mailu wysłanym na adres tego konta. W każdym takim zapisie usuwane są adres, temat, kontekst wiadomości (który może zawierać powód odrzucenia) oraz treść błędu serwera pocztowego. Zapis zachowuje informację, który to był e-mail, kiedy próbowano go wysłać i czy został wysłany, więc operator nadal może sprawdzić, czy wiadomość wyszła. Każdy zmieniony zapis otrzymuje jeden wpis audytu email_delivery.anonymized, zapisany przez system, bez żadnych innych danych. Adres jest porównywany bez względu na wielkość liter. Zapisy e-maili wysłanych do konta zanonimizowanego przed tym wydaniem nie są objęte, bo adres takiego konta jest już usunięty.

Zadanie uruchamia się raz dziennie w procesie workera i tylko wtedy, gdy moduł jest włączony, więc konto zostaje zanonimizowane najpóźniej dzień po upływie okresu. Gdy moduł jest wyłączony, zadanie się nie uruchamia; konta, którym okres upłynął w tym czasie, anonimizuje pierwszy przebieg po ponownym włączeniu modułu. Przebieg najpierw sprawdza, czy jakieś konto czeka na anonimizację albo czy jakaś wcześniejsza anonimizacja pozostała do dokończenia; jeśli nie, nic nie robi i nie zapisuje wpisu audytu. Gdy tego nie da się sprawdzić, przebieg i tak się odbywa. Dwa nakładające się przebiegi anonimizują konto tylko raz.

Zadanie najpierw anonimizuje organizację osobistą i jej adresy, a konto na końcu. Jeśli przebieg zostanie przerwany, konto zostanie podjęte ponownie w następnym przebiegu, który dokończy brakujące kroki bez powtarzania wpisów audytu kroków już wykonanych. Konto, którego nie da się zanonimizować, nie wstrzymuje pozostałych: przebieg anonimizuje resztę, a następnie zgłasza identyfikatory kont, których nie udało się przetworzyć.

Tak samo jest, gdy zakres usuwanych danych się poszerza. Wszystko, co przebieg z wcześniejszej wersji pozostawił na zanonimizowanym koncie lub w jego organizacji osobistej, na przykład wartości pól niestandardowych, nazwę prawną, adresy e-mail do potwierdzeń zamówień albo powód zablokowania lub odrzucenia, usuwa następny przebieg, niezależnie od obecnego ustawienia okresu przechowywania. Ten przebieg zapisuje po jednym dodatkowym wpisie audytu dla każdego zmienionego rekordu, zachowuje pierwotną datę anonimizacji i nie ogłasza anonimizacji ponownie, więc to, co inne moduły robią przy anonimizacji, na przykład usuwanie zgłoszeń klienta przez moduł Formularze, nie jest wykonywane drugi raz.

Wycofanie osobistej książki adresowej​

Do pierwszego wydania tej zmiany moduł prowadził drugą, osobistą książkę adresową (customer_addresses). Na żaden jej adres nie dało się złożyć zamówienia. Zostaje wycofana dla wszystkich, w dwóch wydaniach:

  • Wydanie 1 (to). Każdy dawny punkt końcowy osobistej książki odpowiada 410 Gone z kodem CUSTOMER_ADDRESS_BOOK_RETIRED, po polsku lub po angielsku. Jednorazowe zadanie w tle, uruchamiane przez proces workera, gdy ten moduł jest włączony, przetwarza pozostałe wiersze:
    • wiersze klienta indywidualnego są przenoszone do książki jego organizacji osobistej. Adres, który już w niej jest, nie jest kopiowany drugi raz, a istniejący adres domyślny pozostaje domyślny. Każdy wiersz ma wpis audytu customer_address.merge;
    • każdy inny wiersz (członka firmy, klienta indywidualnego, którego organizacja osobista została już zanonimizowana, albo konta, którego organizacji nie da się znaleźć) jest usuwany: czyszczony, miękko usuwany i audytowany jako customer_address.erased;
    • wiersz, którego książka adresowa nie przyjmuje — na przykład z krajem, który nie jest już aktywny — zostaje, oznaczony powodem (customer_address.merge_refused). Widzi go tylko operator, na karcie Adresy klienta.
  • Wydanie 2. Tabela i pozostały kod są usuwane. Aktualizacja odmawia, dopóki zostaje choćby jeden wiersz.

Stronę operatora opisuje uwaga do aktualizacji Wycofanie osobistej książki adresowej (wydanie 1 z 2).

Gdy zadanie anonimizacji anonimizuje konto, w ten sam sposób czyści też każdy wiersz tego konta w tej książce, niezależnie od tego, czy wiersz został przeniesiony, usunięty przez zadanie, usunięty przez klienta czy odrzucony, z jednym wpisem audytu customer_address.anonymized na wiersz. Dotyczy to każdego konta, także członka firmy.

API publiczne​

Trasy administracyjne są chronione przez customers:read (odczyt), customers:manage (zmiany) i customers:impersonate (logowanie jako klient).

Metoda i ścieżkaKtoPrzeznaczenie
POST /api/v1/customers/registeranonimowySamodzielna rejestracja (zależna od ustawienia)
GET /api/v1/storefront/settings/customer-registrationanonimowyCzy samodzielna rejestracja jest dostępna (allowRegistrationWithoutOrganization)
GET /api/v1/me/customerklientWłasny profil z organizationRole, faktycznymi uprawnieniami permissions i preferredLanguage (null, dopóki nieznany)
PATCH /api/v1/me/customer/preferred-languageklientTreść { preferredLanguage }: język wiadomości e-mail klienta. Język oferowany przez kanał sprzedaży żądania, dopasowany bez względu na wielkość liter i zapisany tak, jak zapisuje go kanał; odpowiedź { data: { preferredLanguage } }. W przeciwnym razie 422 PREFERRED_LANGUAGE_NOT_OFFERED. Audytowane jako customer_account.set_preferred_language, bez języka
POST /api/v1/me/customer/change-passwordklientZmiana hasła. Udana zmiana wylogowuje konto ze wszystkich pozostałych sesji (sesja, z której wysłano żądanie, zostaje), unieważnia niewykorzystane tokeny resetu hasła i wycofuje każde rozpoczęte, a niedokończone logowanie.
GET/POST /api/v1/me/customer/addresses · PATCH/DELETE .../:id · PUT .../:id/defaultklientWycofane: 410 CUSTOMER_ADDRESS_BOOK_RETIRED. Używaj /api/v1/organizations/mine/addresses
GET /api/v1/me/customer/defaultsklientDomyślna metoda płatności i dostawy oraz adresy domyślne z książki organizacji
PUT /api/v1/me/customer/defaultsklientUstawienie domyślnej metody płatności i dostawy. Treść podająca billingAddressId lub shippingAddressId dostaje odpowiedź 410 CUSTOMER_ADDRESS_BOOK_RETIRED
GET /api/v1/me/customer/ordersklientWłasna historia zamówień
GET /api/v1/me/customer/quote-requestsklientWłasna historia zapytań ofertowych
GET /api/v1/admin/customersadministratorLista (ograniczona uprawnieniami)
GET /api/v1/admin/customers/:idadministratorSzczegóły
POST /api/v1/admin/customers/:id/block · /unblockadministratorBlokowanie / odblokowanie
DELETE /api/v1/admin/customers/:id · POST .../restoreadministratorUsunięcie miękkie / przywrócenie
POST /api/v1/admin/customers/:id/impersonateadministratorRozpoczęcie logowania jako klient
POST /api/v1/admin/customers/:id/password-resetadministratorE-mail z linkiem do ustawienia hasła
POST/DELETE /api/v1/admin/customers/:id/organizationadministratorPrzypisanie do organizacji / odłączenie
PUT /api/v1/admin/customers/:id/customer-groupadministratorUstawienie / usunięcie grupy klientów
PATCH /api/v1/admin/customers/:id/custom-fieldsadministratorScalenie wartości pól niestandardowych klienta (customers:manage); odrzucona wartość daje 422 CUSTOM_FIELD_VALUE_INVALID i nic nie zapisuje
GET /api/v1/admin/customers/:id/addressesadministratorTylko do odczytu: { organization, personal } — książka organizacji oraz wiersze osobistej książki, których zadanie nie przeniosło, każdy z mergeRefusal
POST /api/v1/admin/customers/:id/addressesadministratorWycofane: 410 CUSTOMER_ADDRESS_BOOK_RETIRED
POST /api/v1/admin/customers/:id/vat-validateadministratorWalidacja numeru NIP/VAT
GET /api/v1/admin/customers/:id/orders · /quote-requests · /cartsadministratorPanele historii tylko do odczytu
GET /api/v1/admin/customers/onlineadministratorKlienci obecnie online

Ustawienia​

KodTypWartość domyślnaPrzeznaczenie
customers.allow_registration_without_organizationbooleanfalseWłącza samodzielną rejestrację w danym kanale sprzedaży
customers.deletion_retention_daysnumber365Okres, w którym można przywrócić konto przed trwałą anonimizacją
customers.presence_freshness_minutesnumber10Próg uznania klienta za „online”

Schemat​

  • 20260611T140403_customer_accounts_lifecycle.ts (należy do customer_accounts) — dodaje do customer_accounts kolumny customer_group_id, stan blokady (blocked_at, block_reason, block_source, blocked_by_*) oraz stan usunięcia i anonimizacji (deletion_requested_by_admin_user_id, anonymized_at).
  • 20260611T140404_customers_customer_addresses_init.ts — tabela customer_addresses (jeden adres domyślny dla każdej pary (customer, kind)), czyli wycofana osobista książka adresowa.
  • 20261105T180317_customers_address_book_retirement.ts — kolumny pochodzenia, które zapisuje zadanie wycofania (merged_into_address_id, merged_at, merge_refusal), oraz indeks wierszy, które zadanie ma jeszcze przetworzyć. Wydanie 2 usuwa tabelę.

Domyślne preferencje płatności i dostawy korzystają z istniejącej tabeli quick_order_default_preferences; nowa tabela nie jest tworzona.

Wyszukiwanie globalne​

Wyszukiwanie globalne w panelu administracyjnym (paleta poleceń, ⌘K / Ctrl+K) znajduje klientów. Ten moduł udostępnia poniższe pola; to, które z nich są używane, wybiera się na ekranie konfiguracji wyszukiwania globalnego.

PolePrzeszukiwane domyślnie
E-mailtak
Imię i nazwiskotak

Wynik pokazuje imię i nazwisko, e-mail, organizację oraz informację, czy konto jest zablokowane, a jego wybranie otwiera klienta. Konta usunięte i zanonimizowane nie są znajdowane. Klienci pojawiają się dla roli z uprawnieniem customers:read, a przedstawiciel handlowy widzi tych klientów, których pokazuje mu lista klientów.