Cenniki (Pricing)¶

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

Elastyczne ceny z pelna obsluga VAT — od stawek domyslnych po indywidualne cenniki dla stalych klientow.

1. Opis ogolny¶

Domena Cennikow zarzadza polityka cenowa obiektow i zajec. To jak ksiega cen w recepcji — ale z automatycznym obliczaniem VAT, mozliwoscia ustalania indywidualnych stawek dla klientow i historia zmian cen.

System obsluguje dwa typy cennikow:

• Cennik godzinowy — dla obiektow wynajmowanych na godziny (sale, boiska)
• Cennik za zajecia — dla aktywnosci grupowych (fitness, warsztaty)

2. Architektura domeny¶

2.1 Modele danych¶

2.2 Diagram relacji¶

erDiagram
    Pricing ||--o| Client : "cennik indywidualny"
    Pricing }o--|| Item : "priceable (morph)"
    Pricing }o--|| Activity : "priceable (morph)"
    Reservation ||--o| Pricing : "pricing_id (FK)"

    Pricing {
        uuid id PK
        string priceable_type
        uuid priceable_id
        decimal value
        uuid client_id FK
        string vat_rate_override
        boolean is_active
        datetime created_at
        datetime updated_at
    }

2.3 Struktura tabeli w bazie danych¶

Tabela: pricings

Migracja: 0001_01_01_000018_create_pricings.php

Indeksy:

Klucze obce:

2.4 Atrybuty wyliczane (Accessors)¶

2.5 Scopes (zakresy zapytan)¶

2.6 Relacje modelu¶

2.7 Traity modelu¶

3. Endpointy API¶

Prefix: /api/pricings Middleware: auth:api, role:admin|supervisor|employee Plik routow: routes/api/auth/pricing.php

3.1 Lista cennikow¶

GET /api/pricings¶

• Opis: Pobiera liste cennikow z filtrami i paginacja
• Autoryzacja: Role: admin, supervisor, employee
• Controller: PricingController@index -> IndexPricingController

Query Parameters (filtry):

Dozwolone filtry (Spatie QueryBuilder):

Relacje ladowane w odpowiedzi:

• priceable — obiekt (Item) lub aktywnosc (Activity)
• client — klient (jesli cennik indywidualny)

Response (sukces, 200):

{
  "data": [
    {
      "id": "uuid-cennika",
      "priceable_type": "Domain\\Item\\Model\\Item",
      "priceable_id": "uuid-obiektu",
      "value": 100.00,
      "value_gross": 123.00,
      "client_id": null,
      "vat_rate_override": "23",
      "effective_vat_rate": "23",
      "effective_vat_rate_label": "23%",
      "is_active": true,
      "is_default": true,
      "price_unit": "hour",
      "price_unit_label": "za godzine",
      "created_at": "2026-02-26 10:00:00",
      "updated_at": "2026-02-26 10:00:00",
      "can": {
        "view": true,
        "create": true,
        "update": true
      },
      "priceable": { "..." : "dane obiektu/aktywnosci" },
      "client": null
    }
  ],
  "links": { "..." : "linki paginacji" },
  "meta": { "..." : "metadane paginacji" }
}

3.2 Tworzenie cennika¶

POST /api/pricings¶

• Opis: Tworzy nowy cennik dla obiektu lub aktywnosci
• Autoryzacja: Role: admin, supervisor, employee + Policy create (sprawdza przynaleznosc do organizacji)
• Controller: PricingController@store -> StorePricingController

Body (Request):

Custom Validation Rule — CheckExistPriceableIdRule:

Sprawdza czy:

1. priceable_type jest podklasa Eloquent\Model
2. Istnieje rekord o podanym priceable_id w tabeli danego modelu

Przyklad request:

{
  "priceable_type": "Domain\\Item\\Model\\Item",
  "priceable_id": "550e8400-e29b-41d4-a716-446655440000",
  "value": 100.00,
  "vat_rate_override": "23",
  "client_id": null,
  "is_active": true
}

Response (sukces, 200):

{
  "message": "The Pricing has been successfully added",
  "status": 200,
  "success": false
}

Logika biznesowa przy tworzeniu:

1. Walidacja danych wejsciowych
2. Sprawdzenie policy create (przynaleznosc do organizacji)
3. Wywolanie Pricing::create($validated)
4. Observer creating automatycznie:
5. Ustawia is_active = true jesli nie podano
6. Dezaktywuje istniejace aktywne cenniki dla tej samej kombinacji (priceable + client)

