Zasoby / Obiekty (Item)¶

Fundament systemu rezerwacji — wszystko, co można zarezerwować: sale, boiska, sprzęt, pojazdy.

Co to jest?¶

Domena Zasobów (Item) zarządza obiektami do wynajmu. To jak katalog wszystkich sal i obiektów w gminie — z pełną informacją o lokalizacji, wyposażeniu, dostępności i cenach.

Każdy obiekt może być: - Salą konferencyjną w urzędzie - Halą sportową w szkole - Boiskiem piłkarskim - Kortem tenisowym - Sprzętem do wypożyczenia (namioty, stoły, krzesła)

Jakie problemy rozwiązuje?¶

Struktura domeny¶

app/Domain/Item/
├── Action/
│   ├── Attr/                  # Atrybuty obliczane (9 klas)
│   │   ├── GetCurrentPriceAttr.php
│   │   ├── GetCurrentPriceGrossAttr.php
│   │   ├── GetCurrentPriceVatRateAttr.php
│   │   ├── GetCurrentPricingAttr.php
│   │   ├── GetIsParentAttr.php
│   │   ├── GetLowestPriceAttr.php
│   │   ├── GetLowestPriceGrossAttr.php
│   │   ├── GetLowestPriceVatRateAttr.php
│   │   └── GetLowestPricingAttr.php
│   ├── Controller/            # Single-action controllers (12 klas)
│   │   ├── IndexItemController.php
│   │   ├── ShowItemController.php
│   │   ├── StoreItemController.php
│   │   ├── UpdateItemController.php
│   │   ├── IndexItemBlockController.php
│   │   ├── ShowItemBlockController.php
│   │   ├── StoreItemBlockController.php
│   │   ├── StoreMultipleItemBlockController.php
│   │   ├── CheckItemBlockConflictsController.php
│   │   ├── IndexItemManagerController.php
│   │   ├── StoreItemManagerController.php
│   │   └── DeleteItemManagerController.php
│   ├── Other/                 # Logika biznesowa i obserwatory (24 klasy)
│   │   ├── ApplyItemAggregatesOrm.php
│   │   ├── CreateItem.php
│   │   ├── UpdateItem.php
│   │   ├── CreateItemBlock.php
│   │   ├── CreateItemBlockSchedule.php
│   │   ├── CreateItemManager.php
│   │   ├── CreatingItemObserver.php
│   │   ├── UpdatedItemObserver.php
│   │   ├── CreatingItemBlockObserver.php
│   │   ├── CreatedItemBlockObserver.php
│   │   ├── UpdatingItemBlockObserver.php
│   │   ├── UpdatedItemBlockObserver.php
│   │   ├── DeletingItemBlockObserver.php
│   │   ├── ExceptionChangeStateItem.php
│   │   ├── SetActiveInactiveChildItem.php
│   │   ├── DisableOverlappingItemBlocks.php
│   │   ├── ForceCancelReservationAndDisableItemBlock.php
│   │   ├── FindConflictingReservationsForItemBlock.php
│   │   ├── FindConflictingReservationsForPeriod.php
│   │   ├── CancelConflictingReservationsForItemBlock.php
│   │   ├── GetItemBlockConflictSummary.php
│   │   ├── BuildItemBlockCancellationReason.php
│   │   ├── HandleItemBlockDateChange.php
│   │   └── HandleItemBlockIsActiveChange.php
│   ├── Scope/                 # Query scopes (8 klas)
│   │   ├── ScopeSearchFunc.php
│   │   ├── ScopePriceFromFunc.php
│   │   ├── ScopePriceToFunc.php
│   │   ├── ScopeCapacityFromFunc.php
│   │   ├── ScopeCapacityToFunc.php
│   │   ├── ScopeAreaFromFunc.php
│   │   ├── ScopeAreaToFunc.php
│   │   └── ScopeExcludeSelfAndChildrenFunc.php
│   └── Sort/                  # Sortowania (1 klasa)
│       └── SortByLowestPrice.php
├── Controller/                # Kontrolery HTTP (3 klasy)
│   ├── ItemController.php
│   ├── ItemBlockController.php
│   └── ItemManagerController.php
├── Model/                     # Modele Eloquent (3 klasy)
│   ├── Item.php
│   ├── ItemBlock.php
│   └── ItemManager.php
├── Notification/              # Powiadomienia (2 klasy)
│   ├── ItemManagerCreatedNotification.php
│   └── ItemManagerDeletedNotification.php
├── Observer/                  # Obserwatory Eloquent (3 klasy)
│   ├── ItemObserver.php
│   ├── ItemBlockObserver.php
│   └── ItemManagerObserver.php
├── Request/                   # Walidacja żądań (10 klas + 6 reguł)
│   ├── IndexItemControllerRequest.php
│   ├── StoreItemControllerRequest.php
│   ├── UpdateItemControllerRequest.php
│   ├── ChangeCategoryItemControllerRequest.php
│   ├── IndexItemBlockControllerRequest.php
│   ├── StoreItemBlockControllerRequest.php
│   ├── StoreMultipleItemBlockControllerRequest.php
│   ├── CheckItemBlockConflictsRequest.php
│   ├── IndexItemManagerControllerRequest.php
│   ├── StoreItemManagerControllerRequest.php
│   └── Rule/
│       ├── AllowedParentItemRule.php
│       ├── AllowedItemManagerRule.php
│       ├── AssignLikeManagerRule.php
│       ├── UniqueItemManagerRule.php
│       ├── ItemBlockAvailabilityRule.php
│       └── ItemBlockAvailabilityUpdateRule.php
├── Resource/                  # Zasoby API (3 klasy)
│   ├── ItemResource.php
│   ├── ItemBlockResource.php
│   └── ItemManagerResource.php
└── Service/                   # Traity i enumy (3 pliki)
    ├── ItemEnumService.php
    ├── TraitItem.php
    └── TraitControllerItem.php

