servicedesk/wiki/admin/README.md

Przewodnik — Administrator

Panel administratora (/admin) to jedno miejsce do konfiguracji całego systemu: struktura zgłoszeń (kategorie, pola, statusy, priorytety, SLA), automatyzacje (reguły SLA, wyzwalacze, automatyzacja AI zgłoszeń), użytkownicy i zespoły, treści (szablony, szybkie akcje, e-maile), wygląd/branding oraz integracje (LDAP, poczta SMTP/IMAP, BookStack, AI, API).

Domyślnie każde konto ląduje po zalogowaniu w panelu Klienta; przełącz się do panelu Administratora przez menu profilu (prawy górny róg).

Kategorie i pola dodatkowe

• Kategorie / podkategorie — nazwa + opis (widoczny klientowi przy wyborze). Podkategoria może mieć domyślny priorytet, nadawany automatycznie nowym zgłoszeniom w tej podkategorii.
• Pola dodatkowe (custom fields) — typ (tekst / tekst długi / lista wyboru / checkbox / data / liczba), czy wymagane, opcje (dla listy wyboru). Każde pole przypisuje się do jednej lub wielu podkategorii z określoną kolejnością wyświetlania — te pola pojawiają się klientowi w formularzu zgłoszenia i operatorowi w widoku zgłoszenia.

Użytkownicy

• Lista użytkowników z rolami (Klient / Operator / Administrator — konto może mieć więcej niż jedną). Rola nadaje dostęp do odpowiedniego panelu.
• Pola użytkownika — analogicznie do pól zgłoszenia, ale dla profilu użytkownika (np. Stanowisko, Dział, Firma, telefon) — mogą być mapowane na atrybut LDAP (ldap_attribute), żeby wypełniały się automatycznie przy synchronizacji z katalogiem.
• Synchronizuj z LDAP — ręczne wymuszenie ponownej synchronizacji kont z katalogu (poza standardowym sync-on-login).
• Konta lokalne (utworzone tu, z hasłem) logują się przez fallback e-mail + hasło lokalne, gdy dopasowanie po LDAP-owym atrybucie loginu się nie powiedzie — tak działa domyślne konto awaryjne admin@example.com.

Zespoły

Każdy zespół ma listę członków (operatorów) i listę podkategorii, za które odpowiada. Gdy w Konfiguracji włączone jest „automatyczne przypisywanie wg kategorii”, nowe zgłoszenie w danej podkategorii trafia od razu do właściwego zespołu. Operator spoza zespołu nie widzi jego kolejki (poza zgłoszeniami bez zespołu i przypisanymi mu bezpośrednio).

Statusy, priorytety i SLA

• Statusy mają trzy stałe etapy (stage): new, open, closed. Statusy „Nowe”, „Otwarty” i „Zamknięte” są zablokowane (locked) i nie można ich usunąć — pozostałe (W trakcie, Oczekuje na klienta, itd.) są w pełni edytowalne/usuwalne dowolnie w ramach etapu „open”. Każdy status ma nazwę, kolor i kolejność wyświetlania.
• Priorytety — nazwa, kolor, kolejność.
• SLA — dla każdego priorytetu: czas do pierwszej odpowiedzi (response_mins) i czas do rozwiązania (resolution_mins), w minutach. Priorytet z czasem rozwiązania = 0 nigdy nie jest liczony jako naruszenie SLA (np. priorytet „Brak”). Naruszenia sprawdza cykliczne zadanie co 15 minut (tickets:check-sla-breaches) i może powiadomić operatora.

Automatyzacja SLA

Reguły, które same zmieniają zgłoszenie po określonym czasie ciszy ze strony klienta (liczonym od ostatniej odpowiedzi klienta, a jeśli jeszcze nie odpowiedział — od utworzenia zgłoszenia). Każda reguła ma:

• Nazwę i przełącznik aktywna/nieaktywna.
• Próg w minutach.
• Opcjonalne zawężenie — priorytet / kategoria (podkategoria) / zespół; puste pole = dowolny. Wszystkie warunki muszą być spełnione naraz.
• Akcję — zmień priorytet / status / zespół / przypisanego operatora, oraz wartość docelową.

