Notatki (Note)¶

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

1. Opis ogolny¶

Domena Notatek zarzadza wewnetrznymi komentarzami pracownikow dodawanymi do roznych encji w systemie. To jak karteczki samoprzylepne na dokumentach — pracownicy moga dodawac uwagi do klientow, rezerwacji, obiektow, zajec i reklamacji, ktore sa widoczne tylko dla zespolu. System zapewnia pelna historie zmian kazdej notatki (audit trail), przypinanie waznych notatek oraz specjalne oznaczanie notatek do wyswietlenia w rezerwacji.

2. Architektura domeny¶

2.1 Modele danych¶

Model Note¶

Pola fillable:

Relacje:

Model NoteLog¶

Pola fillable:

Relacje:

2.2 Diagram relacji¶

erDiagram
    Note ||--o{ NoteLog : "ma historie zmian"
    Note }o--|| User : "autor"
    NoteLog }o--|| User : "wykonawca zmiany"
    Note }o--|| Client : "notatka do klienta"
    Note }o--|| Reservation : "notatka do rezerwacji"
    Note }o--|| Item : "notatka do obiektu"
    Note }o--|| Activity : "notatka do zajec"
    Note }o--|| Complaint : "notatka do reklamacji"

2.3 Struktura tabel w bazie danych¶

Tabela notes¶

Tabela note_logs¶

3. Endpointy API¶

Wszystkie endpointy wymagaja uwierzytelnienia (JWT) i roli: ADMIN, SUPERVISOR lub EMPLOYEE.

Prefix: /api/notes

3.1 Lista notatek¶

GET /api/notes¶

• Opis: Zwraca paginowana liste notatek z relacjami
• Autoryzacja: Role: ADMIN, SUPERVISOR, EMPLOYEE
• Route name: notes.index
• Query Parameters: Standardowe parametry paginacji (page, per_page, filtry Spatie Query Builder)
• Request: IndexNoteControllerRequest
• Walidacja:

• Response (sukces — 200):

  {
    "data": [
      {
        "id": "uuid-notatki",
        "notable_type": "Domain\\Client\\Model\\Client",
        "notable_id": "uuid-klienta",
        "user_id": "uuid-pracownika",
        "content": "Staly klient, rabat 10%",
        "is_pinned": true,
        "show_in_reservation": false,
        "created_at": "2026-02-26 10:30:00",
        "updated_at": "2026-02-26 10:30:00",
        "can": {
          "view": true,
          "create": true,
          "update": true
        },
        "user": { "..." : "dane autora" },
        "notable": { "..." : "dane encji nadrzednej" },
        "logs": []
      }
    ],
    "links": { "..." : "paginacja" },
    "meta": { "..." : "metadane" }
  }
  

• Zaladowane relacje: user, notable

3.2 Szczegoly notatki¶

GET /api/notes/{noteId}¶

• Opis: Zwraca pojedyncza notatke z pelna historia zmian
• Autoryzacja: Role: ADMIN, SUPERVISOR, EMPLOYEE
• Parametry URL:

• Response (sukces — 200):

  {
    "data": {
      "id": "uuid-notatki",
      "notable_type": "Domain\\Reservation\\Model\\Reservation",
      "notable_id": "uuid-rezerwacji",
      "user_id": "uuid-pracownika",
      "content": "Klient prosi o przygotowanie 50 krzesel",
      "is_pinned": false,
      "show_in_reservation": true,
      "created_at": "2026-02-26 10:30:00",
      "updated_at": "2026-02-26 11:00:00",
      "can": {
        "view": true,
        "create": true,
        "update": true
      },
      "user": { "..." : "dane autora" },
      "notable": { "..." : "dane rezerwacji" },
      "logs": [
        {
          "id": "uuid-logu",
          "note_id": "uuid-notatki",
          "user_id": "uuid-pracownika",
          "event_type": "created",
          "event_type_lang": "utworzony",
          "changes": null,
          "created_at": "2026-02-26 10:30:00",
          "user": { "..." : "dane uzytkownika" }
        },
        {
          "id": "uuid-logu-2",
          "note_id": "uuid-notatki",
          "user_id": "uuid-innego-pracownika",
          "event_type": "updated",
          "event_type_lang": "zaktualizowany",
          "changes": {
            "content": {
              "old": "Klient prosi o krzesla",
              "new": "Klient prosi o przygotowanie 50 krzesel"
            }
          },
          "created_at": "2026-02-26 11:00:00",
          "user": { "..." : "dane uzytkownika" }
        }
      ]
    }
  }
  

