Harmonogramy (Schedule)¶

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

1. Opis ogólny¶

Domena Harmonogramów odpowiada za wizualizację czasu w systemie ZAJMIJ.TO. Jest to centralny punkt agregacji danych z różnych źródeł — rezerwacje, blokady obiektów i sesje zajęć grupowych — prezentowanych w formie kalendarza z możliwością eksportu do PDF.

Model Schedule jest zapisem czasowym o polimorficznym powiązaniu (scheduleable), reprezentującym:

• slot rezerwacji (ReservationSlot) — zarezerwowany czas przez klienta,
• slot oczekującej rezerwacji (WaitingReservationSlot) — tymczasowa blokada (soft-lock) podczas składania rezerwacji przez niezalogowanego użytkownika,
• blokadę obiektu (ItemBlock) — planowe lub awaryjne wyłączenie obiektu.

Sesje zajęć (ActivityItem) nie są przechowywane w tabeli schedules — są konwertowane do formatu harmonogramu w locie podczas pobierania danych (klasa ConvertActivityItemsToScheduleFormat).

Kluczowe cechy¶

• Harmonogram jest tylko do odczytu — nie posiada endpointów tworzenia, aktualizacji ani usuwania. Wpisy tworzone są automatycznie przez inne domeny (Reservation, Item).
• Obsługuje filtrowanie z uwzględnieniem hierarchii obiektów (obiekt nadrzędny i podrzędne w jednym zapytaniu).
• Eksport PDF obsługuje trzy widoki: miesięczny (kalendarz siatki), tygodniowy (oparty na minutach) i listowy (tabela z podsumowaniem statystyk).
• Dostęp publiczny (bez logowania) do endpointu index jest możliwy, lecz z ograniczeniami.

2. Architektura domeny¶

2.1 Modele danych¶

Schedule (Domain\Schedule\Model\Schedule)¶

Główny model harmonogramu. Każdy rekord reprezentuje jedno zdarzenie czasowe.

Atrybuty wirtualne (computed):

Relacje:

Publiczne filtry ($publicFilters):

id, item_id, organization_id, dates_between

Scope'y modelu:

2.2 Diagram relacji (Mermaid)¶

erDiagram
    schedules {
        uuid id PK
        uuid organization_id FK
        string scheduleable_type
        uuid scheduleable_id
        uuid item_id FK
        datetime start_at
        datetime end_at
    }

    organizations {
        uuid id PK
        string name
    }

    items {
        uuid id PK
        string name
        uuid parent_id FK
    }

    reservation_slots {
        uuid id PK
        uuid reservation_id FK
    }

    waiting_reservation_slots {
        uuid id PK
        uuid waiting_reservation_id FK
    }

    item_blocks {
        uuid id PK
        string reason_type
    }

    activity_items {
        uuid id PK
        uuid activity_id FK
        date date
        time start_time
        time end_time
    }

    schedules }o--|| organizations : "organization_id"
    schedules }o--|| items : "item_id (cascade)"
    schedules }o--o| reservation_slots : "scheduleable (morph)"
    schedules }o--o| waiting_reservation_slots : "scheduleable (morph)"
    schedules }o--o| item_blocks : "scheduleable (morph)"

flowchart TD
    subgraph "Źródła danych harmonogramu"
        RS[ReservationSlot\nrezerwacja klienta]
        WRS[WaitingReservationSlot\nsoft-lock niezalogowanego]
        IB[ItemBlock\nblokada obiektu]
        AI[ActivityItem\nsesja zajęć grupowych]
    end

    subgraph "Tabela schedules"
        S[Schedule\n📅 start_at / end_at]
    end

    subgraph "Źródła wirtualne (bez DB)"
        AIV[ActivityItem\nkonwertowane w locie]
    end

    RS -->|morphOne| S
    WRS -->|morphOne| S
    IB -->|morphOne| S
    AI -->|ConvertActivityItemsToScheduleFormat| AIV
    AIV -.->|wynik zapytania PDF| S

2.3 Struktura tabel w bazie danych¶

Tabela schedules (migracja: 0001_01_01_000022_create_schedules.php):

CREATE TABLE schedules (
    id             UUID PRIMARY KEY,
    organization_id UUID NULL,
    scheduleable_type VARCHAR(255) NOT NULL,
    scheduleable_id   UUID NOT NULL,
    item_id        UUID NOT NULL,
    start_at       DATETIME NOT NULL,
    end_at         DATETIME NOT NULL,
    created_at     DATETIME,
    updated_at     DATETIME,

    INDEX (organization_id),
    INDEX (scheduleable_type, scheduleable_id),
    INDEX (item_id),

    FOREIGN KEY (item_id) REFERENCES items(id) ON DELETE CASCADE,
    FOREIGN KEY (organization_id) REFERENCES organizations(id) ON DELETE CASCADE
);

