Klienci (Client)¶

Baza stałych klientów — osoby fizyczne i firmy z historią rezerwacji i indywidualnymi cenami.

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

Co to jest?¶

Domena Klientów zarządza bazą osób i firm korzystających z systemu rezerwacji. To jak kartoteka klientów w recepcji — z pełną historią rezerwacji, preferencjami VAT i możliwością ustalenia indywidualnych cen.

Klient może być: - Osobą fizyczną — Jan Kowalski - Firmą — ABC Sp. z o.o. (z NIP i REGON)

Jakie problemy rozwiązuje?¶

Struktura domeny¶

app/Domain/Client/
├── Action/
│   ├── Attr/
│   │   ├── GetAmountDueAttr.php          # Obliczanie zaległości
│   │   ├── GetTotalPendingAttr.php       # Obliczanie kwot oczekujących
│   │   ├── GetTotalRefundedAttr.php      # Obliczanie zwrotów
│   │   └── GetTotalSpentAttr.php         # Obliczanie wydatków
│   ├── Controller/
│   │   ├── IndexClientController.php     # Listowanie klientów z filtrami
│   │   ├── ShowClientController.php      # Szczegóły klienta
│   │   ├── StoreClientController.php     # Tworzenie klienta
│   │   └── UpdateClientController.php    # Aktualizacja klienta
│   ├── Other/
│   │   ├── ApplyClientAggregatesOrm.php  # Optymalizacja zapytań SQL
│   │   ├── CreateClient.php              # Tworzenie klienta (Client::create)
│   │   ├── FindClientByEmail.php         # Wyszukiwanie po email
│   │   ├── FindClientByNip.php           # Wyszukiwanie po NIP
│   │   ├── FindOrCreateClient.php        # Znajdź lub utwórz klienta
│   │   ├── GenerateClientColor.php       # Losowanie koloru klienta
│   │   ├── UpdateClient.php              # Aktualizacja danych klienta
│   │   └── UpdateClientIfNeeded.php      # Warunkowa aktualizacja pustych pól
│   └── Scope/
│       └── ScopeSearchFunc.php           # Zakres wyszukiwania tekstowego
├── Controller/
│   └── ClientController.php              # Główny kontroler
├── Model/
│   └── Client.php                        # Model Eloquent
├── Observer/
│   └── ClientObserver.php                # Observer (pusty - zarezerwowany)
├── Policy/
│   └── ClientPolicy.php                  # Polityka autoryzacji
├── Request/
│   ├── IndexClientControllerRequest.php  # Walidacja listy
│   ├── StoreClientControllerRequest.php  # Walidacja tworzenia
│   └── UpdateClientControllerRequest.php # Walidacja edycji
├── Resource/
│   └── ClientResource.php                # Transformacja JSON API
└── Service/
    ├── ClientEnumService.php             # Enum (pusty - zarezerwowany)
    ├── TraitClient.php                   # Metody domenowe
    └── TraitControllerClient.php         # Metody kontrolera

Kluczowe funkcjonalności¶

Dla administratora¶

Jak to działa?¶

Scenariusz 1: Automatyczne tworzenie klienta¶

flowchart LR
    A[Mieszkaniec rezerwuje] --> B{Czy istnieje klient?}
    B -->|NIP znany<br>i firma| C[Aktualizuj puste pola]
    B -->|Email znany| C
    B -->|Nowy| D[Utwórz klienta]
    D --> E[Losuj kolor]
    C --> F[Powiąż z rezerwacją]
    E --> F

1. Mieszkaniec składa rezerwację podając dane
2. System sprawdza kolejno:
   • Czy istnieje klient z tym NIP (jeśli firma)?
   • Czy istnieje klient z tym emailem?
3. Jeśli znaleziono — aktualizuje tylko puste pola (nie nadpisuje istniejących)
4. Jeśli nie znaleziono — tworzy nowego klienta z automatycznie wylosowanym kolorem
5. Rezerwacja jest powiązana z klientem

Scenariusz 2: Indywidualny cennik dla firmy¶

1. Firma "ABC Sp. z o.o." regularnie wynajmuje salę
2. Administrator tworzy dla niej indywidualny cennik: 80 zł/godz. (zamiast 100 zł)
3. Przy każdej rezerwacji tej firmy — automatycznie stosowana jest niższa cena
4. Na fakturze widoczna jest stawka 80 zł

Scenariusz 3: Sprawdzenie historii klienta¶

1. Administrator otwiera kartę klienta
2. Widzi wszystkie rezerwacje, płatności, zwroty
3. Widzi statystyki: łącznie wydał 5000 zł, zwrócono 200 zł
4. Może dodać notatkę wewnętrzną

Struktura tabeli w bazie danych¶

Tabela clients¶

Klucze obce¶

Indeksy¶

Tabele powiązane¶

Endpointy API¶

Wszystkie endpointy wymagają uwierzytelnienia (JWT) i roli ADMIN, SUPERVISOR lub EMPLOYEE.

GET /api/clients¶

Lista klientów z filtrami, paginacją i agregatami finansowymi.

Parametry zapytania:

Response (sukces — 200):

Paginowana kolekcja ClientResource (patrz sekcja Odpowiedź API).

GET /api/clients/{clientId}¶

Szczegóły pojedynczego klienta z agregatami finansowymi.

Parametry URL:

Response (sukces — 200): Pojedynczy obiekt ClientResource.

Response (błąd — 404): NotFoundModelException jeśli klient nie istnieje.

POST /api/clients¶

