Reklamacje i skargi (Complaint)¶

Ostatnia aktualizacja dokumentacji: 26 lutego 2026 Stan synchronizacji z kodem: ✅ Zsynchronizowany

1. Opis ogólny¶

Domena Reklamacji zarządza zgłoszeniami problemów od klientów — od złożenia reklamacji, przez wymianę wiadomości, aż po rozwiązanie sprawy. To jak cyfrowa książka skarg i wniosków z pełnym workflow, historią korespondencji i możliwością dołączania zdjęć czy dokumentów.

Klienci mogą składać reklamacje bez logowania — wystarczy kod dostępu z rezerwacji. System automatycznie generuje unikalny numer zgłoszenia i kod dostępu, umożliwiając śledzenie statusu sprawy i wymianę wiadomości z obsługą.

2. Architektura domeny¶

2.1 Modele danych¶

Complaint (Reklamacja)¶

• Ścieżka: app/Domain/Complaint/Model/Complaint.php
• Tabela: complaints
• Klucz: UUID (string, HasUuids)
• Interfejsy: HasMedia (Spatie MediaLibrary)
• Traity: HasUuids, InteractsWithMedia
• Observery: StatusLogObserver, ComplaintObserver
• Hidden fields: access_code (ukryty w serializacji, ale zwracany w Resource)

Relacje:

Kolekcje mediów:

Kolekcja attachments akceptuje: image/jpeg, image/png, image/gif, image/webp, video/mp4, video/quicktime, video/x-msvideo, application/pdf, application/msword, application/vnd.openxmlformats-officedocument.wordprocessingml.document.

ComplaintMessage (Wiadomość reklamacji)¶

• Ścieżka: app/Domain/Complaint/Model/ComplaintMessage.php
• Tabela: complaint_messages
• Klucz: UUID (string, HasUuids)
• Observer: ComplaintMessageObserver

Relacje:

2.2 Diagram relacji¶

