Powiadomienia (Notification)¶

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

1. Opis ogolny¶

Domena Powiadomien odpowiada za automatyczne informowanie uzytkownikow o zdarzeniach w systemie. To jak sekretarka, ktora wysyla wszystkie potwierdzenia — od utworzenia rezerwacji, przez platnosc, az po prosbe o opinie.

System obsluguje 39 typow powiadomien rozproszonych po 11 domenach biznesowych, z centralnym mechanizmem wysylania opartym na kolejkach. Kazde powiadomienie wysylane jest asynchronicznie i zapisywane w bazie danych.

Kanaly komunikacji:

• Email — sformatowane wiadomosci HTML z przyciskiem akcji
• Baza danych — zapis do odczytu w panelu administratora

2. Architektura domeny¶

2.1 Modele danych¶

Notification¶

Model glowny rozszerzajacy DatabaseNotification. Wykorzystuje UUID jako klucz glowny.

Cechy modelu:

• Uzywa traitu HasUuids — automatyczne generowanie UUID
• Obserwowany przez NotificationObserver (obecnie pusty — placeholder)
• Relacja polimorficzna notifiable() (MorphTo) — moze wskazywac na dowolny model
• Casty dat: format Y-m-d H:i:s
• Activity log wylaczony (dontSubmitEmptyLogs)

DatabaseNotification (klasa bazowa)¶

Rozszerza CustomModel, dostarcza metody zarzadzania stanem odczytu:

2.2 Diagram relacji¶

classDiagram
    class Notification {
        +UUID id
        +string type
        +string notifiable_type
        +UUID notifiable_id
        +JSON data
        +timestamp read_at
        +markAsRead()
        +markAsUnread()
        +read() bool
        +unread() bool
    }

    class CustomNotification {
        +string subject
        +string content
        +array action
        +via() array
        +toMail() MailMessage
        +toArray() array
    }

    class SendNotification {
        +__invoke(user, channel, mail, class, params)
    }

    class SimpleSendNotification {
        +__invoke(channel, mails, class, params)
    }

    class SendNotificationJob {
        +handle()
    }

    Notification --|> DatabaseNotification : extends
    CustomNotification --|> LaravelNotification : extends
    SendNotification --> Notification : creates record
    SimpleSendNotification --> SendNotificationJob : dispatches
    SendNotificationJob --> SendNotification : calls

2.3 Struktura tabel w bazie danych¶

Tabela: notifications

Migracja: 0001_01_01_000009_create_notifications.php

3. Endpointy API¶

Wszystkie endpointy wymagaja uwierzytelnienia (auth:api) i jednej z rol: ADMIN, SUPERVISOR, EMPLOYEE.

3.1 Lista powiadomien¶

GET /api/notifications¶

• Opis: Pobiera liste powiadomien z filtrowaniem i paginacja
• Autoryzacja: ADMIN widzi wszystkie powiadomienia; SUPERVISOR/EMPLOYEE widza tylko swoje (filtrowane po notifiable_type = User i notifiable_id = auth_id)
• Controller: NotificationController@index → IndexNotificationController
• Request: IndexNotificationControllerRequest

Query Parameters:

Walidacja (FormRequest):

Reguly paginacji dziedziczone z paginationDefaultRequestRules() (TraitSupport).

Response (sukces — 200):

{
  "data": [
    {
      "id": "uuid-string",
      "type": "ReservationCreatedNotification",
      "notifiable_type": "User",
      "notifiable_id": "uuid-string",
      "data": {
        "subject": "Potwierdzenie rezerwacji nr ABC123",
        "content": "<p>Dziekujemy za dokonanie rezerwacji...</p>"
      },
      "can_be_edit": true,
      "read_at": "2026-02-26 10:30:00",
      "created_at": "2026-02-26 10:00:00",
      "updated_at": "2026-02-26 10:30:00"
    }
  ],
  "meta": { "current_page": 1, "per_page": 15, "total": 42 }
}

