v1.0.0

wiki/admin/README.md

@@ -0,0 +1,115 @@
+# Przewodnik — Administrator
+
+Panel administratora (`/admin`) to jedno miejsce do konfiguracji całego systemu:
+struktura zgłoszeń (kategorie, pola, statusy, priorytety, SLA), użytkownicy i
+zespoły, treści (szablony, szybkie akcje, e-maile), wygląd/branding oraz
+integracje (LDAP, SMTP, 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.
+
+## 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).
+- **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) — 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.
+
+## 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.
+- **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.
+- **SMTP** — host, port, szyfrowanie, użytkownik/hasło, adres/nazwa nadawcy.
+  Przycisk **„Testuj połączenie”** analogicznie do LDAP.
+
+  > Po świeżej instalacji (`migrate:fresh --seed`) te dwie sekcje 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.
+
+## 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`.

wiki/client/README.md

@@ -0,0 +1,55 @@
+# Przewodnik — Klient
+
+Panel klienta (`/client`) służy do zgłaszania problemów/próśb i śledzenia ich
+rozwiązania. Po zalogowaniu każde konto domyślnie ląduje właśnie tutaj — nawet jeśli
+posiada też uprawnienia operatora lub administratora (przełączysz się przez menu
+profilu w prawym górnym rogu).
+
+## Zgłaszanie nowej sprawy
+
+1. Kliknij **„Nowe zgłoszenie”**.
+2. Wybierz **kategorię**, a następnie **podkategorię** — lista i opisy pod każdą
+   pozycją pomagają wybrać właściwą (np. „VPN” vs „Sieć wewnętrzna”).
+3. Uzupełnij **temat** i **opis** sprawy. W zależności od wybranej podkategorii
+   mogą pojawić się dodatkowe pola (np. numer inwentarzowy sprzętu, kwota,
+   data potrzebna, zgoda przełożonego) — administrator skonfigurował je specjalnie
+   dla tej podkategorii.
+4. Opcjonalnie dodaj **załączniki** (limit rozmiaru/liczby/plików ustala admin —
+   komunikat o błędzie poinformuje, jeśli coś przekracza limit).
+5. Wyślij zgłoszenie. Otrzymasz e-mail potwierdzający (jeśli powiadomienia są
+   włączone) z linkiem do podglądu.
+
+Zgłoszenie można też wysłać **bez logowania** ze strony głównej — wystarczy podać
+e-mail; konto zostanie założone automatycznie (jeśli administrator włączył
+auto-provisioning gości), a dalsze śledzenie sprawy odbywa się przez link z maila
+albo po zalogowaniu.
+
+## Śledzenie zgłoszeń
+
+Dashboard klienta dzieli zgłoszenia na dwie zakładki:
+
+- **Bieżące** — zgłoszenia jeszcze nie zamknięte.
+- **Archiwum** — zgłoszenia zamknięte.
+
+Otwórz dowolne zgłoszenie, by zobaczyć:
+
+- aktualny **status** i **priorytet**,
+- pełną **historię wiadomości** (Twoje i operatora — notatki wewnętrzne operatora
+  nie są widoczne dla klienta),
+- **SLA** — orientacyjny czas do rozwiązania wg priorytetu sprawy.
+
+## Odpowiadanie
+
+W widoku zgłoszenia można dopisać kolejną wiadomość w dowolnym momencie (np. dodać
+brakujące informacje albo potwierdzić rozwiązanie) — operator zobaczy ją i, jeśli
+powiadomienia są włączone, dostaniesz e-mail przy każdej zmianie statusu lub nowej
+odpowiedzi operatora.
+
+## Najczęstsze pytania
+
+- **Nie widzę mojego zgłoszenia** — sprawdź zakładkę Archiwum, jeśli sprawa została
+  już zamknięta.
+- **Zmieniłem zdanie co do kategorii** — napisz o tym w wiadomości; tylko operator/
+  administrator może zmienić kategorię/podkategorię już złożonego zgłoszenia.
+- **Nie dostaję e-maili** — powiadomienia e-mail są konfigurowalne przez admina i
+  mogą być wyłączone dla niektórych zdarzeń; sprawdź też SPAM.

wiki/operator/README.md

