readme

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