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), użytkownicy i zespoły, treści (szablony, szybkie akcje, e-maile), wygląd/branding oraz integracje (LDAP, SMTP, BookStack, 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.

SMTP (host, port, szyfrowanie, użytkownik/hasło, adres/nazwa nadawcy, z przyciskiem „Testuj połączenie”) konfiguruje się w zakładce E-MAIL, razem z layoutem/stopką wiadomości — patrz sekcja wyżej.

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 — strony i książki / tylko strony / tylko książki.
  • 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.

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.