ASWI - Pokročilé softwarové inženýrství » ASWI 2022 » Úprava systému BrainIn pro neurorehabilitace pacientů se získaným poškozením mozku (KIV) - JVDF

h1. Rest API

* offline mobilní aplikace

* při připojení k internetu bude posílat dosažené výsledky a stahovat nové úlohy a balíky přidělené terapeutem

* potřeba navrhnout a implementovat Rest API, se kterým bude moct aplikace komunikovat

----

h3. Další problémy s binárními soubory

Po přípravě prototypu a začátku testování bylo zjištěno, že výstupní funkce generuje moc velké objekty pro jednu úlohu (cca 400 obrázků -> 80MB, s kompresí 70MB).

Po krátké diskuzi se zadavatelem bylo zjištěno, že tento výsledek je nechtěný, prostě to je moc dat, které by se posílaly, kdy by se jednalo o více úloh najednout.

h4. Nové řešení odesílání binárních souborů

Na základě konverzace je potřeba upravit odesílání binárních souborů následovně.

Bude potřeba, posílat nějaké informace ke každému obrázku. Porovnání bude probíhat v mobilní aplikaci a případné originální obrázky se stáhnu přes endpoint. Místo cesty k obrázku bude objekt, který bude obsahovat následující informace (lze to vyřešit i přes index do pole s informacemi o obrázcích - to už je jedno): cestu k souboru, paměťovou velikost, šířku, výšku a ideálně průměrné hodnoty RGB kanálů a jasu (zaokrouhlené na celá čísla - je jedno jestli dolů nebo nahoru, vyhnul bych se ale klasickému zaokrouhlování). Hodnoty RGB + jas pro každý pixel lze najít v instancích třídy Color. Ty atributy ve webové aplikaci budou nejspíše pojmenovány R, G, B, A a grayscale lze získat přes funkci GetBrightness().

U zvuku bychom mohli řešit dobu trvání, přenosovou rychlost, velikost a případně další.

K těm dalším typům binárních souborů - musíme počítat třeba s GIFy. Mohli bychom to prozatím pořešit tak, že když to nebude obrázek a zvuk, tak budeme porovnávat pouze název a paměťovou velikost.

----

h3. Schůzka s M. Horkým dne 11. dubna 2022

h4. Binární soubory

V úlohách se vyskytují binární soubory. Problém nastává u endpointu, který přijímá výsledky z mobilní aplikace. Na vstupu má totiž řetězec, ve kterém by se vyskytoval "někde" base64 řetězec, který reprezentuje obrázek.

Na schůzce bylo domluveno, že se použije již vytvořený endpoint pro ukládání souborů (nutno najít). Mobilní aplikace nejdříve uloží všechny obrázky pomocí této funkce a následně cesty k souborům pošle standardně ve stringu (jak tomu již je ve webových verzích hrách).

h4. Lokalizace

Na schůzce se řešilo, jakým způsobem se budou posílat do mobilní aplikace lokalizace textů a parametrů úlohy.

Návrhem a schváleným řešením se nakonec stalo to, že spolu s přihlaš. údaji bude mobilní aplikace posílat i informaci, ve které lokalizaci se budou úlohy odesílat. 

Zároveň je ještě potřeba udělat analýza na to, zdali je velký rozdíl ve velikost odesílaných dat při odesílání konkrétní nebo všech lokalizací. Hlavně otestovat na logopedických úlohách (na produkci).

+ bylo by nejlepší vytvořit sdílené prostředí pro nás a M. Horkého, aby viděl aktuální verze návrhů atd.

----

h3. Architektura

V DMS byl přidán soubor s architekturou -> {{dmsf(727)}}

Jedná se o návrh architektury. Spíš o jednotlivé částí aplikace, kde se vývoj požadavku bude odehrávat. 

Co se týká změn, ty budou pouze aditivní. Nebudou se zde odehrávat žádné změny stávající funkcionality.

----

h3. Vstupní JSON 

Pro implementaci bude využita nejspíše funkce Neurop3/Services/TestSerivce/saveResult:347

Vzhled dtoIn -> {{dmsf(725)}}

----

App version - .NET Framework 3.6.1.

----

h3. Schůzka s M. Horkým dne 22. března 2022

* záznam ze schůzky, kde se řešil návrh JSON objektu, který bude odesílán z webové aplikace a diskuze nad ověřováním uživatele

h4. Návrh JSONu

Co se týká JSON objektu, byla schválena následují podoba viz. příloha -> {{dmsf(724)}}

Pro vytvoření metod lze použít následující konfiguraci pro PostMan -> {{dmsf(723)}}

h4. Ověřování uživatele

* v aktuální implementaci se využívá nějaká .NET knihovna, která hashování řeší sama 

* nakonec bylo domluveno, že mobilní aplikace bude posílat *jméno a heslo v _plaintext_ formě*

** přes SSL

* v budoucnu lze přistoupit k asymetrickému šifrování či změnit implementaci ověřování (_"udělat si vlastní"_)

----

h3. Schůzka s M. Horkým dne 14. března 2022 

* záznam ze schůzky, kde se probíral návrh API a dořešení dalších otázek, které vznikly při analýze

h4. Odesílání souborů