Custom messages walidacji:

3.3 Zmiana stanu cennika¶

PATCH /api/pricings/{pricingId}/change-state¶

• Opis: Przelacza stan is_active cennika (aktywacja/dezaktywacja)
• Autoryzacja: Role: admin, supervisor, employee + Policy update
• Controller: PricingController@changeState

Parametry URL:

Response (sukces, 200):

{
  "message": "Stan zostal zmieniony",
  "status": 200
}

Logika biznesowa:

1. Sprawdzenie policy update (przynaleznosc do organizacji)
2. Przelaczenie pola is_active na przeciwna wartosc
3. Observer updating — jesli cennik jest aktywowany (is_active zmienia sie na true):
4. Dezaktywuje inne aktywne cenniki dla tej samej kombinacji (priceable + client), wykluczajac biezacy

4. Logika biznesowa¶

4.1 Glowne procesy¶

Scenariusz 1: Ustawienie cennika dla sali¶

flowchart LR
    A[Wybiera obiekt] --> B[Dodaje cennik]
    B --> C[Podaje cene netto]
    C --> D[Wybiera stawke VAT]
    D --> E[Zapisuje]
    E --> F[System oblicza brutto]

1. Administrator otwiera obiekt "Sala konferencyjna"
2. Klika "Dodaj cennik"
3. Wpisuje cene netto: 100 zl/godz.
4. Wybiera stawke VAT: 23%
5. Zapisuje — system automatycznie oblicza brutto: 123 zl/godz.
6. Cennik jest aktywny od razu

Scenariusz 2: Indywidualna stawka dla stalego klienta¶

1. Firma "ABC Sp. z o.o." jest stalym klientem
2. Administrator tworzy cennik dla tej firmy
3. Cena netto: 80 zl/godz. (rabat 20%)
4. VAT: 23%
5. Od teraz przy rezerwacjach tej firmy — automatycznie stawka 80 zl

Scenariusz 3: Zmiana ceny obiektu¶

1. Administrator tworzy nowy cennik: 120 zl/godz.
2. System automatycznie dezaktywuje poprzedni cennik (100 zl/godz.)
3. Nowe rezerwacje — po nowej cenie
4. Istniejace rezerwacje — zachowuja stara cene (snapshot)
5. Historia cen jest zachowana

Scenariusz 4: Obiekt staje sie bezplatny (is_paid = false)¶

1. Gdy is_paid na obiekcie/aktywnosci zmienia sie na false
2. Klasa SetZeroForIsPaidDirtyField automatycznie tworzy cennik:
3. value = 0
4. is_active = true
5. client_id = null
6. vat_rate_override = '23'
7. Observer creating dezaktywuje poprzednie cenniki

4.2 Reguly biznesowe¶

1. Tylko jeden aktywny cennik — dla kazdej kombinacji (obiekt/aktywnosc + klient) moze istniec tylko jeden aktywny cennik
2. Automatyczna dezaktywacja — tworzenie nowego cennika lub aktywacja istniejacego automatycznie dezaktywuje pozostale dla tej samej kombinacji
3. Hierarchia cennikow — cennik kliencki ma priorytet nad domyslnym
4. Cena minimalna — wartosc cennika nie moze byc ujemna (min:0)
5. Snapshot w rezerwacji — przy tworzeniu rezerwacji cena jest "zamrazana" w reservationable_snapshot
6. Dozwolone typy — cenniki moga byc tworzone tylko dla modeli Item i Activity
7. Kasowanie kaskadowe — usuniecie klienta kasuje jego cenniki (onDelete: cascade)
8. Zachowanie referencji — usuniecie cennika ustawia pricing_id w rezerwacji na NULL (onDelete: set null)

4.3 Klasy akcji (Action)¶

Controllery¶

Atrybuty¶

Logika biznesowa (Other)¶

4.4 Observer modelu¶

Klasa: Domain\Pricing\Observer\PricingObserver

Rejestracja: Atrybut #[ObservedBy(PricingObserver::class)] na modelu Pricing

Szczegoly dezaktywacji (DeactivateActivePricings):

Zapytanie:
  WHERE priceable_type = ? AND priceable_id = ?
  AND is_active = true
  AND (client_id = ? | client_id IS NULL)  -- w zaleznosci od cennika
  [AND id != ? -- jesli excludeCurrent = true]
SET is_active = false

5. Autoryzacja i uprawnienia¶

5.1 Middleware (routy)¶

Wszystkie endpointy cennikow wymagaja:

• auth:api — uwierzytelnianie JWT
• role:admin|supervisor|employee — dostep tylko dla personelu

5.2 Policy — PricingPolicy¶

Klasa bazowa: Support\Policy\BasePolicy

Metoda before(): Administratorzy (admin) maja pelny dostep do wszystkich operacji — policy nie jest dalej sprawdzane.

Szczegoly metody create:

1. Sprawdza czy obiekt (priceable) istnieje
2. Pobiera organization_id z obiektu/aktywnosci
3. Supervisor — sprawdza przynaleznosc do organizacji
4. Employee — sprawdza czy jest ItemManager dla danego obiektu

Szczegoly metody update:

1. Rozwiazuje organization_id przez relacje polimorficzna (priceable)
2. Uzywa ->withoutGlobalScopes() aby ominac ewentualne filtry globalne
3. Supervisor — sprawdza przynaleznosc do organizacji
4. Employee — sprawdza isItemManager przez relacje polimorficzna

6. Stawki VAT¶

System obsluguje wszystkie polskie stawki VAT:

Enum: Domain\Pricing\Service\VatEnumService (backed string enum)

Metody statyczne:

7. Hierarchia cennikow¶

System stosuje nastepujaca hierarchie przy pobieraniu ceny:

flowchart TD
    A[Klient sklada rezerwacje] --> B{Ma cennik indywidualny?}
    B -->|Tak| C[Uzyj cennika klienta]
    B -->|Nie| D{Jest cennik domyslny?}
    D -->|Tak| E[Uzyj cennika domyslnego]
    D -->|Nie| F[Obiekt bezplatny]

Klasa: GetEffectivePricing

1. Cennik kliencki — jesli klient ma przypisany aktywny cennik indywidualny, uzyj go
2. Cennik domyslny — jesli nie ma cennika klienckiego, uzyj domyslnego (aktywnego, bez client_id)
3. Brak cennika — zwraca null (obiekt bezplatny)

8. Jednostki cenowe¶

9. Dyrektywa Omnibus¶

System automatycznie sledzi najnizsza cene z ostatnich 30 dni:

Klasa: TheLowestModelPricing

Enum: PricingEnumService::OMNIBUS_DAYS = '30'

Logika:

SELECT MIN(value) FROM pricings
WHERE priceable_type = ? AND priceable_id = ?
AND client_id IS NULL
AND created_at >= NOW() - 30 DAYS

timeline
    title Historia cen obiektu
    1 lutego : 100 zl
    10 lutego : 90 zl (promocja)
    20 lutego : 110 zl
    Dzis : Najnizsza cena 30 dni = 90 zl

10. Snapshot cennika w rezerwacji¶

Przy tworzeniu rezerwacji system zapisuje pelny snapshot cennika w polu reservationable_snapshot['_pricing_snapshot']. Dzieki temu:

• Usuniecie cennika nie powoduje utraty danych rezerwacji
• Zmiana ceny nie wplywa na istniejace rezerwacje
• Audyt — zawsze wiadomo jaka byla cena jednostkowa w momencie rezerwacji

Zapisywane dane (w _pricing_snapshot)¶

11. API Resource — struktura odpowiedzi¶

Klasa: Domain\Pricing\Resource\PricingResource

Relacje ladowane: priceable, client

12. Enumy¶

PricingEnumService¶

Klasa: Domain\Pricing\Service\PricingEnumService (backed string enum)

Metoda statyczna: getAllowedPriceableTypes() — zwraca tablice dozwolonych FQCN.

VatEnumService¶

Opisany w sekcji 6. Stawki VAT.

13. Powiazania z innymi domenami¶

Diagram powizan¶

graph LR
    Pricing -->|morphTo| Item["Zasoby (Item)"]
    Pricing -->|morphTo| Activity["Aktywnosci (Activity)"]
    Pricing -->|belongsTo| Client["Klienci (Client)"]
    Reservation["Rezerwacje"] -->|pricing_id FK| Pricing
    Item -->|morphMany| Pricing
    Activity -->|morphMany| Pricing
    Client -->|hasMany| Pricing

Tabela powizan¶

Wykorzystanie przez inne domeny¶

14. Konfiguracja¶

Tworzenie cennika¶

Zasady aktywacji¶

Publiczny cennik¶

Obiekty i aktywnosci maja pole is_public_price_list (boolean). Gdy wlaczone, cennik jest widoczny dla niezalogowanych uzytkownikow.

15. Znane ograniczenia i TODO¶

Wartosc biznesowa¶

Przykladowe metryki¶