@@ -0,0 +1,93 @@
+# Przewodnik — Operator
+
+Panel operatora (`/operator`) to miejsce pracy z kolejką zgłoszeń: przegląd,
+odpowiadanie, zmiana statusu/priorytetu/przypisania oraz — nowość — statystyki
+zespołu.
+
+Domyślnie każde konto ląduje po zalogowaniu w panelu Klienta; przełącz się do
+panelu Operatora przez menu profilu (prawy górny róg), jeśli konto ma tę rolę.
+
+## Kolejka zgłoszeń
+
+Panel główny (`/operator`) pokazuje listę zgłoszeń z zakładkami po lewej stronie:
+
+- **Otwarte** — wszystkie zgłoszenia jeszcze nie zamknięte, widoczne dla Ciebie.
+- **Moje zgłoszenia** — przypisane do Ciebie.
+- **Nieprzypisane** — czekają na przejęcie przez kogoś z zespołu.
+- **Zamknięte** — archiwum.
+- **Zespoły** — osobna zakładka na każdy zespół, do którego należysz (administrator
+  widzi wszystkie zespoły).
+
+Nie-administratorzy widzą tylko zgłoszenia swoich zespołów, zgłoszenia bez
+przypisanego zespołu, oraz wszystko przypisane bezpośrednio do nich.
+
+**Filtry** nad tabelą: status, priorytet, kategoria, wyszukiwanie po numerze/
+temacie/kliencie. **Kolumny** można dowolnie włączać/wyłączać przyciskiem
+„Kolumny”, a nagłówki kolumn sortują listę.
+
+**Akcje zbiorcze**: zaznacz kilka zgłoszeń checkboxami, by je **scalić** (pierwsze
+zaznaczone staje się główne, reszta trafia do niego jako wiadomości i zostaje
+zamknięta) albo **usunąć**.
+
+## Praca ze zgłoszeniem
+
+W widoku pojedynczego zgłoszenia:
+
+- **Zmiana statusu / priorytetu / zespołu / przypisanego operatora** — z listy
+  rozwijanej; „Przypisz do mnie” to skrót jednym kliknięciem.
+- **Odpowiedź publiczna** — widoczna dla klienta; można wybrać **szablon
+  odpowiedzi** (wstawia gotowy tekst do edycji) i wysłać razem ze zmianą statusu
+  jedną **szybką akcją** (np. „Wyślij i zamknij”) zamiast dwóch osobnych kroków.
+- **Notatka wewnętrzna** — widoczna tylko dla operatorów/adminów, np. do
+  przekazania kontekstu innemu operatorowi.
+- **Załączniki** — do odpowiedzi/notatki, w granicach limitów ustawionych przez
+  administratora.
+- **Licznik czasu pracy** — start/stop/reset przy zgłoszeniu; czas zapisuje się
+  automatycznie nawet przy zamknięciu karty (mechanizm `sendBeacon`).
+- **Edycja danych zgłoszenia** — temat, opis, podkategoria, pola dodatkowe;
+  zmiana kategorii może wysłać powiadomienie do klienta.
+- **Historia** — log każdej zmiany (status, priorytet, zespół, przypisanie) z
+  datą.
+
+## Statystyki (`/operator/stats`)
+
+Nowa zakładka **„Statystyki”** (przycisk w pasku narzędzi kolejki) pokazuje pulpit
+analityczny z możliwością filtrowania — dane odświeżają się na żywo przy każdej
+zmianie filtra, bez przeładowania strony.
+
+**Filtry:**
+
+- **Zakres dat** — Dziś / 7 dni / 30 dni / 90 dni / Cały okres / zakres
+  niestandardowy (od–do).
+- **Zespół, priorytet, kategoria, operator** — jak w kolejce; nie-administratorzy
+  widzą tylko swoje zespoły i przypisanych do nich operatorów.
+
+**Kafelki KPI:**
+
+| Wskaźnik | Co pokazuje |
+|---|---|
+| Łącznie zgłoszeń | liczba zgłoszeń w wybranym zakresie/filtrach |
+| Otwarte / Zamknięte | podział + % zamkniętych |
+| Śr. czas 1. odpowiedzi | średni czas od utworzenia do pierwszej odpowiedzi operatora |
+| Śr. czas rozwiązania | średni czas od utworzenia do zamknięcia (przybliżony — brak osobnej daty "rozwiązano", liczony do ostatniej aktualizacji zamkniętego zgłoszenia) |
+| Naruszenia SLA | % zgłoszeń, które przekroczyły czas rozwiązania wg priorytetu (zgodnie z regułami SLA w Admin > Statusy/Priorytety) |
+
+**Wykresy** (paski poziome, kolor = ta sama identyfikacja co w kolejce dla statusu/
+priorytetu; najedź kursorem na pasek, by zobaczyć dokładną wartość):
+
+- Zgłoszenia wg statusu
+- Zgłoszenia wg priorytetu
+- Zgłoszenia wg kategorii
+- Obciążenie zespołów
+- Obciążenie operatorów (ranking wg liczby przypisanych zgłoszeń)
+
+**Trend** — dzienny wykres słupkowy „Nowe zgłoszenia” i „Zamknięte zgłoszenia”
+obok siebie (maks. ostatnie 60 dni wybranego zakresu, żeby słupki pozostały
+czytelne przy długich okresach).
+
+## Wskazówki
+
+- Zgłoszenie bez przypisanego zespołu jest widoczne dla wszystkich operatorów —
+  warto je szybko zaklasyfikować/przypisać.
+- Szybkie akcje i szablony odpowiedzi konfiguruje administrator (Admin > Szybkie
+  akcje / Szablony odpowiedzi) — zgłoś mu, jeśli brakuje przydatnego szablonu.