Files

Kacper 90fae0a4de v1.1.0

- In-app notifications: a bell in the top bar backed by Laravel's database
  notification channel, alongside existing e-mail notifications (same
  per-trigger toggle drives both; ticket links now correctly point into the
  recipient's own area instead of always linking to the client view).
- Drag-and-drop attachments on every upload form, plus inline image
  thumbnails in the message thread instead of a plain download link.
- Customer satisfaction (CSAT) rating: clients rate a closed ticket 1-5 stars
  with an optional comment; shown read-only to operators, surfaced as a KPI
  on the stats dashboard, and linked from the "ticket closed" e-mail.
- Saved queue views: operators can save/apply/delete named filter+sort+
  column presets in the ticket queue and mark one as their default.
- Full-text search (MySQL FULLTEXT, portable LIKE fallback) across ticket
  subject/body and reply message bodies, now also on the client's own ticket
  list.
- Stats CSV export for the currently filtered ticket set.
- Optional BookStack knowledge-base integration (off by default): suggests
  articles by category/subcategory while creating a ticket and in a separate
  sidebar for operators on an existing ticket (with a copy-link button).
  Configurable connection/SSL bypass/search-type filter, plus two
  independent per-shelf allow-lists so nothing is ever searched until an
  admin opts specific shelves in.
- Closed tickets no longer show in "Moje zgłoszenia"/"Nieprzypisane"/team
  queue tabs, only under "Zamknięte" (matching how "Otwarte" already worked).
- Wired up the Admin > About "Wersja" field to config('app.version')/VERSION
  in .env instead of a stale hardcoded string.
- Fixed: TicketService::setStatus() now checks a status's stage rather than
  the literal key 'closed' to decide whether to fire the "ticket closed"
  notification/stop the timer.
- Updated README/ARCHITECTURE/CHANGELOG/install/SECURITY docs and all three
  wiki/ role guides for the above; documented a root-vs-www-data file
  ownership gotcha in CLAUDE.md (running artisan commands via a plain
  `docker exec` can leave root-owned Blade cache files that later break
  recompilation for the www-data Apache process).

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

2026-07-22 15:18:09 +02:00

README.md

v1.1.0

2026-07-22 15:18:09 +02:00

README.md

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. „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. Ten sam przełącznik kontroluje zarówno e-mail, jak i powiadomienie w dzwoneczku w aplikacji — nie ma osobnego ustawienia dla powiadomień w apce.

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.
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.