# Routing MVC — Helpdesk

Dokument zawiera zaprojektowany routing dla systemu helpdesk w architekturze MVC. Zawiera: opis autoryzacji, middleware, nazwy tras, metody HTTP, kontrolery i akcje oraz dodatkowe propozycje (API, webhooki, testy integracji).

---

## Założenia ogólne

* System ma trzy główne role: `guest` (niezalogowany), `customer` (zalogowany klient), `agent` (wsparcie/operator), `admin` (pełne uprawnienia). Rolę `customer` i `agent` mogą być różne grupy/role w LDAP.
* Logowanie przez LDAP (endpoint do testu i konfiguracji w panelu admina).
* Tworzenie zgłoszeń możliwe bez logowania **tylko** dla osób, które posiadają już konto — weryfikacja po polu `email` (wysłanie jednorazowego linku/weryfikacja tokenem). Gość może utworzyć zgłoszenie po pozytywnej weryfikacji email.
* RESTful approach dla zasobów: `tickets`, `users`, `categories`, `groups`, `roles`, `custom_fields`, `integrations`, `comments`, `attachments`.
* Wszystkie wrażliwe akcje wymagają CSRF tokenów (formularze) i uwierzytelnienia.

---

## Middleware

* `Auth` — sprawdza zalogowanego użytkownika.
* `GuestOnly` — dostępne tylko dla niezalogowanych (np. formularz tworzenia zgłoszenia bez logowania + weryfikacja email).
* `Role:admin` — tylko admin.
* `Role:agent` — agent lub admin.
* `RateLimit` — ochrona endpointów publicznych (np. tworzenie zgłoszeń bez logowania, endpointy API publiczne).
* `VerifyEmailToken` — walidacja tokenu przy tworzeniu zgłoszenia przez gościa.
* `CanViewTicket` — sprawdza czy dany użytkownik/agent ma prawo przeglądać zgłoszenie.

---

## Schemat tras (ważniejsze)

> Notacja: [METODA] /ścieżka -> Kontroler@akcja (nazwa_trasy) — uprawnienia / uwagi

### Autoryzacja i sesje

* [GET]  /login -> AuthController@showLoginForm (auth.login) — guest
* [POST] /login -> AuthController@login (auth.login.post) — guest (LDAP)
* [POST] /logout -> AuthController@logout (auth.logout) — auth
* [GET]  /ldap/test -> Admin\IntegrationController@testLdap (admin.ldap.test) — role:admin

### Publiczne (gość) — tworzenie zgłoszeń z weryfikacją email

* [GET]  /ticket/new -> PublicTicketController@showCreateForm (public.ticket.new) — guest
* [POST] /ticket/verify-email -> PublicTicketController@requestEmailVerification (public.ticket.verify-email) — guest

  * body: { email }
  * akcja: jeśli email istnieje w DB -> wyślij e-mail z jednorazowym tokenem; jeśli nie istnieje -> odrzuć
* [GET]  /ticket/verify?token=... -> PublicTicketController@verifyToken (public.ticket.verify) — guest, VerifyEmailToken
* [POST] /ticket/create -> PublicTicketController@create (public.ticket.create) — guest (po VerifyEmailToken) lub auth
* [GET]  /ticket/{id}/view-public -> PublicTicketController@publicView (public.ticket.view) — możliwe ograniczone, jeśli ticket jest publiczny lub token w URL

> Uwaga: Po weryfikacji email dla gościa powinna powstać tymczasowa sesja (może krótkotrwały cookie) pozwalająca na dokończenie zgłoszenia.

### Klient (Customer) – panel klienta

* [GET]  /client/dashboard -> Client\DashboardController@index (client.dashboard) — auth, role:customer
* [GET]  /client/tickets -> Client\TicketController@index (client.tickets) — auth, filtr: open/closed
* [GET]  /client/tickets?status=open -> Client\TicketController@index (client.tickets.open)
* [GET]  /client/tickets/{id} -> Client\TicketController@show (client.ticket.show) — auth, CanViewTicket
* [GET]  /client/tickets/new -> Client\TicketController@createForm (client.ticket.new) — auth
* [POST] /client/tickets -> Client\TicketController@store (client.ticket.store) — auth
* [POST] /client/tickets/{id}/comment -> Client\TicketController@addComment (client.ticket.comment) — auth, CanViewTicket
* [POST] /client/tickets/{id}/attachments -> Client\AttachmentController@upload (client.attachment.upload) — auth

