# Specyfikacja wymagań rozwiązania

1. Obsługa zakodowanych linków z zawartym ciągiem startowym TheStore2
2. Obsługa osadzeń ramek pixel streamingu razem z przekazaniem parametrów dla danych badań przeznaczonych
3. Obsługa przekierowań do ankiety po pomyślnie zrealizowanym badaniu
4. Obsługa zamknięcia sesji i powiązanej ramki przy zakończeniu badania
5. Implementacja zabezpieczenia przeciwko podwójnemu wykonaniu badania na tym samym identyfikatorze sesji

## Specyfikacja biznesowa

### Obsługa zakodowanych linków z zawartym ciągiem startowym TheStore2

Wymaganie dotyczy realizacji obsługi linków zawierających zakodowaną formę parametrów startowych potrzebnych aplikacji 3D do poprawnego uruchomienia się.
Za równo proxy jak i sam program TheStore wspierają następujące parametry (zwane również przełącznikami).
Poniższa lista prezentuje listę przełączników w ich pełnej nazwie, wartości domyślnej, sugerującej typ danych, oraz przykładowe wartości w nawiasach.

-scenarios="" (S1+S2+S3)
-resp_id="" (string)
-project="" (string)
-question_label="" (string)
-culture="" (skróty języka, np. en, de)
-idle_time= (integer)
-show_timer= (0/1)
-WS_staging= (0/1)
-show_log= (0/1)
-local= (0/1)

### Obsługa osadzeń ramek pixel streamingu razem z przekazaniem parametrów dla danych badań przeznaczonych

Wymaganie dotyczy realizacji dynamicznego generowania iframe z pixel streamingiem na bazie danych podanych w URL. Jednocześnie, generowana ramka wyświetlająca stream, jest skorelowana do danych przekazywanych przez URL, co pozwala na wyświetlenie odpowiedniego streama konkretnemu respondentowi.

### Obsługa przekierowań do ankiety po pomyślnie zrealizowanym badaniu

Wymaganie dotyczy implementacji solucji, która będzie odpowiadać za poprawne przekierowanie respondentna do ankiety, która jest wskazana przez dostawcę usług ankietowych. Wymaganie obejmuje realizację takiego przekierowania, które będzie odróżniać trzy sytuacje, które są opisane odpowiednimi kodami:
- 0 - pełny sukces, przekierowanie do linku sukcesu,
- 1 - błąd respondenta, zwykle chodzi o timeout, przekierowanie do odpowiedniej podstrony z błędem,
- 2 - błąd techniczny, czyli błąd sieciowy, albo błąd infrastruktury serwerowej, kończy się przekierowaniem do odpowiedniego linku dostarczonego przez dostawcę ankiety.

### Obsługa zamknięcia sesji i powiązanej ramki przy zakończeniu badania

Wymaganie dotyczy implementacji mechanizmu, który powinien obsługiwać zakończenie sesji na serwerze Furioosa w momencie zakończenia badania, jednocześnie usuwając ramkę Furioosa ze strony.

### Implementacja zabezpieczenia przeciwko podwójnemu wykonaniu badania na tym samym identyfikatorze sesji

Wymaganie dotyczy realizacji mechanizmu, którego zadaniem jest zabezpieczenie przed sytuacją, w której respondent cofnie się z ekranu końcowego na ekran systemu badawczego i uruchomi po raz drugi sesję na ten sam respondent_id z tym samym id sesji.

## Specyfikacja techniczna

### Przygotowanie mechanizmu odczytu zakodowanych linków

Implementacja mechanizmu, którego zadaniem jest dekodowanie linków utworzonych z listy parametrów przy użyciu przełączników, których lista jest w sekcji poprzedniej tego dokumentu. Użyty algorytm kodowania to base64.

### Przygotowanie mechanizmu przygotowania czystej maszyny wirtualnej, przekopiowania i uruchomienia

