Revize 0f42a3c4

Updated documentation with description of application core and modularity and architectures with principles

documentation/main.tex

@@ -1 @@
-\documentclass[12pt, a4paper]{thesiskiv}
+\documentclass[
+12pt,
+a4paper,
+pdftex,
+czech,
+titlepage]{thesiskiv}
 \usepackage[czech]{babel}
 \usepackage[IL2]{fontenc}
 \usepackage[utf8]{inputenc}
@@ -19 +24 @@
   urlcolor=black,
   bookmarksopen=true}
   
-\lstdefinestyle{mystyle}{
-    frame=single,
-    commentstyle=\color{codegreen},
-    keywordstyle=\color{magenta},
-    stringstyle=\color{codepurple},
-    basicstyle=\ttfamily\footnotesize,
-    breakatwhitespace=false,         
-    breaklines=true,                 
-    keepspaces=true,                 
-    numbers=left,                    
-    numbersep=5pt,                  
-    showspaces=false,                
-    showstringspaces=false,
-    showtabs=false,                  
-    tabsize=2
-}
-
-\lstset{style=mystyle}
-
-\lstset{frame=tb,
-  language=C,
-  aboveskip=3mm,
-  belowskip=3mm,
-  showstringspaces=false,
-  columns=flexible,
-  basicstyle={\small\ttfamily},
-  numbers=none,
-  breaklines=true,
-  breakatwhitespace=true,
-  tabsize=3
-}
 % Začátek dokumentu
 \begin{document} 
 
@@ -75 +49 @@
 \tableofcontents
 
 %Kapitola1
-\chapter{Myšlenky a funkce aplikace}
+\chapter{Seznámení}
 
-V rámci předmětu ASWI/KIV byla pvytvořena modulární webová aplikace pro firmu Leuze. Aplikace slouží jako prostředí pro správu cílů zaměstnanců. Na základě splnění těchto cílů, aplikace počítá .... něco s platem .... 
+Následující kapitoly Vás blíže seznámí s implementací webové aplikace pro správu cílů psanou pomocí technologií ASP.NET Core, Blazor Server a další. Dokument obsahuje mimo jiné základní popis použitých architektur, vzorů a způsobů pro modularitu, rozšíření, udržitelnost kódu a snadnou testovatelnost jednotlivých vrstev aplikace nezávisle na sobě. Aplikace byla vytvořena za pomocí .NET 5.0.
 
+\chapter{Architektura a použité vzory}
 