### Agent (wsparcie)

* [GET]  /agent/dashboard -> Agent\DashboardController@index (agent.dashboard) — role:agent
* [GET]  /agent/tickets -> Agent\TicketController@index (agent.tickets) — role:agent (filtry: assigned, unassigned, priority)
* [GET]  /agent/tickets/{id} -> Agent\TicketController@show (agent.ticket.show) — role:agent, CanViewTicket
* [POST] /agent/tickets/{id}/assign -> Agent\TicketController@assign (agent.ticket.assign) — role:agent
* [POST] /agent/tickets/{id}/status -> Agent\TicketController@changeStatus (agent.ticket.status) — role:agent
* [POST] /agent/tickets/{id}/comment -> Agent\TicketController@addComment (agent.ticket.comment) — role:agent
* [POST] /agent/tickets/{id}/private-note -> Agent\TicketController@addPrivateNote (agent.ticket.private_note) — role:agent

### Admin

* [GET]  /admin -> Admin\DashboardController@index (admin.dashboard) — role:admin

**Zarządzanie użytkownikami**

* [GET]  /admin/users -> Admin\UserController@index (admin.users)
* [GET]  /admin/users/new -> Admin\UserController@createForm (admin.users.new)
* [POST] /admin/users -> Admin\UserController@store (admin.users.store)
* [GET]  /admin/users/{id} -> Admin\UserController@show (admin.users.show)
* [PUT]  /admin/users/{id} -> Admin\UserController@update (admin.users.update)
* [DELETE]/admin/users/{id} -> Admin\UserController@destroy (admin.users.delete)
* [POST] /admin/users/{id}/sync-ldap -> Admin\UserController@syncFromLdap (admin.users.sync) — test/merge

**Integracje (LDAP, SMTP)**

* [GET]  /admin/integrations -> Admin\IntegrationController@index (admin.integrations)
* [GET]  /admin/integrations/new -> Admin\IntegrationController@createForm (admin.integration.new)
* [POST] /admin/integrations -> Admin\IntegrationController@store (admin.integration.store)
* [GET]  /admin/integrations/{id}/edit -> Admin\IntegrationController@edit (admin.integration.edit)
* [PUT]  /admin/integrations/{id} -> Admin\IntegrationController@update (admin.integration.update)
* [POST] /admin/integrations/{id}/test -> Admin\IntegrationController@test (admin.integration.test) — np. test LDAP bind, test SMTP send

**Kategorie, Grupy, Role**

* RESTful routes: `/admin/categories`, `/admin/groups`, `/admin/roles` — CRUD (index,new,store,show,edit,update,destroy)

**Custom Fields (jak Zammad)**

* [GET]  /admin/custom-fields -> Admin\CustomFieldController@index (admin.custom_fields)
* [GET]  /admin/custom-fields/new -> Admin\CustomFieldController@createForm
* [POST] /admin/custom-fields -> Admin\CustomFieldController@store
* [GET]  /admin/custom-fields/{id}/edit -> Admin\CustomFieldController@edit
* [PUT]  /admin/custom-fields/{id} -> Admin\CustomFieldController@update
* [DELETE]/admin/custom-fields/{id} -> Admin\CustomFieldController@destroy

---

## API (REST) — przydatne dla integracji i frontend SPA

> Prefiks: `/api/v1` — zwraca JSON, zabezpieczone tokenem (OAuth2/JWT) lub kluczem API

* [POST] /api/v1/tickets -> Api\TicketController@create — public (z limitem) lub z tokenem
* [GET]  /api/v1/tickets -> Api\TicketController@index — auth
* [GET]  /api/v1/tickets/{id} -> Api\TicketController@show
* [POST] /api/v1/tickets/{id}/comments -> Api\CommentController@store
* [GET]  /api/v1/users -> Api\UserController@index
* [POST] /api/v1/webhooks -> Api\WebhookController@receive — do obsługi zewnętrznych systemów

