Rezerwacje (Reservation)¶

Ostatnia aktualizacja dokumentacji: 2026-02-26 Stan synchronizacji z kodem: ✅ Zsynchronizowany

Serce systemu zajmij.to — pełny cykl życia rezerwacji od utworzenia, przez płatność, aż po zwrot i opinię.

1. Opis ogólny¶

Domena Rezerwacji odpowiada za cały proces rezerwowania obiektów i zapisów na zajęcia. To jak elektroniczna recepcja, która pracuje 24 godziny na dobę, 7 dni w tygodniu — przyjmuje rezerwacje, pobiera płatności, wysyła potwierdzenia i obsługuje zwroty.

System obsługuje dwa typy rezerwacji:

• Rezerwacje godzinowe — wynajem sal, boisk, sprzętu na określone godziny
• Zapisy na zajęcia — uczestnictwo w zajęciach grupowych (fitness, basen, warsztaty)

2. Architektura domeny¶

2.1 Modele danych¶

2.2 Diagram relacji¶

erDiagram
    Reservation ||--o{ ReservationSlot : "hasMany"
    Reservation ||--o{ ReservationPayment : "hasMany"
    Reservation ||--o{ ReservationPaidLog : "hasMany"
    Reservation ||--o{ ReservationPaymentReminderLog : "hasMany"
    Reservation }o--|| Organization : "belongsTo"
    Reservation }o--o| Client : "belongsTo"
    Reservation }o--o| Pricing : "belongsTo"
    Reservation ||--o| Review : "hasOne"
    Reservation ||--o{ Complaint : "hasMany"
    Reservation ||--o{ Note : "morphMany"
    Reservation ||--o{ Schedule : "morphMany"
    Reservation ||--o{ StatusLog : "morphMany"

    ReservationSlot }o--|| Reservation : "belongsTo"
    ReservationSlot ||--o| Schedule : "morphOne"
    ReservationSlot ||--o{ ReservationPaymentRefund : "hasMany"
    ReservationSlot }o--o| User : "cancelledBy"

    ReservationPayment }o--|| Reservation : "belongsTo"
    ReservationPayment ||--o{ ReservationPaymentRefund : "hasMany"
    ReservationPayment ||--o| ReservationPaymentReceipt : "hasOne"
    ReservationPayment }o--o| User : "creator"

    ReservationPaymentRefund }o--|| ReservationPayment : "belongsTo"
    ReservationPaymentRefund }o--o| ReservationSlot : "belongsTo"
    ReservationPaymentRefund }o--o| User : "processor"
    ReservationPaymentRefund }o--o| User : "manualConfirmer"

    ReservationPaymentReceipt }o--|| ReservationPayment : "belongsTo"

    ReservationPaymentLog }o--o| Reservation : "belongsTo"
    ReservationPaymentLog }o--o| ReservationPayment : "belongsTo"
    ReservationPaymentLog }o--o| Organization : "belongsTo"

    ReservationPaidLog }o--|| Reservation : "belongsTo"
    ReservationPaidLog }o--o| ReservationPayment : "belongsTo"
    ReservationPaidLog }o--o| ReservationPaymentRefund : "belongsTo"
    ReservationPaidLog }o--o| User : "changer"

    WaitingReservation }o--|| Organization : "belongsTo"
    WaitingReservation ||--o{ WaitingReservationSlot : "hasMany"

    WaitingReservationSlot }o--|| WaitingReservation : "belongsTo"
    WaitingReservationSlot ||--o| Schedule : "morphOne"

2.3 Struktura tabel w bazie danych¶

Tabela reservations¶

Tabela reservation_slots¶

Tabela reservation_payments¶

Tabela reservation_payment_refunds¶

Tabela reservation_payment_receipts¶

Tabela reservation_payment_logs¶

Tabela reservation_paid_logs¶

Tabela waiting_reservations¶

Tabela waiting_reservation_slots¶

3. Endpointy API¶

3.1 Rezerwacje¶

GET /api/reservations¶

• Opis: Lista rezerwacji z filtrami (paginacja, sortowanie)
• Autoryzacja: Admin, Supervisor, Employee (middleware role)
• Query Parameters: Standardowe filtry Spatie QueryBuilder + relations[]

GET /api/reservations/{reservationId}¶