+\section{ExtCore Framework}
+
+ExtCore umožňuje vytvářet webové aplikace z hlediska nezávislých přepoužitelných modulů či rozšíření. Každý z těchto modulů se skládá z jednoho či více ASP.NET Core projektů. Jakýkoliv project založení na ExtCore framework dokáže načíst a identifikovat třídy a objekty definované v jakékoliv importované knihovně (volitelně například pomocí predikátů pro filtrování) a následné získání jejich instancí. Libovolný modul nebo rozšíření během inicializace a spuštění webové aplikace spusti svůj vlastní kód. Pomocí priorit můžeme určit správné pořadí jednotlivých volání. Tuto funkcionalitu lze použít pro konfiguraci, registraci služeb atd. Jakýkoliv modul nebo rozšíření mohou spolu komunikovat pomocí událostí na straně serveru.
+
+\section{Clean architektura}
+
+V čisté architektuře se jádro aplikace dělí na dvě vrstvy. Domain vrstvu obaluje vrstva application. Ve vrstvě Domain si budeme udržovat entity („domains“) a hodnotové objekty („value objects“) naší aplikace. Jako entitu lze chápat každou třídu popisující chování objektu reálného světa, jejíž jedinečnost je určena hodnotou identifikátoru. Hodnotový objekt musíme chápat jinak. Hodnotový objekt je objekt, jehož jedinečnost je určena jeho hodnotou. Například telefonní číslo či adresa. Část jádra, nazývající se application, zastřešuje veškerou práci prováděnou s entitami či hodnotovými objekty - pravidla, neboli business rules. Jako příklad si můžeme představit například pravidlo „ulož zákazníka“. V jádře ovšem nenalezneme databázi. Nalezneme ji ve vrstvě persistence, na obrázku vyznačené zelenou barvou. Na obrázku je šipkou naznačena závislost vrstvy persistence na vrstvě application. Konkrétněji vrstva application nesmí využívat třídy definované ve vrstvě Persistence. Vrstvu persistence si v cibulové architektuře můžeme představit jako plugin do vrstvy application. V aplikační vrstvě definujeme rozhraní, které je následně ve vrstvě Persistence implementováno. Vrstva infrastructure slouží ke shlukování implementací komunikací s dalšími externími technologiemi, na kterých nechceme být závislí. Může se například jednat o technologii zodpovědnou za odesílání emailů z aplikace nebo tisk souborů atp.
+
+\section{Domain Driven Design}
+
+V kontextu vývojových fází softwaru je hlavní zaměření DDD na část analýzy a návrhu, ale zároveň zasahuje do fází sběru požadavků a implementace. Propojení těchto fází je podle DDD nutností k dosažení efektivního vývojového procesu, protože každá může odhalit detaily o doméně z jiné perspektivy. Avizuje se, že DDD není svázáno s žádnou konkrétní metodologií, ale nejvíce můžeme z těchto přístupů vytěžit v rámci agilních metodologií vývoje.\\
+
+Pro aplikovatelnost DDD uvádí dvě podmínky:
+
+\begin{itemize}
+	\item iterativní přístup k vývoji 
+	\item zapojení doménových expertů do procesu vývoje
+\end{itemize}
+
+Pod pojmem doména rozumíme oblast, kterou daný software řeší, např. bankovnictví, řízení letového provozu atd. Účelem softwaru je zefektivnit práci v této doméně. Aby toho bylo dosaženo, musí být software odrazem domény. To znamená, že musí být vybudován na hlavních konceptech a prvcích domény a vztazích mezi nimi. Doména ale existuje v reálném světě, takže ji není možné přímo přeložit do programového kódu. Proto potřebujeme vytvořit abstrakci domény – její model. Model domény nechápe DDD jako nějaký diagram, ale jako znalost o doméně, která je v tomto diagramu obsažena. Tato znalost může mít mnoho reprezentací: funkční specifikace, UML diagramy, kód programu nebo testy. Z tohoto úhlu pohledu, lze podle DDD chápat jako pět doporučení jak efektivně modelovat doménu:
+
+\begin{enumerate}
+	\item \textbf{Provázání modelu a implementace.} Model bez možnosti implementace je v oblasti komerčního softwaru zbytečný a implementace, která není založena na modelu, snadno sklouzne k řešení problémů, které jsou mimo obor domény a opomenutí těch skutečně důležitých. 
+	\item \textbf{Model reflektuje jazyk doménových expertů.} Aby model během celého vývoje odrážel skutečnosti dané domény, je třeba používat ve všech jeho reprezentacích shodný jazyk, který vychází z jazyka doménových expertů. 
+	\item \textbf{Model zachycuje znalosti.} Objekty modelu nejsou pouze datových schématem, v modelu musíme zachytit také chování objektů a pravidla domény. 
+	\item \textbf{Destilace modelu.} Model se během vývoje stále mění, integrujeme do něj nově objevené koncepty domény a odstraňuje nebo modifikujeme ty, které se ukážou jako irelevantní.
+	\item \textbf{Komunikace a experimentování.} Model je předmětem komunikace mezi doménovými experty a dalšími vývojáři. Tím, jak se jej snažíme popsat větami, se často objeví dosud skryté souvislosti. Prostřednictvím diskuzí a brainstormingů můžeme rychle procházet a posuzovat jeho různé variace.
+\end{enumerate}
+
+
+\section{Command-Query Responsibility Segregation}
+
+CQRS (Command-Query Responsibility Segregation) je architektonický model, který odděluje modely pro čtení a zápis dat. Základní princip je, že je možné rozdělit operace systému na dvě silně oddělené kategorie:\\
+
+\begin{enumerate}
+	\item \textbf{Queries.} Tyto dotazy vrátí výsledek a nezmění stav systému, a nejsou k dispozici žádné vedlejší účinky.
+	\item \textbf{Commands.} Tyto příkazy mění stav systému.
+\end{enumerate}
+
+CQRS je jednoduchý koncept: Jedná se o metody v rámci stejného objektu, které jsou buď dotazy, nebo příkazy. Každá metoda buď vrátí stav nebo stav změní, ale ne obojí. I jeden objekt vzoru úložiště může odpovídat CQS. CQS se dá považovat za základní princip pro CQRS. CQRS společně s DDD jsou hlavními principy využívanými při vytváření aplikací jako mikroslužeb. Tato práce tyto principy využivá taktéž, avšak pouze v rámci monolitické aplikace. Jejich aplikováním lze zajistit snadnou udržitelnost, rozšiřitelnost a testovatelnost jednotlivých vrstev a služeb aplikace.
+
+\section{Repository pattern}
+
+Návrhový vzor pro přístup k datům, který má za úkol řešit centralizaci kódu pro přístup k datům a tím odstranit možné duplicity. Přináší podpory silně typovaných objektů. Zlepšuje udržitelnost a čitelnost kódu oddělením business logiky aplikace od logiky služeb pro přístup k datům. Důvod pro použití návrhového vzoru v řešení je odstínění přístupu k perzistentním datům pomocí Entity Framework od vyšších vrstev aplikace. Jedna konkrétní implementace repository umožnuje přístup k jednomu typu objektů daného typu T. Model aplikace nemá ponětí o tom, jakým způsobem je persistován. O to se stará právě Repository. Navíc díky tomu, že se o persistenci stará cizí objekt, stačí nám znát pouze jeho rozhranní a v případě potřeby ho snadno nahradit jiným.
+
+\section{Entity Framework}
+
+Entity Framework (EF) Core slouží pro relační mapování objektů (tzv. ORM), který:
+
+\begin{itemize}
+	\item Umožňuje vývojářům v rozhraní .NET pracovat s databází pomocí objektů .NET.
+	\item Eliminuje nutnost pro většinu kódu přístupu k datům, který je obvykle nutné zapsat.
+\end{itemize}
+
+EF podporuje následující přístupy k vývoji modelů:
+
+\begin{itemize}
+	\item Vygeneruje model z existující databáze.
+	\item Ruční kód modelu, aby odpovídal databázi.
+	\item Po vytvoření modelu použijte k vytvoření databáze z modelu migraci EF . Migrace umožňují vývoj databáze jako změn modelu.
+\end{itemize}
+
+\newpage
+\begin{lstlisting}
+	using System.Collections.Generic;
+	using Microsoft.EntityFrameworkCore;
+	
+	namespace Intro
+	{
+		public class BloggingContext : DbContext
+		{
+			public DbSet<Blog> Blogs { get; set; }
+			public DbSet<Post> Posts { get; set; }
+			
+			...
+		}
+		
+		public class Blog
+		{
+			public int BlogId { get; set; }
+			public string Url { get; set; }
+			public int Rating { get; set; }
+			public List<Post> Posts { get; set; }
+		}
+		
+		public class Post
+		{
+			public int PostId { get; set; }
+			public string Title { get; set; }
+			public string Content { get; set; }
+			
+			public int BlogId { get; set; }
+			public Blog Blog { get; set; }
+		}
+	}
+\end{lstlisting}
+
+\newpage
+Instance tříd entit se načítají z databáze pomocí jazyka LINQ (Language Integrated Query).\\
+
+\begin{lstlisting}
+	using (var db = new BloggingContext())
+	{
+		var blogs = db.Blogs
+		.Where(b => b.Rating > 3)
+		.OrderBy(b => b.Url)
+		.ToList();
+	}
+\end{lstlisting}
+
+Data se vytvářejí, odstraňují a upravují v databázi s použitím instancí tříd vaší entity.\\
+
+
+\begin{lstlisting}
+	using (var db = new BloggingContext())
+	{
+		var blog = new Blog { Url = "http://sample.com" };
+		db.Blogs.Add(blog);
+		db.SaveChanges();
+	}
+\end{lstlisting}
+
+Více informací ohledně Entity Framework a Entity Framework Core lze najít na \href{https://docs.microsoft.com/cs-cz/ef/core/}{Microsoft Docs}.
+
+\section{Blazor}
+
+Blazor používá komponenty. Celé to je o jejich vnořování a vkládání jejich hierarchií do stránek a layoutů. Komponenty se píšou buď přímo v C\# nebo Razoru. Pochopitelně to není ten úplně samý Razor, který znáte z Razor Pages nebo MVC, ale princip zůstává – je to předloha, ze které se vygeneruje třída komponenty. Stačí v zásadě pochopit, že blok markup kódu v .razor souboru kompiler vezme a vygeneruje z něj metodu pro vykreslení komponenty. Takže každou existující komponentu můžete vzít, zdědit z ní a přepsat její metodu vykreslení. To se hodí pro upravení již existujících komponent. Vygenerované třídy komponent jsou navíc partial, což je ideální, pokud nechcete mít klasický C\# kód u markup kódu dané komponenty – prostě použijete druhý soubor.\\
+
+Blazor se při překreslování DOMu snaží pracovat co nejefektivněji, ale za to po vás něco chce. Všechny komponenty a elementy mají id, které vzhledem k jejich rodiči musí být unikátní, a navíc mezi jejich sourozenci ve vzestupné posloupnosti – toho se musíte držet, pokud vykreslovací funkci komponenty píšete ručně. Blazor je díky identifikátorům schopen rychle zjistit změny v DOMu a to, co může použije znovu bez nutnosti smazání starých a vytvoření nových položek stejného typu – prostě do nich znovu pošle vstupní parametry. To vás může nemile překvapit, pokud má komponenta vlastní vnitřní stav, který na vstupních parametrech nezávisí – vnitřní stav vám zůstane, ale parametry se změní na parametry komponenty, co měla toto id při minulém vykreslení (typicky v kolekcích). Naštěstí lze dát komponentám i unikátní klíč (atribut key), který zajistí, že se parametry namapují vždy na tu stejnou komponentu.\\
+
+Blazor má bezproblémově vyřešeno jednosměrné zasílání parametrů do vnořených komponent. Buď parametr zašlete jen do přímého potomka, nebo do všech vnořených potomků (tzv. kaskádové parametry) a vnořené komponenty si je odchytí buď podle typu nebo jména. Obecně všechny události v Blazoru jsou řešeny pomocí struktury EventCallback, která zvládne synchronní i asynchronní operace a zároveň oznámí komponentě, že došlo ke změně jejího stavu a ta se poté překreslí. Při překreslení komponenty se překreslí i její vnořené komponenty, které používají nějakou její proměnnou jako vstupní parametr.\\
+
+\chapter{Jádro aplikace}
+
+\section{Rozložení implementace}
+
+Řešení aplikace je rozděleno do několika projektů. Projekt \textit{Leuze.App} je vstupní bod aplikace, který inicializuje veškerou infrastrukturu aplikace, které dale vyřizuje požadavky jednotlivých uživatelů. Nejdůležitější částí implementace je tzv. “jádro”. Jádro se skládá z celkem 5 projektů.
+
+\textit{Leuze.Core.Application.Identity} uchovává veškeré datové modely aplikačního uživatele, tedy v našem případě především modely pro Identity Framework (uživatel, role, …) a model popisující oprávnění pro role. \textit{Leuze.Core.Application.UI} je součástí prezentační vrstvy architektury. V tomto projektu nalezneme veškeré definice UI/UX stránek jádra aplikace společně s jejich komponenty, jazykovými mutacemi atd. \textit{Leuze.Core.Application} je pak součástí business vrstvy aplikace. V tomto projektu je inicializují veškeré potřebné podpůrné záležitosti pro chod aplikace, je aktivován a nastaven ExtCore Framework, který z nakonfigurovaného adresaře načte veškeré dodatečné rozšiřující knihovny. Mimo jiné obsahuje tento projekt veškeré podpůrné třídy pro vytváření nových modulů, využívající v rámci business logiky principy CQRS.\\
+
+Předposledním projektem jádra je \textit{Leuze.Core.Domain}. Tento projekt obsahuje veškeré doménové modely (v našem případě nazveme doménovým modelem databázovou entitu). Veškeré tyto entity jsou schopné vytvářet v systému události, která se zpropagují do příslušných vrstev a lze tak na změnu stavu modelů reagovat změnou stavu navazující.\\
+
+Posledních projektem jádra je \textit{Leuze.Core.Infrastructure.Persistence}. Jak jeho název naznačuje, tato vrstva je stará o persistenci dat. Poskytuje tedy implementace rozhraní repozitářů definovaných v doméně aplikace, registraci doménových modelů do EF pomocí Fluent API, konfiguraci samotného modulárního databázového kontextu aplikace. Z důvodu modulárnosti aplikace bylo nutné pro podporu migrací vytvořit samostatnou třídu pro “Shared Design Time” továrnu databázového kontextu. Databázový kontext neobsahuje přímo jednotlivé DbSet “vlastnosti” (properties), o vytváření těchto setů se stará ExtCore Framework při inicializaci modulárního databázového modelu.\\
+
+\section{Princip vytváření a implementace modulů}
+
+Již samotné jádro aplikace zavádí několik pravidel pro správné strukturování a propojení vrstev. Jednotlivé moduly se musí skládat alespoň ze čtyř projektů, aby bylo zajištěno dostatečné oddělení datové, business a prezentační vrstvy. Prvním projektem je \textit{XXX.Application.UI}, jenž poskytuje vstupní body pro jednotlivé HTTP požadavky uživatelů (obsahuje tedy hlavně kontrolery) a jejich modely. Tento projekt má přímou referenci na projekt \textit{XXX.Application}, který obsahuje výčet služeb business logiky, tedy v našem případě definování a implementace Commands a Queries pro danou doménu řešeného problému. \textit{XXX.Application} pak má přímou referenci na samotný projekt domény dané problematiky, označmě jej jako projekt \textit{XXX.Domain}. Doménový projekt obsahuje definice doménových modelů problematiky, definuje jejich události a může implementovat “handlery” pro zachycení jiných událostí definovaných v rámci celé aplikace (tzn. i na akce definované v jiných modulech). Posledním povinným projektem je \textit{XXX.Infrastructure.Persistence}, obsahující, podobně jako stejně pojmenováný projekt jádra, implementaci pro rozhraní repozitáře a registrátory entity. Je důležité upozornit, že z důvodu oddělení služeb infrastruktury nemají projekty \textit{XXX.Domain}, \textit{XXX.Application} a \textit{XXX.Application.UI} žádnou referenci na \textit{XXX.Infrastructure.Persistence}. Tímto je zajištěno oddělení datové vrstvy, která má přímou referenci na \textit{XXX.Domain} projekt. \\
+
+Veškeré definice rozhraní služeb jsou tedy definovány v rámci \textit{XXX.Domain}. Tento projekt však nemá o jejich implementaci ponětí a jejich využívání je možné pomocí “Dependency Injection” daného rozhraní, které implementující projekt zaregistroval do poskytovatele služeb.
+\\
+
+Závislosti a reference jednotlivých projektů a vrstev tak, jak byly popsány výše, je nutné dodržet pro správné oddělení jednotlivých vrstev a zajištění si správné provázanosti funkcionalit (abychom se nemuseli zabývat cyklickými závislostmi mezi projekty v řešení).\\
 
 %Kapitola2
 
@@ -114 +241 @@
 V tabulce uživatelů je zobrazeno jméno, email, role, typ a senior. První tři sloupce jsou sebevysvětlující, typ je lokální nebo síťový (AD) a senior značí nadřízeného. 
 Po kliknutí na Upravit je zde možnost změny jména (pouze zobrazovací), emailové adresy (pro přihlašování), role (jeden uživatel může mít pouze jednu roli) a možnost nastavení nadřízeného (lze vybrat pouze ze seznamu TL uživatelů, smazání nadřízeného se provede vybráním možnosti Vyberte uživatele)
 
-%Kapitola3
-\chapter{Implementace}
-
 
 %Kapitola4
 \chapter{Bezpečnost}
 
 
-
 %Kapitola5
 \chapter{How to run}