Merge pull request 'docs: add slots docs' (!310) from docs-slots into main

Reviewed-on: #310
Reviewed-by: Constantin Simonis <constantin@simonis.lol>

projektdokumentation/Inhalt.tex

@@ -3,4 +3,5 @@
 \input{Inhalt/Projektarchitektur}
 \input{Inhalt/CI}
 \input{Inhalt/Dice.tex}
+\input{Inhalt/Slots.tex}
 \input{Inhalt/Auth.tex}

projektdokumentation/Inhalt/Slots.tex

@@ -0,0 +1,57 @@
+\clearpage
+\section{Slots}
+
+\subsection{Was ist Slots?}
+Das Spiel 'Slots' ist eine digitale Implementierung eines klassischen Spielautomaten. Spieler setzen einen Betrag und drehen die Walzen, um Kombinationen von Symbolen zu erhalten. Ziel ist es, drei gleiche Symbole auf der mittleren Gewinnlinie zu erzielen, um einen Gewinn basierend auf dem Multiplikator des Symbols zu erhalten. Das Spiel bietet eine einfache und intuitive Möglichkeit, Glücksspiel zu erleben.
+
+\subsubsection{Zufallszahlengenerierung}
+Zur Generierung der Walzenpositionen verwendet diese Implementierung die Standardklasse \texttt{java.util.Random}. Für jede der drei Walzen wird eine pseudo-zufällige Zahl zwischen 0 und der \texttt{REEL\_LENGTH} (32) generiert. Diese Zahlen bestimmen die Startposition jedes Walzenstreifens. Die Walzenstreifen selbst werden bei der Initialisierung des \texttt{SlotService} einmalig erstellt und dann zufällig gemischt, um eine faire Verteilung der Symbole zu gewährleisten.
+
+\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.
+\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
+\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.
+\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.
+\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.
+\end{itemize}