Aktywności (Activity)¶

Zajęcia grupowe i wydarzenia — joga, aqua aerobik, warsztaty ceramiczne i inne aktywności z harmonogramem sesji.

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

Co to jest?¶

Domena Aktywności zarządza zajęciami grupowymi i wydarzeniami. To jak karta kursów w domu kultury — każda aktywność (np. "Joga dla początkujących") ma wiele sesji (poniedziałki o 18:00), na które zapisują się uczestnicy. System zarządza harmonogramem, pojemnością, trenerami i rezerwacjami.

Kluczowa koncepcja: Activity (szablon) → ActivityItem (sesja)

flowchart TD
    A[Activity: Joga dla początkujących] --> B[Sesja: Pon 18:00]
    A --> C[Sesja: Śr 18:00]
    A --> D[Sesja: Pt 18:00]
    B --> E[Rezerwacje uczestników]
    C --> F[Rezerwacje uczestników]
    D --> G[Rezerwacje uczestników]

Jakie problemy rozwiązuje?¶

Kluczowe funkcjonalności¶

Dla administratora¶

Dla klienta¶

Activity vs ActivityItem¶

Activity (Szablon aktywności)¶

Co to jest: Definicja zajęć — nazwa, opis, pojemność, cena.

Atrybuty wyliczane Activity¶

ActivityItem (Sesja)¶

Co to jest: Konkretny termin zajęć — data, godzina, trener.

Atrybuty wyliczane ActivityItem¶

Struktura tabel w bazie danych¶

Tabela activities¶

Tabela activity_items¶

Indeksy:

• activity_items_date_activity_start_index — indeks złożony na (date, activity_id, start_time)
• activity_items_trainer_id_index — indeks na trainer_id

Jak to działa?¶

Scenariusz 1: Tworzenie nowych zajęć¶

sequenceDiagram
    participant A as Administrator
    participant S as System
    participant Q as Kolejka

    A->>S: Tworzy aktywność "Aqua aerobik"
    A->>S: Dodaje sesje: Pon/Śr/Pt 10:00
    A->>S: Ustawia powtarzanie: 10 tygodni
    S->>S: Observer ustawia organization_id z item
    S->>S: Tworzy cennik (jeśli is_paid=true)
    S->>Q: Dispatchuje CreateManyActivityItemsJob
    Q->>S: Generuje 30 sesji (3×10)
    S-->>A: Aktywność gotowa

1. Administrator definiuje aktywność (max 10 definicji sesji jednocześnie)
2. Wybiera dni tygodnia i godziny
3. Ustawia ile tygodni z góry generować (max 100)
4. System asynchronicznie tworzy sesje (kolejka domain)
5. Zajęcia gotowe do rezerwacji

Scenariusz 2: Klient zapisuje się na zajęcia¶

sequenceDiagram
    participant K as Klient
    participant S as System
    participant R as Rezerwacja

    K->>S: Przegląda zajęcia
    K->>S: Wybiera "Joga" w poniedziałek
    S->>S: Sprawdza dostępność miejsc
    S->>S: Sprawdza deadline rezerwacji
    K->>R: Tworzy rezerwację
    R-->>K: Potwierdzenie zapisu

Scenariusz 3: Anulowanie sesji¶

flowchart TD
    A[Administrator anuluje sesję] --> B[System ustawia is_canceled=true]
    B --> C[Observer: is_active = false]
    C --> D[Observer: dispatch CancelReservationsForActivityItemJob]
    D --> E[Job na kolejce cancellations]
    E --> F[Dla każdej rezerwacji: CancelReservation.cancelDueToActivityCancellation]
    F --> G[Anulowanie slotów + zwroty + notyfikacja email]

Gdy sesja zostaje anulowana (is_canceled=true), observer automatycznie:

