genofire/hs_monolith
genofire
/
hs_monolith
Archived
1
0
Fork 0
Code Releases Activity

[Task] documentation

This commit is contained in:
mlabusch 2017-06-07 17:16:11 +02:00
parent eedf934ca5
commit 6ee8346160
4 changed files with 25 additions and 24 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

15
documentation/microservice_stock/chapter/Anforderungen.tex
View File

@ -1,7 +1,7 @@
\section{Definition der Anforderungen}
\label{sec: Definition der Anforderungen}
Der Microservice Warenwirtschaft dient der Verwaltung der Warenbestände für den Webshop Mosh. Er ermöglicht es zum Beispiel, dass neue Waren erfasst werden können und keine Waren verkauft werden, die sich nicht mehr im Warnbestand befinden. Die nachfolgende Tabelle \ref{tabl:Begriffe} definiert die hier verwendeten Begriffe, so wie sie in dem Code und innerhalb dieser Dokumentation genutzt werden.
Der Microservice Warenwirtschaft dient der Verwaltung der Warenbestände für den Webshop Mosh. Er ermöglicht es zum Beispiel, neue Waren zu erfassen und verhindert den Verkauf von Waren, die sich nicht mehr im Warnbestand befinden. Die nachfolgende Tabelle \ref{tabl:Begriffe} definiert die hier verwendeten Begriffe, so wie sie in dem Code und innerhalb dieser Dokumentation genutzt werden.
\begin{table}[H]
\begin{small}
\begin{center}
@ -23,10 +23,7 @@ Der Microservice Warenwirtschaft dient der Verwaltung der Warenbestände für de
\end{small}
\end{table}
\textit{\textit{Dieser Microservice ist Teil der Prüfungsleistung in den Modul KSS im Masterstudiengang komplexe Softwaresysteme des Sommersemesters 2017 an der Hochschule Bremen. Zu der gestellten Aufgabenstellung gehört nicht, den Microservice zusammen mit den Microservices der anderen Gruppen in einen gemeinsamen, lauffähigen Webshop zu integrieren.}}
\newpage
Die übergeordnete Aufgabe dieses Microservice ist die Speicherung der Waren mit ihrem Lagerort sowie einem Zeitstempel, wann sie ablaufen. Nachfolgend werden die weiteren, detaillierten Anforderungen an diesen Microservice zusammengefasst.
Die übergeordnete Aufgabe dieses Microservice ist die Speicherung der Waren mit ihrem Lagerort sowie einem Ablaufdatum, wann sie ablaufen. Nachfolgend sind die weiteren, detaillierten Anforderungen an diesen Microservice zusammengefasst.
\begin{itemize}
\item \textbf{Funktionen des Admin-Frontends}
@ -43,7 +40,11 @@ Die übergeordnete Aufgabe dieses Microservice ist die Speicherung der Waren mit
\end{itemize}
\item \textbf{Optionale Zusatzfunktionen}
\begin{itemize}
\item Ausgabe einer Statistik, wie viele Waren sich gesamt und durchschnittlich im Warenbestand befinden im Admin-Fontend
\item Ampeldarstellung pro Ware, die Anzeigt ob diese bereits ihr angegebenes Ablaufdatum erreicht hat, im Admin-Frontend
\item Admin-Frontend: Ausgabe einer Statistik, wie viele Waren sich gesamt und durchschnittlich im Warenbestand befinden
\item Admin:Frontend: Ampeldarstellung pro Ware, die Anzeigt ob diese bereits ihr angegebenes Ablaufdatum erreicht hat
\end{itemize}
\end{itemize}
Die Angabe der Anzahl ist bei dem Hinzufügen neuer Waren zum Warenbestand verpflichtend, da ohne sie die Verwaltung neu eingetroffener Waren nicht möglich ist. Gleiches gilt für die Angabe des Ablaufdatums, diese ist speziell bei der Verwaltung von Lebensmitteln notwendig, um die Kunden vor abgelaufenen Waren und das vertreibende Unternehmen so vor Haftungen, Anzeigen bei der Gesundheitsbehörde oder Image-Schäden zu schützen. Die Datumsangabe erfolgt dabei im amerikanischen Format \textit{Jahr-Monat-Tag}. \par
Im Gegensatz dazu sind die Angabe von Lagerplatz und Kommentar bei dem Hinzufügen neuer Waren optional, da diese Informationen für die Verwaltung des reinen Warenbestandes nicht essentiell notwendig sind. Diese beiden Angaben sind als Freitextfelder umzusetzen, um speziell bei dem Lagerort flexibel die Nutzung verschiedener Benennungschema für Regale oder Lagerräume zu ermöglichen und den Benutzer hier nicht einzuschränken. \par
Der Microservice ist in den bestehenden Monolithen Mosh zu integrieren, eine Kommunikation mit anderen Microservices wird jedoch nicht hergestellt.