Kluczowe funkcjonalności¶

Dla mieszkańca¶

Dla administratora¶

Jak to działa?¶

Scenariusz 1: Dodanie nowego obiektu¶

flowchart LR
    A[Nowy obiekt] --> B[Dane podstawowe]
    B --> C[Lokalizacja TERYT]
    C --> D[Wyposażenie]
    D --> E[Godziny działania]
    E --> F[Cennik]
    F --> G[Zdjęcia]
    G --> H[Publikacja]

1. Administrator tworzy nowy obiekt w panelu
2. Podaje nazwę, opis i kategorię (np. "Sala konferencyjna", kategoria "Sale")
3. Wprowadza adres z autouzupełnianiem TERYT (województwo → powiat → gmina → miejscowość)
4. Zaznacza wyposażenie: WiFi, parking, klimatyzacja, toalety, kuchnia...
5. Ustawia godziny działania (np. 8:00-22:00)
6. Dodaje cennik (np. 50 zł/godz. netto) — wymagany gdy is_paid=true
7. Wgrywa zdjęcia obiektu
8. Publikuje obiekt — od teraz widoczny dla mieszkańców

Scenariusz 2: Blokada na czas konserwacji¶

flowchart TD
    A[Tworzenie blokady] --> B{Koliduje z rezerwacjami?}
    B -->|Nie| C[Blokada aktywna]
    B -->|Tak| D[Automatyczna anulacja slotów]
    D --> E[Obliczenie zwrotów]
    E --> F[Wysłanie powiadomień]
    F --> G[Auto-potwierdzenie zwrotów]
    G --> C
    C --> H[Dezaktywacja nakładających się blokad]

1. Administrator tworzy blokadę dla obiektu
2. Wybiera typ: "Konserwacja"
3. Podaje zakres dat: 15-17 stycznia
4. Dodaje opis: "Wymiana oświetlenia"
5. System automatycznie anuluje kolidujące sloty rezerwacji
6. Inicjuje zwroty za anulowane sloty (auto-potwierdza oczekujące zwroty ręczne)
7. Wysyła powiadomienie do klientów (częściowe lub pełne anulowanie)
8. Dezaktywuje nakładające się istniejące blokady na ten sam obiekt

Scenariusz 3: Mieszkaniec szuka sali na imprezę¶

1. Mieszkaniec wchodzi na listę obiektów
2. Filtruje: kategoria "Sale", pojemność od 50 osób, cena do 100 zł/godz.
3. System pokazuje pasujące obiekty posortowane wg ceny
4. Mieszkaniec klika w wybrany obiekt
5. Widzi: zdjęcia, opis, mapę, wyposażenie, kalendarz dostępności
6. Klika "Rezerwuj" i przechodzi do procesu rezerwacji

Modele danych¶

Item (Obiekt)¶

