HSWO_BSC_BACHELORS_THESIS/chapters/konzeption-entwicklung.tex

\chapter{Umsetzung}
\label{chap:umsetzung}
Infolge der Anforderungsanalyse befasst sich das Kapitel \enquote{Umsetzung} mit der Implementation der Anforderungen in dem
Brown-Field Projekt \cite{bib:schwarzer-vorlesung-swa} in Form einer TYPO3-Extension.

\section{Setup einer TYPO3-Extension}
TYPO3-Extension werden via Composer installiert \cite{bib:typo3-docs-managing-extensions}.
Um eine TYPO3-Extension zu erstellen muss also ein Composer-Paket erstellt werden.
Um vermeidbare Komplexität zu verhindern wird das Composer-Paket das eine die hier betrachtete
TYPO3-Extension darstellt, lokal in den versionierten Ordner \enquote{packages} gelegt.
Dieses Verzeichnis wird als Quelle für Composer-Pakete in der
Haupt-composer.json-Datei hinterlegt.
Somit wird ein Composer-Paket nur für dieses Projekt bereitgestellt,
ohne den Aufwand, der mit dem Bereitstellen eines Paketes einhergeht, zu haben.
\\
\\
Um das grundlegende Setup einer Extension effizient durchzuführen wurde eine
existierende Extension vergleichbarem Funktionsumfanges kopiert, umbenannt, und eingefügt.
Spezifisch ist der \enquote{vergleichbare Funktionsumfang}, dass es Datenmodelle und Plugins
gibt.

\section{Digitization}
Die Phase der Digitazion befasst sich mit der digitalen Abbildung von Objekten der realen Welt
in einer Art und Weise sodass diese elektronisch weiterverarbeitet werden können \cite{bib:dougherty, bib:loebbecke}.
Das bedeutet, dass in diese Phase Datenobjekte definiert und implementiert werden.
Ein Datenobjekt besteht nach firmeninternen Konventionen aus zumindest
vier Komponenten:
\begin{description}
  \item{Datenbanktabelle} \\
    Die Datenbanktabelle persistiert Informationen.
  \item{Domain Model} \\
    Das Domain Model (auch Model genannt) ist eine PHP-Klasse,
    die jeweils die Daten einer Zeile der Datenbanktabelle abbildet.
  \item{Repository} \\
    Ein Repository ist eine PHP-Klasse, die die Schnittstelle
    zwischen der Datenbank und der Model-Klasse darstellt.
  \item{\ac{TCA}} \\
    Der \ac{TCA} des Modells definiert, wie diese Objekte im TYPO3-Backend dargestellt werden
    und bearbeitbar sind.
\end{description}
\cite{bib:typo3-docs-extbase-reference}.

Im Folgenden wurde ein semiformales Diagramm der Objekte und ihren Relationen nach dem
Pflichtenheft angefertigt und in Rücksprache mit dem \ac{PO} finalisiert.

\begin{nicepic}
    \includegraphics[width=1\textwidth]{images/objektrelationen-weinlandmosel-einlieferungswerkzeug.png}
    \captionof{figure}{Objektrelationen}
    \caption*{Quelle: Eigene Darstellung}
    \label{fig:objektrelationen}
\end{nicepic}

