diff --git a/README.md b/README.md index 7a6e67f..9102bbc 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,208 @@ -# servicedesk +# 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. + +--- + +Jeżeli chcesz, w następnym kroku wygeneruję konkretną implementację routingu dla wybranego frameworka (np. Laravel, Slim, Symfony).