3. Endpointy API¶

Uwierzytelnianie¶

3.1 GET /api/schedules¶

Trasa: no-auth-schedules.index (publiczny) / schedules.index (zalogowany)

Opis: Pobiera listę harmonogramów z paginacją i filtrowaniem. Zwraca kolekcję ScheduleResource. Klucze scheduleable, scheduleable_id i can są usuwane z odpowiedzi dla niezalogowanych użytkowników.

Klasy: ScheduleController::index → TraitControllerSchedule::indexScheduleController → IndexScheduleController::__invoke

Parametry zapytania:

Ograniczenie dla niezalogowanych: Filtr dates_between ograniczony do maksymalnie 365 dni (klasa ScopeDatesBetweenFunc, stała MAX_DAYS_FOR_GUEST = 365).

Eager loading (domyślne): Poprzez ApplyScheduleAggregatesOrm automatycznie ładowane są: - scheduleable z morphWith: - ReservationSlot → ['refunds', 'reservation.client', 'reservation.latestNote'] - ItemBlock → ['creator.role'] - item.childrens

Odpowiedź (ScheduleResource):

{
  "data": [
    {
      "id": "uuid",
      "organization_id": "uuid|null",
      "scheduleable_type": "Domain\\Reservation\\Model\\ReservationSlot",
      "scheduleable_id": "uuid",
      "item_id": "uuid",
      "start_at": "2026-02-01 08:00:00",
      "end_at": "2026-02-01 10:00:00",
      "can_be_edit": false,
      "created_at": "2026-01-01 12:00:00",
      "updated_at": "2026-01-01 12:00:00",
      "scheduleable_color": "#248bc7",
      "can": {
        "view": true,
        "update": false,
        "delete": false
      },
      "scheduleable": { ... },
      "item": { ... },
      "organization": { ... }
    }
  ],
  "meta": { ... },
  "links": { ... }
}

Uwaga: Dla niezalogowanych użytkowników pola scheduleable, scheduleable_id i can są usuwane z odpowiedzi (tablica UNALLOWED_NO_AUTH_KEYS).

3.2 GET /api/schedules/export-pdf¶

Trasa: schedules.export-pdf (wymaga logowania)

Opis: Generuje plik PDF z harmonogramem w jednym z trzech widoków. Zwraca plik do pobrania (typ MIME application/pdf). Nazwa pliku: harmonogram_{widok}_{data}.pdf (np. harmonogram_lista_2026-02-26_123456.pdf).

Klasy: ScheduleController::exportPdf → TraitControllerSchedule::exportSchedulePdfController → ExportSchedulePdfController::__invoke

Role wymagane: admin, supervisor, employee

Parametry zapytania:

Reguła filtrów: Co najmniej jeden z filtrów filter[item_id], filter[client_id] lub filter[activity_id] jest wymagany. Jeśli żaden nie jest podany, walidacja zwraca błąd filter_required dla wszystkich trzech pól.

Reguła zakresu dat: Filtr filter[dates_between] ograniczony do 31 dni (klasa DateRangeBetweenRule i ValidateDateRange).

Priorytet zakresu dat: 1. filter[dates_between] — jeśli podany 2. month — jeśli podany (oblicza pełny miesiąc) 3. Domyślnie: bieżący miesiąc

Szablony Blade (barryvdh/laravel-dompdf):

Format pliku PDF: - Papier: A4 - Czcionka: DejaVu Sans (obsługa polskich znaków) - Orientacja: konfigurowalna

4. Logika biznesowa¶

4.1 Główne procesy¶

Pobieranie listy harmonogramów (IndexScheduleController)¶

flowchart TD
    A[GET /api/schedules] --> B[Walidacja parametrów\nIndexScheduleControllerRequest]
    B --> C[IndexScheduleController::__invoke]
    C --> D[Budowanie QueryBuilder\nz filtrami i sortowaniem]
    D --> E[ApplyScheduleAggregatesOrm\ndefaultSort + eager loading]
    E --> F{Filtr dates_between?}
    F -->|Tak| G[ScopeDatesBetweenFunc\nwhere start_at <= to\nAND end_at >= from]
    F -->|Nie| H[Brak filtra dat]
    G --> I{Niezalogowany\ni > 365 dni?}
    I -->|Tak| J[DateRangeExceedsLimitException]
    I -->|Nie| K[Zwrot ScheduleResource]
    H --> K

Filtry dostępne w IndexScheduleController:

Logika ScopeItemWithHierarchyFunc: Gdy podany jest item_id, system wyszukuje: 1. Sam podany obiekt 2. Jego obiekt nadrzędny (jeśli parent_id nie jest null) 3. Wszystkie jego obiekty podrzędne (where parent_id = item_id)