Mechanizm wymagany do realizacji to mechanizm realizowany manualnie.
Wymaga znajomości panelu kontrolnego Furioosa. Za równo utworzenie maszyny wirtualnej jak i przekopiowanie plików aplikacji 3D realizuje się za pomocą tego panelu oraz przeglądarki internetowej. Uruchomienie aplikacji 3D może nastąpić w wyniku zarezerwowania maszyny z Fast-Startem (natychmiastowa alokacja maszyny wirtualnej), albo też przy każdym wywołaniu systemu Furioosa używając wygenerowanych przez panel linków SDK.
Mechanizm został wypracowany w drodze pracy nad systemem.

### Przygotowanie mechanizmu obsługi jednocześnie pięćdziesięciu badanych

Wymaganie zakłada, że rozwiązanie jest w stanie obsłużyć jednoczesne obciążenie liczby badań równej 50. Równoległość działania całego rozwiązania jest naturalna dla całego projektu mechanizmu, więc wymaganie jest spełnione poprzez odpowiednią alokację zasobów infrastrukturalnych.

### Przygotowanie mechanizmu zabezpieczenia przed race condition (badanemu ma się wyświetlić pixel streaming z maszyny z jego identyfikatorem i wybranymi dla niego parametrami)

Wymaganie techniczne dotyczy realizacji obsługi przypadku "race condition" - sytuacji, gdy jednocześnie próbuje zrealizować badanie więcej niż 1 respondent całkowicie równolegle do siebie. Rozwiązanie ma być odporne na sytuację, w której 1 z respondentów podłączy się do systemu o bardzo, ale skończenie małej jednostce czasu, co spowoduje, że otrzyma nieswoje parametry i uruchomi się nieodpowiednie badanie. Taka sytuacje nie może występować realnie wcale.

### Umożliwienie pełnego przeprowadzenia badania na pixel streamingu

W ramach tego wymogu technicznego wchodzą następujące elementy:

#### Umożliwienie uruchomienia aplikacji na pełnym ekranie

Wymóg dotyczy możliwości uruchomienia aplikacji na pełnym ekranie za równo na urządzeniu mobilnym jak i komputerze laptopie bez względu na użytkowaną przeglądarkę i/lub system operacyjny.

#### Umożliwienie obsługi aplikacji za pomocą klawiatury i myszki wraz z obsługą przełączenia pomiędzy kursorem systemowym, a kursorem aplikacji

Wymóg dotyczy możliwości obsługi aplikacji użytkując myszkę/ekran dotykowy oraz klawiaturę fizyczną/ekranową.
Aplikacja musi wspierać przełączania kursora z systemowego na ten, który jest dostępny w aplikacji i służy do poruszania się - w przypadku urządzenia mobilnego chodzi o "focus" na kontenerze aplikacji tak, by całość gestów użytkownika była odbierana przez aplikację.

#### Umożliwienie przeprowadzenia badania na urządzeniach mobilnych - tablety i smartfony

Wymaganie dotyczy realizacji interface klientu Webowego rozwiązania tak, by wspierało szeroką gammę urządzeń mobilnych oraz przeglądarek na różnych systemach operacyjnych - przede wszystkim Android oraz iOS.

### Przygotowanie aplikacji do uruchomienia w klastrze Kubernetes

Wymaganie dotyczy refaktoryzacji kodu oraz dodania odpowiednich deklaracji wdrożenia dla rozwiązania GitLab CI z integracją klastra Kubernetes w ramach usługi Google Kubernetes Engine (GKE).
Aplikacja została dostosowana do tego, aby być uruchamiana na takim rozwiązania zgodnie z odpowiednimi praktykami dotyczącymi skalowania w poziomie, bezstanowości oraz zużycia zasobów w środowisku wspóldzielonym/

### Przygotowania bazy danych, w której zapisywane są wszystkie dane związane z obsługą linków (identyfikator respondenta, identyfikator badania, lista scenariuszy, link powrotny, informacji o uruchomionej maszynie w pixel streamingu i statusu badania - czy zostało zakończone)

Wymaganie zakłada implementację mechanizmu obsługującego logowanie danych statystycznych z najważniejszymi informacjami z perspektywy biznesowej - kwestie analizy ruchu i generowania raportów dot. success rate, failure rate systemu oraz szczegółowej diagnozy błędów.