• Opis: Szczegóły rezerwacji z relacjami (complaints, statusLogs)
• Autoryzacja: Admin, Supervisor, Employee (middleware role)

POST /api/reservations (auth)¶

• Opis: Tworzenie rezerwacji przez administratora
• Autoryzacja: Policy update na Item/Activity
• Zachowanie: Tworzy rezerwację bezpośrednio (bez soft-lock)

POST /api/no-auth/reservations (noAuth)¶

• Opis: Tworzenie rezerwacji przez mieszkańca (gość)
• Autoryzacja: Brak (throttle public-store)
• Zachowanie: Tworzy WaitingReservation z soft-lock, wysyła email potwierdzający

PATCH /api/reservations/{reservationId}¶

• Opis: Aktualizacja rezerwacji (dane klienta, sloty, cena)
• Autoryzacja: Policy update na Reservation

PATCH /api/reservations/{reservationId}/change-status¶

• Opis: Zmiana statusu rezerwacji
• Autoryzacja: Policy update na Reservation

PATCH /api/reservations/{reservationId}/change-send-notifications¶

• Opis: Włączenie/wyłączenie powiadomień dla rezerwacji
• Autoryzacja: Policy update na Reservation

PUT /api/reservations/{reservationId}/confirm-price¶

• Opis: Potwierdzenie ceny rezerwacji przez admina
• Autoryzacja: Policy update na Reservation

GET /api/reservations/{reservationId}/cancellation-info (auth + noAuth)¶

• Opis: Informacje o polityce anulowania i kwotach zwrotu
• Autoryzacja: Auth: dowolny zalogowany | NoAuth: throttle public-find

GET /api/no-auth/reservations/{reservationId}/find¶

• Opis: Wyszukanie rezerwacji przez UUID + access_code (dla gościa)
• Autoryzacja: Brak (throttle public-find)

POST /api/no-auth/confirm-reservation-email¶

• Opis: Potwierdzenie emaila rezerwacji (konwersja WaitingReservation → Reservation)
• Autoryzacja: Brak (throttle public-store)

3.2 Płatności¶

GET /api/reservation-payments (auth + noAuth)¶

• Opis: Lista płatności z filtrami
• Autoryzacja: Auth: Admin/Supervisor/Employee | NoAuth: throttle public-find

POST /api/reservation-payments (auth + noAuth)¶

• Opis: Tworzenie nowej płatności (online P24, manual, free, dopłata)
• Autoryzacja: Auth: Policy update na Reservation | NoAuth: throttle public-store

GET /api/reservation-payments/{paymentId}¶

• Opis: Szczegóły płatności
• Autoryzacja: Admin, Supervisor, Employee

POST /api/reservation-payments/{paymentId}/mark-as-completed¶

• Opis: Ręczne oznaczenie płatności jako opłaconej (manual payments)
• Autoryzacja: Policy update na ReservationPayment

POST /api/reservation-payments/{paymentId}/cancel¶

• Opis: Anulowanie oczekującej płatności
• Autoryzacja: Policy update na ReservationPayment

POST /api/reservation-payments/{paymentId}/refund¶

• Opis: Inicjowanie zwrotu (pełny lub częściowy)
• Autoryzacja: Policy update na ReservationPayment

GET /api/reservation-payments/{paymentId}/receipt (auth + noAuth)¶

• Opis: Pobranie paragonu PDF
• Autoryzacja: Auth: dowolny | NoAuth: throttle public-find

POST /api/reservation-payments/{paymentId}/send-receipt¶

• Opis: Wysłanie paragonu emailem
• Autoryzacja: Policy update na ReservationPayment

POST /api/reservation-payments/{paymentId}/verify-p24-status (auth + noAuth)¶

• Opis: Weryfikacja statusu transakcji P24
• Autoryzacja: Auth: dowolny | NoAuth: throttle public-store

POST /api/reservation-payment-callback (auth + noAuth)¶

• Opis: Webhook callback z Przelewy24 po płatności
• Autoryzacja: Throttle payment-callback, weryfikacja sygnatury SHA384

3.3 Zwroty¶

GET /api/reservation-payment-refunds (auth + noAuth)¶

• Opis: Lista zwrotów z filtrami
• Autoryzacja: Auth: Admin/Supervisor/Employee | NoAuth: throttle public-find