* odesílat se budou komprimované soubory pomocí kompresního programu *Gzip*

* následně se bude soubor převádět do řetězce v *Base64* formátu, který bude přiložen do odesílaného JSONu

* dle zákazníka se zatím jedná pouze o prvotní verzi a není prý úplně důvod tolik řešit optimalizaci

** _"z počátku (v prvních iteracích) upřednostnit jednodušší a rychlejší řešení, než optimalizaci - tu pak můžeme dotáhnout, když to půjde hladce a zbyde čas"_

h4. Autorizace

* co se týká autorizace, řešení je zcela na nás

* nejspíše nebude potřeba speciální endpoint pro ověřování

* potřeba zaheshovat login a heslo

** _"ověření pacienta (hashovaný login/heslo) - potřebuji pak informaci o typu hashovací funkce"_

h4. Endpointy a data

* celkový počet endpointů zatím vypadá na 2

** asi nebudeme vytvářet Swagger API, nemá moc smysl pro 2 endpointy

* formát komunikace *JSON*

* návrh API proběhne v iterace od 15.3. - 29.3.2022

h4. Základní scénář

# Připojení pacienta k internetu.

# Po zapnutí aplikace request s datumem posledního stažení změn.

# Zpět informace o nových změnách (nově přidělené balíky, změny v přidělených úlohách). 

** U každé úlohy potřebuji ID šablony. 

** Ke každé úloze by také měla být kompletní konfigurace včetně všech multimediálních souborů.

** Datum změny by mohlo být umístěno někde v databázi - prověřit.

# Kdykoli se pak může odeslat JSON s nasbíranými daty. 

** Tady pozor na možné změny v balících - pokud nedošlo k celkovému odstranění úlohy - myslím opravdu celkovému ne pouze z balíku - tak by se data měla uložit vždy).

----

h3. Odesílání souborů přes Rest API

* po analýze bylo zjištěno a nalezena 2 řešení, která by byla možná implementovat

* potřeba probrat s M. Horkým na nějaké schůzce, které řešení se zvolí, zda by bylo potřeba řešit úplně jinak

h4. -1. Řetězec v Base64-

* -Base64 je kódování, které převádí binární data na posloupnosti tisknutelných znaků.- 

* -umožňuje přenos binárních dat kanály, které dovolují pouze přenos textů.- 

* -Výhody:-

** -funguje na jakákoliv binární data (obrázky, soubory, ...)-

** -velice jednoduchá implementace v C#-

* -Nevýhody-

** -největší nevýhodou tohoto řešení je, že velikost vytvořeného/odesílaného řetězce je zhruba o 20-30% větší--

h4. 2. Komprimované Base64

* *nevýhodu prvního řešení lze odstranit nějakou kompresí (Gzip, DeflateStream, ...)*

* *podle zvolené komprese by se sice ztrácela kvalita obrázků, ale přenos dat by se mohl zrychlit, protože velikost dat by měla být menší*

** *nechceme aby stahování/odesílání trvalo příliš dlouho (pacient může trénovat pouze po dobu jedné hry, či pouze zkoumat dosažené výsledky)*

* *řešení by fungovalo tak, že by se*

** *zapnula aplikace a zahájilo se tak stahování/odesílání potřebného obsahu*

** *mobilní aplikace by přijala komprimovaný obrázek v base 64 formátu*

* *pokud by byla potřeba stejná kvalita obrázků, jak v aplikace tak v systému byla by možnost spolu s komprimovaným obrázkem posílat i url*

** *url by obsahovala adresu, kde by se nacházel soubor v plné kvalitě*

** *po stažení všech potřebných/nových dat ze systému by se na pozadí aplikace zahájilo stahování obrázků v plné kvalitě a nenarušovalo uživatele*

h4. -3. Použít multipart/from-data namísto JSONu-

* -POST a PUT metody jsou RESTFull, jak jen to jde-

** -obsahují textový vstup společně se soubory-

* -nevýhodou je, že přenos už nebude realizovaný pomocí JSONu, který je daleko jednodušší k testování, ladění, ...-

h3. Autorizace přeš API

* -vhodné přes autorizační token získaný při přihlášení s omezenou platností-

** -potřeba ujasnit u zákazníka (na předchozí schůzce zmiňoval, že ještě upřesní své požadavky)-

* tento bod byl dne 14.3. vyjasněn se společníkem zákazníka (M. Horký)

** konkrétní informace lze dohledat v tomto dokumentu výše (viz. [[#Schůzka s M. Horkým dne 14. března 2022]])

* provedena analýza provedené hashovací funkce (viz https://stackoverflow.com/questions/20621950/asp-net-identitys-default-password-hasher-how-does-it-work-and-is-it-secure)

** nutná konzultace se zákazníkem o vyhovujcí variantě authorizace

** původní varianta ukládání zaheshovaného hesla by byla složita z důvodu solení hashe

h3. Navrhované endpointy

* podoba endpointů bude vytvořena po zhodnocení nároků a vlastností mobilní aplikace pro kterou API vzniká

* tento bod byl dne 14.3. konzultován se společníkem zákazníka (M. Horký)

** konkrétní informace lze dohledat v tomto dokumentu výše (viz. [[#Schůzka s M. Horkým dne 14. března 2022]])