Merge pull request 'chore: Add docs for coinflip' (!309) from docs/coinflip into main

Reviewed-on: #309
Reviewed-by: Constantin Simonis <constantin@simonis.lol>
Reviewed-by: Jan-Marlon Leibl <jleibl@proton.me>

projektdokumentation/Inhalt.tex

@@ -2,6 +2,8 @@
 \input{Inhalt/Einleitung}
 \input{Inhalt/Projektarchitektur}
 \input{Inhalt/CI}
+\input{Inhalt/Auth.tex}
 \input{Inhalt/Dice.tex}
 \input{Inhalt/Slots.tex}
-\input{Inhalt/Auth.tex}
+\input{Inhalt/Coinflip.tex}
+

projektdokumentation/Inhalt/Coinflip.tex

@@ -0,0 +1,39 @@
+\clearpage
+\section{Coinflip}
+
+\subsection{Was ist Coinflip?}
+Das Münzwurf-Spiel 'Coinflip' ist ein klassisches Glücksspiel, das in seiner digitalen Umsetzung den traditionellen Münzwurf simuliert. Das Spiel basiert auf dem einfachen Prinzip einer Münze mit zwei Seiten: Kopf und Zahl. Spieler setzen auf eine der beiden Seiten und haben eine 50\%-ige Gewinnchance. Die Einfachheit des Spiels macht es zu einem idealen Einstiegsspiel für neue Nutzer der Casino-Plattform.
+
+Im Gegensatz zu komplexeren Spielen wie Dice bietet Coinflip eine feste Gewinnwahrscheinlichkeit von 50\% und einen konstanten Multiplikator von 2x. Dies bedeutet, dass Spieler bei einem Gewinn ihren Einsatz verdoppeln, während sie bei einer Niederlage ihren gesamten Einsatz verlieren.
+
+\subsubsection{Zufallszahlengenerierung}
+Die Implementierung verwendet die Standardklasse java.util.Random zur Generierung des Münzwurfs. 
+Die Zufallsgenerierung erzeugt einen booleschen Wert, der anschließend einer der beiden Münzseiten zugeordnet wird. 
+Diese binäre Entscheidung gewährleistet die faire 50:50-Verteilung, die für ein authentisches Münzwurf-Erlebnis erforderlich ist.
+
+\subsubsection{Spielablauf und Datenfluss}
+
+Der Spielablauf von Coinflip folgt einem strukturierten Datenfluss zwischen Frontend und Backend. Der Controller empfängt die Spielanfrage mit folgenden Parametern:
+
+\begin{itemize}
+    \item \textbf{Einsatz:} Der gesetzte Münzbetrag.
+    \item \textbf{Gewählte Seite:} Die vom Spieler gewählte Münzseite (Kopf oder Zahl).
+\end{itemize}
+
+Nach dem Erhalt der Anfrage führt der Controller eine Guthabenprüfung durch. Bei ausreichendem Guthaben wird die Anfrage an die Service-Schicht weitergeleitet, andernfalls wird eine entsprechende Fehlermeldung zurückgegeben.
+
+Die Service-Klasse verarbeitet die Spiellogik in folgender Reihenfolge:
+\begin{enumerate}
+    \item Abbuchung des Einsatzes vom Spielerkonto.
+    \item Generierung des zufälligen Münzwurfs (Kopf oder Zahl).
+    \item Vergleich zwischen gewählter Seite und Wurfergebnis.
+    \item Bei einem Gewinn: Gutschrift des doppelten Einsatzes auf das Spielerkonto.
+    \item Rückgabe des Spielergebnisses an das Frontend.
+\end{enumerate}
+
+Das Spielergebnis wird strukturiert an das Frontend übermittelt und enthält:
+\begin{itemize}
+    \item Gewinnstatus (gewonnen/verloren)
+    \item Auszahlungsbetrag (bei Gewinn: 2x Einsatz)
+    \item Geworfene Münzseite
+\end{itemize}

projektdokumentation/Inhalt/Slots.tex

@@ -1,4 +1,3 @@
-\clearpage
 \section{Slots}
 
 \subsection{Was ist Slots?}
@@ -10,48 +9,48 @@ Zur Generierung der Walzenpositionen verwendet diese Implementierung die Standar
 \subsubsection{Symbole und Auszahlungen}
 Das Slots-Spiel verwendet verschiedene Symbole, die jeweils einen spezifischen Auszahlungsmultiplikator und eine bestimmte Häufigkeit auf den Walzenstreifen haben. Die Symbole sind:
 \begin{itemize}
-    \item \textbf{SEVEN:} Höchster Auszahlungsmultiplikator (\texttt{1000x}). Seltenstes Symbol auf den Walzen.
-    \item \textbf{BAR:} Hoher Auszahlungsmultiplikator (\texttt{85x}).
-    \item \textbf{BELL:} Mittlerer Auszahlungsmultiplikator (\texttt{40x}).
-    \item \textbf{CHERRY:} Niedriger Auszahlungsmultiplikator (\texttt{10x}). Häufiger auf den Walzen.
-    \item \textbf{BLANK:} Kein Auszahlungsmultiplikator (\texttt{0x}). Dient als Platzhalter und führt bei dreifachem Erscheinen zu keinem Gewinn.
+	\item \textbf{SEVEN:} Höchster Auszahlungsmultiplikator (\texttt{1000x}). Seltenstes Symbol auf den Walzen.
+	\item \textbf{BAR:} Hoher Auszahlungsmultiplikator (\texttt{85x}).
+	\item \textbf{BELL:} Mittlerer Auszahlungsmultiplikator (\texttt{40x}).
+	\item \textbf{CHERRY:} Niedriger Auszahlungsmultiplikator (\texttt{10x}). Häufiger auf den Walzen.
+	\item \textbf{BLANK:} Kein Auszahlungsmultiplikator (\texttt{0x}). Dient als Platzhalter und führt bei dreifachem Erscheinen zu keinem Gewinn.
 \end{itemize}
 Die genaue Verteilung der Symbole auf den Walzenstreifen (\texttt{REEL\_LENGTH = 32}) ist wie folgt:
 \begin{itemize}