Reguły sprawdza cykliczne zadanie co 15 minut (automation:run-rules, razem z tickets:check-sla-breaches). Akcja korzysta z tych samych mechanizmów co ręczna zmiana przez operatora — dostaje wpis w historii zgłoszenia (z dopiskiem „Automatyzacja: nazwa reguły”), wysyła standardowe powiadomienie dla tej zmiany i pojawia się na żywo w kolejce/widoku zgłoszenia. Reguła nie powtarza się dla tego samego zgłoszenia, dopóki klient znów nie napisze albo zgłoszenie nie zostanie zamknięte i otwarte ponownie — więc bezpiecznie zostawić kilka aktywnych reguł naraz, bez ryzyka zapętlenia się co 15 minut.

Wyzwalacze

W odróżnieniu od Automatyzacji SLA (działa po czasie ciszy klienta), wyzwalacze reagują natychmiast na zdarzenie w zgłoszeniu: utworzenie, dowolna zmiana pola, zmiana statusu/priorytetu/przypisania/zespołu/kategorii, nowa wiadomość publiczna. Każdy wyzwalacz ma:

• Zdarzenie, na które reaguje.
• Warunki (opcjonalne, wszystkie muszą być spełnione naraz — ORAZ) na polu statusu, priorytetu, zespołu, podkategorii, zgłaszającego, tematu lub treści.
• Akcje wykonywane po kolei — ustaw status/priorytet/zespół/operatora, albo wyślij powiadomienie e-mail do zgłaszającego lub przypisanego operatora.

Akcja „Wyślij powiadomienie e-mail” korzysta z własnych szablonów wyzwalaczy (sekcja „Szablony e-mail wyzwalaczy” na tej samej zakładce) — w pełni dodawalnych/edytowalnych/usuwalnych przez administratora, celowo osobnych od stałych szablonów opisanych niżej (te są przypisane 1:1 do zdarzeń systemowych i nie da się ich usunąć ani dodać nowego). Wyzwalacz może zmienić to samo pole, które sam sprawdza w warunku — zabezpieczenie przed zapętleniem: akcja, która tylko potwierdzałaby już ustawioną wartość, nic nie robi, a licznik głębokości zatrzymuje prawdziwy cykl między dwoma wyzwalaczami.

Szybkie akcje odpowiedzi

Przyciski w widoku zgłoszenia operatora, które wysyłają odpowiedź i od razu zmieniają status (np. „Wyślij i zamknij”) — konfigurowalne: etykieta, docelowy status, kolejność. Status jest tu „miękkim” odniesieniem (po kluczu) — usunięcie statusu w Admin nie usuwa powiązanej z nim szybkiej akcji, po prostu przestaje zmieniać status.

Szablony odpowiedzi

Gotowe teksty (zwykły tekst, bez HTML — pole odpowiedzi w kolejce to zwykły <textarea>) do szybkiego wstawienia w odpowiedzi operatora, np. „Prośba o więcej informacji”, „Restart usuwa problem”.

Szablony e-mail i powiadomienia

• Szablony e-mail — treść HTML (nagłówki <p>, linki jako <a href="{link}">, itd. — nie zwykły tekst z \n, bo trafia bezpośrednio do maila jako markup) z placeholderami: {numer}, {imie}, {temat}, {status}, {kategoria}, {priorytet}, {zespol}, {operator}, {link}. Każdy szablon opakowuje się automatycznie we wspólny layout (nagłówek z nazwą firmy + stopka — patrz niżej). Te szablony są przypisane na stałe do zdarzeń systemowych (nie da się ich dodać/usunąć/przepiąć na inne zdarzenie) — dla wyzwalaczy (zakładka Wyzwalacze) służy osobny, w pełni dowolny zestaw szablonów, opisany wyżej.
• Stopka e-mail i layout HTML — stopka jest edytowalna (z przyciskiem „Resetuj” do wartości domyślnej); sam layout nie jest edytowalny z poziomu UI.
• Powiadomienia — lista zdarzeń (zgłoszenie utworzone, zmiana statusu/ kategorii/priorytetu/zespołu/przypisania, zgłoszenie zamknięte, operator odpowiedział, SLA przekroczone, nowe zgłoszenie w zespole) — każde ma przełącznik włącz/wyłącz, odbiorcę (klient / operator) i przypisany szablon. Usunięcie przypisanego szablonu po prostu wyłącza wysyłkę tego powiadomienia, dopóki ktoś nie wybierze nowego. „Zmiana statusu” i „zgłoszenie zamknięte” się wzajemnie wykluczają dla tej samej zmiany — zamknięcie zgłoszenia wysyła wyłącznie powiadomienie „zgłoszenie zamknięte”, żeby nie dublować maila. „Nowe zgłoszenie w zespole” (domyślnie włączone) trafia do każdego operatora w zespole, którego podkategorie pasują do nowego zgłoszenia, nie tylko do jednej przypisanej osoby. Ten sam przełącznik kontroluje zarówno e-mail, jak i powiadomienie w dzwoneczku w aplikacji — nie ma osobnego ustawienia dla powiadomień w apce, a dzwoneczek pokazuje tylko nieprzeczytane (znikają po kliknięciu/oznaczeniu) i aktualizuje się na żywo.
• Preferencje powiadomień per operator/admin (/settings/notifications, menu profilu → „Powiadomienia”) — każdy sam wybiera, dla nowego zgłoszenia/ aktualizacji/eskalacji, jaki zakres zgłoszeń (moje / nieprzypisane / obserwowane / wszystkie) ma go powiadamiać dzwoneczkiem i czy dodatkowo e-mailem, plus opcjonalne natywne powiadomienia push przeglądarki. To ustawienie jest niezależne od globalnego przełącznika powiadomień opisanego wyżej — dotyczy dodatkowego powiadamiania innych operatorów/adminów o zgłoszeniach w ich zakresie, nie zastępuje go.