6
documentation/microservice_stock/chapter/DokStruktur.tex
View File

@ -1,6 +1,6 @@
\section{Dokumentationsstruktur}
\label{sec: Dokumentationsstruktur}
Für die Dokumentation des Microservice Warenwirtschaft wurden eine Kombination aus drei Dokumenten gewählt. Zum einen beschreibt ein bebildertes Handout auf einer Seite die Funktionen des Admin-Frontends für den Benutzer. Diese sehr kurze Dokumentenform wurde gewählt, da Benutzer häufig nicht gewillt sind, umfangreiche Anleitungen zu lesen um eine Anwendung nutzen zu können. Vielmehr wollen sie schnell einen Überblick der Kernfunktionalitäten erhalten.\par
Auf der anderen Seite muss der Microservie auch für Entwickler dokumentiert sein, hierfür wurde diese Dokumentation angelegt. Sie beginn anstelle eines Abstract mit einem Steckbrief des Microservice, der dessen grundlegende Struktur und Funktionalität kurz beschreibt. In dem eigentlichen Dokument werden dann zunächst die Anforderungen an den Microservice beschrieben, da ihre Umsetzung das primäre Ziel der Entwicklung ist. Weiter werden der Microservice mit seinem Aufbau, den Schnittstellen und der Anpassung des gegebenen Monolithen sowie Implementierungsregeln beschrieben. Dieses Dokument schließt mit einem \textit{Getting Started} Guide. Auf Details wir ein Abkürzungs- oder Literaturverzeichnis wurde in dieser Dokumention bewusst verzichtet, um sie kurz zu halten. Zitate und Verweise werden hier in Form von Fußnoten integriert.\par
Abschließend dokumentiert das Testprotkoll, als drittes Dokument, die für diesen Microservice angewendet Black-Box-Testfälle - das heißt jene Tests die anhand der Anforderungen und aus Sicht des Benutzer durchgeführt wurden.
Für die Dokumentation des Microservice Warenwirtschaft wurden eine Kombination aus drei Dokumenten gewählt. Zum einen beschreibt ein bebildertes Handout auf einer Seite die Funktionen des Admin-Frontends für den Benutzer. Diese sehr kurze Dokumentenform wurde gewählt, da Benutzer häufig nicht gewillt sind, umfangreiche Anleitungen zu lesen um eine Anwendung nutzen zu können. Vielmehr wollen sie schnell einen Überblick der Kernfunktionalitäten erhalten. Aus diesem Grund wurde auch auf eine Benutzerdokumentation für die Kunden verzichtet, da angenommen wird dass die Darstellung der Produktverfügbarkeit als Ampel selbsterklärend ist.\par
Auf der anderen Seite muss der Microservie auch für Entwickler dokumentiert sein, hierfür wurde diese Dokumentation angelegt. Sie beginn anstelle eines Abstract mit einem Steckbrief des Microservice, der dessen grundlegende Struktur und Funktionalität kurz beschreibt. Das eigentliche Dokument beschreibt zunächst die Anforderungen an den Microservice, da Entwicklung sich an diesen primär orientiert. Weiter werden der Microservice mit seinem Aufbau, den Schnittstellen und der Anpassung des gegebenen Monolithen sowie Implementierungsregeln beschrieben. Dieses Dokument schließt mit einem \textit{Getting Started} Guide. Auf Details wir ein Abkürzungs- oder Literaturverzeichnis wurde in dieser Dokumention bewusst verzichtet, um sie kurz zu halten. Zitate und Verweise werden hier in Form von Fußnoten integriert.\par
Abschließend dokumentiert das Testprotkoll -- als drittes Dokument -- die für diesen Microservice angewendet Black-Box-Testfälle - das heißt jene Tests die anhand der Anforderungen und aus Sicht des Benutzer durchgeführt wurden.