erDiagram
    Complaint ||--o{ ComplaintMessage : "messages()"
    Complaint }o--|| Organization : "organization()"
    Complaint }o--o| Reservation : "reservation()"
    Complaint }o--o| User : "supervisor()"
    Complaint }o--o| User : "solver()"
    Complaint ||--o{ Note : "notes() [morph]"
    Complaint ||--o{ Media : "media [attachments]"

    Complaint {
        uuid id PK
        uuid uuid
        string access_code
        uuid organization_id FK
        uuid reservation_id FK
        string first_name
        string last_name
        string email
        string mobile_phone
        enum type
        text message
        enum status
        enum priority
        uuid supervisor_id FK
        uuid resolved_by FK
        datetime resolved_at
        datetime created_at
        datetime updated_at
    }

    ComplaintMessage {
        uuid id PK
        uuid complaint_id FK
        enum author_type
        string author_name
        string author_email
        text message
        datetime created_at
        datetime updated_at
    }

2.3 Struktura tabel w bazie danych¶

Migracja: database/migrations/0001_01_01_000020_create_complaints.php

Tabela complaints¶

Tabela complaint_messages¶

Indeksy złożone: (complaint_id, created_at), (author_type, created_at)

3. Endpointy API¶

3.1 Endpointy uwierzytelnione (auth)¶

Middleware bazowe: auth:api, user_is_active, throttle:api, to_user_access, user_accepted_agreements.

Middleware roli ADMIN|SUPERVISOR|EMPLOYEE na: index, show, update, changeStatus, assignSupervisor.

GET /api/complaints¶

• Opis: Lista reklamacji z filtrami i paginacją
• Autoryzacja: Rola ADMIN, SUPERVISOR lub EMPLOYEE
• Query Parameters:
  • Paginacja (standardowa z TraitSupport)
  • filter[id] — dokładne dopasowanie UUID
  • filter[type] — typ reklamacji (issue, refund, suggestion, other)
  • filter[status] — status (new, in_progress, resolved, closed)
  • filter[priority] — priorytet (low, medium, high)
  • filter[supervisor.name] — częściowe dopasowanie nazwy opiekuna
  • filter[solver.name] — częściowe dopasowanie nazwy osoby rozwiązującej
• Response (sukces): Paginowana kolekcja ComplaintResource z relacjami: reservation, organization, supervisor, solver

GET /api/complaints/{complaintId}¶

• Opis: Szczegóły pojedynczej reklamacji
• Autoryzacja: Rola ADMIN, SUPERVISOR lub EMPLOYEE
• Parametry URL: complaintId (UUID)
• Response (sukces): ComplaintResource z relacjami
• Response (błędy): 404 — reklamacja nie znaleziona (NotFoundModelException)

POST /api/complaints¶

• Opis: Tworzenie nowej reklamacji (dostępne dla wszystkich zalogowanych, bez wymogu roli)
• Body (Request): StoreComplaintControllerRequest — patrz sekcja 4.3
• Response (sukces): 200 — "The Complaint has been successfully added"

PATCH /api/complaints/{complaintId}¶

• Opis: Aktualizacja reklamacji
• Autoryzacja: Rola ADMIN|SUPERVISOR|EMPLOYEE + Policy update (musi należeć do organizacji)
• Parametry URL: complaintId (UUID)
• Body (Request): UpdateComplaintControllerRequest — patrz sekcja 4.3
• Response (sukces): 200 — "The Complaint has been successfully updated"

PATCH /api/complaints/{complaintId}/change-status¶

• Opis: Zmiana statusu reklamacji
• Autoryzacja: Rola ADMIN|SUPERVISOR|EMPLOYEE + Policy update
• Parametry URL: complaintId (UUID)
• Body (Request): ChangeStatusComplaintControllerRequest

{
  "status": "in_progress"
}

• Response (sukces): 200 — standardowa odpowiedź z changeStatusXController
• Reguły biznesowe: Używa generycznej metody changeStatusXController z TraitControllerSupport

PATCH /api/complaints/{complaintId}/assign-supervisor¶

• Opis: Przypisanie opiekuna do reklamacji
• Autoryzacja: Rola ADMIN|SUPERVISOR|EMPLOYEE + Policy update
• Parametry URL: complaintId (UUID)
• Body (Request): AssignSupervisorComplaintControllerRequest

{
  "supervisor_id": "uuid-of-user"
}

• Response (sukces): 200 — "Supervisor has been successfully assigned to the complaint"
• Reguły biznesowe: Opiekun musi być pracownikiem organizacji powiązanej z reklamacją (VerifySupervisorIsInOrganizationRule)

GET /api/complaint-messages¶

• Opis: Lista wiadomości dla danej reklamacji
• Autoryzacja: Brak wymogu roli (weryfikacja przez complaint_id + complaint_uuid + complaint_access_code)
• Query Parameters: Paginacja + complaint_id (required), complaint_uuid (required), complaint_access_code (required)
• Response (sukces): Paginowana kolekcja ComplaintMessageResource

POST /api/complaint-messages¶

• Opis: Dodanie wiadomości do reklamacji
• Autoryzacja: Brak wymogu roli
• Body (Request): StoreComplaintMessageControllerRequest — patrz sekcja 4.3
• Response (sukces): 200 — "The Complaint message has been successfully added"

GET /api/complaint-attachments¶

• Opis: Lista załączników reklamacji
• Autoryzacja: Brak wymogu roli (weryfikacja przez complaint_id + complaint_uuid + complaint_access_code)
• Response (sukces): Kolekcja ComplaintAttachmentResource

POST /api/complaint-attachments¶

• Opis: Dodanie załączników do reklamacji
• Autoryzacja: Brak wymogu roli (weryfikacja przez dane reklamacji)
• Body (Request): StoreComplaintAttachmentControllerRequest — patrz sekcja 4.3
• Response (sukces): 201 — kolekcja ComplaintAttachmentResource

DELETE /api/complaint-attachments/{attachmentId}¶

• Opis: Usunięcie załącznika
• Autoryzacja: Brak wymogu roli (weryfikacja przez dane reklamacji)
• Parametry URL: attachmentId (UUID)
• Body (Request): DeleteComplaintAttachmentControllerRequest (wymaga complaint_id, complaint_uuid, complaint_access_code)
• Response (sukces): 200 — "Attachment deleted successfully"

3.2 Endpointy publiczne (noAuth)¶

Middleware bazowe: require_app_client, global_database_transaction, app_mode, check_site_enable, set_locale, security_headers, throttle:api.

Route names (noAuth): no-auth-complaints.store, no-auth-complaints.find, no-auth-complaint-messages.index, no-auth-complaint-messages.store, no-auth-complaint-attachments.index, no-auth-complaint-attachments.store, no-auth-complaint-attachments.delete.

4. Logika biznesowa¶

4.1 Główne procesy¶

Proces tworzenia reklamacji¶

sequenceDiagram
    participant K as Klient
    participant S as System
    participant A as Administrator
    participant E as Email

    K->>S: Składa reklamację (po rezerwacji)
    S->>S: Generuje UUID i kod dostępu
    S->>S: Kopiuje dane z rezerwacji (imię, email, telefon)
    S->>E: Wysyła potwierdzenie z kodem
    E-->>K: Email z kodem i linkiem
    S->>A: Nowa reklamacja w panelu
    A->>S: Przypisuje opiekuna
    S->>E: Powiadomienie dla opiekuna
    A->>S: Odpowiada klientowi
    S->>E: Email do klienta
    E-->>K: Odpowiedź od obsługi

1. Klient po rezerwacji składa reklamację podając reservation_id, reservation_uuid i reservation_access_code
2. CreatingComplaintObserver generuje unikalny uuid (UUID v4) i access_code (10 znaków, wielkie litery via Str::random(10))
3. Dane kontaktowe (first_name, last_name, email, mobile_phone) są automatycznie kopiowane z rezerwacji, jeśli nie zostały podane
4. organization_id jest automatycznie ustawiany z rezerwacji
5. Domyślny status: new
6. CreatedComplaintObserver wysyła ComplaintCreatedNotification do klienta (email)
7. Jeśli przypisano opiekuna — ComplaintNewSupervisorNotification do opiekuna

Proces wymiany wiadomości¶

flowchart TD
    A[Nowa wiadomość] --> B{Kto pisze?}
    B -->|Zalogowany użytkownik| C[author_type = staff]
    C --> D[Ustaw author_name z user.name]
    B -->|Niezalogowany klient| E[author_type = resident]
    E --> F[Ustaw author_name z complaint.first_name + last_name]
    D --> G{Czy poprzednia wiadomość<br>od tego samego autora?}
    F --> G
    G -->|Tak| H[Nie wysyłaj powiadomienia]
    G -->|Nie| I{Kto jest odbiorcą?}
    I -->|Klient pisał| J[Email do opiekuna]
    I -->|Opiekun pisał| K[Email do klienta]

Logika powiadomień (SendComplaintMessageCreatedNotification):

1. Sprawdza czy poprzednia wiadomość w wątku (last by created_at) ma inny author_email niż bieżąca
2. Jeśli ten sam email — powiadomienie nie jest wysyłane (zapobiega podwójnym powiadomieniom)
3. Jeśli autor to resident → email do supervisor.email
4. Jeśli autor to staff → email do complaint.email (klient)

Proces śledzenia statusu (dostęp publiczny)¶

1. Klient otwiera link z emaila
2. Endpoint GET /api/no-auth/complaints/{complaintId}/find wymaga uuid i access_code
3. FindComplaintUUIDAccessCode szuka reklamacji po uuid, access_code i id
4. ExceptionFindComplaintUUIDAccessCode sprawdza rate limiting (checkAccessLockout, rateLimitAccessAttempt)
5. Przy niepowodzeniu — rzuca FindComplaintUUIDAccessCodeException (409)

4.2 Reguły biznesowe¶

1. Rezerwacja musi być potwierdzona — status rezerwacji musi być confirmed (ReservationStillToComplaintRule)
2. Rezerwacja musi być zakończona — end_at musi być w przeszłości
3. Termin złożenia — maksymalnie MAX_DAY_TO_ADD_COMPLAINT dni od zakończenia rezerwacji (konfigurowalny)
4. Weryfikacja rezerwacji — wymagane reservation_id, reservation_uuid i reservation_access_code (VerifyReservationCorrectDataRule)
5. Opiekun musi być pracownikiem organizacji — walidacja VerifySupervisorIsInOrganizationRule sprawdza existOrganizationEmployee()
6. Niezalogowani nie mogą przypisać opiekuna — CreatingComplaintObserver ustawia supervisor_id = null jeśli !auth()->check()
7. Automatyczne kopiowanie danych z rezerwacji — organization_id zawsze, first_name, last_name, email, mobile_phone tylko jeśli puste
8. Automatyczne zarządzanie rozwiązaniem — UpdatingComplaintObserver: status resolved → ustawia resolved_at + resolved_by; inny status → czyści te pola
9. Powiadomienia o istotnych zmianach — UpdatedComplaintObserver wysyła ComplaintUpdatedNotification tylko gdy zmienione pola to nie supervisor_id i nie updated_at
10. Rate limiting dostępu publicznego — ExceptionFindComplaintUUIDAccessCode używa checkAccessLockout i rateLimitAccessAttempt dla resource type RATE_LIMIT_RESOURCE_COMPLAINT
11. Honeypot antyspamowy — przy tworzeniu przez niezalogowanego: pola website, company_website, fax_number muszą być puste (max:0)
12. Filtr wulgaryzmów — pola author_name, author_email i message w wiadomościach walidowane regułą blasp_check

4.3 Walidacje¶

StoreComplaintControllerRequest (Tworzenie reklamacji)¶

UpdateComplaintControllerRequest (Aktualizacja reklamacji)¶

ChangeStatusComplaintControllerRequest (Zmiana statusu)¶

AssignSupervisorComplaintControllerRequest (Przypisanie opiekuna)¶

FindComplaintControllerRequest (Podgląd reklamacji)¶

StoreComplaintMessageControllerRequest (Dodanie wiadomości)¶

IndexComplaintMessageControllerRequest (Lista wiadomości)¶

StoreComplaintAttachmentControllerRequest (Dodanie załączników)¶

IndexComplaintAttachmentControllerRequest (Lista załączników)¶

DeleteComplaintAttachmentControllerRequest (Usunięcie załącznika)¶

5. Autoryzacja i uprawnienia¶

Middleware roli¶

Kontroler ComplaintController stosuje middleware role:ADMIN|SUPERVISOR|EMPLOYEE na metodach: index, show, update, changeStatus, assignSupervisor.

Metoda store jest dostępna bez roli — zarówno dla zalogowanych jak i niezalogowanych użytkowników.

Kontrolery ComplaintMessageController i ComplaintAttachmentController nie mają middleware roli — dostęp jest kontrolowany przez weryfikację complaint_id + complaint_uuid + complaint_access_code.

Laravel Policies¶

ComplaintPolicy (app/Domain/Complaint/Policy/ComplaintPolicy.php)¶

ComplaintMessagePolicy (app/Domain/Complaint/Policy/ComplaintMessagePolicy.php)¶

Matryca uprawnień¶

6. Eventy i efekty uboczne¶

ComplaintObserver¶

ComplaintMessageObserver¶

7. Powiadomienia¶

Wszystkie powiadomienia są wysyłane asynchronicznie przez SimpleSendNotificationJob (kolejka) kanałem mail.

8. Powiązania z innymi domenami¶

9. Konfiguracja¶

10. Znane ograniczenia i TODO¶

Struktura domeny¶

app/Domain/Complaint/
├── Action/
│   ├── Controller/
│   │   ├── AssignSupervisorComplaintController.php  # Przypisanie opiekuna
│   │   ├── DeleteComplaintAttachmentController.php  # Usuwanie załącznika
│   │   ├── FindComplaintController.php              # Znajdź reklamację (publiczny)
│   │   ├── IndexComplaintAttachmentController.php   # Lista załączników
│   │   ├── IndexComplaintController.php             # Lista reklamacji
│   │   ├── IndexComplaintMessageController.php      # Lista wiadomości
│   │   ├── ShowComplaintController.php              # Szczegóły reklamacji
│   │   ├── StoreComplaintAttachmentController.php   # Dodawanie załączników
│   │   ├── StoreComplaintController.php             # Tworzenie reklamacji
│   │   ├── StoreComplaintMessageController.php      # Dodawanie wiadomości
│   │   └── UpdateComplaintController.php            # Aktualizacja reklamacji
│   └── Other/
│       ├── CreateComplaint.php                      # Tworzenie + załączniki
│       ├── CreateComplaintAttachments.php            # Upload plików (Spatie Media)
│       ├── CreateComplaintMessage.php                # Tworzenie wiadomości
│       ├── CreatedComplaintMessageObserver.php       # Powiadomienie po wiadomości
│       ├── CreatedComplaintObserver.php              # Powiadomienie po utworzeniu
│       ├── CreatingComplaintMessageObserver.php      # Auto-uzupełnianie autora
│       ├── CreatingComplaintObserver.php             # UUID, kod, dane z rezerwacji
│       ├── ExceptionFindComplaintUUIDAccessCode.php  # Rate limiting dostępu
│       ├── FindComplaintUUIDAccessCode.php           # Wyszukiwanie po UUID+kod
│       ├── SendComplaintMessageCreatedNotification.php # Logika powiadomień wiadomości
│       ├── UpdateComplaint.php                      # Aktualizacja danych
│       ├── UpdatedComplaintObserver.php             # Powiadomienia po aktualizacji
│       └── UpdatingComplaintObserver.php            # resolved_at/resolved_by
├── Controller/
│   ├── ComplaintAttachmentController.php            # Kontroler załączników
│   ├── ComplaintController.php                      # Główny kontroler
│   └── ComplaintMessageController.php               # Kontroler wiadomości
├── Model/
│   ├── Complaint.php                                # Model reklamacji
│   └── ComplaintMessage.php                         # Model wiadomości
├── Notification/
│   ├── ComplaintCreatedNotification.php              # Email: reklamacja utworzona
│   ├── ComplaintMessageCreatedNotification.php       # Email: nowa wiadomość
│   ├── ComplaintNewSupervisorNotification.php        # Email: nowy opiekun
│   └── ComplaintUpdatedNotification.php              # Email: aktualizacja
├── Observer/
│   ├── ComplaintMessageObserver.php                  # Observer wiadomości (creating, created)
│   └── ComplaintObserver.php                         # Observer reklamacji (creating, created, updating, updated)
├── Policy/
│   ├── ComplaintMessagePolicy.php                    # Polityka wiadomości
│   └── ComplaintPolicy.php                           # Polityka reklamacji
├── Request/
│   ├── AssignSupervisorComplaintControllerRequest.php
│   ├── ChangeStatusComplaintControllerRequest.php
│   ├── DeleteComplaintAttachmentControllerRequest.php
│   ├── FindComplaintControllerRequest.php
│   ├── IndexComplaintAttachmentControllerRequest.php
│   ├── IndexComplaintControllerRequest.php
│   ├── IndexComplaintMessageControllerRequest.php
│   ├── Rule/
│   │   ├── RequiredWhenNotAuthenticatedRule.php       # Pole wymagane gdy niezalogowany
│   │   ├── ReservationStillToComplaintRule.php        # Warunki złożenia reklamacji
│   │   ├── VerifyComplaintCorrectDataRule.php         # Weryfikacja UUID+kod
│   │   └── VerifySupervisorIsInOrganizationRule.php   # Opiekun z organizacji
│   ├── StoreComplaintAttachmentControllerRequest.php
│   ├── StoreComplaintControllerRequest.php
│   ├── StoreComplaintMessageControllerRequest.php
│   └── UpdateComplaintControllerRequest.php
├── Resource/
│   ├── ComplaintAttachmentResource.php               # JSON załącznika
│   ├── ComplaintMessageResource.php                  # JSON wiadomości
│   └── ComplaintResource.php                         # JSON reklamacji
└── Service/
    ├── ComplaintEnumService.php                       # Statusy, typy, priorytety, typy autorów
    ├── TraitComplaint.php                            # Metody domenowe
    └── TraitControllerComplaint.php                  # Metody kontrolera

Enumy (ComplaintEnumService)¶

Statusy reklamacji¶

Typy reklamacji¶

Priorytety¶

Typy autorów wiadomości¶

Workflow reklamacji¶

stateDiagram-v2
    [*] --> new: Złożenie reklamacji
    new --> in_progress: Podjęcie sprawy
    in_progress --> resolved: Rozwiązanie problemu
    resolved --> closed: Zamknięcie sprawy
    in_progress --> new: Ponowne otwarcie
    resolved --> in_progress: Ponowne otwarcie

Odpowiedź API (Resource)¶

ComplaintResource¶

Automatycznie ładowane relacje: reservation, organization, supervisor, solver.

Pola niedostępne dla niezalogowanych: can.

ComplaintMessageResource¶

Pola niedostępne dla niezalogowanych: can.

ComplaintAttachmentResource¶