Model: Domain\Item\Model\Item Tabela: items UUID: Tak (HasUuids) Observer: ItemObserver (creating, updated) MediaLibrary: Tak (HasMedia, InteractsWithMedia) Activity Log: Tak (dziedziczy z CustomModel) Appends: avg_reviews, total_reviews

Relacje:

Atrybuty obliczane (accessory z wzorcem array_key_exists fallback):

Konwersje mediów (Spatie MediaLibrary):

ItemBlock (Blokada obiektu)¶

Model: Domain\Item\Model\ItemBlock Tabela: item_blocks UUID: Tak (HasUuids) Observer: ItemBlockObserver (creating, created, updating, updated, deleting) Activity Log: Tak (dziedziczy z CustomModel)

Relacje:

ItemManager (Zarządca obiektu)¶

Model: Domain\Item\Model\ItemManager Tabela: item_managers UUID: Tak (HasUuids) Observer: ItemManagerObserver (created, deleted) Activity Log: Tak (dziedziczy z CustomModel)

Relacje:

Endpointy API¶

Obiekty (Items)¶

Blokady obiektów (ItemBlocks)¶

Zarządcy obiektów (ItemManagers)¶

Autoryzacja i uprawnienia (Policies)¶

System autoryzacji opiera się na trzech policy: ItemPolicy, ItemBlockPolicy i ItemManagerPolicy. Wszystkie rozszerzają BasePolicy, która dostarcza metody helper: belongsToOrganization(), isSupervisor(), isEmployee(), isItemManager().

ItemPolicy¶

ItemBlockPolicy¶

ItemManagerPolicy¶

Walidacja żądań¶

StoreItemControllerRequest (tworzenie obiektu)¶

Pola wymagane: organization_id, category_id, name, is_active, is_public, street, street_number, postal_code, city, commune, district, voivodeship, teryt_data, is_paid, reservation_start_time, reservation_end_time, can_full_day_reservation, color

Reguły niestandardowe:

UpdateItemControllerRequest (edycja obiektu)¶

Wszystkie pola są opcjonalne (sometimes) — umożliwia częściową aktualizację (partial update).

Reguły niestandardowe (Update):

StoreItemBlockControllerRequest (tworzenie blokady)¶

StoreMultipleItemBlockControllerRequest (masowe blokady)¶

CheckItemBlockConflictsRequest (sprawdzanie konfliktów)¶

StoreItemManagerControllerRequest (przypisanie zarządcy)¶

Reguły niestandardowe:

ChangeCategoryItemControllerRequest (zmiana kategorii)¶

Zasoby API (Resources)¶

ItemResource¶

Relacje ładowane: organization, category, parent Ukryte dla niezalogowanych (UNALLOWED_NO_AUTH_KEYS): can_be_edit, is_in_use, reservations, reviews, schedules, can

Zawiera wszystkie pola modelu Item plus atrybuty obliczane: can_be_edit, total_reviews, avg_reviews, current_price, current_price_gross, current_price_vat_rate, lowest_price, lowest_price_gross, lowest_price_vat_rate, is_in_use, is_parent, thumbnail, color.

ItemBlockResource¶

Relacje ładowane: creator, canceler Ukryte dla niezalogowanych: tylko can

ItemManagerResource¶

Relacje ładowane: item, user Ukryte dla niezalogowanych: tylko can

Filtrowanie i sortowanie¶

Filtry obiektów (IndexItemController)¶

Sortowania obiektów¶

Filtry blokad (IndexItemBlockController)¶

Filtry zarządców (IndexItemManagerController)¶

Optymalizacja N+1 (ApplyItemAggregatesOrm)¶

Lista obiektów (GET /api/items) używa ApplyItemAggregatesOrm do eliminacji problemu N+1 query. Zamiast ładować relacje osobno dla każdego obiektu, system wykonuje agregaty w jednym zapytaniu:

Accessory w modelu Item sprawdzają array_key_exists() — jeśli agregat jest dostępny w atrybutach, używają go zamiast wykonywać osobne zapytanie.

Cykl życia obiektów (Observers)¶

ItemObserver¶

flowchart LR
    A[creating] --> B["CreatingItemObserver<br/>auto-generowanie slug"]
    C[updated] --> D["UpdatedItemObserver<br/>is_paid → zerowanie cennika<br/>is_active → kaskada na dzieci"]

ItemBlockObserver¶

