Architektura Harmonogramu i Rezerwacji

1. Struktura Danych i Relacje Encji

System opiera się na zaawansowanym modelu relacyjnym z wykorzystaniem natywnych typów czasowych baz danych (np. przedziały czasowe z uwzględnieniem stref czasowych).

• Harmonogramy Stałe: Definiują ramy dostępności (godziny pracy) w cyklu tygodniowym.
• Punkty Startowe: Definiują niestandardowe punkty początkowe wymuszające określone godziny startowe w grafiku (używane w inteligentnym trybie restrykcyjnym).
• Blokady i Wyjątki (Time Blocks): Definiują wyjątki czasowe (urlopy, przerwy, ręczne blokady). Encja ta obsługuje dziedziczenie – może blokować globalnie całą organizację lub precyzyjnie wybranego specjalistę.
• Sloty Grupowe: Klasy/zajęcia grupowe posiadające z góry określone ramy czasowe, rygorystyczne limity uczestników oraz przypisaną usługę bazową.
• Model Rezerwacji: Główna encja rezerwacji elastycznie wiąże się z usługami, personelem lub dedykowanymi slotami grupowymi.

1.1 Ochrona Integralności Danych (Constraints)

System wykorzystuje niskopoziomowe indeksy wykluczające (Exclusion Constraints) na poziomie silnika bazy danych, aby w sposób całkowicie atomowy blokować wyścigi (Race Conditions) podczas jednoczesnych rezerwacji. Próba zapisu potwierdzonej rezerwacji, której czas trwania nakłada się na istniejącą rezerwację w obrębie tego samego zasobu, jest natychmiastowo i bezpiecznie odrzucana przez jądro bazy danych.

2. Rdzeń Logiki Biznesowej: Ewaluacja Dostępności

Ewaluacja wolnych terminów realizowana jest przez wysoce zoptymalizowane procedury składowane (RPC - Remote Procedure Call) uruchamiane bezpośrednio w bazie danych, co eliminuje opóźnienia sieciowe. Działanie silnika dzieli się na dwa scenariusze uzależnione od zdefiniowanych progów wyprzedzenia.

2.1 Scenariusz Elastyczny (Generowanie Serii)

Aktywowany dla dat bliskich (przed upływem zdefiniowanego progu inteligentnego).

• Wykorzystuje natywne funkcje generowania siatki czasu.
• Odfiltrowuje sloty zachodzące na przeszłość.
• Asynchronicznie odfiltrowuje sloty, dla których zakresy czasowe kolidują ze zdefiniowanymi wyjątkami (urlopy, przerwy).

2.2 Scenariusz Restrykcyjny (Inteligentny Harmonogram / Punkty Styku)

Aktywowany dla dat wykraczających poza próg, zapobiega zjawisku fragmentacji grafiku ("poszatkowany kalendarz").

• Zamiast generowania ciągłej siatki czasowej, silnik tworzy strukturę (CTE) zawierającą unikalne, ściśle zdefiniowane punkty startowe (tzw. Anchor Points).
• Potencjalny nowy slot rezerwacyjny może rozpocząć się wyłącznie w miejscu przylegającym do początku zmiany, zdefiniowanego punktu lub dokładnego czasu zakończenia innej rezerwacji. Metoda ta wymusza przyleganie nowych zdarzeń do już istniejących.

3. Logika Kolizji: Wizyty Indywidualne vs Grupowe

Procedury ewaluacji weryfikują kolizje wykorzystując dynamiczne rozgałęzienia logiki (Control Flow) w zależności od typu usługi.

• Tryb 1:1: Jakakolwiek istniejąca rezerwacja potwierdzona w weryfikowanym przedziale czasowym u danego pracownika powoduje bezwzględne odrzucenie wyliczanego slotu.
• Tryb Grupowy:
  1. System blokuje nakładanie się różnych typów wizyt (np. indywidualnych na grupowe).
  2. Akceptuje slot grupowy wyłącznie pod warunkiem, że suma przypisanych rezerwacji jest ściśle mniejsza niż zdefiniowany w systemie, sztywny próg maksymalnej liczby uczestników.

4. Architektura Warstwy API i Zapis Danych

Przepływ danych w aplikacji został zaprojektowany z myślą o bezpieczeństwie i wydajności:

1. Frontend (UI) i Optymalizacja Stanu: Komponenty klienckie utrzymują lokalny stan kalendarza. Żądania dostępności (w formacie ustrukturyzowanych obiektów JSON) wysyłane są do autoryzowanych endpointów API.
2. Mutacje Danych (Server Actions): Zapis danych realizowany jest wyłącznie w bezpiecznym środowisku serwerowym (Next.js Server Actions), z pominięciem publicznych REST API. Akcje te realizują ścisłą walidację struktur DTO (Data Transfer Objects) i wykorzystują uprzywilejowane poświadczenia serwerowe, w pełni opierając bezpieczeństwo zapisu na warstwie backendowej.

5. Architektura Modułu Zajęć Grupowych

Moduł zajęć grupowych różni się architektonicznie od standardowych rezerwacji, wprowadzając własne mechanizmy renderowania, zarządzania stanem oraz ochrony prywatności.

• Zarządzanie Stanem i Feature Flags: Dostępność modułu jest globalnie sterowana architekturą Feature Flags na poziomie ustawień organizacji.
• Pseudonimizacja Uczestników (RODO): Zapisy na zajęcia grupowe wykorzystują mechanizm pseudonimizacji. Dzięki temu w publicznym widoku dostępności wyświetlana jest lista zapisanych uczestników bez ujawniania ich danych osobowych, podczas gdy pełne dane pozostają bezpiecznie ukryte w panelu administracyjnym.
• Optymalizacja Renderowania (UI): Aby zapobiec problemom nakładania się na siebie wielu elementów (Z-Index rendering issue), system wdraża inteligentną agregację bloków – w widoku kalendarza pojedyncze rezerwacje grupowe są agregowane do jednego, nadrzędnego interfejsu zarządzania instancją zajęć.