POST /api/reservation-payment-refunds/{refundId}/confirm¶

• Opis: Potwierdzenie ręcznego zwrotu (pending_manual → completed)
• Autoryzacja: Policy update na ReservationPaymentRefund

GET /api/reservation-payment-refunds/{refundId}/download (auth + noAuth)¶

• Opis: Pobranie potwierdzenia zwrotu PDF
• Autoryzacja: Auth: dowolny | NoAuth: throttle public-find

POST /api/reservation-payment-refunds/{refundId}/send¶

• Opis: Wysłanie potwierdzenia zwrotu emailem
• Autoryzacja: Policy update na ReservationPaymentRefund

POST /api/reservation-payment-refund-callback (auth + noAuth)¶

• Opis: Webhook callback z P24 po zwrocie
• Autoryzacja: Throttle payment-callback, weryfikacja sygnatury

3.4 Sloty¶

GET /api/reservation-slots (auth + noAuth)¶

• Opis: Lista slotów rezerwacji
• Autoryzacja: Auth: dowolny | NoAuth: throttle public-find

GET /api/reservation-slots/{slotId} (auth + noAuth)¶

• Opis: Szczegóły slotu
• Autoryzacja: Auth: dowolny | NoAuth: throttle public-find

POST /api/cancel-reservation-slots (auth + noAuth)¶

• Opis: Anulowanie wybranych slotów rezerwacji
• Autoryzacja: Auth: Policy update na Reservation | NoAuth: throttle public-store

3.5 Załączniki¶

GET /api/reservation-attachments (auth + noAuth)¶

• Opis: Lista załączników rezerwacji
• Autoryzacja: Auth: dowolny | NoAuth: throttle public-find

POST /api/reservation-attachments (auth + noAuth)¶

• Opis: Dodanie załącznika (zdjęcia, PDF, dokumenty)
• Autoryzacja: Auth: Policy update na Reservation | NoAuth: throttle public-store
• Akceptowane formaty: JPEG, PNG, GIF, WebP, MP4, MOV, AVI, PDF, DOC, DOCX

DELETE /api/reservation-attachments/{attachmentId} (auth + noAuth)¶

• Opis: Usunięcie załącznika
• Autoryzacja: Auth: Policy update na Reservation | NoAuth: throttle public-store

3.6 Logi płatności¶

GET /api/reservation-paid-logs¶

• Opis: Lista logów zmian płatności (audyt)
• Autoryzacja: Admin, Supervisor, Employee

4. Logika biznesowa¶

4.1 Główne procesy¶

Proces tworzenia rezerwacji (mieszkaniec / noAuth)¶

1. Walidacja danych (formularz, dostępność slotów, deadline, blokady)
2. Obliczenie ceny na podstawie cennika (CalculatePriceForReservationable)
3. Utworzenie WaitingReservation z WaitingReservationSlot (soft-lock)
4. Każdy WaitingReservationSlot tworzy wpis w Schedule (blokuje termin)
5. Wysłanie emaila z linkiem potwierdzającym (ReservationEmailConfirmationNotification)
6. Po kliknięciu linku:
7. Walidacja tokenu i ważności (confirmation_token, expires_at)
8. Usunięcie WaitingReservation (i wpisów Schedule)
9. Utworzenie Reservation z ReservationSlot (nowe wpisy Schedule)
10. Wygenerowanie identyfikatorów (UUID, access_code)
11. Przypisanie/utworzenie klienta (FindOrCreateClientForReservation)
12. Zbudowanie snapshotu (BuildReservationSnapshots)
13. Ustalenie statusu płatności (DetermineReservationPricingAndStatus)
14. Wysłanie powiadomień (SendNewReservationNotifications)

Proces tworzenia rezerwacji (admin / auth)¶

1. Walidacja danych (formularz, dostępność slotów)
2. Bezpośrednie utworzenie Reservation z ReservationSlot (bez soft-lock)
3. Wygenerowanie identyfikatorów, snapshot, ustalenie ceny
4. Powiadomienia do klienta i managera

Proces płatności online (Przelewy24)¶

