v1.0.0
This commit is contained in:
116
README.md
Normal file
116
README.md
Normal file
@@ -0,0 +1,116 @@
|
||||
# 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, branding, LDAP/SMTP |
|
||||
|
||||
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
|
||||
|
||||
- **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.
|
||||
- **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.
|
||||
- **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.
|
||||
- **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.
|
||||
- **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) with KPI tiles (volume, SLA breach rate,
|
||||
average first-response/resolution time) and breakdowns by status, priority,
|
||||
category, team and operator workload, plus a daily created-vs-closed trend.
|
||||
- **Branding & config** — company name/logo/favicon/accent color, login notice,
|
||||
e-mail layout/footer, LDAP connection + user sync, SMTP connection, attachment
|
||||
limits, session lifetime, timezone — all editable from Admin > Konfiguracja.
|
||||
- **LDAP auth** — logins bind against an LDAP/LLDAP 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.
|
||||
- **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.
|
||||
|
||||
## 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.
|
||||
- **Frontend**: Blade + Livewire + a little Alpine.js for local UI state; Tailwind
|
||||
v4 via Vite for `resources/css/app.css`. 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` — `servicedesk` (php:apache, source bind-mounted
|
||||
from `./src`, no image rebuild needed for PHP/Blade/route changes) + `mariadb`,
|
||||
fronted by Traefik with a private-CA TLS cert.
|
||||
|
||||
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-servicedesk-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/Services/ TicketService (ticket lifecycle + notifications)
|
||||
app/Ldap/ LDAP user model + 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/views/ Blade templates
|
||||
routes/web.php Client/Operator/Admin routes (role-gated)
|
||||
routes/api.php REST API (Sanctum, ability-gated)
|
||||
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
|
||||
```
|
||||
Reference in New Issue
Block a user