Nachdem in Erfahrung gebracht wurde, welche konkreten Datenobjekte benötigt werden,
wurden Attribute dieser Objekte dem Pflichtenheft entnommen. Diese wurden in einem
formalen Klassendiagramm festgehalten und in Rücksprache mit dem \ac{PO}
weiter bis zu festen Datentypen und Auswahlmöglichkeiten konkretisiert.
Beispielsweise, dass Wettbewerbskategorien durch TYPO3-Categories repräsentiert werden sollen.
Das hat den Vorteil, dass TYPO3-Categories bereits native Bestandteile eines TYPO3-Redaktionssystemes sind
und bereits alle relevanten Attribute anbieten. Diese sind ein Titel,
eine Parentkategorie und eine Beschreibung.
Das Parent-Attribut ist benötigt, da $n$ dieser Attribute einen Attributbaum bilden
\cite{bib:typo3-docs-sys-category}.
Somit ist es möglich Unterkategorien zu erstellen. Beispiele hierfür sind die
Unterkategorien \enquote{Trockener Riesling} und \enquote{Halbtrockener Riesling} für die Überkategorie
\enquote{Riesling}.
Rebsorten, Geschmack, Weineigenschaften und Qualität sollen eigene Datentypen
anstatt einfacher Zeichenfolgen sein.
Ziel davon ist, dass sich Nutzer für einen vorgefertigten, nominalen Eintrag in einem Dropdown-Menü
entscheiden müssen und diese Auswahlmöglichkeiten immer noch im TYPO3-Backend pflegbar sind.
Weinlagen sind im Brown-Field-Projekt bereits vorhanden, also sollen hierfür existierenden Daten
eingebunden werden.
Pro Wein sollen beliebig viele Weineigenschaften auswählbar sein, Wettbewerbskategorien,
Geschmacksrichtung, etc, jeweils nur ein Element.
Weitere Notizen zu diesem Gespräch sind im Anhang unter \fullref{chap:anhang-notizen-digitization}
zu finden.
\\
\\
Da das Klassendiagramm gegeben lesbare Schrift nicht auf eine Textseite passt,
befindet es sich vollseitig im Anhang unter \fullref{chap:anhang-class-diagram}.
Die weitere Implementation der Datenobjekte ist unkompliziert und besteht hauptsächlich aus
repetitivem Schreiben von SQL-Tabellen, Domain-Model-Klassen und \acp{TCA}.
Um $m,n$-Beziehungen wie Beispielsweise der Menge der für eine Probe zugelassenen Kategorien
\enquote{allowedCategories} zwischen $m$ \enquote{Jahresauswahlprobe}-Objekten und
$n$ \enquote{Category}-Objekten zu ermöglichen, werden MM-Tabellen (many-to-many) benötigt,
diese Beziehungen in Form zweier Foreign Keys speichern.
Die Repository-Klassen können \enquote{leer} gelassen werden,
da zu diesem Zeitpunkt keine erweiterte Auswahllogik für Datenbankanfragen benötigt wird.
Wichtig ist hierbei, dass eine Repository-Klasse existiert. Alle unverzichtbaren
Schnittstellen werden über die Basisklasse \enquote{Repository} geerbt
\cite{bib:typo3-docs-extdev-tut-tea-repositories}.
Mit Abschluss der Digitization können alle Datenstrukturen im TYPO3-Backend händisch angelegt,
eingesehen, gelöscht und bearbeitet werden.


\section{Teilnehmerregistrierung}
Ein essenzieller Teil des Jahresauswahlprobenwerkzeuges ist die Registrierung von Teilnehmern.
Dieses Modul repräsentiert den ersten Berührungspunkt der Winzer mit dem System.
Dem Pflichtenheft ist zu entnehmen, dass es zwei Kategorien von Teilnehmerregistrierungen gibt:
\begin{enumerate}
  \item Nutzer ist \ac{WM}-Mitglied
  \item Nutzer ist kein \ac{WM}-Mitglied
