Merge remote-tracking branch 'origin/master'

Author: topnax

Repository/IRepository.cs

@@ -6,6 +6,7 @@ namespace Repository
     // TODO comments
     public interface IRepository<T>
     {
+        // TODO remove from IRepository
         public object ToRow(T entry);
 
         public int Add(T entry);
@@ -35,4 +36,4 @@ public interface IPortfolioEntryRepository : IRepository<PortfolioEntry>
 
         public int DeletePortfolioEntries(int portfolioId);
     }
-}
+}

doc/doc.tex

@@ -29,6 +29,8 @@
 \usepackage[sorting=nyt,style=ieee]{biblatex}
 \addbibresource{literatura.bib}
 
+\lstdefinestyle{sharpc}{language=[Sharp]C, frame=lr, rulecolor=\color{blue!80!black}}
+
 \lstdefinestyle{flex}{
     frame=tb,
     aboveskip=3mm,
@@ -45,7 +47,7 @@
     breakatwhitespace=true,
     tabsize=3
 }
-
+\lstset{style=sharpc}
 \lstset{
     frame=tb,
     language=XML,
@@ -149,8 +151,7 @@ \subsection{Webový zdroj CoinGecko}
 Aktuální i historický kurz drtivé většiny všech existujících kryptoměn bez nutnosti registrace nabízí pomocí REST rozhraní webová služba CoinGecko\cite{coingecko2021}. Jediným omezením tohoto API je počet provedených požadavků za minutu, který je stanoven na 100, což je pro aplikaci určenou ke sledování kryptoměnového portfólia více než dostačující.
 
 \begin{lstlisting}
-$ curl -X GET "https://api.coingecko.com/api/v3/simple/price?ids=bitcoin&vs_cur
-rencies=usd" -H  "accept: application/json"
+\$ curl -X GET "https://api.coingecko.com/api/v3/simple/price?ids=bitcoin&vs_currencies=usd" -H  "accept: application/json"
 
 {
   "bitcoin": {
@@ -159,15 +160,85 @@ \subsection{Webový zdroj CoinGecko}
 }
 \end{lstlisting}
 
-\section{Výběr databáze pro implementaci datové vrstvy aplikace}
+\subsection{Výběr databáze pro implementaci datové vrstvy aplikace}
 
 Jelikož vytvářená aplikace není určená pro použití vícero uživateli najednou, ale pouze pro jednoho uživatele na jednom zařízení, tak pro ukládání dat aplikace je vhodná lokální databáze. 
 
 V úvahu připadá ukládat portfólia a transakce ve formátu JSON či XML přímo na souborový systém, ale z důvodu relace M:N mezi portfólii a kryptoměnami nejsou tyto typy databází příliš vhodné. Jako lepší volba tedy jeví nějaká relační databáze, např. SQLite, která je často používána při tvorbě desktopových aplikací a ukládá se ve formě jednoho souboru na souborový systém zařízení.
 
+
+
+\section{Popis architektury vytvořené aplikace}
+\subsection{Databázová vrstva}
+Ve vytvořené aplikaci je datová vrstva implementována pomocí tzv. \textit{repozitářů}, kdy každý repozitář představuje perzistentní úložiště dané entity, do kterého lze zapisovat a následně z něj číst.
+
+Kontrakt generického rozhraní repozitáře se skládá z následujících definic metod:
+\begin{itemize}
+    \item \texttt{public int Add(T entry)} -- přidá daný objekt do perzistentního úložiště a vrátí vygenerované ID
+    \item \texttt{public T Get(int id)} -- vyhledá a případně vrátí objekt z perzistentního úložiště dle předaného identifikátoru \texttt{id}
+    \item \texttt{List<T> GetAll()} -- vyhledá a případně vrátí seznam všech objektů z perzistentního úložiště
+    \item \texttt{public bool Update(T entry)} -- nahraje do perzistentního úložiště aktualizovanou verzi objektu, který se zde již nachází. Vrátí \texttt{true}, pokud aktualizace proběhla úspěšně nebo \texttt{false}, pokud během této operace došlo k nějaké chybě.
+    \item \texttt{public bool Delete(T entry)} -- smaže předaný objekt z úložiště a vrátí \texttt{true}, pokud smazání proběhlo úspěšně nebo \texttt{false}, pokud během této operace došlo k nějaké chybě.
+
+\end{itemize}
+
+\noindent Ve vytvořené aplikaci jsou definovány následující repozitáře:
+\begin{itemize} 
+    \item \texttt{IPortfolioRepository} -- úložiště objektů představujících jednotlivá portfólia spravované v aplikaci
+    \item \texttt{IPortfolioEntryRepository} -- úložiště objektů představujících položky existujících portfólií 
+    \item \texttt{IMarketOrderRepository} -- úložiště objektů představujících uskutečněné obchody dané položky portfólia
+\end{itemize}
+
+\subsubsection{Generování SQL dotazů}
+K jednoduchému a intuitivnímu generování SQL dotazů je použita knihovna \textbf{SqlKata Query Builder}\footnote{\url{https://github.com/sqlkata/querybuilder}}, kdy lze SQL dotazy vytvářet pomocí řetězení volání metod poskytovaných touto knihovnou.
+
+\begin{lstlisting}[language=Java, caption={Příklad generování SQL dotazu pro výběr všech transakcí dané položky portfólia pomocí knihovny SqlKata Query Builder.},captionpos=b, label={lst:sm-showcase}]
+Db.Get().Query(tableName).Where("portfolio_entry_id", portfolioEntryId).Get()
+\end{lstlisting}
+
+Tato knihovna přímo umožňuje nad předaným databázovým spojením vygenerovaný SQL dotaz přímo vykonat, kdy k této činnosti využívá knihovnu \textbf{Dapper}\footnote{\url{https://github.com/DapperLib/Dapper}}. Výsledkem metod pro vykonání generovaných dotazů jsou objekty typu \texttt{dynamic}, které je třeba mapovat na instance tříd dle modelu entity se kterou pracujeme.
+
+\begin{lstlisting}[language=Java,caption={Příklad mapování objektu typu \texttt{dynamic} na instanci třídy \texttt{Portfolio}.},captionpos=b, label={lst:sm-mapping}]
+public override Portfolio FromRow(dynamic d) =>
+            new Portfolio((string) d.name, (string) d.description, (Currency) d.currency_code, (int) d.id);
+\end{lstlisting}
+
+Jelikož velká část kódu pro implementaci metod repozitáře je pro všechny možné typy stejná, tak je tato část kódu sdílena pomocí abstraktní třídy \texttt{SqlKataRepository}. Implementace pro konkrétní třídy modelu musí akorát implementovat kód pro vytvoření instance dané třídy z objektu typu \texttt{dynamic} a naopak. V aplikaci se nachází implementace \texttt{SqlKataPortfolioRepository}, \texttt{SqlKataPortfolioEntryRepository} a \texttt{SqlKataMarketOrderRepository}.
+
+\subsection{Služba pro výpočet výkonu jednotlivých entit}
+Aby bylo možné vypočítat výkon (výdělek či ztráta) jednotlivých entit (portfólio, položka portfólia či uskutečněný obchod), byla vytvořeno rozhraní \texttt{ISummaryService} a jeho implementace \texttt{SummaryServiceImpl}.
+
 \section{Framework pro grafické rozhraní}
 \textit{Frontend realizovaný pomocí Blazor frameworku, zabalený do Electron wrapperu}
 
+\section{Oveření kvality vytvořeného software}
+
+Pro ověření kvality vytvořeného software pro sledování obchodního portfólia s kryptoměnami byly vytvořeny desítky jednotkových a integračních testů ověřující funkčnost základních modulů. Tyto testy se nachází v projektu \texttt{Tests}. Jako testovací framework byl zvolen framework \texttt{XUnit}\footnote{\url{https://github.com/xunit/xunit}}.
+
+Knihovna \texttt{moq}\footnote{\url{https://github.com/moq/moq4}} byla použita pro vytvoření \textbf{mock} objektů datové vrstvy při testování kódu služeb \texttt{PortfolioService}, \texttt{PortfolioEntryService} a \texttt{MarketOrderService} (jednotkové testy).
+
+Během integračních testů repozitářů datové vrstvy není použita databáze umístěná na souborovém systému, nýbrž databáze uložená v operační paměti z důvodu urychlení vykonávání testů. Připojení k databázi umístěné v operační paměti slouží řetězec \texttt{Data Source=:memory:}. 
+
+Vytvořené integrační testy ověřují funkčnost datové vrstvy a datového zdroje pro získvání informací o aktuálním stavu trhu s kryptoměnami.
+
+\begin{lstlisting}[caption={Struktura projektu \texttt{Tests} obsahující integrační a jednotkové testy}, captionpos=b]
+            |-- Integration
+            |   |-- CryptoStatsSource
+            |   |   |-- CryptoNameResolverTest.cs
+            |   |   `-- CryptoStatsSourceTest.cs
+            |   `-- Repository
+            |       |-- MarketOrderTest.cs
+            |       |-- PortfolioEntryTest.cs
+            |       `-- PortfolioTest.cs
+            `-- Unit
+                `-- Service
+                    |-- MarketOrderServiceTest.cs
+                    |-- PortfolioEntryServiceTest.cs
+                    |-- PortfolioServiceTest.cs
+                    `-- SummaryServiceTest.cs
+\end{lstlisting}
+
+
 
 \printbibliography