Relacje ladowane: notifiable

3.2 Oznacz wszystkie jako przeczytane¶

PATCH /api/read-notifications¶

• Opis: Oznacza wszystkie nieprzeczytane powiadomienia zalogowanego uzytkownika jako przeczytane
• Autoryzacja: ADMIN, SUPERVISOR, EMPLOYEE
• Controller: NotificationController@read → ReadNotificationController
• Body: Brak

Response (sukces — 200):

{
  "message": "Notifications have been successfully updated",
  "status": 200
}

3.3 Oznacz pojedyncze jako przeczytane¶

PATCH /api/notifications/{notificationId}/set-read¶

• Opis: Oznacza konkretne powiadomienie jako przeczytane
• Autoryzacja: ADMIN, SUPERVISOR, EMPLOYEE
• Controller: NotificationController@setRead → ReadNotificationController
• Parametry URL: notificationId (UUID)

Response (sukces — 200):

{
  "message": "Notifications have been successfully updated",
  "status": 200
}

4. Logika biznesowa¶

4.1 Glowne procesy¶

Proces wysylania powiadomienia¶

sequenceDiagram
    participant D as Domena (Akcja/Observer)
    participant T as TraitSupport
    participant J as SendNotificationJob
    participant Q as Kolejka (notifications)
    participant S as SendNotification
    participant N as CustomNotification
    participant M as Mail
    participant DB as Baza danych

    D->>T: sendNotification(user, channel, mail, class, params)
    T->>J: dispatch(...).onQueue('notifications')
    J-->>Q: Zadanie w kolejce
    Q->>S: __invoke(user, channel, mail, class, params)
    S->>S: shouldSkipReservationNotification?
    alt Pomijanie wlaczone
        S-->>S: return (nie wysyla)
    end
    S->>N: new NotificationClass(...params)
    alt Uzytkownik istnieje
        S->>N: user->notify(notification)
        N->>M: toMail() — email HTML
        N->>DB: toArray() — zapis do tabeli notifications
    else Brak uzytkownika (np. klient bez konta)
        S->>N: Notification::route(channel, mail)->notify()
        S->>S: getNotifiableFromParamsNotification()
        S->>DB: Notification::create() — reczny zapis
    end

Proces masowego wysylania (SimpleSendNotification)¶

Uzywany np. przy aktualizacji dokumentow prawnych (wysylka do wszystkich klientow):

sequenceDiagram
    participant A as Akcja domenowa
    participant SS as SimpleSendNotification
    participant J as SendNotificationJob
    participant Q as Kolejka

    A->>SS: __invoke(channel, [emails], class, params)
    loop Dla kazdego emaila
        SS->>J: dispatch(user, channel, email, class, params)
        J-->>Q: Zadanie w kolejce
    end

4.2 Reguly biznesowe¶

1. Asynchronicznosc — wszystkie powiadomienia wysylane sa przez kolejke notifications, nie blokuja uzytkownika
2. Pomijanie powiadomien — rezerwacje z flaga send_notifications = false pomijaja wysylke powiadomien rezerwacyjnych i reklamacyjnych
3. Kontrola dostepu — administratorzy widza wszystkie powiadomienia; pozostale role widza tylko swoje
4. Kanaly — domyslnie ['mail', 'database']; niektore powiadomienia nadpisuja na ['mail'] (np. PinApprovedNotification)
5. Automatyczne czyszczenie — powiadomienia starsze niz REMOVE_NOTIFICATIONS_OLDER_THAN_DAYS dni sa usuwane przez komende CRON
6. Polimorfizm — powiadomienia moga byc przypisane do dowolnego modelu przez notifiable_type / notifiable_id
7. Zapis dla klientow bez konta — jesli odbiorca nie ma konta User, system recznie tworzy rekord w tabeli notifications z odpowiednim notifiable_type i notifiable_id