\end{enumerate}
Der primäre Unterschied zwischen Mitgliedern und Nicht-Mitgliedern ist, dass Mitglieder bereits einen
Stammdatensatz hinterlegt haben.
Dieser Stammdatensatz bildet die Angaben zum Weingut des zu digitalisierendem Anmeldeformulares ab.
Nicht-Mitglieder sind dem System noch gänzlich unbekannt und müssen im Zuge der Registrierung ihres Nutzers
ihre Stammdaten angeben, während sich Mitglieder lediglich einloggen müssen und eine Schaltfläche
\enquote{Teilnehmer werden} betätigen.
Der mit dem \ac{PO} ausgearbeitete UX-Flow der Registrierung sieht vor, dass der Nutzer zunächst gefragt wird,
ob er Mitglied sei oder nicht. Hierzu gibt es je einen Button. Ist der Nutzer ein Mitglied,
wird er auf ein Loginform, mit der Option zur Registrierung weitergeleitet.
Nach erfolgreichem Login, wird ein Teilnehmerobjekt erstellt.
Wählt der Nutzer \enquote{Nein, ich bin kein Mitglied} aus, würde er auf ein Registrierungsformular
weitergeleitet, auf um sich einen Nicht-Mitgliederaccount anzulegen. Im Zuge dieser Registrierung werden
Stammdaten zum Weingut angefragt.

\begin{nicepic}
    \includegraphics[width=0.9\textwidth]{images/ux-flow-registrierung.png}
    \captionof{figure}{UX-Flow: Registrierung}
    \caption*{Quelle: Eigene Darstellung}
    \label{fig:uxflow-registrierung}
\end{nicepic}

Da das Brown-Field-Projekt bereits Accountlogins und -Registrierungen implementiert und nutzt,
werden auf diese Lösungen zurückgegriffen, um einen einheitlichen Workflow beizubehalten. Accountregistrierungen werden über den
\enquote{femanager} \cite{bib:typo3-docs-femanager} realisiert, während Logins via TYPO3's nativem
Frontend-Nutzer-Login gelöst werden. Das ist explizit von femanager so angedacht:
\quotecite{Note: Login and a I forgot my password function is part of the core and not part of femanager.}
\cite{bib:typo3-docs-femanager}.

Im Folgenden wird der Registrierungsprozess im Detail beschrieben:\\
Grundlegend gibt es drei relevante Nutzerzustände vor der Registrierung:
\begin{enumerate}
  \item Kein Mitglied
  \item Mitglied, mit Konto
  \item Mitglied, ohne Konto
\end{enumerate}

Diese Prozesse sehen wie folgt aus:
\subsection*{Kein Mitglied}
Ist ein Nutzer kein Mitglied, so muss er zunächst einen Account erstellen.
Anfangs wählt dieser Nutzer \enquote{Ich bin kein Mitglied} auf der Registrierungsseite aus.
Daraufhin navigiert der Browser zu einem Registrierungs-Formular.
Hierfür muss eine Email-Adresse und ein Passwort vergeben und den Nutzungsbestimmungen zugestimmt werden.
Im Anschluss erhält der Nutzer eine Bestätigungsemail mit einem Aktivierungslink.
Wird dieser Link geöffnet, wird der Account freigeschalten und ein Login-Feld erscheint.
Nach erfolgreichem Login wird der Nutzer mit einem
Stammdatenformular konfrontiert. Dabei handelt es sich um Angaben zum teilnehmenden Weingut.
Wird dieses Formular abgeschickt, ist die Teilnehmerregistrierung abgeschlossen.

\subsection*{Mitglied, mit Konto}
Ist ein Nutzer ein Mitglied und hat bereits ein Mitgliedskonto, muss dieser auf der Registrierungsseite
\enquote{Ich bin ein Mitglied} auswählen. An dieser Stelle navigiert der Browser zu einem Login-Formular.
Hier kann sich das Mitglied nun anmelden. Tut er dies erfolgreich, ist die Teilnehmerregistrierung
abgeschlossen.

