servicedesk/README.md

# Servicedesk

Helpdesk / ticketing system built with Laravel + Livewire (Polish UI). Clients submit
support tickets, operators triage and resolve them inside team queues, and admins
configure everything else — categories, SLA rules, templates, branding, LDAP/SMTP,
and a REST API for external integrations.

## Roles & areas

The app has three areas, gated by role (a user can hold more than one at once):

| Area | Route prefix | Who | What they do |
|---|---|---|---|
| Client | `/client` | `client` | Submit tickets, track status, reply, see resolution |
| Operator | `/operator` | `operator` | Work the ticket queue, reply/resolve, see team statistics |
| Admin | `/admin` | `admin` | Configure categories, users, teams, SLA, templates, triggers, branding, LDAP/SMTP/BookStack |

Every account gets the `client` role by default (see `AssignDefaultRole` for LDAP-provisioned
accounts), and always lands on `/client` first after login regardless of what other
roles it also holds — staff switch into Operator/Admin via the role switcher in the
header. See **[wiki/client](wiki/client/README.md)**, **[wiki/operator](wiki/operator/README.md)**,
and **[wiki/admin](wiki/admin/README.md)** for role-specific how-to guides.

## Feature overview

- **Navigation** — a segmented Klient/Operator/Administrator switcher in the
  top bar (only the areas a user actually holds, current one highlighted,
  hover-previews the destination before you click) replaces the old dropdown
  role switcher; the profile menu shows name/e-mail/role badges above
  Powiadomienia/Wyloguj się; every page sets its own browser-tab title
  (ticket subject, selected queue, active admin tab, ...) anchored with the
  company name; and a command-palette global search (Ctrl+K/Cmd+K, or a
  "Szukaj" sidebar button) finds tickets from anywhere, scoped to what the
  searching user can see, with Gmail-style `od:`/`temat:`/`treść:`/`numer:`
  operators. The operator sidebar also lists the last 6 tickets they
  actually opened ("Ostatnio przeglądane").
- **Tickets** — number, subject, body, category/subcategory, status, priority, team,
  assignee, custom fields (per subcategory), attachments, full message thread
  (public replies + internal notes), history log, merge, delete. The operator
  queue (50/page) and client dashboard (20/page, current/archive tracked
  separately) paginate rather than rendering every matching ticket at once.
- **SLA** — per-priority response/resolution time targets; a scheduled command
  (`tickets:check-sla-breaches`, every 15 min) flags overdue tickets and can notify
  the assigned operator.
- **SLA automation rules** (Admin > Automatyzacja SLA) — configurable rules that
  change a ticket's priority/status/team/assignee after N minutes of customer
  silence (optionally scoped to a priority/category/team), evaluated every 15
  minutes (`automation:run-rules`). Reuses the same `TicketService` setters a
  manual operator action would, so an automated change gets the same history
  entry, notification, and live broadcast as a human doing it; each rule fires
  once per ticket until a fresh customer reply or a close/reopen resets it.
- **Real-time updates** — the operator ticket queue and both ticket-detail views
  (operator and client) update live over WebSockets (Laravel Reverb): new
  tickets, status/priority/team/assignee changes, and new replies ("live chat")
  all show up without a manual refresh. A periodic fallback refresh (with a
  visible, clickable countdown badge — click it to fetch immediately and reset
  the countdown) covers a dropped websocket connection. All of the refresh/poll
  intervals in the app, browser-side and the background scheduled commands
  alike, are configurable from Admin > Konfiguracja (see below).
- **Categories & custom fields** — admin-defined categories/subcategories, each with
  its own set of custom fields (text/textarea/select/checkbox/date/number) and an
  optional default priority. Subcategories within a category can be reordered with
  up/down arrows in Admin > Kategorie; the order set there is what clients/operators
  see everywhere a subcategory picker is shown.
- **Teams** — subcategories auto-route to a team; operators only see their own
  team's queue (plus unrouted tickets and anything assigned to them) unless they're
  an admin. Reassigning a ticket to a team, though, is unrestricted — an operator
  can route a ticket to any team, not just one they belong to.