2
documentation/microservice_stock/chapter/GettingStarted.tex
View File

@ -8,7 +8,7 @@ go get ./...
\end{lstlisting}
\subsection{Start des Microservice}
Um den Microservice Warenwirtschaft zu starten, muss die folgende Befehlszeile unter dem Root-Verzeichnis des Microservice ausgeführt werden. Anschließend wird der Microservice unter \texttt{http://localhost:8080/} bereitgestellt. Zusätzlich wird der Microservice aktuell unter der URL \texttt{https://stock.pub.warehost.de/} automatisch ausgebracht.
Um den Microservice Warenwirtschaft zu starten, ist die folgende Befehlszeile unter dem Root-Verzeichnis des Microservice auszuführen. Anschließend wird der Microservice unter \linebreak \texttt{http://localhost:8080/} bereitgestellt. Zusätzlich ist der Microservice aktuell unter der URL \texttt{https://stock.pub.warehost.de/} erreichbar.
\begin{lstlisting}[caption=Start des Go-Microservice]
go run main.go
\end{lstlisting}

26
documentation/microservice_stock/chapter/Struktur.tex
View File

@ -1,6 +1,6 @@
\section{Architektur des Microservice}
\label{sec: Architektur des Microservice}
Der Microservice Warenwirtschaft wurde in der Programmiersprache Go\footnote{https:\//golang.org\/doc\/} entwickelt. Go-An-wendungen bestehen aus Packages, in denen die einzelnen Go-Files organisiert sind, Klassen im Sinne der Objektorientierung gibt es nicht. Der Microservice Warenwirtschaft setzt sich aus den neun Packages zusammen, die in der Abbildung \ref{pic:Struktur des Microservice} dargestellt werden. In den nachfolgenden Unterkapiteln \ref{subsec: Presentation Layer} und \ref{subsec: Application Layer} werden die Packages und die darin enthaltenen Go-Files des Presentation sowie des Application Layers kurz vorgestellt. Go-Files mit der Bezeichnung \texttt{<<Name>>\_test.go} beinhalten Whitebox-Testfälle um die Funktionen der benannten Go-Files zu prüfen. Aus Gründen der Übersichtlichkeit werden diese Files hier nicht explizit aufgeführt. Die weiteren Unterkapitel beschreiben die Schnittstellen, den Persistant Layer sowie die Log-Level, das Admin-Frontend und schließlich die Anpassung des Monolithen,um den Microservice Warenwirtschaft in diesen zu integrieren.
Der Microservice Warenwirtschaft wurde in der Programmiersprache Go\footnote{https:\//golang.org\/doc\/} entwickelt. Go-An-wendungen bestehen aus Packages, in denen die einzelnen Go-Files organisiert sind, Klassen im Sinne der Objektorientierung gibt es nicht. Der Microservice Warenwirtschaft setzt sich aus den neun Packages zusammen, die die Abbildung \ref{pic:Struktur des Microservice} dargestellt. In den nachfolgenden Unterkapiteln \ref{subsec: Presentation Layer} und \ref{subsec: Application Layer} werden die Packages und die darin enthaltenen Go-Files des Presentation sowie des Application Layers kurz vorgestellt. Go-Files mit der Bezeichnung \texttt{<<Name>>\_test.go} beinhalten Whitebox-Testfälle um die Funktionen der benannten Go-Files zu prüfen. Aus Gründen der Übersichtlichkeit werden diese Files hier nicht explizit aufgeführt. Die weiteren Unterkapitel beschreiben die Schnittstellen, den Persistant Layer sowie das Admin-Frontend und schließlich die Anpassung des Monolithen, um den Microservice Warenwirtschaft in diesen zu integrieren.
\begin{figure}[H]
\centering
@ -12,9 +12,9 @@ Der Microservice Warenwirtschaft wurde in der Programmiersprache Go\footnote{htt
\newpage
\subsection{Schnittstellen zu anderen Microservices}
\label{subsec: Schnittstellen zu anderen Microservices}
Der Microservice Warenwirtschaft weißt drei Schnittstellen\footnote{Da es nicht Teil der übergeordneten Aufgabenstellung war, die Microservices der einzelnen Projektgruppen zu einem lauffähigen Webshop zusammenzufügen, greift der Microservice Warenwirtschaft an diesen Stellen auf Testdaten zurück} zu anderen Microservices auf. Zunächst soll für die Authentifizierung der Benutzer des Admin-Frontends vollständig auf den Microservice Benutzerauthentifizierung zurückgegriffen werden. Anstelle einer Login-Maske weißt das Admin-Frontend deshalb bisher nur einen Icon in Form eines Schlosses auf. Dieser symbolisiert, ob ein Benutzer die passende Berechtigung für das Admin-Front besitzt (Schloss geschlossen) oder nicht (Schloss geöffnet). \par
Der Microservice Warenwirtschaft weißt drei Schnittstellen\footnote{Da es nicht Teil der übergeordneten Aufgabenstellung war, die Microservices der einzelnen Projektgruppen zu einem lauffähigen Webshop zusammenzufügen, greift der Microservice Warenwirtschaft an diesen Stellen auf Testdaten zurück} zu anderen Microservices auf. Zunächst greift der Microservice Warenwirtschaft für die Authentifizierung der Benutzer des Admin-Frontends vollständig auf einen Microservice Benutzerauthentifizierung zurück. Anstelle einer Login-Maske weißt das Admin-Frontend deshalb bisher nur einen Icon in Form eines Schlosses auf. Dieser symbolisiert, ob ein Benutzer die passende Berechtigung für das Admin-Front besitzt (Schloss geschlossen) oder nicht (Schloss geöffnet). \par
Weiter benötigt der Microservice Warenwirtschaft Informationen darüber, ob ein Benutzer eine Ware in den Warenkorb gelegt hat und ob eine Bestellung abgeschlossen wurde. So können Waren im Warenkorb für die Bestellung durch andere Benutzer blockiert und die erfolgreich bestellten Waren aus dem Warenbestand gelöscht werden. Diese Funktionalitäten geben eine eine Schnittstelle zu dem Microservice Bestellung vor. \par
Die dritte Schnittstelle besteht zu dem Microservice Produktkatalog, von welchem die angebotenen Produkte -- die sich dementsprechend im Lager befinden können -- abgefragt werden. Die drei nachfolgenden Listings zeigen die Daten, die von den der Microservices Produktkatalog und Bestellung im JSON-Format erwartet, beziehungsweise an diese ausgegeben werden.
Die dritte Schnittstelle besteht zu dem Microservice Produktkatalog, von welchem die Warenwirtschaft die angebotenen Produkte -- die sich dementsprechend im Lager befinden können -- abfragt. Die drei nachfolgenden Listings zeigen die Daten, die von den Microservices Produktkatalog und Bestellung im JSON-Format erwartet, beziehungsweise an diese ausgegeben werden.
\begin{lstlisting}[caption=Datenabfrage aus dem Produktkatalog]
{
@ -45,12 +45,12 @@ Die dritte Schnittstelle besteht zu dem Microservice Produktkatalog, von welchem
\subsection{Presentation Layer -- Admin-Frontend}
\label{subsec: Presentation Layer}
Der Presentation Layer umfasst alle Packages, die sich mit der eigentlichen Darstellung der Warenwirtschaft aus der Sicht des Endbenutzers befassen. Im Detail ist dies das Package \textbf{\texttt{webroot}}, welches den statischen Inhalt der Frontends, wie zum Beispiel die HTML-Files und Bilder enthält. \par
Die Startseite \textit{List} des Admin-Frontends zeigt eine Übersicht aller vorhandenen Produkte mit ihrer Anzahl an Waren (Abbildung \ref{pic:Admin-Frontend -- List}). Letztere wird mit einem Ampelsystem dargestellt, wobei ein vollkommen rot gefärbter Kreis einem Warenbestand von null entspricht und der Kreis mit zunehmender Anzahl an Waren immer mehr grün eingefärbt wird. Zu jeden Produkt kann über den, mit einem Plus, gekennzeichneten Button Waren hinzugefügt werden. Ein Klick auf das jeweilige Produkt führt zu dessen Produktseite. \par
Die Produktseiten führen die ID, die Gesamtanzahl an Waren sowie die einzelnen Waren auf (Abbildung \ref{pic:Admin-Frontend -- Produktseite}). Diese können jeweils über den Icon in Form eines Mülleimers manuell gelöscht werden. Auch auf den Produktseiten können über einen, mit einem Plus gekennzeichneten, Button neue Waren hinzugefügt werden. Beim Hinzufügen von neuen Waren sind für diese ein Ablaufdatum, eine Lagerposition sowie ein Kommentar und die Anzahl anzugeben (Abbildung \ref{pic:Admin-Frontend -- Hinzufuegen von Waren}). Um den Microservice auch in anderen Einsatzgebieten, als einem Webshop für Obst- und Gemüse einsetzen zu können, sind hier nur die Felder Lagerposition und Anzahl verpflichtend. Die Seite \textit{Statistics} gibt letztendlich einen Überblick der gesamten und der durchschnittlichen Waren im Warenbestand.
Die Startseite \textit{List} des Admin-Frontends zeigt eine Übersicht aller vorhandenen Produkte mit ihrer Anzahl an Waren (Abbildung \ref{pic:Admin-Frontend -- List}). Letztere wird mit einem Ampelsystem dargestellt, wobei ein vollkommen rot gefärbter Kreis einem Warenbestand von null entspricht und der Kreis mit zunehmender Anzahl an Waren immer mehr grün eingefärbt wird. Zu jedem Produkt können über den, mit einem Plus, gekennzeichneten Button Waren hinzugefügt werden. Ein Klick auf das jeweilige Produkt führt zu dessen Produktseite. \par
Die Produktseiten führen die ID, die Gesamtanzahl an Waren sowie die einzelnen Waren auf (Abbildung \ref{pic:Admin-Frontend -- Produktseite}). Diese können jeweils über den Icon in Form eines Mülleimers manuell gelöscht werden. Auch auf den Produktseiten sind über einen, mit einem Plus gekennzeichneten, Button neue Waren hinzufügbar. Beim Hinzufügen von neuen Waren sind für diese ein Ablaufdatum, eine Lagerposition sowie ein Kommentar und die Anzahl anzugeben (Abbildung \ref{pic:Admin-Frontend -- Hinzufuegen von Waren}). Die Seite \textit{Statistics} gibt letztendlich einen Überblick der gesamten und der durchschnittlichen Waren im Warenbestand.
\begin{figure}[H]
\centering
\includegraphics[width=0.65 \textwidth]{./pics/product.png}
\includegraphics[width=0.75 \textwidth]{./pics/product.png}
\caption{Admin-Frontend -- Produktseite}
\label{pic:Admin-Frontend -- Produktseite}
\end{figure}
@ -58,7 +58,7 @@ Die Produktseiten führen die ID, die Gesamtanzahl an Waren sowie die einzelnen
\begin{figure}[H]
\centering
\includegraphics[width=0.65 \textwidth]{./pics/add.png}
\includegraphics[width=0.75 \textwidth]{./pics/add.png}
\caption{Admin-Frontend -- Hinzufügen von Waren}
\label{pic:Admin-Frontend -- Hinzufuegen von Waren}
\end{figure}
@ -67,11 +67,11 @@ Die Produktseiten führen die ID, die Gesamtanzahl an Waren sowie die einzelnen
\newpage
\subsection{Application Layer}
\label{subsec: Application Layer}
Die Packages des Application Layers umfassen die Logik des Microservice Warenwirtschaft. Sie werden nachfolgend aufgelistet und kurz beschrieben.
Die Packages und Go-Files des Application Layers umfassen die Logik des Microservice Warenwirtschaft. Sie werden nachfolgend aufgelistet und kurz beschrieben.
\paragraph{cmd:} Go-File main.go, welches die Applixation letztendlich ausführt und alle Angaben zu den Config-Files der Applikation enthält
\paragraph{cmd:} Go-File main.go, welches die Applikation letztendlich ausführt und alle Angaben zu den Config-Files der Applikation enthält
\paragraph{http:} Go-Files, die die Anwendungslogik (Funktionen) und die API-Routen beinhalten.
\paragraph{http:} Go-Files, die die Anwendungslogik (Funktionen) und die API-Routen beinhalten
\begin{itemize}
\item \texttt{bindapi.go}: Funktionen, die für das Binden der URL-Pfade notwendig sind
\item \texttt{good.go}: Funktionen für das Hinzufügen von Waren zum Warenbestand
@ -117,7 +117,7 @@ Die Packages des Application Layers umfassen die Logik des Microservice Warenwir
\subsection{Persistant Layer}
Der Persitant Layer umfasst eine SQL-Lite-Datenbank, die im Cache gehalten wird. Die nachfolgende Abbildung \ref{pic:Datenbankmodell des Microservice} zeigt den grundsätzlichen Aufbau der Datenbank. Sie speichert den Warenbestand (stock) in Produkten (product). Jedes Produkt wird mit seiner ID und seinem Namen gehalten, die aus dem Produktkatalog bezogen und in einem Cache zwischengespeichert werden. Zu jedem Produkt gehören wiederum mehrere Waren (good), die eine ID, ein Ablaufdatum und eine Lagerposition besitzen. Dabei kann eine Ware nur zu einem Produkt gehören. Die Datenbank kann über die Konfigurationsdatei \texttt{config\_example.conf}, deren relevanter Ausschnitt nachfolgend dargestellt wird, flexibel angepasst werden.
Der Persitant Layer umfasst eine SQL-Lite-Datenbank, die im Cache gehalten wird. Die nachfolgende Abbildung \ref{pic:Datenbankmodell des Microservice} zeigt den grundsätzlichen Aufbau der Datenbank. Sie speichert den Warenbestand (stock) in Produkten (product). Jedes Produkt wird mit seiner ID und seinem Namen gehalten, die aus dem Produktkatalog bezogen und in einem Cache zwischengespeichert werden. Zu jedem Produkt gehören wiederum mehrere Waren (good), die eine ID, ein Ablaufdatum, eine Lagerposition und einen Kommentar besitzen. Dabei kann eine Ware nur zu einem Produkt gehören. Die Datenbank kann über die Konfigurationsdatei \texttt{config\_example.conf}, deren relevanter Ausschnitt nachfolgend dargestellt wird, flexibel angepasst werden.
\begin{lstlisting}[caption=Datenbankeinstellungen in der Konfigurationsdatei]
@ -131,7 +131,7 @@ connection = "file::memory:?mode=memory&cache=shared"
\begin{figure}[H]
\centering
\includegraphics[width=0.45 \textwidth]{./pics/db.pdf}
\includegraphics[width=0.40 \textwidth]{./pics/db.pdf}
\caption{Datenbankmodell des Microservice}
\label{pic:Datenbankmodell des Microservice}
\end{figure}
@ -139,7 +139,7 @@ connection = "file::memory:?mode=memory&cache=shared"
\newpage
\subsection{Integrierte Tests}
\label{subsec: Integrierte Test}
Neben bisherigen Packages, die bereits Whitebox-Tests umfassen, ist in dem Package \textbf{\texttt{test}} ein weiteres Go-File (\texttt{testRest.go}) enthalten. Dieses setzt einen Test des Webservers um, bei dem auf Testdaten eines Produktkataloges zurückgegriffen wird. Mit Hilfe der integrierten Tests kann in der hier beschriebenen Version eine Code-Coverage von 100\% erreicht werden, das heißt jedes Stück Code wird mindestens einmal zur Ausführung gebracht.
Neben den bisherigen Packages, die bereits Whitebox-Tests umfassen, ist in dem Package \textbf{\texttt{test}} ein weiteres Go-File (\texttt{testRest.go}) enthalten. Dieses setzt einen Test des Webservers um, bei dem auf Testdaten eines Produktkataloges zurückgegriffen wird. Mit Hilfe der integrierten Tests wird in der hier beschriebenen Version eine Code-Coverage von 100\% erreicht, das heißt jedes Stück Code wird mindestens einmal zur Ausführung gebracht.
\subsection{Anpassung des Monolithen}
\label{subsec: Anpassung des Monolithen}