### Wybranie dostawcy maszyn wirtualnych i przygotowanie mechanizmów po jego stronie

Wymaganie dotyczy wyboru dostawcy usług pixel streamingowych oraz wyznaczenie potrzebnych zmian po stronie dostawcy, aby integracja z naszym rozwiązaniem była możliwa.
W ramach realizacji wymagania wybrany został dostawca Furioos, zaś zmian po stronie dostawcy nie dokonywano żadnych.
Zastany stan systemu był wystarczajacy, aby w pełni zrealizować wymagania biznesowe postawione przed całym systemem.
Furioos w ramach swojego systemu zapewnia:
- maszyny wirtualne, na których można bez problemów uruchamiać zaawansowane wizualizacje 3D,
- mechanizmy zarządzania zasobami oraz połączeniem do serwerów wirtualizacji,
- SDK wspierające tworzenie własnego rozwiązania,
- dokumentację do SDK,
- panel zarządzania maszynami wirtualnymi.

W ramach zarządzania infrastrukturą wirtualizacji Furioos zapewnia:
- kolejkowanie sesji,
- alokację maszyny wirtualnej pod konkretną aplikację,
- szybki start - zaalokowana maszyna wirtualna może być uruchomiona zaraz po alokacji; dzięki temu maszyna jest dostępna w czasie poniżej 5s,
- opcje konfiguracyjne: region, jakość streama, zasoby: CPU, RAM.

## Scenariusze testowe dla funkcjonalności zgodnych z wymaganiami

### Pozytywny przypadek

Ten przypadek to przejście pozytywnie próby aplikacji przy założeniu, że użytkownik nie popełnia żadnych błędów w ramach użytkowania systemu.
Ten przypadek ma wyglądać następująco:
- wyświetlenie strony systemu,
- załadowanie się okna Furioosa na stronie,
- załadowanie się maszyny wirtualnej po kliknięciu przycisku Play,
- użytkownik pomyślnie wykonuje scenariusz badawczy i wysyła wyniki na serwer,
- serwer API odbiera dane i zapisuje je poprawnie do bazy danych,
- dane są dostępne w bazie danych i są w pełni skompletowane.

### Przypadek wystąpienia timeout

Ten przypadek to sprawdzenie przypadku, gdy powyższy przypadek jest ok, ale użytkownik w trakcie trwania badania w sklepie wirtualnym, przestanie wchodzić w interakcję z aplikacją TheStore2 co spowoduje wyłączenie badania i przekierowanie pod odpowiedni link.
Ten przypadek należy testować w następujący sposób, przechodząc przez poniższe kroki:

- wyświetlenie strony systemu,
- załadowanie się okna Furioosa na stronie,
- załadowanie się maszyny wirtualnej po kliknięciu przycisku Play,
- użytkownik nie zaczyna wykonywać badania lub przestaje je wykonywać w trakcie, zostawiając je nieaktywne na tyle długo, że dochodzi do wyłączenia TheStore2 i przekierowania na link awaryjny.

### Przypadek wystąpienia błędu technicznego

Ten przypadek służy sprawdzeniu czy występują błędy techniczne w całości ciągu zdarzeń w systemie.
Może on wystąpić w dowolnym momencie w trakcie życia aplikacji i może dotyczyć np. niepoprawnych parametrów podanych w URL, ale może to też być problem z połączeniem się do proxy po WebSockets z poziomu TheStore2 lub też problem połączenia do API.
Ten przypadek jest wykluczony jako występujący w razie potwierdzenia prawdziwości 1. przypadku.

### Przypadek powrócenia na stronę systemu po przekierowaniu

System musi być odporny na błąd wynikający z przechowywania zawartości HTML w przeglądarce - w przypadku, gdyby respondent cofnął o stronę po pomyślnym przekierowaniu w wyniku jednego z 3 powyższych przypadków, mogłoby dojść do sytuacji, że uprzednio użyty uniqid, byłby użyty ponownie, co prowadziłoby do błędu. System musi zapobiegać takiej sytuacji, wymuszając przeładowanie okna po ewt. cofnięciu się użytkownika po przekierowaniu.

