Dokumentacja Techniczna: Integracja z Kalendarzem Google (EnterSlot)

Dokument opisuje architekturę dwukierunkowej synchronizacji pomiędzy platformą EnterSlot a Kalendarzem Google. Rozwiązanie opiera się na branżowym standardzie OAuth 2.0, strumieniowaniu zdarzeń w czasie rzeczywistym za pomocą Webhooków (Google Calendar API v3) oraz rygorystycznych zasadach minimalizacji danych (RODO).

1. Architektura Autoryzacji i Przepływ OAuth 2.0

Proces łączenia konta pracownika z Kalendarzem Google jest realizowany poprzez bezpieczny przepływ delegacji dostępu z wymuszeniem odświeżania w tle.

• Inicjalizacja i Zabezpieczenia: Proces rozpoczyna się od wygenerowania unikalnego parametru kryptograficznego (ciąg losowy), który służy do ochrony przed atakami typu CSRF. Parametry sesyjne są zapisywane w bezpiecznych, krótkotrwałych ciasteczkach (HttpOnly, Secure).
• Callback i Rejestracja Webhooka: Po pomyślnej autoryzacji, serwer wymienia kod tymczasowy na tokeny dostępu i odświeżania. Równolegle, system natychmiast nawiązuje subskrypcję zdarzeń typu PUSH (Webhook) w architekturze Google API, generując unikalny identyfikator kanału.
• Bezpieczne Przechowywanie: Tokeny uwierzytelniające oraz metadane kanału webhooka są bezpiecznie szyfrowane i utrwalane w izolowanym rejestrze integracyjnym bazy danych.

2. Dwukierunkowa Synchronizacja Danych

Mechanizm gwarantuje spójność kalendarzy w czasie rzeczywistym, działając w dwóch niezależnych, asynchronicznych wektorach.

Kierunek A: EnterSlot -> Google Calendar (Push)

Każda operacja mutacji harmonogramu po stronie EnterSlot automatycznie odzwierciedla się w usługach zewnętrznych.

• Zarządzanie Tokenami (Token Rotation): Przed wysłaniem żądania do API, wewnętrzny mikroserwis weryfikuje ważność tokena i w razie potrzeby proaktywnie odświeża go, automatycznie aktualizując rekordy w bazie, co zapobiega przerwom w synchronizacji.
• Mapowanie Zdarzeń: Wydarzenia wypychane do zewnętrznego kalendarza otrzymują ustandaryzowane opisy oraz identyfikatory kolorystyczne zgodne z identyfikacją wizualną usług.

Kierunek B: Google Calendar -> EnterSlot (Webhooks)

Zmiany dokonywane bezpośrednio w Kalendarzu Google (np. przez aplikację mobilną pracownika) są natychmiastowo i bezstratnie propagowane do systemu EnterSlot.

• Nasłuchiwanie (Event Driven Architecture): Zewnętrzne API wysyła żądanie POST za każdym razem, gdy w kalendarzu nastąpi zmiana. Zabezpieczony endpoint serwera autoryzuje żądanie na podstawie specyficznych nagłówków weryfikacyjnych.
• Paginacja i Niezawodność: System implementuje pełną obsługę paginacji strumieni danych, zapobiegając utracie informacji nawet przy bardzo gęstych grafikach i limitach zwracanych wyników na pojedyncze zapytanie.
• Twarda Synchronizacja: System nadpisuje nadchodzące blokady pochodzące ze źródła zewnętrznego świeżym stanem z API, co gwarantuje pełną zgodność ze zmodyfikowanymi lub usuniętymi wydarzeniami prywatnymi.

3. Automatyzacja i Cykl Życia Webhooków

Subskrypcje webhooków posiadają ściśle ograniczony czas życia (TTL - Time To Live).

• Proaktywne Odświeżanie (Background Jobs): Aby utrzymać ciągłość synchronizacji, zaimplementowano zautomatyzowane procesy w tle (Cron Jobs). Uruchamiają się one cyklicznie i wyszukują subskrypcje zbliżające się do końca swojej ważności.
• Bezprzerwowy Przepływ (Zero Downtime): Mechanizm odnawiania w pełni automatycznie zamyka stare kanały notyfikacji, generuje nowe identyfikatory UUID, otwiera świeże kanały nasłuchowe i aktualizuje daty wygaśnięcia, wszystko to bez zauważalnych przerw w działaniu usługi dla użytkownika końcowego.

4. Privacy by Design i Zgodność z RODO

Integracja została zaprojektowana od podstaw z zachowaniem rygorystycznych standardów prywatności, fizycznie maskując wrażliwe dane na styku obu systemów.

• Eksport do Google (Anonimizacja Klienta): Podczas wypychania rezerwacji z infrastruktury EnterSlot, dane klienta podlegają procesowi częściowej anonimizacji. Do usługi zewnętrznej wysyłany jest wyłącznie format skrócony (np. inicjał nazwiska). Wrażliwe dane kontaktowe (telefony, e-maile) nigdy nie opuszczają bezpiecznej infrastruktury głównej aplikacji.
• Import z Google (Maskowanie Zdarzeń Prywatnych): Zdarzenia pobierane z prywatnego kalendarza pracownika są ściśle filtrowane. Oryginalne tytuły i szczegóły wydarzeń (np. prywatne wizyty lekarskie) są natychmiastowo nadpisywane uniwersalnym komunikatem zastępczym. Gwarantuje to, że żaden współpracownik ani administrator nie uzyska dostępu do prywatnego życia specjalisty.
• Bezpieczne Rozłączanie (Cleanup): Procedura odłączania integracji nie tylko niszczy tokeny, ale prewencyjnie zamyka kanały powiadomień w zewnętrznym API (zapobiegając osieroconym strumieniom danych) oraz kaskadowo oczyszcza grafik ze wszystkich blokad zaimportowanych z tego specyficznego źródła.