- **Client search** (Operator > Klienci) — find any account by name or e-mail
  (not just role=client — a ticket's customer can be any user), see its role
  badges and ticket count, and jump straight into the queue pre-filtered to
  that customer.
- **Templates** — canned response snippets for the reply box, admin-configurable
  "quick actions" (send + transition status in one click), and HTML e-mail
  templates for every ticket lifecycle event (created, status/priority/category/
  team changed, closed, operator replied, SLA breached), each independently
  enable/disable-able.
- **Operator statistics** (`/operator/stats`) — filterable dashboard (date range,
  team, priority, category, assignee) organized into sections: KPI tiles (volume,
  SLA breach rate, average first-response/resolution time, CSAT); breakdowns by
  status, priority, category and subcategory; team/operator workload; top 10
  clients by ticket volume plus a client × subcategory cross-tab (top 5
  subcategories, rest folded into "Inne"); CSAT average by team and by operator;
  and a daily created-vs-closed trend.
- **Branding & config** — company name/logo/favicon/accent color, login notice,
  e-mail layout/footer, SMTP connection (Admin > E-MAIL), attachment limits,
  session lifetime, timezone (Admin > Konfiguracja), and LDAP connection + user
  sync + BookStack (Admin > Integracje).
- **LDAP auth** — logins bind against a directory (`config/auth.php`,
  `config/ldap.php`); local accounts (e.g. the emergency `admin` account) fall back
  to e-mail + local password when the LDAP bind doesn't match. A "Typ katalogu"
  toggle (Admin > Integracje) switches between LLDAP/OpenLDAP (default) and
  Active Directory, which auto-selects the right schema/login attribute
  (`sAMAccountName` + `objectGUID` for AD, vs. `uid` + `entryUUID`).
- **Triggers** (Admin > Wyzwalacze) — event-driven business rules that fire
  immediately on a ticket lifecycle event (created, any field updated, status/
  priority/assignee/team/category changed, new public reply): AND-combined
  conditions gate a sequence of actions (set status/priority/team/assignee, or
  send an e-mail using a dedicated set of freely add/edit/delete-able trigger
  e-mail templates, kept separate from the fixed per-event system templates).
  Complements the time-based SLA automation rules above rather than replacing
  them.
- **Ticket watching** — operators can star/"Obserwuj" any ticket to follow it
  regardless of assignment/team, which feeds the "Obserwowane zgłoszenia" scope
  in their notification preferences.
- **Per-user notification preferences** (`/settings/notifications`) — each
  operator/admin chooses, per event category (new ticket, ticket update,
  escalation), which scope of tickets (mine, unassigned, watched, all) notifies
  them via the in-app bell, and whether that also sends an e-mail; plus an
  opt-in toggle for native in-tab browser push notifications.
- **REST API** (`/api/v1/...`, Sanctum token auth, ability-scoped: `tickets:read`,
  `tickets:write`, `dictionaries:read`, `users:read`) for tickets/messages/users/
  categories/statuses/priorities/teams — issued via admin-managed API clients.
  Interactive docs (L5-Swagger) at `/admin/api-docs`.
- **PWA** — installable manifest + icons for the client-facing area.
- **In-app notifications** — a bell in the top bar (client/operator/admin areas)
  backed by Laravel's database notification channel, alongside the existing
  e-mail notifications (same per-trigger enable toggle drives both); shows
  unread notifications only — reading one removes it from the list. Updates
  live over WebSockets the moment a notification is created (with a 30s
  fallback poll), and can optionally raise a native browser push notification
  while the tab is open (see per-user notification preferences above).
  Includes a dedicated trigger notifying every operator on a team whose
  subcategories match a newly created ticket.
- **Attachments** — drag-and-drop upload (in addition to the file picker); every
  attachment shows in the message thread as just its filename, opening in a new
  tab on click (no inline image preview).
- **E-mail intake (IMAP)** *(optional, off by default)* — clients can create
  tickets or reply to an existing one just by sending/replying to an e-mail;
  configure any number of mailboxes in Admin > Poczta (e.g. one address per
  team), each routed to a specific subcategory or a whole category. A reply
  is matched back to its ticket via the number/checksum already present in
  every notification's subject; automatic replies (autoresponders, bounces)
  are detected and rejected instead of creating junk tickets, and the
  "restrict tickets to LDAP" setting is enforced for e-mail exactly like the
  guest web form. A manual "Pobierz teraz" button fetches immediately
  outside the 5-minute schedule; all activity is logged separately to
  `storage/logs/imap-*.log`. Tickets/messages that came in by e-mail show a
  small mail-icon badge in the operator queue and ticket view.
- **Configurable ticket numbering** (Admin > Konfiguracja) — a custom prefix and
  minimum zero-padded length for the ticket number, plus an optional "hide
  ticket order" mode that displays a stable per-ticket checksum instead of the
  sequential number. When enabled, ticket URLs switch to the same checksum too,
  so the number in the link always matches the one on the page; the REST API is
  unaffected and always addresses tickets by `id`.
- **Customer satisfaction (CSAT)** — clients rate a ticket 1–5 stars (+ optional
  comment) once it's closed; average/response-rate surfaced as a KPI on the
  operator stats dashboard, with a link in the "ticket closed" e-mail.
- **Saved queue views** — operators can save their current filter/sort/column
  combination in the ticket queue, mark one as default, and switch between them.
- **Full-text search** — MySQL/MariaDB `FULLTEXT` search (with a portable `LIKE`
  fallback) across ticket subject/body and reply message bodies, available in
  both the operator queue and the client's own ticket list.
- **Stats export** — the operator stats dashboard can export the currently
  filtered ticket set as CSV.
- **BookStack knowledge-base integration** *(optional, off by default)* —
  suggests relevant BookStack articles by category/subcategory while a ticket
  is being created, and in a separate sidebar panel on an existing ticket for
  both operators and clients (with a copy-link button for operators). Loads in
  after the page's first paint rather than blocking it. Configured entirely
  from Admin > Integracje: connection + API token, optional SSL-verification
  bypass for self-signed instances, a content-type filter (books/pages/
  chapters, independently toggleable) and a "search by" mode (name / tags /
  both), and two independent per-shelf allow-lists (nothing is searched until
  an admin opts specific shelves in, separately for ticket-creation
  suggestions vs. the operator/client ticket-view sidebar). A pair of
  "Otaguj nową treść"/"Otaguj wszystko ponownie" buttons (also available as
  `php artisan bookstack:tag-content`) use the AI integration below to
  auto-tag every book/chapter/page with matching subcategory names, so the
  tag-based search mode has something to find.
- **Generic AI integration** (Admin > Integracje > "Integracja AI") *(optional,
  off by default)* — an OpenAI-compatible chat-completions client (Groq,
  OpenAI, or a self-hosted Ollama instance) configured by base URL, optional
  API key, model, and an SSL-verification toggle. Not tied to a single
  feature — it backs the BookStack auto-tagging above and the AI ticket
  triage/summary below, and is meant to be reused by anything that needs an
  LLM call in the future.
- **AI-driven ticket triage + summary** (Admin > Integracje >
  "Automatyzacja AI dla zgłoszeń") *(optional, off by default, requires the AI
  integration above)* — five independent toggles run once per new ticket, in
  the background (`ai:run-ticket-automation`, never synchronously at
  submission): assign a category/subcategory when missing, pick a
  subcategory when only a category is set, recheck/correct an
  already-categorized ticket, rewrite an unclear subject, and set a priority
  from the ticket's content. Every applied change is logged in the ticket's
  history. Separately, an AI-generated summary + suggested next action for
  every ticket, shown to operators only in a "Podsumowanie AI" sidebar card
  with a manual "Wygeneruj teraz" button, an admin-editable prompt
  (reset-to-default button included), and a per-transcript excerpt of the
  ticket's own opening body alongside the reply thread (so long tickets
  don't lose the original request once it scrolls out of the message
  window). Refreshed by the same periodic sweep by default; an optional
  admin toggle regenerates it immediately after every new reply/note
  instead of waiting for the next scheduled run.
