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, poczta SMTP/IMAP,
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.
  - **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.

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](../../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** — 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`.