\subsection*{Mitglied, ohne Konto}
Ist ein Nutzer ein Mitglied und hat noch kein Mitgliedskonto, muss dieser auf der Registrierungsseite
\enquote{Ich bin ein Mitglied} auswählen. An dieser Stelle navigiert der Browser zu einem Login-Formular.
Auf diesem Login-Formular existiert ein Button \enquote{Jetzt registrieren}, sowie ein Hinsweistext dazu.
Da der Nutzer noch keinen Account hat, muss dieser auf \enquote{Jetzt registrieren} klicken.
Daraufhin navigiert der Browser zu einem Registrierungsformular, das eine Email-Adresse, ein Passwort
und die Zustimmung zur Datenverarbeitung benötigt. Ist dieses Formular abgeschickt, erhält das Mitglied
eine Email mit einem Bestätigungslink. Wird dieser Bestätigungslink angeklickt, wird das Mitgliedskonto
freigegeben und es öffnet sich ein Login-Formular.
Nach erfolgreichem Login wird das Mitgliedskonto um die notwendingen Teilnehmereigenschaften erweitert
und ist somit erfolgreich als Teilnehmer registriert.

\subsection*{Umsetzung}
Um das umzusetzen wurde zunächst ein simples Weichen-Content-Element erstellt.
Dieses Content-Element hat die Parameter \enquote{question}, \enquote{answ-1-link}, \enquote{answ-1-text},
\enquote{answ-2-link} sowie \enquote{answ-2-text}.
Der Zweck dieses Content-Elementes ist es, Nutzer basierend auf einer ausformilierten Frage auf eine
von zwei Seiten weiterzuleiten. Anschließend wurden Registrierungen über Femanager-Plugin-Content-Elemente
realisiert.
Anpassungen der versendeten Emails erfolgen durch Überschreiben der Email-Templates von Femanager.
Weiterleitungen zu bestimmten Seiten nachdem ein Nutzer spezielle Events ausgelöst hat können über TypoScript
konfiguriert werden \cite{bib:typo3-docs-femanager}. Logins werden über das TYPO3-Native Loginformular
gelöst. Im TYPO3-Loginformular kann man Weiterleitungen zu spezialisierten Seiten im Backend-UI festlegen
\cite{bib:typo3-docs-felogin}.
Für alle funktionalen Belange wurde ein TYPO3-Plugin registriert. Dieses Plugin verfügt über einen
ActionController, der Nutzeranfragen an PHP-Funktionen (\enquote{Actions})
bindet.
In diesen Actions wird Fehlerbehandlung durchgeführt, Datenmodelle der Domäne erstellt und in der
Datenbank persistiert sowie Daten für die Anzeige im Frontend aufbereitet \cite{bib:typo3-docs-extbase}.
Neue Datenobjekte werden in Repositories registriert \cite{bib:typo3-docs-extdev-tut-tea-repositories}. Diese Repositories sind Aggregate des Controllers,
werden jedoch nach dem \enquote{Inversion of Control}-Prinzip via Dependency Injection instanziiert und
der ActionController-Klasse über Methode übergeben \cite{bib:typo3-docs-di}.
Als problematisch erweisen sich bidirektionale Verbindungen zwischen Datenmodellen, wenn die Foreign Keys
über das SQL-Schlüsselwort \enquote{AUTO\_INCREMENT} in der Datenbank definiert werden.
In diesem Fall wollen wir
einen MasterRecord, der Betriebsinformationen speichert, bidirektional an ein Teilnehmerobjekt linken.
Als ForeignKeys werden hierfür ihre jeweiligen Uids herangezogen, da diese Werte durch
\enquote{AUTO\_INCREMENT} auf der Datenbankebene gehandhabt werden.
Es gilt also, dass ein MasterRecord $a$ die TeilnehmerUid von einem Teilnehmer $b$ hält und dass
$b$ die MasterRecordUid von $a$ hält.
Die Problematik hierbei ist, dass diese Uids erst nach dem persistieren in der Datenbank bekannt sind,
da diese Werte erst im Zuge der Persistierung erstellt werden. Das ist so, da das
\enquote{AUTO\_INCREMENT}-Schlüsselwort lediglich zu SQL gehört und SQL nur von der Datenbank ausgeführt wird.
Die Lösung hierfür ist es, beide Elemente zu erstellen und zu persistieren, danach ihre Uids gegenseitig
bekannt machen um sie danach erneut zu persistieren.