1. Dezaktywuje sesję (is_active = false)
2. Dispatchuje CancelReservationsForActivityItemJob na kolejkę cancellations (z afterCommit())
3. Job przetwarza każdą rezerwację osobno — pełny flow anulowania:
   • Zmiana statusu rezerwacji na canceled
   • Anulowanie aktywnych slotów
   • Automatyczny zwrot płatności (jeśli opłacona)
   • Wysyłka powiadomienia email do klienta z informacją o odwołanych zajęciach

Scenariusz 4: Dezaktywacja aktywności¶

flowchart TD
    A[Activity.is_active = false] --> B[Observer wykrywa zmianę]
    B --> C[CancelItemsForDisabledActivity]
    C --> D[Wszystkie ActivityItems.is_active = false]

Sesje są dezaktywowane w partiach po 2000 dla wydajności.

Scenariusz 5: Zmiana is_paid na false¶

Gdy aktywność zostanie przełączona na bezpłatną (is_paid=false), observer UpdatedActivityObserver automatycznie tworzy nowy cennik z wartością 0 (aktywny, VAT 23%, bez client_id). Poprzednie cenniki pozostają bez zmian.

Powiązania z innymi domenami¶

Wartość biznesowa¶

Zarządzanie pojemnością¶

Definicja limitów¶

Obliczanie dostępnych miejsc¶

available_slots = max_participants - active_reservations_count - active_waiting_reservations_count

Gdzie:

• active_reservations_count — rezerwacje z wykluczeniem statusów CANCELED i REJECTED
• active_waiting_reservations_count — rezerwacje oczekujące z expires_at > now() (niewygasłe)

Walidacja przy aktualizacji¶

Poziomy trudności¶

Poziomy zdefiniowane w ActivityEnumService z tłumaczeniami (getLevels()).

Przypisanie trenera¶

Walidacja dostępności¶

System sprawdza czy trener nie ma konfliktu (TrainerAvailabilityRule):

flowchart TD
    A[Przypisz trenera do sesji] --> B{Sprawdź konflikty}
    B -->|Brak konfliktów| C[Przypisz]
    B -->|Konflikt| D{force_add_trainer?}
    D -->|Tak| C
    D -->|Nie| E[Błąd: Trener zajęty]

Wykrywanie konfliktów¶

System sprawdza czy czasy się nakładają (tylko sesje nieanulowane):

existingStart < newEnd AND existingEnd > newStart

Walidacja przy tworzeniu vs aktualizacji¶

Wymuszenie przypisania¶

Parametr force_add_trainer=true pozwala pominąć walidację (dla wyjątkowych sytuacji).

Cennik¶

Konfiguracja¶

Atrybuty cenowe¶

Optymalizacja cenowa (Aggregates ORM)¶

Na listach (GET /activities) ceny wyliczane są za pomocą subqueries SQL (ApplyActivityAggregatesOrm) zamiast ładowania relacji, co eliminuje problem N+1 query.

Deadline rezerwacji¶

Konfiguracja¶

Przykład¶

Sesja: 2024-02-12 18:00
reservation_deadline_hours: 24
Deadline: 2024-02-11 18:00 (dzień wcześniej)

Po przekroczeniu deadline'u nowe rezerwacje są blokowane.

Polityka anulowania¶

Pola konfiguracyjne¶

Wykorzystanie¶

• Pokazywane klientowi przy rezerwacji
• Sprawdzane przy próbie anulowania
• Wpływa na decyzję o zwrocie

Media i dokumenty¶

Zdjęcia¶

Konwersje niekolejkowane (nonQueued) — przetwarzane synchronicznie.

Regulamin zajęć¶

Widoczność publiczna¶

Flagi widoczności¶

Logika wyświetlania¶

flowchart TD
    A[Użytkownik przegląda zajęcia] --> B{is_public?}
    B -->|Nie| C[Ukryj]
    B -->|Tak| D{is_active?}
    D -->|Nie| C
    D -->|Tak| E[Pokaż]
    E --> F{is_public_price_list?}
    F -->|Tak| G[Pokaż cenę]
    F -->|Nie| H{Zalogowany?}
    H -->|Tak| G
    H -->|Nie| I[Ukryj cenę]