Wygląd / Branding

Nazwa firmy, logo, favicon, kolor akcentu (motyw jasny/ciemny podąża za nim), oraz komunikat na stronie logowania (typ: informacja/ostrzeżenie/sukces/ ważne + treść HTML).

Konfiguracja

• Ogólne — domyślny status nowego zgłoszenia, automatyczne przypisywanie wg kategorii, limity załączników (rozmiar/liczba/typy), czas życia sesji, strefa czasowa.
  • Numeracja zgłoszeń — dowolny prefiks numeru (domyślnie #) i minimalna długość (dopełniana zerami z przodu, dotyczy tylko trybu sekwencyjnego). Checkbox „Ukryj kolejność zgłoszeń” przełącza wyświetlany numer z kolejnego (np. #1042) na stałą, losowo wyglądającą sumę kontrolną (np. #559122) przypisaną zgłoszeniu raz, na zawsze — tak, by po samym numerze nie dało się odgadnąć, ile jest zgłoszeń ani w jakiej kolejności powstały. Podgląd pod polami pokazuje na żywo, jak będzie wyglądał numer dla realnego zgłoszenia z bazy, zanim się zapisze zmiany. Gdy ta opcja jest włączona, linki do zgłoszeń też posługują się sumą kontrolną zamiast kolejnego numeru — stary link ze zwykłym numerem przestaje działać. REST API (/api/v1/...) tego nie dotyczy — tam zgłoszenia zawsze identyfikuje się po id, niezależnie od tego ustawienia.
• Częstotliwość odświeżania i harmonogramu — dwie grupy pól:
  • Odświeżanie w przeglądarce — co ile sekund odświeża się (poza aktualizacjami na żywo) widok zgłoszenia (klient i operator), lista zgłoszeń operatora, i dzwonek powiadomień.
  • Zadania w tle — co ile minut uruchamiają się sprawdzanie naruszeń SLA, reguły automatyzacji, pobieranie e-maili (IMAP) i automatyzacja AI zgłoszeń. Zmiana obowiązuje od najbliższego tyknięcia harmonogramu (co minutę), bez potrzeby restartu czy redeployu.

SMTP (host, port, szyfrowanie, użytkownik/hasło, adres/nazwa nadawcy, z przyciskiem „Testuj połączenie”) konfiguruje się w zakładce Poczta, razem z layoutem/stopką wiadomości i skrzynkami IMAP (patrz niżej).

Poczta — odbieranie zgłoszeń i odpowiedzi e-mailem (IMAP)

Zakładka Poczta (dawniej „E-MAIL") łączy konfigurację SMTP (wysyłka) ze skrzynkami IMAP (odbiór) — obie strony wymiany e-mailowej z klientem żyją razem, zamiast być rozrzucone po różnych zakładkach.

• Wiele skrzynek IMAP jednocześnie — np. zgloszenia-it@firma.pl i zgloszenia-hr@firma.pl jako dwie osobne, niezależnie włączane skrzynki, każda z własnym hostem/portem/szyfrowaniem/loginem/hasłem i folderem.
• Cel nowych zgłoszeń — jeden wspólny selektor pozwala wybrać albo konkretną podkategorię (trafi też do jej zespołu, tak jak zgłoszenie założone przez formularz web), albo całą kategorię bez wskazywania podkategorii (zgłoszenie zostaje nieprzypisane do zespołu, ale kategoria jest widoczna i można po niej filtrować kolejkę operatora), albo zostawić puste (zgłoszenie całkiem nieprzypisane).
• Dopasowywanie odpowiedzi — odpowiedź na powiadomienie e-mail (temat zawiera numer/sumę kontrolną zgłoszenia) trafia jako kolejna wiadomość do tego samego wątku, nie jako nowe zgłoszenie — widoczna na żywo u operatora, tak jak każda inna odpowiedź.
• Filtry przed śmieciowymi zgłoszeniami — automatyczne odpowiedzi (autorespondery, „poza biurem”, bounce/mailer-daemon) są rozpoznawane po nagłówkach (Auto-Submitted, Precedence) i typowych frazach w temacie (PL i EN) i odrzucane bez tworzenia zgłoszenia; dodatkowa lista zablokowanych nadawców per skrzynka (domyślnie mailer-daemon, postmaster, no-reply, noreply).
• „Tylko użytkownicy z LDAP” (Integracje → LDAP) działa identycznie dla poczty jak dla formularza gościa na stronie głównej — jeśli włączone, e-mail od nieznanego nadawcy (spoza LDAP i bez lokalnego konta) jest odrzucany, nie tworzy zgłoszenia.
• Folder po przetworzeniu / folder odrzuconych (opcjonalnie) — jeśli puste, wiadomość zostaje na miejscu tylko oznaczona jako przeczytana.
• Przycisk „Pobierz teraz” przy każdej skrzynce — ręczne, natychmiastowe sprawdzenie poczty bez czekania na harmonogram (co 5 minut), działa też dla wyłączonej skrzynki; pokazuje od razu liczbę nowych/odpowiedzi/odrzuconych/ błędów.
• Przycisk „Testuj połączenie” sprawdza niezapisane wartości formularza, bez zapisywania.
• Log — cała aktywność (połączenia, każda decyzja per wiadomość, błędy) trafia do osobnego pliku storage/logs/imap-*.log, niezależnie od ogólnego poziomu logowania aplikacji — najlepsze miejsce do sprawdzenia, dlaczego dany e-mail się nie przetworzył.
• Znacznik „e-mail" — zgłoszenie i pojedyncze wiadomości utworzone z poczty mają widoczną ikonę koperty w kolejce operatora i w widoku zgłoszenia, odróżniając je od zgłoszeń/odpowiedzi z formularza web.

Sprawdzanie skrzynek działa cyklicznie tylko wtedy, gdy na serwerze jest skonfigurowany zewnętrzny cron wywołujący php artisan schedule:run (patrz install.md) — bez tego działa wyłącznie przycisk „Pobierz teraz”.

Integracje

• LDAP — host, port, base DN, bind DN + hasło, SSL, filtr użytkownika ((uid={0}) domyślnie), auto-provisioning gości, ograniczenie tworzenia kont/zgłaszania tylko przez LDAP. Przycisk „Testuj połączenie” sprawdza bind bez zapisywania zmian.

  Po świeżej instalacji (migrate:fresh --seed) LDAP i SMTP zawierają przykładowe wartości (ldap.example.com, smtp.example.com, changeme-*-password) — koniecznie podmień je na rzeczywiste dane przed oddaniem systemu do użytku.

• Baza wiedzy BookStack — opcjonalna integracja, domyślnie wyłączona. Po włączeniu:

  • Adres instancji, Token ID, Token Secret — token API generuje się w BookStacku: Profil → Ustawienia API. Rola/użytkownik właściciela tokenu musi mieć w BookStacku uprawnienie „Access System API”, inaczej zapytania kończą się błędem 403 mimo poprawnych danych logowania.
  • Weryfikuj certyfikat SSL — włączone domyślnie; wyłącz tylko jeśli instancja BookStack korzysta z certyfikatu self-signed/prywatnego CA.
  • Przeszukuj — trzy niezależne checkboxy: Książki / Strony / Rozdziały (dowolna kombinacja).
  • Szukaj po — słowa kluczowe w nazwie / tagi / oba. Wyszukiwanie po tagach dopasowuje artykuły oznaczone w BookStacku tagiem o nazwie zgodnej z podkategorią zgłoszenia (np. tag „Drukarki i skanery”) — patrz automatyczne tagowanie niżej, żeby nie robić tego ręcznie dla całej wiki.
  • Dozwolone półki — dwie niezależne checklisty: jedna dla podpowiedzi przy tworzeniu zgłoszenia (klient, operator, formularz gościa na stronie głównej), druga dla panelu bocznego operatora na widoku istniejącego zgłoszenia. Dopóki żadna półka nie jest zaznaczona w danej liście, wyszukiwanie w tym kontekście nic nie zwraca — trzeba świadomie wskazać, które półki wolno przeszukiwać. Przycisk „Odśwież listę półek” wymusza ponowne pobranie listy z BookStacka (inaczej może się odświeżyć samoistnie po do 30 minutach po zmianie w BookStacku).
  • Pokazuj podpowiedzi także niezalogowanym — domyślnie wyłączone; bez zaznaczenia podpowiedzi przy tworzeniu zgłoszenia widzą tylko zalogowani klienci/operatorzy, nie formularz gościa na stronie głównej.
  • Przycisk „Testuj połączenie” sprawdza niezapisane wartości formularza (analogicznie do LDAP/SMTP) i pokazuje dokładny komunikat błędu z BookStacka, jeśli połączenie się nie powiedzie.
  • Automatyczne tagowanie treści (AI) — przyciski „Otaguj nową treść” (pomija już otagowane pozycje) i „Otaguj wszystko ponownie” (klasyfikuje od nowa całą wiki) używają integracji AI (niżej) do otagowania każdej książki/strony/rozdziału nazwami pasujących podkategorii helpdesku — bez tego wyszukiwanie „po tagach” wyżej nic nie znajdzie. Wymaga wcześniej skonfigurowanej i włączonej integracji AI. Dostępne też z linii poleceń: php artisan bookstack:tag-content (--dry-run, --force, --limit=N).

• Integracja AI — opcjonalna, domyślnie wyłączona, ogólne połączenie z dostawcą modelu językowego (nie tylko dla BookStacka — patrz „Automatyzacja AI dla zgłoszeń” niżej). Pola: adres API (dowolny dostawca kompatybilny z OpenAI — np. Groq, OpenAI, lokalny Ollama), klucz API (opcjonalny — zostaw puste dla lokalnych instancji bez autoryzacji), model, weryfikacja SSL (wyłącz tylko dla instancji z certyfikatem self-signed, np. lokalny Ollama). Przycisk „Testuj połączenie” jak przy pozostałych integracjach.

• Automatyzacja AI dla zgłoszeń — wymaga włączonej integracji AI powyżej. Zgłoszenia przetwarzane są w tle, cyklicznie (ai:run-ticket-automation, interwał konfigurowalny w Konfiguracji) — nie synchronicznie przy składaniu zgłoszenia, więc nie spowalnia to klienta.

  • Automatyczna kategoryzacja — pięć niezależnych przełączników: przypisz kategorię/podkategorię, gdy zgłoszenie nie ma żadnej; dobierz podkategorię, gdy ma tylko kategorię; zweryfikuj i ewentualnie popraw już przypisaną podkategorię; popraw temat zgłoszenia, jeśli jest niejasny; ustaw priorytet na podstawie treści. Każde zgłoszenie jest sprawdzane tylko raz — zmiany trafiają do historii zgłoszenia z adnotacją „Automatyzacja: klasyfikacja AI” (patrz „Historia” w przewodniku operatora).
  • Podsumowanie AI dla operatora — osobny przełącznik generuje krótkie podsumowanie + sugerowaną kolejną akcję dla każdego zgłoszenia, widoczne tylko operatorowi (panel boczny „Podsumowanie AI” w widoku zgłoszenia), odświeżane automatycznie, gdy w wątku pojawi się nowa wiadomość.
  • Prompt systemowy podsumowania — edytowalne pole tekstowe z gotową wartością domyślną i przyciskiem „Resetuj”.

API

Panel /admin/api-docs udostępnia interaktywną dokumentację (Swagger) REST API (/api/v1/...) — tokeny wydaje się przez API Clients, z uprawnieniami (abilities) ograniczonymi do: tickets:read, tickets:write, dictionaries:read (kategorie/statusy/priorytety/zespoły), users:read.