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. Synchronizacja Zdarzeń (Kolejkowanie i Webhooki)

System wykorzystuje zaawansowaną architekturę sterowaną zdarzeniami (Event-Driven Architecture), która separuje odbiór powiadomień od ich faktycznego przetwarzania. Gwarantuje to wysoką wydajność i odporność na limity czasowe (timeouts) infrastruktury bezserwerowej.

• Asynchroniczny Task Queue: Po otrzymaniu sygnału POST z Google API (webhook), serwer wykonuje jedynie szybką rejestrację zdarzenia w trwałej warstwie danych (tabela webhook_events) z przypisaniem identyfikatora worker_id. Proces ten trwa <200ms, co zapewnia natychmiastową odpowiedź dla serwerów Google.
• Procesor Zdarzeń (Worker): Dedykowany procesor zadań, wyzwalany w cyklach minutowych, pobiera zgromadzone zdarzenia i wykonuje właściwą logikę biznesową. Obejmuje to pobieranie list zmian (events.list), analizę parametrów status oraz synchronizację z bazą danych EnterSlot.
• Obsługa Masowych Zmian (Batching): Dzięki kolejkowaniu, system jest odporny na nagłe skoki aktywności. Zadania są przetwarzane w kontrolowanych paczkach, co optymalizuje zużycie zasobów CPU i zapobiega przeciążeniu bazy danych podczas jednoczesnej synchronizacji wielu organizacji.

3. Stabilność Połączenia i Mechanizm Self-healing

Integracja została zaprojektowana z myślą o długotrwałej pracy bez konieczności interwencji użytkownika, stosując techniki automatycznej naprawy sesji.

• Automatyczne Odnawianie Kanałów: System monitoruje daty wygaśnięcia subskrypcji webhooków. Z odpowiednim wyprzedzeniem proces odnawiania zamyka stare kanały, generuje nowe identyfikatory UUID i otwiera świeże kanały nasłuchowe.
• Mechanizm Self-healing: Raz na 7 dni system wymusza resetowanie parametru syncToken dla każdej integracji. Powoduje to wykonanie pełnej synchronizacji (Full Sync) stanu kalendarza z ostatnich 30 dni, co skutecznie eliminuje ewentualne rozbieżności danych (tzw. data drift) powstałe w wyniku awarii sieciowych lub błędów po stronie dostawcy API.
• Zarządzanie Retencją Logów: Przetworzone i archiwalne zdarzenia z kolejki są automatycznie usuwane po 30 dniach, co zapewnia optymalną wydajność indeksów bazodanowych i minimalizuje ślad cyfrowy zgodnie z polityką czystości danych.

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.