1. Utworzenie ReservationPayment (status: pending)
2. Rejestracja transakcji w P24 (P24PaymentCreator)
3. Wygenerowanie URL płatności i podpisu SHA384
4. Klient przekierowany do P24
5. P24 wysyła callback (ProcessPrzelewy24Callback):
6. Weryfikacja sygnatury (P24CallbackValidator)
7. Weryfikacja statusu transakcji (VerifyP24TransactionStatus)
8. Oznaczenie płatności jako completed (MarkPaymentAsCompleted)
9. Dystrybucja kwoty do slotów (DistributePaymentToSlots)
10. Aktualizacja payment_status rezerwacji
11. Wygenerowanie paragonu (ReceiptService)
12. Wysłanie powiadomień (SendPaymentConfirmedNotification)

Proces zwrotu¶

1. Walidacja (RefundValidator): status completed/partially_refunded, kwota ≤ available
2. Ustalenie metody zwrotu (DetermineRefundMethod)
3. Utworzenie ReservationPaymentRefund
4. Jeśli gateway: wysłanie do P24 (InitiateGatewayRefund → CallP24RefundApi)
5. Jeśli manual: status pending_manual, oczekuje na potwierdzenie admina
6. Po zakończeniu (CompleteRefund):
7. Aktualizacja refunded_amount na slotach (UpdateSlotsRefundedAmountsFromRefund)
8. Aktualizacja payment_status płatności i rezerwacji
9. Wygenerowanie potwierdzenia zwrotu (RefundConfirmationService)
10. Wysłanie powiadomień (SendRefundProcessedNotification)

4.2 Reguły biznesowe¶

1. Rezerwacja nie może kolidować z istniejącą rezerwacją — system sprawdza harmonogram
2. Anulowanie jest możliwe tylko w statusach pending lub confirmed
3. Edycja rezerwacji możliwa tylko w statusach pending lub confirmed
4. Slot w przeszłości nie może być zarezerwowany (SlotNotInPastRule)
5. Rezerwacja wymaga deadline'u — X godzin przed terminem (ReservationDeadlineRule)
6. Minimalny zwrot to 0.01 PLN (MIN_REFUND_AMOUNT)
7. Maksymalnie 50 oczekujących zwrotów na płatność (MAX_PENDING_REFUNDS_PER_PAYMENT)
8. Duplikaty zwrotów wykrywane w oknie 60 sekund (DUPLICATE_WINDOW_SECONDS)
9. Zwrot bramkowy: max 3 próby z opóźnieniem 2 sekund (MAX_RETRY_ATTEMPTS, RETRY_DELAY_SECONDS)
10. Niezalogowany użytkownik przy anulowaniu slotów — zwrot zawsze pending_manual
11. Gdy refunded_amount >= price slotu → automatyczne anulowanie slotu
12. Gdy wszystkie sloty anulowane → automatyczne anulowanie rezerwacji
13. Dopłata: jeśli amount > remaining, system automatycznie zwiększa total_price
14. Blokada obiektu anuluje tylko kolidujące sloty, nie całe rezerwacje
15. Odwołanie zajęć anuluje wszystkie rezerwacje powiązane z danym ActivityItem
16. Cena nie może być zmniejszona poniżej opłaconej kwoty (wymaga zwrotu)
17. Rezerwacja wymaga akceptacji regulaminu obiektu, jeśli obiekt go posiada (ReservationableStatuteRequiredRule)

4.3 Walidacje (Form Requests)¶

StoreReservationControllerRequest — tworzenie rezerwacji¶

Custom Rules: - SlotAvailabilityRule — sprawdza czy termin nie jest zajęty - SlotNotInPastRule — termin nie może być w przeszłości - ReservationDeadlineRule — deadline rezerwacji - ItemBlockConflictRule — brak kolizji z blokadami - ReservationableAllowedRule — obiekt pozwala na rezerwację - ReservationableStatuteRequiredRule — regulamin obiektu wymagany - FullDayReservationRule — rezerwacja pełnodniowa (jeśli dotyczy) - ActivityItemHasAvailableSlotsRule — wolne miejsca na zajęciach - VerifyReservationCorrectDataRule — spójność danych

RefundReservationPaymentControllerRequest — zwrot¶

Custom Rules: - MaxRefundAmountPaymentRule — kwota ≤ dostępna na płatności - MaxRefundAmountReservationRule — kwota ≤ dostępna na rezerwacji

5. Autoryzacja i uprawnienia¶

Polityki (Policies)¶

Middleware¶

6. Eventy i efekty uboczne¶

