Opinie (Review)¶

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

1. Opis ogólny¶

Domena Opinii zarządza ocenami i komentarzami klientów po zakończonych rezerwacjach. To jak książka gości w hotelu — po zakończonej rezerwacji klient może wystawić ocenę (1–5 gwiazdek) i napisać komentarz, który pomoże innym w wyborze obiektu lub zajęć. System obsługuje polimorficzne opinie (przypisywane do obiektów Item lub aktywności Activity), moderację przez administratorów oraz automatyczne przypomnienia o wystawieniu opinii.

2. Architektura domeny¶

2.1 Model danych — Review¶

Fillable:

Filtry publiczne ($publicFilters): id, reviewable_type, reviewable_id, organization_id, reservation_id, rating

Relacje:

Relacje odwrotne w innych modelach:

2.2 Diagram relacji¶

erDiagram
    Review ||--o| Reservation : "reservation_id"
    Review }o--|| Organization : "organization_id"
    Review }o--o| User : "disabled_by"
    Review }o--|| Item : "reviewable (morph)"
    Review }o--|| Activity : "reviewable (morph)"

    Reservation ||--o| Review : "hasOne"
    Item ||--o{ Review : "morphMany"
    Activity ||--o{ Review : "morphMany"
    Organization ||--o{ Review : "hasMany"

2.3 Struktura tabeli reviews¶

Indeksy: organization_id (index), reservation_id (index + unique), reviewable_type + reviewable_id (morph index)

Klucze obce:

• organization_id → organizations.id ON DELETE CASCADE
• reservation_id → reservations.id ON DELETE CASCADE
• disabled_by → users.id ON DELETE SET NULL

3. Endpointy API¶

3.1 Endpointy publiczne (bez autoryzacji)¶

GET /api/reviews¶

• Opis: Lista opinii z filtrowaniem i paginacją (publiczny dostęp)
• Route name: no-auth-reviews.index
• Autoryzacja: Brak — endpoint publiczny
• Kontroler: ReviewController@index → IndexReviewController
• Request: IndexReviewControllerRequest

Query Parameters:

Eager loading: reviewable, reservation, organization, disabler, reservation.latestNote, reviewable.media

Response (sukces, 200):

{
  "data": [
    {
      "id": "uuid",
      "reviewable_type": "Domain\\Item\\Model\\Item",
      "reviewable_id": "uuid",
      "organization_id": "uuid",
      "rating": 4,
      "comment": "Świetne wyposażenie",
      "can_be_edit": true,
      "is_active": true,
      "created_at": "2026-02-20 14:30:00",
      "updated_at": "2026-02-20 14:30:00",
      "reviewable": { "..." },
      "organization": { "..." }
    }
  ],
  "meta": { "..." }
}

POST /api/reviews¶

• Opis: Dodanie nowej opinii do rezerwacji (publiczny dostęp)
• Route name: no-auth-reviews.store
• Autoryzacja: Brak — endpoint publiczny
• Middleware: throttle:public-store (rate limiting)
• Kontroler: ReviewController@store → StoreReviewController → CreateReview
• Request: StoreReviewControllerRequest

Body (Request):

Reguły biznesowe (walidacja):

Response (sukces, 200):

{
  "message": "The Review has been successfully added",
  "status": 200
}

Response (błędy, 422):

{
  "message": "Sorry, the reservation you are trying to access has already been reviewed.",
  "errors": {
    "reservation_id": ["Sorry, the reservation you are trying to access has already been reviewed."]
  }
}

Możliwe błędy walidacji:

3.2 Endpointy uwierzytelnione¶

GET /api/reviews (auth)¶

• Opis: Lista opinii z filtrowaniem — wersja uwierzytelniona (pełne dane)
• Autoryzacja: Brak wymogu roli (wszyscy zalogowani użytkownicy)
• Kontroler: ReviewController@index → IndexReviewController
• Request: IndexReviewControllerRequest
• Zachowanie: Identyczne jak endpoint publiczny, ale odpowiedź zawiera wszystkie pola (w tym reservation, disabled_by, disabled_at, can)

GET /api/reviews/{reviewId} (auth)¶

• Opis: Szczegóły pojedynczej opinii
• Autoryzacja: role:ADMIN|SUPERVISOR|EMPLOYEE
• Kontroler: ReviewController@show → ShowReviewController
• Eager loading: reviewable, reservation, organization, disabler, reservation.latestNote, reviewable.media

Response (sukces, 200):

{
  "data": {
    "id": "uuid",
    "reviewable_type": "Domain\\Item\\Model\\Item",
    "reviewable_id": "uuid",
    "organization_id": "uuid",
    "reservation_id": "uuid",
    "rating": 4,
    "comment": "Świetne wyposażenie, klimatyzacja działa doskonale",
    "can_be_edit": true,
    "is_active": true,
    "disabled_by": null,
    "disabled_at": null,
    "created_at": "2026-02-20 14:30:00",
    "updated_at": "2026-02-20 14:30:00",
    "can": {
      "view": true,
      "update": true
    },
    "reviewable": { "..." },
    "reservation": { "..." },
    "organization": { "..." },
    "disabler": null
  }
}

Response (błąd, 404): NotFoundModelException — opinia nie istnieje

PATCH /api/reviews/{reviewId}/change-state (auth)¶

• Opis: Zmiana widoczności opinii (aktywacja/dezaktywacja)
• Autoryzacja: role:ADMIN|SUPERVISOR|EMPLOYEE + Policy update (użytkownik musi należeć do organizacji opinii)
• Kontroler: ReviewController@changeState → changeStateXController
• Zachowanie: Przełącza pole is_active na przeciwną wartość. Wywołuje event updating na modelu (withEvents = true), co triggeruje UpdatingReviewObserver — automatycznie ustawia disabled_by i disabled_at.

Response (sukces, 200):

{
  "message": "State changed successfully",
  "status": 200
}

POST /api/reviews (auth)¶

• Opis: Dodanie opinii (wersja uwierzytelniona)
• Autoryzacja: Brak wymogu roli — dostępne dla wszystkich zalogowanych
• Zachowanie: Identyczne jak endpoint publiczny, ale bez pól honeypot (walidacja honeypot stosowana tylko dla niezalogowanych)

4. Logika biznesowa¶

4.1 Główne procesy¶

Proces tworzenia opinii¶

sequenceDiagram
    participant K as Klient
    participant V as Walidacja
    participant O as Observer
    participant DB as Baza danych

    K->>V: POST /api/reviews (dane + kody dostępu)
    V->>V: VerifyReservationCorrectDataRule
    V->>V: ReservationStillReviewableRule
    V->>V: blasp_check (komentarz)
    V->>V: Honeypot (jeśli no-auth)

    alt Walidacja OK
        V->>O: CreatingReviewObserver
        O->>O: Ustal reviewable_type/id z rezerwacji
        O->>O: Ustal organization_id z rezerwacji
        O->>DB: Zapisz opinię
        DB-->>K: 200 + komunikat sukcesu
    else Walidacja błąd
        V-->>K: 422 + komunikat błędu
    end

1. Klient wysyła dane opinii wraz z reservation_id, reservation_uuid i reservation_access_code
2. VerifyReservationCorrectDataRule weryfikuje, że trójka identyfikatorów odpowiada istniejącej rezerwacji
3. ReservationStillReviewableRule sprawdza:
   • Rezerwacja nie ma jeszcze opinii
   • Rezerwacja się zakończyła (slot date_time_to w przeszłości)
   • Nie upłynął limit MAX_DAY_TO_ADD_REVIEW dni
4. Filtr blasp_check sprawdza komentarz pod kątem nieodpowiednich słów
5. Pola honeypot (tylko no-auth) — odrzucenie bota
6. CreatingReviewObserver automatycznie uzupełnia:
   • reviewable_type i reviewable_id — na podstawie reservationable_type rezerwacji (Item → Item, ActivityItem → Activity)
   • organization_id — z rezerwacji
7. Opinia jest tworzona jako hasOne na rezerwacji ($reservation->review()->create(...))

Proces moderacji opinii¶

sequenceDiagram
    participant A as Administrator
    participant S as System
    participant O as UpdatingReviewObserver
    participant DB as Baza danych

    A->>S: PATCH /reviews/{id}/change-state
    S->>S: Autoryzacja (role + policy)
    S->>O: UpdatingReviewObserver
    alt Dezaktywacja (is_active: true → false)
        O->>DB: disabled_by = Auth::id()
        O->>DB: disabled_at = now()
    else Aktywacja (is_active: false → true)
        O->>DB: disabled_by = null
        O->>DB: disabled_at = null
    end
    DB-->>A: 200 sukces

4.2 Reguły biznesowe¶

1. Jedna opinia na rezerwację — kolumna reservation_id ma constraint UNIQUE
2. Opinia tylko po zakończeniu rezerwacji — wszystkie sloty muszą się zakończyć przed dodaniem opinii
3. Limit czasowy — opinia musi zostać dodana w ciągu MAX_DAY_TO_ADD_REVIEW dni od zakończenia rezerwacji (parametr konfigurowalny)
4. Weryfikacja tożsamości — wymagane podanie reservation_id + reservation_uuid + reservation_access_code
5. Filtr blasfemii — komentarze sprawdzane regułą blasp_check
6. Ochrona antyspamowa — honeypot dla niezalogowanych, rate limiting throttle:public-store
7. Automatyczne przypisanie obiektu — observer ustala reviewable_type/id i organization_id na podstawie rezerwacji
8. Polimorficzność obiektu — Item przypisywany bezpośrednio, ActivityItem → przypisywana Activity (rodzic)
9. Śledzenie moderacji — przy dezaktywacji automatycznie zapisywany jest moderator (disabled_by) i czas (disabled_at)
10. Reaktywacja — przy ponownej aktywacji pola disabled_by i disabled_at są czyszczone

4.3 Walidacje¶

StoreReviewControllerRequest¶

IndexReviewControllerRequest¶

Standardowe reguły paginacji (paginationDefaultRequestRules()) + filtry publiczne modelu Review (publicFilterRequestRules()).

5. Autoryzacja i uprawnienia¶

5.1 Policy — ReviewPolicy¶

5.2 Middleware na endpointach¶

5.3 Matryca uprawnień¶

6. Observery i efekty uboczne¶

6.1 ReviewObserver¶

Plik: Domain\Review\Observer\ReviewObserver Rejestracja: Atrybut #[ObservedBy(ReviewObserver::class)] na modelu

6.2 CreatingReviewObserver — szczegóły¶

1. Sprawdza, czy opinia ma reservation_id i czy rezerwacja istnieje
2. Na podstawie reservationable_type rezerwacji określa reviewable:
   • Item::class → obiekt bezpośrednio
   • ActivityItem::class → $res->reservationable->activity (nadrzędna aktywność)
   • inne → null (brak przypisania)
3. Ustawia reviewable_type, reviewable_id, organization_id na modelu opinii

6.3 UpdatingReviewObserver — szczegóły¶

1. Sprawdza, czy pole is_active uległo zmianie (isDirty)
2. Jeśli dezaktywacja (is_active → false):
   • disabled_by = ID zalogowanego użytkownika
   • disabled_at = aktualny czas
3. Jeśli aktywacja (is_active → true):
   • disabled_by = null
   • disabled_at = null

7. Notyfikacje — przypomnienie o opinii¶

Przypomnienie o opinii jest obsługiwane przez domenę Reservation, nie Review:

7.1 Warunki wysłania przypomnienia¶

7.2 Treść powiadomienia¶

• Temat: "Zaproszenie do wystawienia opinii - rezerwacja nr {uuid}"
• Treść: Podziękowanie za skorzystanie z usług + zachęta do wystawienia opinii
• Dane: Numer rezerwacji, kod dostępu, nazwa usługi, data
• Przycisk CTA: "Wystaw opinię" → link do frontendu /rezerwacje/{id}?uuid={uuid}&access_code=

7.3 Po wysłaniu¶

Pole review_reminder_sent_at na rezerwacji jest ustawiane na aktualny czas — zapobiega wielokrotnemu wysyłaniu.

8. Powiązania z innymi domenami¶

8.1 Statystyki opinii (domena Statistic)¶

GetReviewStatistics¶

Zwraca: - total — łączna liczba opinii - average_rating — średnia ocena - by_rating — rozkład ocen (1–5) - with_comment — liczba opinii z komentarzem - without_comment — liczba opinii bez komentarza

Filtrowanie: zakres dat (date_from, date_to), lista itemIds.

GetRecentReviews¶

Zwraca ostatnie aktywne opinie (domyślnie 10), z relacjami reservation, reviewable, organization.

8.2 Raport opinii (domena Report)¶

Klucz raportu: reviews.summary

Filtry:

Kolumny raportu: Nazwa obiektu, Średnia ocena, Liczba opinii, 5 gwiazdek, 4 gwiazdki, 3 gwiazdki, 2 gwiazdki, 1 gwiazdka

8.3 Atrybuty obliczeniowe (Support)¶

GetTotalReviewsAttr¶

Oblicza łączną liczbę aktywnych opinii (is_active = true) dla modelu. Optymalizacja: 1. Wykorzystuje reviews_count jeśli dostępny (agregat) 2. Filtruje załadowaną relację jeśli dostępna 3. W ostateczności wykonuje loadCount z filtrem

GetAvgReviewsAttr¶

Oblicza średnią ocenę aktywnych opinii. Analogiczna optymalizacja jak wyżej, z zaokrągleniem do 2 miejsc po przecinku.

9. Konfiguracja¶

Parametr jest odczytywany przez TraitConfiguration::getConfigurationBySlug() w ReservationStillReviewableRule.

10. Zabezpieczenia¶

11. Skala ocen¶

12. Co mozna oceniac?¶

System obsługuje opinie dla dwóch typów encji (ustalanych automatycznie przez CreatingReviewObserver):

Obiekty (Item)¶

Zajecia (Activity)¶

13. Dane demo (Seeder)¶

ReservationSeeder automatycznie tworzy opinie dla ~30% zakończonych rezerwacji z losowymi ocenami (1–5) i komentarzami. Observer ReviewObserver automatycznie ustala reviewable_type/id i organization_id na podstawie rezerwacji.

14. Pliki domeny — struktura¶

app/Domain/Review/
├── Action/
│   ├── Controller/
│   │   ├── IndexReviewController.php      # Lista opinii z filtrowaniem
│   │   ├── ShowReviewController.php       # Szczegóły opinii
│   │   └── StoreReviewController.php      # Tworzenie opinii
│   └── Other/
│       ├── CreateReview.php               # Logika tworzenia opinii
│       ├── CreatingReviewObserver.php      # Observer: ustalanie reviewable/organization
│       └── UpdatingReviewObserver.php      # Observer: śledzenie moderacji
├── Controller/
│   └── ReviewController.php               # Główny kontroler
├── Model/
│   └── Review.php                         # Model Eloquent
├── Observer/
│   └── ReviewObserver.php                 # Dispatcher observerów
├── Policy/
│   └── ReviewPolicy.php                   # Polityka autoryzacji
├── Request/
│   ├── IndexReviewControllerRequest.php   # Walidacja listy
│   ├── StoreReviewControllerRequest.php   # Walidacja tworzenia
│   └── Rule/
│       ├── ReservationStillReviewableRule.php   # Limit czasowy + deduplikacja
│       └── VerifyReservationCorrectDataRule.php # Weryfikacja kodów rezerwacji
├── Resource/
│   └── ReviewResource.php                 # Transformacja JSON
└── Service/
    ├── ReviewEnumService.php              # Enum (pusty — brak case'ów)
    ├── TraitReview.php                    # Trait serwisowy
    └── TraitControllerReview.php          # Trait kontrolera

16. Historia zmian¶