---

## Webhooky / powiadomienia

* [POST] /webhook/ticket-updated -> WebhookController@ticketUpdated — obsługa wysyłania powiadomień do zewnętrznych systemów (możliwość konfiguracji w integracjach).
* [POST] /webhook/email-reply -> WebhookController@emailReply — odbiór odpowiedzi z maila (parse i przypisz do ticketu)

---

## Proponowane dodatkowe trasy i funkcje użyteczne

* `/search` (GET) -> globalne wyszukiwanie ticketów, użytkowników, załączników.
* `/reports` (admin) -> eksport CSV/PDF statystyk (liczba zgłoszeń, SLA, średni czas odpowiedzi).
* `/settings` (admin) -> ogólne ustawienia aplikacji.
* `/attachments/{id}/download` -> bezpieczne pobieranie plików (signed URL lub autoryzacja).
* `/tickets/{id}/share` -> generowanie publicznego linku do ticketu (czasowy token).
* `/kb` -> baza wiedzy (opcjonalna) — artykuły, kategorie, tagi.

---

## Przykładowa implementacja (Laravel-like) — fragmenty

```php
// Public
Route::get('/ticket/new', 'PublicTicketController@showCreateForm')->name('public.ticket.new');
Route::post('/ticket/verify-email', 'PublicTicketController@requestEmailVerification')->name('public.ticket.verify-email');
Route::get('/ticket/verify', 'PublicTicketController@verifyToken')->name('public.ticket.verify');
Route::post('/ticket/create', 'PublicTicketController@create')->name('public.ticket.create');

// Auth
Route::get('/login', 'AuthController@showLoginForm')->middleware('guest')->name('auth.login');
Route::post('/login', 'AuthController@login')->middleware('guest');
Route::post('/logout', 'AuthController@logout')->middleware('auth')->name('auth.logout');

// Client
Route::group(['prefix'=>'client','middleware'=>['auth','role:customer']], function(){
    Route::get('dashboard','Client\\DashboardController@index')->name('client.dashboard');
    Route::resource('tickets','Client\\TicketController');
});

// Agent
Route::group(['prefix'=>'agent','middleware'=>['auth','role:agent']], function(){
    Route::get('dashboard','Agent\\DashboardController@index')->name('agent.dashboard');
    Route::resource('tickets','Agent\\TicketController');
});

// Admin
Route::group(['prefix'=>'admin','middleware'=>['auth','role:admin']], function(){
    Route::get('/','Admin\\DashboardController@index')->name('admin.dashboard');
    Route::resource('users','Admin\\UserController');
    Route::resource('integrations','Admin\\IntegrationController');
    Route::resource('categories','Admin\\CategoryController');
    Route::resource('groups','Admin\\GroupController');
    Route::resource('roles','Admin\\RoleController');
    Route::resource('custom-fields','Admin\\CustomFieldController');
});

// API
Route::prefix('api/v1')->group(function(){
    Route::post('tickets','Api\\TicketController@create');
    Route::get('tickets','Api\\TicketController@index');
});
```

---

## Uwagi dotyczące bezpieczeństwa i UX

1. Formularze tworzenia zgłoszeń dla gości: wymuszaj CAPTCHA + rate-limiting + weryfikację email.
2. Token weryfikacyjny powinien być jednorazowy i krótko ważny (np. 15–60 minut).
3. Przy publicznym przeglądaniu ticketu — nie ujawniaj danych wrażliwych bez autoryzacji.
4. Wszystkie pobierania załączników przez publiczne linki — używaj signed URLs z datą wygaśnięcia.
5. Dla API rozważ OAuth2 lub JWT + scope (np. `tickets.read`, `tickets.write`).
6. Loguj wszystkie akcje administracyjne (audyt).

---

## Co mogę zrobić dalej (opcjonalnie)

* Wygenerować gotowy plik routingu `routes/web.php` dla Laravel/Lumen.
* Przygotować specyfikację API (OpenAPI/Swagger) dla `api/v1`.
* Wygenerować przykładowe kontrolery i middleware skeletony.