Added API layer description

docs/mqtt-communication-sequence.drawio

@@ -0,0 +1 @@
+<mxfile host="app.diagrams.net" modified="2020-12-03T11:07:06.295Z" agent="5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/86.0.4240.198 Safari/537.36" etag="ikHYmKMKhruEys4yzSz3" version="13.10.6" type="device"><diagram id="kgpKYQtTHZ0yAKxKKP6v" name="Page-1">5Vpbb6M4FP41SLMPjcBcUh6TtJOt1Gpmt5U62zcnOIk1DkbGNGF+/RpwAGNI6DZ0205f6nNsbHy+79xQDHu23c8ZjDZ3NEDEAGawN+wrAwDLunTFv0yTFhrPsQvFmuFALqoU9/gXkkpTahMcoFhZyCklHEeqcknDEC25ooOM0Z26bEWJemoE10hT3C8h0bWPOOCbQnvpmpX+T4TXm8PJlilntvCwWCriDQzorqayrw17xijlxWi7nyGSGe9gl+K5rx2z5YsxFPI+D9hhMv26Z/4yvTWj8NvjA4DzC7nLMySJvPAUsyBEXNgceAawBQ72dHIj1twj9oyXSF6GpwcLiXtF2TDZklu8QgSHQppGiOGt2IaJGSLV3yvdVODFodBl81YuEwKjGC/ybbNDGVomLMbP6G8UF7TItTQJAxRIqbRpLnBGf5YoZZvqJjrcFzGO9jWVNNkcUfGCLBVL5OylRC9VxV3FhRLxTY0H5UIo+bcud64gEgOJ0gsQAxpiGiIRxSHPz3WnhnvVQIMyvqFrGkJSx+OVdj1Krt7GdlzF2OM2Y7fYeihTu63OsYVRzTXu/np4+G2dwwYqYP+/d3gfxzvcl1rb6WFs3daWdwZb36Br/rR6fCK/5k/2+JuNJ3N4YTmnjZ3dDotsOiF4HQrVgnJOt8JIKAwmWXrOdIQuf542K9pj/iMbjyzHkfI/2eqRK6WrvXw4F9KaUMMy1xXviQIt9/fDLKYJW6LTNOSQrRE/ZsJxO+IMEciFd6vlTAuA8tHvGacrpgAHjDLPK/8chTlialSbNBv7F7eTW9YLisYplq3mRtBkWnF9bSOBO0xry6RDdt6mZHCqyp3v1VgPTGW9GBRvUDG/tPwrnEFPFiJLEAH+dMHEaM1L2tXcI2PgLVyImtmebviWSKpD6S1LwcY8/jTdaIuDINtD5AER/mGVF/Tg1hFlyopZPmyUabTuBEf8vjNMXZiCe56nQlBI/5XWhyV0tYoRb4B5Hvj0xAGD4IFOk9UKMR3JLwHK8v1NYIBZ1t1AjopRxOgCLjDBPP3jd4HbdsBZ4S7jy8j16nEKqIcAdcMByTF+N1VFC7D9klYnfm57sDxVVthDVXCXmq2jZEFwvDFmwJiIU833P/iCgx7R4Iy1kc4Eq2elAvRK5Vjl0yiZzl+5jNUiV6te+xYnJWm7NuooTs4WMzQat31YuQmjhH/k9vFEPDre0LhAxehN28dW1N7Px5UThu3mXN/20e8X552hTG1rpi4+pTQrrVi4RlaBNUspQnAUo8KcuY8sCU3EgdPdBnN0H8E87O0YjNRi6wy8tRofBS3QYkvQYszBeNvjs8cgnbjpXyqduOkd5s/ai/dNZr3b7kFyl9NIOWUp9dLc5XbVZG+Uu/wWNn3OVtY76ucfs5M1NfQEV+4Qh6Iq/SQt6UnYBupIgTMCvrLvoV15A1z1inLQGB+K1/2RB3XfP8hFkLetckEV5XMprUvNOH/IGgIe0/KVtOH7zhuljWNV38keqIN2rySV20wbzSqhb9rwrPForNJTlHmjselXfw26Dt0EtdXTnzOTWMdLxo+ZSvQanSGesDD7xKF/AP0kyeU0kgNllwvbG5ljNb1Y1sgFr08xQqx+aFIsr36uY1//Cw==</diagram></mxfile>

docs/thesis/bib/mybib.bib

@@ -43,11 +43,16 @@
   url         = {https://code.visualstudio.com/},
 }
 