4.3 Mechanizm pomijania powiadomien (Skip Logic)¶

Klasa ShouldSkipReservationNotification sprawdza:

• Dla powiadomien z Domain\Reservation\Notification\ — czy rezerwacja ma send_notifications = false
• Dla powiadomien z Domain\Complaint\Notification\ — czy powiazana rezerwacja ma send_notifications = false

Jesli warunek spelniony — powiadomienie nie jest wysylane.

4.4 Walidacje¶

IndexNotificationControllerRequest¶

Autoryzacja: authorize() zwraca true — kontrola dostepu realizowana na poziomie middleware (role) i w akcji kontrolera (filtrowanie per uzytkownik).

5. Autoryzacja i uprawnienia¶

6. Typy powiadomien¶

System zawiera 39 typow powiadomien rozproszonych po 11 domenach:

6.1 Rezerwacje (18 powiadomien)¶

6.2 Uzytkownicy (5 powiadomien)¶

6.3 Reklamacje (4 powiadomienia)¶

6.4 Dostep PIN (3 powiadomienia)¶

6.5 Organizacje (2 powiadomienia)¶

6.6 Obiekty (2 powiadomienia)¶

6.7 Raporty (1 powiadomienie)¶

6.8 Dokumenty prawne (1 powiadomienie)¶

6.9 Tryb aplikacji (1 powiadomienie)¶

6.10 Zadania kolejek (1 powiadomienie)¶

6.11 Komendy CRON (1 powiadomienie)¶

7. Jak to dziala?¶

Scenariusz 1: Powiadomienia przy rezerwacji¶

sequenceDiagram
    participant K as Klient
    participant S as System
    participant Q as Kolejka
    participant E as Email

    K->>S: Tworzy rezerwacje
    S->>Q: Kolejkuje powiadomienie
    Q->>E: Wysyla email
    E-->>K: "Potwierdzenie rezerwacji"

    K->>S: Potwierdza email
    S->>Q: Kolejkuje powiadomienie
    Q->>E: Wysyla email
    E-->>K: "Link do platnosci"

    K->>S: Oplaca rezerwacje
    S->>Q: Kolejkuje powiadomienie
    Q->>E: Wysyla email
    E-->>K: "Platnosc potwierdzona + rachunek PDF"

    Note over K,E: Alternatywnie — blad platnosci
    K->>S: Platnosc nieudana (P24 callback)
    S->>Q: Kolejkuje powiadomienie
    Q->>E: Wysyla email
    E-->>K: "Platnosc nieudana — sprobuj ponownie"

Scenariusz 2: Przegladanie powiadomien w panelu¶

1. Administrator loguje sie do panelu
2. Widzi liste powiadomien z filtrami (temat, tresc, odbiorca)
3. Moze oznaczyc pojedyncze jako przeczytane (PATCH /notifications/{id}/set-read)
4. Moze oznaczyc wszystkie jako przeczytane (PATCH /read-notifications)
5. Stare powiadomienia sa automatycznie usuwane przez komende CRON

Scenariusz 3: Powiadomienie z pomijaniem¶

flowchart TD
    A[Zdarzenie w domenie] --> B{Typ powiadomienia?}
    B -->|Rezerwacja| C{reservation.send_notifications?}
    B -->|Reklamacja| D{Powiazana rezerwacja.send_notifications?}
    B -->|Inne| E[Wyslij powiadomienie]
    C -->|true| E
    C -->|false| F[Pomin powiadomienie]
    D -->|true| E
    D -->|false| F

8. Infrastruktura techniczna¶

8.1 Klasa bazowa CustomNotification¶

Wszystkie 39 klas powiadomien rozszerzaja Infrastructure\Vendor\CustomNotification:

CustomNotification extends Notification
├── Queueable — wsparcie kolejek
├── TraitSupport — metody pomocnicze
├── Properties: subject, content, action
├── via() → ['mail', 'database']
├── toMail() → SimpleBuildMailMessage
└── toArray() → {subject, content}