Następnie filtruje schedule po wszystkich znalezionych ID.

Generowanie eksportu PDF (ExportSchedulePdfController)¶

flowchart TD
    A[GET /api/schedules/export-pdf] --> B[Walidacja\nExportSchedulePdfControllerRequest]
    B --> C[ParseScheduleExportRequest\nrozparsowanie parametrów]
    C --> D[ValidateDateRange\nmaks. 31 dni]
    D --> E{Podano activity_id?}
    E -->|Tak| F[FetchActivityItemsForExport\nAND ConvertActivityItemsToScheduleFormat]
    E -->|Nie| G[FetchSchedulesForExport\nschedules + opcjonalnie activity_items dla client_id]
    F --> H[BuildSchedulePdfFilterInfo\nnagłówek PDF]
    G --> H
    H --> I[BuildSchedulePdfData]
    I --> J{view_type}
    J -->|month| K[BuildMonthViewPdfData\nsiatkowy kalendarz]
    J -->|week| L[BuildWeekViewMinuteBasedPdfData\noparty na minutach]
    J -->|list| M[BuildListViewPdfData\ntabela + statystyki]
    K --> N[GenerateSchedulePdf\nDomPDF → plik .pdf]
    L --> N
    M --> N

Logika FetchSchedulesForExport: Pobiera harmonogramy z tabeli schedules. Gdy podano client_id, dodatkowo pobiera ActivityItem powiązane z rezerwacjami klienta i konwertuje je na obiekty Schedule (poprzez ConvertActivityItemsToScheduleFormat), a następnie scala obie kolekcje i sortuje po start_at.

Konwersja ActivityItem do formatu Schedule¶

ConvertActivityItemsToScheduleFormat tworzy tymczasowe obiekty Schedule z danych ActivityItem bez zapisu do bazy danych: - schedule->id = activityItem->id - schedule->start_at = data + start_time - schedule->end_at = data + end_time - schedule->scheduleable_type = ActivityItem::class - schedule->scheduleable_id = activityItem->id - Relacja organization = pobrana z activityItem->activity->organization

4.2 Reguły biznesowe¶

1. Harmonogram jest tylko do odczytu. Nie istnieją endpointy POST, PUT, PATCH ani DELETE dla domeny Schedule. Wszystkie wpisy są tworzone przez inne domeny.

2. Zdarzenia WaitingReservationSlot są widoczne w harmonogramie (kolor pomarańczowy), ale nie są renderowane w eksporcie PDF. FormatScheduleEvent zwraca null dla scheduleable_type === WaitingReservationSlot::class.

3. Sesje zajęć (ActivityItem) nie mają wpisów w tabeli schedules. Są pobierane bezpośrednio z tabeli activity_items i konwertowane na format Schedule w locie podczas eksportu PDF.

4. Widok tygodniowy PDF obejmuje całą dobę (00:00–24:00). Konfiguracja WeekViewPdfConfig: DAY_START_HOUR = 0, DAY_END_HOUR = 24, MINUTES_PER_PAGE = 1440. Jeden dzień = jedna strona PDF.

5. Eksport PDF wymaga filtra. Co najmniej jeden z filter[item_id], filter[client_id] lub filter[activity_id] musi być podany.

6. Eksport PDF ograniczony do 31 dni. Walidacja odbywa się na dwóch poziomach: DateRangeBetweenRule (walidacja requesta) i ValidateDateRange (walidacja w kontrolerze akcji).

7. Kolory zdarzeń są obliczane przez GetSchedulableColorAttr:

8. ReservationSlot → kolor klienta (reservation.client.color) lub domyślny #248bc7
9. WaitingReservationSlot → stały #F59E0B (pomarańczowy)

10. Inne (w tym ItemBlock) → stały #EF4444 (czerwony)

11. Nakładające się zdarzenia w widoku tygodniowym są obsługiwane przez DetectOverlapsAndLayout, który przydziela kolumny (column, total_columns) do każdego zdarzenia, aby uniknąć wizualnego nakrywania.

4.3 Walidacje¶

IndexScheduleControllerRequest¶

Korzysta z paginationDefaultRequestRules() (paginacja) i publicFilterRequestRules(Schedule::class) (filtry: id, item_id, organization_id, dates_between). Dostępna publicznie (authorize(): true).

ExportSchedulePdfControllerRequest¶

Domyślne wartości (prepareForValidation): - orientation: landscape jeśli view_type === 'month', w przeciwnym wypadku portrait - include_filters_info: true