Observer: ReservationObserver¶

Observer: StatusLogObserver¶

Automatycznie loguje każdą zmianę statusu do tabeli status_logs (polimorficzna relacja).

Atrybuty wyliczane (Attr)¶

7. Powiadomienia¶

System wysyła automatyczne powiadomienia na każdym etapie:

8. Komendy CRON¶

9. Powiązania z innymi domenami¶

10. Konfiguracja¶

Konfiguracja Przelewy24¶

Plik: config/transfers24.php

Polityka anulowania¶

Każdy obiekt (Item) może mieć własną politykę:

Terminy rezerwacji¶

Stałe konfiguracyjne (ReservationEnumService)¶

11. Statusy i enumy¶

Statusy rezerwacji¶

stateDiagram-v2
    [*] --> pending: Utworzenie
    pending --> confirmed: Potwierdzenie email
    pending --> canceled: Anulowanie
    pending --> rejected: Odrzucenie
    confirmed --> canceled: Anulowanie
    confirmed --> [*]: Zakończenie
    canceled --> [*]
    rejected --> [*]

Statusy płatności rezerwacji (payment_status)¶

Statusy transakcji (ReservationPayment.status)¶

Statusy zwrotów (ReservationPaymentRefund.status)¶

Metody płatności¶

Metody zwrotu¶

Typy zwrotu¶

Typy anulowania¶

Akcje w PaidLog¶

23 typy akcji logowanych w reservation_paid_logs:

12. Dopłaty (Multiple Payments)¶

System obsługuje scenariusz dopłat, gdy rezerwacja ma już częściowe lub pełne opłaty.

Jak to działa?¶

sequenceDiagram
    participant A as Admin
    participant S as System
    participant R as Rezerwacja
    participant P as Płatność
    participant SL as Sloty

    Note over R: total_price=2952, total_paid=2952 (w pełni opłacona)
    A->>S: Dodaj dopłatę (amount=1000, mark_completed=true)
    S->>S: Auto-zwiększa total_price do 3952
    S->>P: Tworzy płatność (completed, 1000 PLN)
    S->>SL: Dystrybuuje 1000 PLN do slotów
    S->>R: Aktualizuje payment_status
    Note over R: total_price=3952, total_paid=3952

Parametry API dla dopłat¶

{
  "reservation_id": "uuid",
  "payment_method": "manual",
  "amount": 1000,
  "mark_completed": true,
  "paid_at": "2026-02-06",
  "reason": "Dopłata za dodatkowy sprzęt"
}

Zasady dopłat¶

13. Mechanizm soft-lock¶

14. Bezpieczeństwo płatności¶

Weryfikacja callbacków P24¶

• Każdy callback weryfikowany podpisem SHA384 (P24CallbackValidator)
• Porównanie amount, session_id, order_id z oryginalnymi danymi
• Logowanie prób fraud (PAYMENT_LOG_CHANNEL_SECURITY)
• Zdarzenia bezpieczeństwa: signature_mismatch, session_mismatch, order_mismatch, amount_mismatch

Logi płatności¶

Szczegółowe logi w reservation_payment_logs:

15. Dane audytowe (Snapshot)¶

Przy tworzeniu rezerwacji system zapisuje snapshot obiektu w polu reservationable_snapshot:

Snapshot dla Item¶

{
  "_pricing_snapshot": {
    "id": "uuid",
    "name": "Cennik standardowy",
    "prices": [...],
    "vat_rate": "23%"
  },
  "_client_snapshot": {
    "first_name": "Jan",
    "last_name": "Kowalski",
    "email": "jan@example.com"
  },
  "_vat_rate_source": "pricing",
  "name": "Sala gimnastyczna",
  "address": "ul. Szkolna 1"
}

Snapshot dla ActivityItem¶

{
  "_pricing_snapshot": {...},
  "_client_snapshot": {...},
  "_vat_rate_source": "pricing",
  "activity_name": "Fitness",
  "activity_item_date": "2026-03-01",
  "trainer_name": "Anna Nowak"
}

16. Kluczowe klasy biznesowe¶

Action/Other — główne klasy¶

Scopes (Query Scopes)¶

17. Media Collections¶

Model Reservation rejestruje dwie kolekcje mediów (Spatie MediaLibrary):

18. Znane ograniczenia i TODO¶