Przebieg testowania to wykonanie wszystkich kroków jak w 1. przypadku, po czym po przekierowaniu, należy cofnąć się na stronę poprzednią (stronę z oknem Furioosa) używając strzałki w tył w przeglądarce. Powinien wyświetlić się niebieski ekran informujący o napotkanym problemie i strona powinna się przeładować po ok. 5s.

### Przypadek wprowadzenia listy parametrów bez parametrów wymaganych

W tym przypadku chodzi o sprawdzenie walidacji, która odbywa się na poziomie proxy. Proxy samo w sobie wymaga podania parametru resp_id, jako, że mapowanie wielu istotnych wartości odbywa się przy użyciu tego parametru.
Dodatkowo, proxy uwzględnia w walidacji również występowanie parametrów istotnych dla samego TheStore - prócz resp_id wymienionego wyżej - project, scenarios.

### Przypadek: Widok mobilny proszący o obrócenie urządzenia tylko na urządzeniach mobilnych, gdy są w pozycji pionowej

W tym przypadku testowym chodzi o sprawdzenie czy na dowolnym urządzeniu z Androidem lub iOS system wyświetli stronę informującą o potrzebie obkręcenia urządzenia do pozycji horyzontalnej, o ile urządzenie już się w takowej nie znajduje. Dodatkowo, trzeba sprawdzić czy widok znika po obkręceniu ekranu samemu oraz po użyciu do tego przycisku.
**Uwaga**: Przycisk występuje tylko na urządzeniach z iOS z racji nie zaimplementowanego przez Apple API.

### Przypadek: Działania mechanizmu do obrócenia ekranu używając przycisku

W tym przypadku testowym chodzi o sprawdzenie czy przycisk występujący na ekranie informującym o potrzebie obrócenia urządzenia działa na różnych przeglądarkach i systemie iOS.
Sprawdzane przeglądarki to: Chrome, Opera, MS Edge, Firefox, Safari.
W przypadku systemu operacyjnego Android implementacja rozwiązania została pominięta, ponieważ nie potrzeba, aby użytkownik wymuszał obrót poprzez kliknięcie, gdyż Androidowe przeglądarki implementują odpowiednie API.

### Przypadek: Obciążenie systemu 50 użytkownikami jednocześnie

W tym przypadku testowym należy sprawdzić czy system jest w stanie zrealizować 50 jednoczesnych sesji na pojedynczej kopii proxy.
W najlepszym przypadku, sesje powinny być wykonywane przez 50 różnych osób z różnych urządzeń, w różnych miejscach względem topologii sieci.

### Przypadek: Ekran o błędzie technicznym

W tym przypadku chcemy sprawdzić, czy błąd techniczny zostanie obsłużony specjalnym ekranem, który zablokuje dalszą interakcję z ramką Furioosa.
Ekran powinien też pozwolić na przeładowanie się systemu, by rozpocząć badanie od nowa, po raz drugi. W przypadku występowania 2. błędu technicznego, system ma przekierować na inny, odrębny widok informujący o całkowitym zakończeniu badania w wyniku błędów technicznych.

### Przypadek: Sprawdzenie wersji językowych uzależnionych od parametru culture

Przypadek testowy ma na celu sprawdzenie czy aplikacja proxy sprawdza wartość parametr culture w boot stringu, a następnie używa go, jeśli jest dostępny, aby ustawić wersję językową. To samo dotyczy aplikacji 3D.
Aktualnie system wspiera wersje: polską (domyślna, nie wymaga parametru), angielska (culture="en"), oraz niemiecka (culture="de").

### Przypadek: Działające ekrany błędów 1 i 2 wbudowane w system

Przypadek testowy ma na celu sprawdzenie czy aplikacja posiada zaimplementowane ekrany błędów dla kodu 1 i 2 w wybranej wersji językowej, zgodnej z parametrem culture.
Strony błędów muszą się znajdywać pod relatywnymi ścieżkami:
/error-1
/error-2