-@misc{nglog,
+@misc{nlog,
   title       = {Az NLog hivatalos oldala},
   url         = {https://nlog-project.org/},
 }
 
+@misc{jwt,
+  title       = {Az JSON Web Token hivatalos oldala},
+  url         = {https://jwt.io/introduction/},
+}
+
 @misc{react,
   title       = {A React.js hivatalos oldala},
   url         = {https://reactjs.org/},
@@ -78,6 +83,11 @@
   url         = {https://github.com/RicoSuter/NSwag},
 }
 
+@misc{swagger-ui,
+  title       = {A Swagger UI hivatalos oldala},
+  url         = {https://swagger.io/tools/swagger-ui/},
+}
+
 @misc{hmacsha512,
   title       = {Az HMACSHA512 dokumentációja},
   url         = {https://docs.microsoft.com/en-us/dotnet/api/system.security.cryptography.hmacsha512},

docs/thesis/content/birdmap-backend.tex

@@ -63,6 +63,7 @@ A \verb+Role+ mező ennek a megkülönböztetsnek a jelzője.
 
 %----------------------------------------------------------------------------
 \subsection{Seedelés}
+\label{subsect:seeding}
 %----------------------------------------------------------------------------
 Az alkalmazás konfigurációs fájljából meg lehet adni alapértelmezett felhasználókat és szolgáltatásokat.
 Ezeknek megkülönböztetésére szolgál az entitások \verb+IsFromConfig+ mezője.
@@ -90,6 +91,7 @@ ha igen, akkor a megadott jelszóból az imént említett folyamattal generált
 \section{Megjelenítési réteg}
 %----------------------------------------------------------------------------
 A fejezet elején említett \verb+Startup+ osztály ebben a rétegben található, itt kerülnek az egyes szolgáltatások regisztrálásra.
+Itt történik a \ref{subsect:seeding} fejezetben leírt adatbázis seedelése is.
 
 Többek között a naplózás is itt kerül inicializálásra, mely az NLog saját konfigurációs fájljával történik.
 Meg lehet adni különböző szűrőket és kimeneteket, amellyel szelektálni lehet, hogy az egyes naplózott események hova kerüljenek.
@@ -111,20 +113,78 @@ Minden \verb+Debug+ szintől nagyobb és \verb+Error+ szinttől kisebb bejegyzé
     ...
 </rules>
 \end{lstlisting}
-% 
-program.cs startup.cs
-middlewares
-logolás
-seedelés
-swagger
+
+A \verb+Startup+ osztály másik metódusa a \verb+Configure+, mellyel a HTTP kérések csővezetéke konfigurálható.
+Azaz, hogy egy kérés-t milyen sorrendben dolgozzák fel a regisztrált szolgáltatások.
+A szerveroldali kivételkezelésre szánt szolgáltatás, az \verb+ExceptionHandlerMiddleware+ is itt van használva, 
+amely elkap minden kivételt, amit a csővezeték további részei dobtak és JSON formátumban visszaadja azokat a kliensnek.
+
+Továbbá az NSwag\cite{nswag} szoftvercsomag segítségével regisztrálok egy szolgáltatást, 
+mely a szerveroldalon található kontrollereket felhasználva generál egy OpenAPI specifikációt és annak egy Swagger UI\cite{swagger-ui} felületet,
+ahol a végpontok kipróbálhatóak, tesztelhetőek kliensoldal nélkül is.
+
+\begin{figure}[!ht]
+    \centering
+    \includegraphics[width=150mm, keepaspectratio]{figures/swagger-ui.png}
+    \caption{Az alkalmazásom Swagger felülete}
+    \label{fig:swagger-ui}
+\end{figure}
+
 %----------------------------------------------------------------------------
 \subsection{Kommunikációs Szolgáltatások}
 %----------------------------------------------------------------------------
-mqtt
-signalR
+A kliensoldal frissítésére több megoldás is létezik. Például bizonyos időközönként lehetne kéréseket indítani a szerver felé a friss adatok megszerzéséért.
+Egy másik megoldás a SignalR használata, amellyel a klienseket eseményvezérelten lehet értesíteni, megvalósítja a kétoldalú kommunikációt.
+Így a kliensek csak akkor indítanak kéréseket amikor az adat tényleg változott. Ezzel a technológiával oldottam meg például, hogy az eszközök állapotainak változására
+frissüljön a felület.
+
+Egy másik szolgáltatás a Birdnetes MQTT kommunikációért felelős szolgáltatás, 
+mely felregisztrál a \ref{subsect:birdnetes-ai-service}-as alfejezetben bemutatott AI Service által publikált üzenetekre.
+Ezekben az üzenetekben található a hanganyagok egyedi azonosítója, illetve azok seregélytől való származásának valószínüsége.
+Ha a szolgáltatás kap egy ilyen üzenetet akkor lekérdezi a \ref{subsect:birdnetes-input-service}-es alfejezetben bemutatott Input Service-től
+a hanganyag azonosítójához tartozó metaadatokat. 
+Ezekből felhasználva a kihelyezett eszköz azonosítóját, a hanganyag beérkezésének dátumát és az említett valószínüséget új üzeneteket készítek, melyeket egy pufferben tárolok.
+Ezt a folyamatot a \ref{fig:birdmap-mqtt-service}-es ábra szemlélteti.
+
+\begin{figure}[!ht]
+    \centering
+    \includegraphics[width=150mm, keepaspectratio]{figures/mqtt-communication-sequence.png}
+    \caption{A Birdmap MQTT szolgáltatásának szekvenciája}
+    \label{fig:birdmap-mqtt-service}
+\end{figure}
+
+A puffer tartalmát másodperces gyakorisággal elküldöm a klienseknek a SignalR segítségével. 
+Azért van szükség a puffer használatára, mert az MQTT-n érkezett üzenetek gyakorisága akár miliszekundum nagyságrendű is lehet. 
+Míg a szerver képes is az üzeneteket feldolgozni, ha ezeket rögtön tovább küldeném a kliensek felé, azok nem biztos, hogy képesek lennének rá.
+
 %----------------------------------------------------------------------------
 \subsection{Kontrollerek}
 %----------------------------------------------------------------------------
+A kontrollerek határozzák meg, hogy a szerveroldalon milyen végpontokat, milyen paraméterekkel lehet meghívni, ahhoz milyen jogosultságok kellenek.
+A jogosultságok kezelését a JSON Web Token-ekkel oldottam meg. A fejlasználó bejelentkezéskor kap egy ilyen token-t, 
+amelyben tárolom a hozzá tartozó szerepet. A \ref{lst:devices-controller}-as listában látszik, hogy hogyan használom ezeket a szerepeket.
+A kontroller végpontjait alapértelmezetten \verb+User+ és \verb+Admin+ jogosultságú felhasználó hívhatja, az online végpontot azonban csak \verb+Admin+ jogosultságú.
+Hasonló képpen oldottam meg ezt a többi kontrollernél is. A \verb+User+ felhasználók csak olyan végpontokat hívhat, mely kizárolag az állapotok olvasásával jár.
+Az \verb+Admin+ felhasználók hívhatnak bármilyen végpontot.
+
+\lstset{style=sharpc, morekeywords={record, async}}
+\begin{lstlisting}[caption=Az eszköz kontroller és annak "online" végpontja, label=lst:devices-controller]
+    [Authorize(Roles = "User, Admin")]
+    [ApiController]
+    [Route("api/[controller]")]
+    public class DevicesController : ControllerBase
+    {
+        [Authorize(Roles = "Admin")]
+        [HttpPost, Route("online")]
+        public async Task<IActionResult> Onlineall()
+        {
+            ...
+        }
+
+        ...
+    }
+\end{lstlisting}
+
 Controllersw
 Dtos
 mapper

docs/thesis/content/birdmap-technologies.tex

@@ -68,6 +68,17 @@ vagy a React.js-t.
 Az Entity Framework Core (röviden EF Core) egy objektum-relációs leképező keretrendszer a .NET-hez. Az adatbázissal való kommunikációt könnyítését szolgálja. 
 Használatával C\#-ban lehet adatbázis lekérdezéseket írni a LINQ (Language-Integrated Query) segítségével.
 
+%----------------------------------------------------------------------------
+\subsection{JSON Web Token}
+%----------------------------------------------------------------------------
+Az autorizációt többféleképpen meg lehet oldani egy alkalmazás szempontjából. Az egyik ilyen megoldás a JSON Web Token-ek (röviden JWT) \cite{jwt} használata,
+ami nem más mint egy szabvány, mely módszert ad a felek közötti információ biztonságos továbbítására JSON objektumokkal.
+Ezen objektumok adatokat tárolhatnak a felhasználóról például a neve vagy a szerepe, melyek segítségével a szerver eldöntheti, 
+hogy van-e jogosultsága hívni az adott végpontot.
+
+A Microsoft-nak van egy beépített szoftvercsomagja, mellyel ilyen tokeneket lehet készíteni és validálni.
+A szerveroldal jogosultság kezelését ezzel a csomaggal oldottam meg.
+
 %----------------------------------------------------------------------------
 \subsection{SignalR}
 %----------------------------------------------------------------------------

docs/thesis/content/birdnetes-introduction.tex

@@ -103,6 +103,7 @@ Tartalmaznak még egy hangszórót is, mely a madarak elijesztését szolgálja.
 
 %----------------------------------------------------------------------------
 \subsubsection{Input Service}
+\label{subsect:birdnetes-input-service}
 %----------------------------------------------------------------------------
 A kihelyezett IoT eszközök által felvett hangfájlok ezen a komponensen keresztül érkeznek be a rendszerbe.
 Itt történik a hanganyaghoz tartozó metaadatok lementése az Input Service saját adatbázisába. 
@@ -112,6 +113,7 @@ publikál egy üzenetet az MQTT üzenetsorra a többi kliensnek feldolgozásra.
 
 %----------------------------------------------------------------------------
 \subsubsection{AI Service}
+\label{subsect:birdnetes-ai-service}
 %----------------------------------------------------------------------------
 Az AI Service példányai fogadják az Input Service-től érkező üzeneteket és elkezdik klasszifikálni az abban található hanganyagot.
 Meghatározzák, hogy a hanganyag mekkora valószínűséggel volt seregély hang vagy sem.

docs/thesis/ideas.txt

@@ -55,6 +55,11 @@ Forma
     - felépítés architektúra
     - App and navigation
     - Components and services
+    - kép minden felületről
+        - kép user és admin felhasználók különbségéről
+            - Device service
+            - dashboard systeminfo service
+        - kép a skeletonról -> igazi adat
 - Tesztkörnyezet
 - Kubenetes
 - Összefoglaló