flowchart LR
    A[creating] --> B["CreatingItemBlockObserver<br/>created_by = auth user<br/>is_active = true"]
    C[created] --> D["CreatedItemBlockObserver<br/>tworzenie Schedule<br/>anulacja kolidujących rezerwacji<br/>dezaktywacja nakładających się blokad"]
    E[updating] --> F["UpdatingItemBlockObserver<br/>cancel_by/cancel_at przy dezaktywacji"]
    G[updated] --> H["UpdatedItemBlockObserver<br/>obsługa zmiany is_active<br/>obsługa zmiany dat"]
    I[deleting] --> J["DeletingItemBlockObserver<br/>usunięcie Schedule"]

ItemManagerObserver¶

Powiązania z innymi domenami¶

Wartość biznesowa¶

Przykładowe metryki¶

Wyposażenie obiektów¶

System pozwala oznaczyć obiekty następującymi udogodnieniami:

Blokady obiektów¶

Blokady pozwalają czasowo wyłączyć obiekt z rezerwacji:

Sprawdzanie konfliktów (check-conflicts)¶

Endpoint POST /api/item-blocks-check-conflicts pozwala sprawdzić, które rezerwacje kolidują z planowaną blokadą przed jej utworzeniem. Obsługuje wiele zakresów dat w jednym zapytaniu:

{
    "item_id": "uuid-obiektu",
    "ranges": [
        {"date_time_from": "2026-02-27 00:00", "date_time_to": "2026-02-27 23:59"},
        {"date_time_from": "2026-02-28 00:00", "date_time_to": "2026-02-28 23:59"},
        {"date_time_from": "2026-03-01 00:00", "date_time_to": "2026-03-01 23:59"}
    ]
}

Odpowiedź (GetItemBlockConflictSummary):

{
    "has_conflicts": true,
    "total_count": 2,
    "total_refund_amount": 150.00,
    "reservations": [
        {
            "id": "uuid",
            "status": "confirmed",
            "payment_status": "completed",
            "client": {
                "first_name": "Jan",
                "last_name": "Kowalski",
                "email": "jan@example.com",
                "mobile_phone": "123456789"
            },
            "total_price": 200.00,
            "is_paid": true,
            "total_paid": 200.00,
            "refund_amount": 100.00,
            "total_slots_count": 5,
            "conflicting_slots_count": 2,
            "will_cancel_entire_reservation": false,
            "conflicting_slots": [
                {"id": "uuid", "date": "2026-02-27", "time_from": "10:00", "time_to": "11:00", "price": 50.00}
            ]
        }
    ]
}

Dane demo (Seeder)¶

ItemBlockSeeder generuje 2–5 blokad na każdy aktywny obiekt. Blokady są nakładane wyłącznie na wolne terminy (bez konfliktów z istniejącymi rezerwacjami i innymi blokadami). Typy blokad: maintenance, failure, internal, event, other — losowo.

Konfiguracja obiektu¶

Godziny działania¶

Polityka rezerwacji¶

Widoczność i płatności¶

SEO i identyfikacja¶

Hierarchia obiektów¶

System pozwala tworzyć struktury hierarchiczne:

Kompleks Sportowy "Orlik"
├── Boisko główne
├── Boisko treningowe
└── Budynek zaplecza
    ├── Szatnia A
    ├── Szatnia B
    └── Sala konferencyjna

Managerowie obiektów¶

Każdy obiekt może mieć przypisanych managerów — użytkowników odpowiedzialnych za ten obiekt:

• Otrzymują powiadomienia email o przypisaniu/usunięciu (via SimpleSendNotificationJob)
• Mogą przeglądać harmonogram swojego obiektu
• Mogą tworzyć blokady
• Mogą dodawać notatki do rezerwacji

Wyjątki¶

Warunki rzucania ChangeStateItemException (ExceptionChangeStateItem):

• Obiekt jest nieaktywny i próbujemy go aktywować
• Organizacja obiektu jest nieaktywna → "Cannot activate this item because the organization is inactive."
• Kategoria obiektu jest nieaktywna → "Cannot activate this item because the category is inactive."

Powiadomienia¶

Powiadomienia wysyłane asynchronicznie via SimpleSendNotificationJob (kolejka domyślna).

Enumy (ItemEnumService)¶

Backed string enum z 5 wartościami — typy powodów blokad:

Historia zmian¶