Ograniczenia dla niezalogowanych¶

ActivityResource — pola total_reservations i can są ukrywane dla niezalogowanych użytkowników. Dodatkowo, jeśli is_public_price_list=false, ukrywane są dodatkowe klucze cenowe (current_price, current_price_gross, current_price_vat_rate, lowest_price, lowest_price_gross, lowest_price_vat_rate).

ActivityItemResource — pole can jest ukrywane dla niezalogowanych użytkowników. Pola cenowe nie dotyczą sesji (brak logiki getExtraUnallowedNoAuthKeys).

Observery i cykl życia¶

ActivityObserver¶

ActivityItemObserver¶

Walidacja aktywacji (Exceptions)¶

Aktywacja Activity¶

Nie można aktywować aktywności (changeState) jeśli:

Aktywacja ActivityItem¶

Nie można aktywować sesji (changeState) jeśli:

Anulowanie ActivityItem¶

Nie można anulować sesji (canceled) jeśli:

Wyszukiwanie i filtrowanie¶

Filtry Activity (GET /activities)¶

Filtry ActivityItem (GET /activity-items)¶

Filtry geograficzne (z Activity → Item)¶

Filtry udogodnień (z Activity → Item)¶

Scope wyszukiwania (search)¶

Przeszukuje przez relację activity:

• name — nazwa aktywności
• desc — opis aktywności
• tags — tagi
• meta_title — tytuł SEO
• meta_description — opis SEO
• category.name — nazwa kategorii

Sortowanie (ActivityItem)¶

API Endpoints¶

Publiczne (bez autoryzacji)¶

Dla zalogowanych użytkowników¶

Walidacja — szczegółowe reguły¶

POST /activities (StoreActivityControllerRequest)¶

PATCH /activities/{activityId} (UpdateActivityControllerRequest)¶

Wszystkie pola są opcjonalne (sometimes). Dodatkowe reguły:

• item_id — sometimes|nullable|uuid|exists:items,id + musi być aktywnym obiektem
• category_id — sometimes|nullable|uuid|exists:categories,id + ActiveCategoryRule(activity)
• max_participants — walidacja MaxParticipantsActivityUpdateRule: nie można zmniejszyć poniżej aktualnej liczby aktywnych rezerwacji
• pricing — opcjonalny array, dodaje nowy cennik (nie zastępuje)

POST /activity-items (StoreActivityItemControllerRequest)¶

PATCH /activity-items/{activityItemId} (UpdateActivityItemControllerRequest)¶

Wszystkie pola opcjonalne (sometimes). TrainerAvailabilityRule zastosowana do date, start_time, end_time i trainer_id — wyklucza aktualną sesję z kontroli konfliktów.

PATCH /activities/{activityId}/change-category (ChangeCategoryActivityControllerRequest)¶

Generowanie powtarzających się sesji¶

Parametry¶

Przykład¶

{
  "activity_items": [
    {
      "start_date": "2024-02-12",
      "day": 1,
      "how_many_repeat_times": 10,
      "start_time": "18:00",
      "end_time": "19:30",
      "trainer_id": "uuid-trenera",
      "level": "beginner",
      "reservation_deadline_hours": 24
    }
  ]
}

Wygeneruje 10 sesji w kolejne poniedziałki.

Uprawnienia¶

Role wymagane (middleware)¶

Akcje store, update, changeState, changeCategory, canceled wymagają roli: Admin, Supervisor lub Employee.

Polityki autoryzacji (Policy)¶

Poza wymaganymi rolami, system sprawdza polityki organizacyjne (ActivityPolicy, ActivityItemPolicy):

ActivityPolicy¶

ActivityItemPolicy¶

Struktura plików domeny¶