Reguła niestandardowa DateRangeBetweenRule: - Sprawdza, że zakres dat nie przekracza $maxDays (domyślnie 31) - Sprawdza, że data końcowa jest po dacie początkowej - Format wejściowy: YYYY-MM-DD,YYYY-MM-DD

5. Autoryzacja i uprawnienia¶

Policy SchedulePolicy¶

Dostęp do endpointów¶

Ograniczenia dla niezalogowanych (ScheduleResource): - Pola scheduleable, scheduleable_id, can są usuwane z odpowiedzi (stała UNALLOWED_NO_AUTH_KEYS). - Filtr dates_between ograniczony do 365 dni (klasa ScopeDatesBetweenFunc).

6. Eventy i efekty uboczne¶

Observer ScheduleObserver¶

Klasa ScheduleObserver (powiązana przez atrybut #[ObservedBy(ScheduleObserver::class)]) jest aktualnie pusta — nie zawiera żadnych hooków cyklu życia modelu.

Brak własnych eventów¶

Domena Schedule nie publikuje własnych eventów domenowych. Wpisy w harmonogramie są tworzone i usuwane przez inne domeny (Reservation, Item) jako efekt uboczny ich operacji.

Tworzenie wpisów (przez inne domeny)¶

Wpisy Schedule są tworzone automatycznie gdy: - Tworzona jest ReservationSlot — morficznie powiązana jako scheduleable - Tworzony jest WaitingReservationSlot — tymczasowa blokada podczas procesu rezerwacji - Tworzony jest ItemBlock — blokada obiektu przez pracownika

Usuwanie wpisów Schedule następuje kaskadowo przez usunięcie powiązanego Item (FK z ON DELETE CASCADE).

7. Notyfikacje¶

Domena Schedule nie generuje własnych notyfikacji. Jest domeną read-only skoncentrowaną na prezentacji danych i eksporcie.

8. Powiązania z innymi domenami¶

graph LR
    SCH[Schedule]

    RES[Reservation]
    RS[ReservationSlot]
    WRS[WaitingReservationSlot]
    ITM[Item]
    IB[ItemBlock]
    ACT[Activity]
    AI[ActivityItem]
    CLI[Client]
    ORG[Organization]
    TRN[Trainer]

    RS -->|morphOne| SCH
    WRS -->|morphOne| SCH
    IB -->|morphOne| SCH
    ITM -->|item_id| SCH
    ORG -->|organization_id| SCH

    RES --> RS
    ITM --> IB
    ACT --> AI
    AI -.->|konwersja w locie\ndo eksportu PDF| SCH

    CLI -.->|filtr client_id\nw eksporcie| SCH
    TRN -.->|dane w\nFormatScheduleEvent| SCH

9. Konfiguracja¶

Enum WeekViewPdfConfig (Domain\Schedule\Enum\WeekViewPdfConfig)¶

Konfiguruje okno czasowe dla widoku tygodniowego PDF:

Wynikowy efekt: Widok tygodniowy PDF generuje jedną stronę na każdy dzień obejmującą całą dobę (00:00–24:00). Paginacja stron obliczana jest jako ceil(total_minutes / MINUTES_PER_PAGE).

Ograniczenia zakresu dat¶

Kolory zdarzeń¶

10. Znane ograniczenia i TODO¶

Ograniczenia¶

1. Brak endpointów zarządzania. Harmonogram jest wyłącznie do odczytu — wpisy można tylko przeglądać i eksportować. Tworzenie/edycja odbywa się wyłącznie przez domeny Reservation i Item.

2. ActivityItem nie jest w tabeli schedules. Sesje zajęć grupowych są pobierane i konwertowane w locie. Oznacza to, że nie mają przypisanego item_id ani organization_id w strukturze Schedule, co może powodować null w tych polach podczas eksportu PDF.

3. Widok tygodniowy PDF = cała doba. WeekViewPdfConfig nie jest konfigurowalny przez parametry API — zakres godzin 00:00–24:00 jest zakodowany na stałe w klasie enum.

4. Brak filtra organization_id w IndexScheduleController. Pole organization_id jest w $publicFilters modelu, ale nie jest zarejestrowane w AllowedFilter kontrolera akcji IndexScheduleController (dostępny jest tylko przez publicFilterRequestRules na poziomie walidacji requesta, nie jako AllowedFilter QueryBuilder).

5. Limit eksportu PDF (31 dni) jest stały. Wartość MAX_DAYS = 31 jest zakodowana na stałe w klasie ValidateDateRange i nie jest konfigurowalna.

6. ScheduleObserver jest pusty. Klasa obserwatora jest zarejestrowana (#[ObservedBy]), ale nie zawiera żadnych hooków — potencjalne miejsce na przyszłą logikę.

7. ScheduleEnumService jest pusty. Enum serwis nie zawiera żadnych wartości.

Historia zmian¶