- **Snipe-IT asset inventory integration** *(optional, off by default)* —
  connects to a Snipe-IT instance (API address + personal API token, plus an
  SSL-verification bypass for self-signed instances) and adds three
  independently toggleable capabilities from Admin > Integracje: a client
  can pick which of their own Snipe-IT assets a ticket concerns while
  creating it (scoped to admin-selected subcategories, empty selection means
  it never shows — same convention as BookStack's shelf allow-lists), an
  operator sees the requester's own assets in a ticket-view sidebar card,
  and an operator can search the entire Snipe-IT inventory from that same
  sidebar (not a separate page) to link shared equipment the requester isn't
  the current owner of. Every asset is shown as "numer środka - numer
  seryjny - producent model" plus its Snipe-IT category; a linked asset's
  live status/assignment is fetched fresh on the ticket page, and unlinking
  stays available to an operator even if both view/search toggles are later
  turned off.

## Tech stack

- **Backend**: Laravel, Livewire (server-driven UI, no SPA build beyond Tailwind/Vite
  for CSS), LdapRecord for directory auth, Sanctum for API tokens, L5-Swagger for
  API docs, Laravel Reverb for WebSocket broadcasting (real-time queue/chat
  updates — see [ARCHITECTURE.md](ARCHITECTURE.md)), webklex/php-imap for the
  optional e-mail intake fetcher (pure-PHP IMAP client, no `ext-imap` needed).
- **Frontend**: Blade + Livewire + a little Alpine.js for local UI state; Tailwind
  v4 via Vite for `resources/css/app.css`; Laravel Echo + Pusher-protocol client
  (`resources/js/echo.js`) for Reverb. No JS charting library — the statistics
  dashboard is hand-rolled inline-styled bar/column charts, so it needs no client
  build step beyond the CSS bundle.
- **Database**: MariaDB.
- **Deployment**: `compose.yaml` — `app` (source bind-mounted from `./src`,
  no image rebuild needed for PHP/Blade/route changes) + `mariadb` + `reverb`
  (same image, `php artisan reverb:start`) + `cron` (same image, `php artisan
  schedule:work` — runs the scheduled commands below without needing a host
  crontab), fronted by Traefik with a private-CA TLS cert (the websocket path
  is routed to `reverb` by a higher-priority Traefik rule; everything else
  goes to `app`). The `servicedesk` image
  itself is built and pushed by Gitea Actions (`.gitea/workflows/build.yml`) to
  the Gitea container registry whenever `Dockerfile` changes — `compose.yaml`
  just pulls a tag, it never builds locally.

See **[install.md](install.md)** for full step-by-step deployment instructions —
both via Docker Compose (this stack) and directly on a server with Apache/Nginx,
including which `.env` values to set (there are two separate `.env` files —
Compose-level and Laravel-level) and the LDAP/SMTP gotcha after a fresh seed.

## Local/dev notes

- The app container mounts `./src` directly — editing PHP/Blade/routes takes effect
  immediately, no rebuild or restart needed.
- CSS/JS changes under `resources/` **do** need a Vite build. Neither the host nor
  the app container has Node installed; rebuild with a throwaway container instead
  of rebuilding the app image:
  ```bash
  sudo docker run --rm -v "$(pwd)/src":/app -w /app node:22 npm run build
  ```
- Fresh install / reset:
  ```bash
  sudo docker exec servicedesk-app-1 php artisan migrate:fresh --seed
  ```
  Seeds real reference data (categories, custom fields, statuses/priorities/SLA,
  teams, quick actions, response/e-mail templates, branding/config with example
  SMTP+LDAP placeholders) and a single local fallback account, **`admin@example.com`
  / `admin`** — replace its password and/or the SMTP/LDAP settings before relying on
  this in anything but a lab environment.

## Project layout

```
src/                     Laravel application
  app/Livewire/          Client/Operator/Admin Livewire components
  app/Models/            Eloquent models
  app/Events/            Broadcast events (TicketQueueChanged, TicketMessagePosted)
  app/Console/Commands/  Scheduled commands (SLA breach check, automation rules, IMAP fetch,
                         AI ticket triage/summary) + bookstack:tag-content + hesk:import
                         (one-time historical migration, see scripts/hesk-import/)
  app/Services/          TicketService (ticket lifecycle + notifications), BookStackClient,
                         ImapMailboxFetcher (I/O) + ImapMessageClassifier (pure logic),
                         AiClient (generic LLM client), BookStackContentTagger,
                         TicketAiTriageService, TicketAiSummaryService, SnipeItClient
  app/Ldap/              LDAP user models — LldapUser (LLDAP/OpenLDAP, default) and
                         AdUser (Active Directory) — plus sync handlers
  database/migrations/   Schema (one file per table group, final shape)
  database/seeders/      DatabaseSeeder — reference data, no ticket data
  resources/css/         Tailwind entrypoint (needs `npm run build` after edits)
  resources/js/echo.js   Laravel Echo/Reverb client + broadcast → Livewire event bridge
  resources/views/       Blade templates
  routes/web.php         Client/Operator/Admin routes (role-gated)
  routes/api.php         REST API (Sanctum, ability-gated)
  routes/channels.php    Broadcasting channel authorization (operator.queue, ticket.{id})
wiki/
  client/                How-to guide for the Client role
  operator/               How-to guide for the Operator role
  admin/                  How-to guide for the Admin role
scripts/
  hesk-import/            One-time Hesk 3.x ticket history import — see its own README.md
```