-    \item SEVEN: 1 Vorkommen
-    \item BAR: 4 Vorkommen
-    \item BELL: 7 Vorkommen
-    \item CHERRY: 10 Vorkommen
-    \item BLANK: 10 Vorkommen
+	\item SEVEN: 1 Vorkommen
+	\item BAR: 4 Vorkommen
+	\item BELL: 7 Vorkommen
+	\item CHERRY: 10 Vorkommen
+	\item BLANK: 10 Vorkommen
 \end{itemize}
 
 \subsubsection{Spielablauf und Datenfluss}
 
 Der zentrale \texttt{SlotController} steuert den Spielablauf und empfängt die Anfragen vom Frontend. Jede Anfrage zum Drehen der Walzen (\texttt{/slots/spin}) enthält die Eckdaten des gewünschten Spins:
 \begin{itemize}
-    \item \textbf{Einsatz:} Der gesetzte Münzbetrag.
+	\item \textbf{Einsatz:} Der gesetzte Münzbetrag.
 \end{itemize}
 
 Zuerst prüft der Controller das Guthaben des Spielers. Bei unzureichenden Mitteln wird der Vorgang abgelehnt. Andernfalls übergibt er die weitere Ausführung an die Dienstklasse (\texttt{SlotService}).
 
 Die Dienstklasse (\texttt{SlotService}) übernimmt die eigentliche Logik des Slots-Spiels:
 \begin{enumerate}
-    \item Zieht den Einsatz vom Spielerkonto ab.
-    \item Generiert zufällige Startpositionen für jede der drei Walzen.
-    \item Ermittelt die Symbole auf der mittleren Gewinnlinie basierend auf den generierten Positionen.
-    \item Bestimmt den Status des Spins (\texttt{WIN}, \texttt{LOSE}, \texttt{BLANK}) basierend auf den ermittelten Symbolen:
-    \begin{itemize}
-        \item \texttt{WIN}: Alle drei Symbole auf der Gewinnlinie sind identisch und keines davon ist \texttt{BLANK}.
-        \item \texttt{BLANK}: Alle drei Symbole auf der Gewinnlinie sind identisch und es handelt sich um \texttt{BLANK}-Symbole. Dies führt zu keinem Gewinn.
-        \item \texttt{LOSE}: Die Symbole auf der Gewinnlinie sind nicht alle identisch.
-    \end{itemize}
-    \item Berechnet den Gewinnbetrag bei einem \texttt{WIN}-Status (Einsatz $\times$ Auszahlungsmultiplikator des Gewinnsymbols) und schreibt ihn dem Spielerkonto gut. Bei \texttt{LOSE} oder \texttt{BLANK} wird kein Betrag gutgeschrieben.
-    \item Erstellt eine 3x3-Matrix der sichtbaren Symbole auf den Walzen, zentriert um die Gewinnlinie.
+	\item Zieht den Einsatz vom Spielerkonto ab.
+	\item Generiert zufällige Startpositionen für jede der drei Walzen.
+	\item Ermittelt die Symbole auf der mittleren Gewinnlinie basierend auf den generierten Positionen.
+	\item Bestimmt den Status des Spins (\texttt{WIN}, \texttt{LOSE}, \texttt{BLANK}) basierend auf den ermittelten Symbolen:
+	      \begin{itemize}
+		      \item \texttt{WIN}: Alle drei Symbole auf der Gewinnlinie sind identisch und keines davon ist \texttt{BLANK}.
+		      \item \texttt{BLANK}: Alle drei Symbole auf der Gewinnlinie sind identisch und es handelt sich um \texttt{BLANK}-Symbole. Dies führt zu keinem Gewinn.
+		      \item \texttt{LOSE}: Die Symbole auf der Gewinnlinie sind nicht alle identisch.
+	      \end{itemize}
+	\item Berechnet den Gewinnbetrag bei einem \texttt{WIN}-Status (Einsatz $\times$ Auszahlungsmultiplikator des Gewinnsymbols) und schreibt ihn dem Spielerkonto gut. Bei \texttt{LOSE} oder \texttt{BLANK} wird kein Betrag gutgeschrieben.
+	\item Erstellt eine 3x3-Matrix der sichtbaren Symbole auf den Walzen, zentriert um die Gewinnlinie.
 \end{enumerate}
 
 Das Ergebnis des Spiels wird an das Frontend zurückgesendet und enthält:
 \begin{itemize}
-    \item \textbf{Status:} Der Status des Spins (\texttt{win}, \texttt{lose}, \texttt{blank}).
-    \item \textbf{Amount:} Der gewonnene Betrag (bei \texttt{WIN}) oder der Einsatz (bei \texttt{LOSE}/\texttt{BLANK}).
-    \item \textbf{Result Matrix:} Eine 3x3-Matrix der Symbole, die auf den Walzen sichtbar sind.
+	\item \textbf{Status:} Der Status des Spins (\texttt{win}, \texttt{lose}, \texttt{blank}).
+	\item \textbf{Amount:} Der gewonnene Betrag (bei \texttt{WIN}) oder der Einsatz (bei \texttt{LOSE}/\texttt{BLANK}).
+	\item \textbf{Result Matrix:} Eine 3x3-Matrix der Symbole, die auf den Walzen sichtbar sind.
 \end{itemize}