Tworzenie nowego klienta. Wymaga autoryzacji (ClientPolicy@create).

Body (Request):

Response (sukces — 200): "The Client has been successfully added"

PATCH /api/clients/{clientId}¶

Aktualizacja danych klienta. Wymaga autoryzacji (ClientPolicy@update).

Wszystkie pola są opcjonalne (sometimes). Email i NIP zachowują unikalność z wykluczeniem aktualnego rekordu.

Response (sukces — 200): "The Client has been successfully updated"

Response (błąd — 404): NotFoundModelException jeśli klient nie istnieje.

PATCH /api/clients/{clientId}/change-state¶

Przełączenie statusu is_active klienta. Wymaga autoryzacji (ClientPolicy@update).

Response (sukces — 200): Komunikat o zmianie statusu.

Powiązania z innymi domenami¶

Integracja z domeną Rezerwacji¶

Klasa FindOrCreateClientForReservation (w domenie Reservation) wyciąga dane klienta z walidowanych danych rezerwacji i deleguje do FindOrCreateClient:

flowchart LR
    A[Dane rezerwacji] --> B[FindOrCreateClientForReservation]
    B --> C{Email lub NIP podany?}
    C -->|Nie| D[Zwróć null]
    C -->|Tak| E[FindOrCreateClient]
    E --> F[Klient]

Pola wyciągane z rezerwacji: first_name, last_name, email, mobile_phone, is_company, company_name, nip, regon, street, street_number, postal_code, city, commune, district, voivodeship.

Integracja z domeną Raportów¶

Domena Client jest źródłem danych dla 2 dedykowanych raportów:

clients.new_registrations — Raport nowych rejestracji klientów:

• Grupowanie po dacie (DATE(created_at))
• Filtrowanie po okresie (this_month, last_month, this_year, last_year, custom)
• Opcjonalne filtrowanie po organization_id
• Kolumny: Data, Liczba nowych klientów

clients.top_spenders — Ranking klientów wg wydatków:

• Dane z rezerwacji o statusie RESERVATION_STATUS_CONFIRMED
• Filtrowanie po okresie i opcjonalnie po organization_id
• Konfigurowalny limit wyników (domyślnie 10, max 30)
• Kolumny: Pozycja, Nazwa klienta, Email, Telefon, Liczba rezerwacji, Liczba slotów, Suma godzin, Zapłacone, Zwroty, Przychód razem

Wartość biznesowa¶

Typy klientów¶

Osoba fizyczna¶

Firma¶

Obsługa VAT¶

Każdy klient może mieć przypisaną stawkę VAT (domyślnie 23%):

Stawki VAT są zarządzane przez VatEnumService z domeny Pricing.

Statystyki finansowe¶

System automatycznie oblicza dla każdego klienta:

Kolory klientów¶

Każdy klient ma przypisany kolor do identyfikacji w harmonogramie. System posiada paletę 15 kolorów:

Wyszukiwanie i filtrowanie klientów¶

Dostępne filtry¶

Paginacja¶

Endpoint GET /api/clients obsługuje standardowe parametry paginacji zdefiniowane w paginationDefaultRequestRules().

Dostęp PIN dla klientów¶

Klienci mogą mieć kod PIN do logowania w systemie:

Automatyczne tworzenie klientów¶

Klasa FindOrCreateClient zarządza automatycznym tworzeniem i rozpoznawaniem klientów przy rezerwacji:

flowchart TD
    A[Dane klienta z rezerwacji] --> B{is_company=true<br>i NIP podany?}
    B -->|Tak| C{Istnieje klient<br>z tym NIP?}
    C -->|Tak| D[Aktualizuj puste pola]
    C -->|Nie| E{Istnieje klient<br>z tym emailem?}
    B -->|Nie| E
    E -->|Tak| D
    E -->|Nie| F[Utwórz nowego klienta]
    F --> G[Wylosuj kolor]
    G --> H[Zwróć klienta]
    D --> H

1. Sprawdzenie NIP (dla firm) — jeśli istnieje klient z tym NIP, aktualizuje puste pola
2. Sprawdzenie email — jeśli istnieje klient z tym emailem, aktualizuje puste pola
3. Tworzenie nowego — jeśli nie znaleziono dopasowania, tworzy nowego z losowym kolorem

Odpowiedź API (Resource)¶

Endpoint zwraca następujące pola w odpowiedzi JSON:

Obiekt can (uprawnienia)¶

Uprawnienia¶

Middleware (role)¶

Middleware: role:ADMIN|SUPERVISOR|EMPLOYEE — stosowany do wszystkich metod kontrolera (index, show, store, update, changeState).

Policy (ClientPolicy)¶

Eventy i efekty uboczne¶

Znane ograniczenia i TODO¶

1. Pusty observer — ClientObserver jest zarezerwowany, ale nie implementuje żadnych hooków
2. Pusty enum — ClientEnumService jest zarezerwowany na przyszłe statusy/typy klientów
3. Brak soft delete — klienci nie są usuwani miękko (brak SoftDeletes), zamiast tego używana jest flaga is_active
4. Brak endpointu DELETE — klienci nie mogą być usuwani przez API, jedynie dezaktywowani
5. GetAmountDueAttr bez GlobalScope — GetAmountDueAttr nie używa withoutGlobalScope w przeciwieństwie do GetTotalPendingAttr, co może prowadzić do różnic w wynikach jeśli UserAccessesGlobalScope jest aktywny (w praktyce amount_due w modelu jest aliasem total_pending, więc różnica nie jest widoczna w API)