Wzorzec konstruktora:

Kazda klasa powiadomienia w konstruktorze:

1. Przyjmuje model(e) domenowe jako parametry
2. Buduje subject (temat emaila)
3. Buduje content (tresc HTML)
4. Ustawia action (przycisk CTA z URL)
5. Opcjonalnie nadpisuje via() lub toMail()

8.2 Budowanie wiadomosci email¶

SimpleBuildMailMessage tworzy MailMessage:

• Laduje konfiguracje gminy (loadMunicipalityConfiguration())
• Ustawia powitanie: "Szanowni Panstwo,"
• Tresc jako HtmlString (formatowany HTML)
• Przycisk akcji z tekstem i URL
• Podpis: "Z powazaniem," + nazwa gminy

8.3 Kolejkowanie¶

Worker: php artisan queue:work --queue=notifications

8.4 Mechanizm wysylki¶

Dwie sciezki wysylki powiadomien:

8.5 Zrodla wyzwalania powiadomien¶

9. Powiazania z innymi domenami¶

graph LR
    N[Notification]
    R[Reservation] -->|18 powiadomien| N
    U[User] -->|5 powiadomien| N
    C[Complaint] -->|4 powiadomienia| N
    A[Access] -->|3 powiadomienia| N
    O[Organization] -->|2 powiadomienia| N
    I[Item] -->|2 powiadomienia| N
    RP[Report] -->|1 powiadomienie| N
    LD[LegalDocument] -->|1 powiadomienie| N
    AM[AppMode] -->|1 powiadomienie| N
    J[Job] -->|1 powiadomienie| N
    CMD[Command] -->|1 powiadomienie| N
    CFG[Configuration] -.->|REMOVE_NOTIFICATIONS_OLDER_THAN_DAYS| N

10. Konfiguracja¶

Parametry systemowe¶

Komenda CRON¶

user-notification:remove-old-user-notifications

Usuwanie realizowane bezposrednio zapytaniem SQL na tabeli notifications — wydajna operacja masowa.

Zmienne srodowiskowe¶

11. Struktura plikow domeny¶

app/Domain/Notification/
├── Action/
│   ├── Controller/
│   │   ├── IndexNotificationController.php      # Lista powiadomien z filtrowaniem
│   │   └── ReadNotificationController.php       # Oznaczanie jako przeczytane
│   └── Other/
│       └── RemoveOldNotificationsCommandAction.php  # Usuwanie starych powiadomien
├── Command/
│   └── RemoveOldNotificationsCommand.php        # Komenda artisan CRON
├── Controller/
│   └── NotificationController.php               # Kontroler z middleware rol
├── Model/
│   ├── DatabaseNotification.php                 # Bazowy model z metodami read/unread
│   └── Notification.php                         # Glowny model z UUID i observerem
├── Observer/
│   └── NotificationObserver.php                 # Observer (obecnie pusty)
├── Request/
│   └── IndexNotificationControllerRequest.php   # Walidacja paginacji
├── Resource/
│   └── NotificationResource.php                 # Transformacja JSON
└── Service/
    ├── NotificationEnumService.php              # Enum konfiguracyjny
    ├── TraitControllerNotification.php          # Trait kontrolera
    └── TraitNotification.php                    # Trait domeny

Pliki infrastruktury i supportu:

12. Struktura powiadomienia¶

Kazde powiadomienie zawiera:

13. Wartosc biznesowa¶

14. Znane ograniczenia i TODO¶

• NotificationObserver jest obecnie pusty — placeholder na przyszle hooki lifecycle
• Brak kanalu push/SMS — obecnie tylko email i baza danych
• Brak mozliwosci konfigurowania przez uzytkownika, ktore typy powiadomien chce otrzymywac
• Klienci nie maja dostepu do API powiadomien — moga je tylko otrzymywac emailem