app/Domain/Activity/
├── Action/
│   ├── Attr/                              # Atrybuty wyliczane
│   │   ├── GetAvailableSlotsAttr.php
│   │   ├── GetCurrentPriceAttr.php
│   │   ├── GetCurrentPriceGrossAttr.php
│   │   ├── GetCurrentPriceVatRateAttr.php
│   │   ├── GetCurrentPricingAttr.php
│   │   ├── GetDateXTimeAttr.php
│   │   ├── GetLowestPriceAttr.php
│   │   ├── GetLowestPriceGrossAttr.php
│   │   ├── GetLowestPriceVatRateAttr.php
│   │   └── GetLowestPricingAttr.php
│   ├── Controller/                        # Akcje kontrolerów
│   │   ├── IndexActivityController.php
│   │   ├── IndexActivityItemController.php
│   │   ├── ShowActivityController.php
│   │   ├── ShowActivityItemController.php
│   │   ├── StoreActivityController.php
│   │   ├── StoreActivityItemController.php
│   │   ├── UpdateActivityController.php
│   │   └── UpdateActivityItemController.php
│   ├── Other/                             # Logika biznesowa i observery
│   │   ├── ActivityItemWithMaxReservations.php
│   │   ├── ApplyActivityAggregatesOrm.php
│   │   ├── ApplyActivityItemAggregatesOrm.php
│   │   ├── CancelItemsForDisabledActivity.php
│   │   ├── CreateActivity.php
│   │   ├── CreateActivityItem.php
│   │   ├── CreateManyActivityItems.php
│   │   ├── CreatingActivityObserver.php
│   │   ├── ExceptionCanceledActivityItem.php
│   │   ├── ExceptionChangeStateActivity.php
│   │   ├── ExceptionChangeStateActivityItem.php
│   │   ├── UpdateActivity.php
│   │   ├── UpdatedActivityObserver.php
│   │   ├── UpdatingActivityItemObserver.php
│   │   ├── UpdatingActivityObserver.php
│   │   ├── UpdatingIsActiveActivityObserver.php
│   │   └── UpdatingIsCanceledActivityItemObserver.php
│   ├── Scope/                             # Query scopes
│   │   ├── ScopeActivityItemHasAvailableSlotsFunc.php
│   │   ├── ScopeDateGreaterThanTodayFunc.php
│   │   ├── ScopeDatesBetweenFunc.php
│   │   ├── ScopePriceFromFunc.php
│   │   ├── ScopePriceToFunc.php
│   │   └── ScopeSearchFunc.php
│   └── Sort/                              # Custom sorty
│       ├── SortByActivityCreatedAt.php
│       ├── SortByActivityName.php
│       ├── SortByAvgReviews.php
│       └── SortByLowestPrice.php
├── Controller/
│   ├── ActivityController.php
│   └── ActivityItemController.php
├── Job/
│   ├── CancelReservationsForActivityItemJob.php
│   └── CreateManyActivityItemsJob.php
├── Model/
│   ├── Activity.php
│   └── ActivityItem.php
├── Observer/
│   ├── ActivityObserver.php
│   └── ActivityItemObserver.php
├── Policy/
│   ├── ActivityPolicy.php
│   └── ActivityItemPolicy.php
├── Request/
│   ├── ChangeCategoryActivityControllerRequest.php
│   ├── IndexActivityControllerRequest.php
│   ├── IndexActivityItemControllerRequest.php
│   ├── Rule/
│   │   ├── MaxParticipantsActivityUpdateRule.php
│   │   └── TrainerAvailabilityRule.php
│   ├── StoreActivityControllerRequest.php
│   ├── StoreActivityItemControllerRequest.php
│   ├── UpdateActivityControllerRequest.php
│   └── UpdateActivityItemControllerRequest.php
├── Resource/
│   ├── ActivityItemResource.php
│   └── ActivityResource.php
└── Service/
    ├── ActivityEnumService.php
    ├── TraitActivity.php
    └── TraitControllerActivity.php

Znane uwagi techniczne¶

Best practices¶

Historia zmian¶