• Zaladowane relacje: user, notable, logs, logs.user

• Bledy: 404 — notatka nie znaleziona

3.3 Tworzenie notatki¶

POST /api/notes¶

• Opis: Tworzy nowa notatke dla wskazanej encji
• Autoryzacja: Role: ADMIN, SUPERVISOR, EMPLOYEE + Policy NotePolicy::create (sprawdza przynaleznosc do organizacji)
• Request: StoreNoteControllerRequest
• Body:

• Przyklad request:

  {
    "notable_type": "Domain\\Client\\Model\\Client",
    "notable_id": "550e8400-e29b-41d4-a716-446655440000",
    "content": "Staly klient, ustalono rabat 10% na wynajem sali A",
    "is_pinned": true,
    "show_in_reservation": false
  }
  

• Response (sukces — 200):

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

• Reguly biznesowe:

  • Pole user_id ustawiane automatycznie na zalogowanego uzytkownika (observer creating)
  • Jesli show_in_reservation = true, inne notatki tej samej encji z show_in_reservation = true zostaja automatycznie odznaczone
  • Wpis w note_logs tworzony automatycznie (event_type: created)

• Custom validation rule NotableExistsRule:

  • Sprawdza czy notable_type jest na liscie dozwolonych typow
  • Sprawdza czy klasa modelu istnieje
  • Sprawdza czy rekord o podanym notable_id istnieje w bazie

• Bledy walidacji (422):

3.4 Aktualizacja notatki¶

PATCH /api/notes/{noteId}¶

• Opis: Aktualizuje istniejaca notatke (tresc, przypinanie, widocznosc w rezerwacji)
• Autoryzacja: Role: ADMIN, SUPERVISOR, EMPLOYEE + Policy NotePolicy::update
• Parametry URL:

• Request: UpdateNoteControllerRequest
• Body:

• Przyklad request:

  {
    "content": "Staly klient, ustalono rabat 15% od stycznia 2026",
    "is_pinned": true
  }
  

• Response (sukces — 200):

  {
    "message": "The Note has been successfully updated",
    "status": 200
  }
  

• Reguly biznesowe:

  • Jesli zmieniono show_in_reservation na true, inne notatki tej samej encji zostaja automatycznie odznaczone
  • Zmiany w polach content, is_pinned, show_in_reservation sa logowane w note_logs z porownaniem starych i nowych wartosci
  • Jesli nie zmieniono zadnego ze sledzonych pol, wpis w logu NIE jest tworzony

• Bledy: 404 — notatka nie znaleziona (NotFoundModelException)

4. Logika biznesowa¶

4.1 Glowne procesy¶

Proces tworzenia notatki¶

flowchart TD
    A[Pracownik wysyla POST /api/notes] --> B[Walidacja danych]
    B --> C{Walidacja OK?}
    C -->|Nie| D[422 - Bledy walidacji]
    C -->|Tak| E[Sprawdzenie NotableExistsRule]
    E --> F{Encja istnieje?}
    F -->|Nie| D
    F -->|Tak| G[Policy: create]
    G --> H{Autoryzacja OK?}
    H -->|Nie| I[403 - Brak dostepu]
    H -->|Tak| J[Observer: creating - ustawia user_id]
    J --> K[Zapis notatki do bazy]
    K --> L[Observer: created]
    L --> M{show_in_reservation?}
    M -->|Tak| N[Odznacz inne notatki tej encji]
    M -->|Nie| O[Pomijaj]
    N --> P[Tworzenie wpisu w note_logs]
    O --> P
    P --> Q[200 - Sukces]

Proces aktualizacji notatki¶

flowchart TD
    A[Pracownik wysyla PATCH /api/notes/noteId] --> B[Walidacja danych]
    B --> C{Walidacja OK?}
    C -->|Nie| D[422 - Bledy walidacji]
    C -->|Tak| E[Szukanie notatki]
    E --> F{Notatka istnieje?}
    F -->|Nie| G[404 - Nie znaleziono]
    F -->|Tak| H[Policy: update]
    H --> I{Autoryzacja OK?}
    I -->|Nie| J[403 - Brak dostepu]
    I -->|Tak| K[Aktualizacja notatki]
    K --> L[Observer: updated]
    L --> M{show_in_reservation zmieniono na true?}
    M -->|Tak| N[Odznacz inne notatki tej encji]
    M -->|Nie| O[Pomijaj]
    N --> P[Ekstrakcja zmian - ExtractChanges]
    O --> P
    P --> Q{Sa zmiany do zalogowania?}
    Q -->|Tak| R[Tworzenie wpisu w note_logs]
    Q -->|Nie| S[Pomijaj log]
    R --> T[200 - Sukces]
    S --> T

4.2 Reguly biznesowe¶

1. Autor automatyczny — pole user_id jest automatycznie ustawiane na zalogowanego uzytkownika w momencie tworzenia notatki (observer creating)
2. Wylacznosc show_in_reservation — dla kazdej encji (tej samej pary notable_type + notable_id) tylko jedna notatka moze miec show_in_reservation = true. Oznaczenie nowej automatycznie odznacza poprzednia
3. Sledzenie zmian — zmiany w polach content, is_pinned, show_in_reservation sa automatycznie logowane w tabeli note_logs z porownaniem starych i nowych wartosci
4. Pomijanie systemowych pol — pola updated_at, created_at, notable_type, notable_id, user_id sa pomijane przy ekstrakcji zmian
5. Brak usuwania notatek — w obecnej implementacji nie istnieje endpoint DELETE — notatki nie moga byc usuwane
6. Zachowanie autora logu po usunieciu uzytkownika — pole user_id w note_logs jest ustawiane na NULL gdy uzytkownik zostanie usuniety (nullOnDelete)

4.3 Walidacje¶

Store (tworzenie)¶

Update (aktualizacja)¶

5. Autoryzacja i uprawnienia¶

5.1 Middleware (kontroler)¶

Wszystkie akcje kontrolera (index, show, store, update) wymagaja jednej z rol:

• ADMIN
• SUPERVISOR
• EMPLOYEE

5.2 Policy (NotePolicy)¶

Policy dziedziczy z BasePolicy, ktora w metodzie before() automatycznie przyznaje pelny dostep administratorom.

flowchart TD
    A[Sprawdz uprawnienia] --> B{Rola ADMIN?}
    B -->|Tak| C[Dostep przyznany - before]
    B -->|Nie| D{Akcja?}
    D -->|view / update| E[Rozwiaz organization_id encji]
    D -->|create| F{Encja nadrzedna istnieje?}
    F -->|Nie| G[Dostep odrzucony]
    F -->|Tak| H[Pobierz organization_id encji]
    E --> I{Ma organization_id?}
    H --> I
    I -->|Tak| J{Uzytkownik nalezy do organizacji?}
    I -->|Nie - view| K[Dostep przyznany]
    I -->|Nie - create/update| L{Jest supervisorem?}
    J -->|Tak| K
    J -->|Nie| G
    L -->|Tak| K
    L -->|Nie| G

6. Eventy i efekty uboczne¶

6.1 Observer NoteObserver¶

6.2 Mechanizm EnsureExclusiveShowInReservation¶

Dla danej pary (notable_type, notable_id) moze byc tylko jedna notatka z show_in_reservation = true. Mechanizm:

1. Sprawdza czy nowa/zaktualizowana notatka ma show_in_reservation = true
2. Jesli tak — wyszukuje inne notatki tej samej encji z show_in_reservation = true
3. Dla kazdej znalezionej ustawia show_in_reservation = false i zapisuje
4. Zapis kazdej z odznaczanych notatek triggeruje observer updated, ktory loguje zmiane

7. Notyfikacje¶

W domenie Notatek nie sa wysylane zadne notyfikacje. Notatki sa wewnetrznym narzedziem zespolu i nie generuja powiadomien email ani in-app.

8. Powiazania z innymi domenami¶

8.1 Encje z mozliwoscia dodawania notatek¶

8.2 Zaleznosci¶

graph LR
    Note -->|morphTo| Client
    Note -->|morphTo| Reservation
    Note -->|morphTo| Item
    Note -->|morphTo| Activity
    Note -->|morphTo| Complaint
    Note -->|belongsTo| User
    NoteLog -->|belongsTo| Note
    NoteLog -->|belongsTo| User

9. Konfiguracja¶

Domena Notatek nie posiada dedykowanych parametrow konfiguracyjnych. Dziala w oparciu o stale wartosci:

10. Znane ograniczenia i TODO¶