diff --git a/backend/build.gradle.kts b/backend/build.gradle.kts index 3704255..afb8f0b 100644 --- a/backend/build.gradle.kts +++ b/backend/build.gradle.kts @@ -50,7 +50,7 @@ dependencies { implementation("org.springframework.boot:spring-boot-starter-oauth2-resource-server:3.5.0") implementation("org.springframework.boot:spring-boot-starter-oauth2-client:3.5.0") runtimeOnly("org.postgresql:postgresql") - implementation("org.springdoc:springdoc-openapi-starter-webmvc-ui:2.8.8") + implementation("org.springdoc:springdoc-openapi-starter-webmvc-ui:2.8.9") implementation("io.jsonwebtoken:jjwt-api:0.12.6") runtimeOnly("io.jsonwebtoken:jjwt-impl:0.12.6") runtimeOnly("io.jsonwebtoken:jjwt-jackson:0.12.6") diff --git a/projektdokumentation/Abkuerzungen.tex b/projektdokumentation/Abkuerzungen.tex index ce8cfc6..b1979ea 100644 --- a/projektdokumentation/Abkuerzungen.tex +++ b/projektdokumentation/Abkuerzungen.tex @@ -13,10 +13,13 @@ % Die Option (in den eckigen Klammern) enthält das längste Label oder % einen Platzhalter der die Breite der linken Spalte bestimmt. \begin{acronym}[WWWWW] - %\acro{API}{Application Programming Interface} + \acro{API}{Application Programming Interface} + \acro{CI}{Continuous Integration} + \acro{CI/CD}{Continuous Integration/Continuous Deployment} \acro{CLI}{Command Line Interface} \acro{CRM}{Customer Relationship Management} \acro{CRON}{Vorgangsausführung gemäß geplanten Zeitabläufen für UNIX Programme} + \acro{E2E}{End-to-End} \acro{eCommerce}{Electronic Commerce} \acro{ERM}{Entity-Relationship-Model} \acro{GUI}{Graphical User Interface} diff --git a/projektdokumentation/Deckblatt.tex b/projektdokumentation/Deckblatt.tex index 6060837..51f3840 100644 --- a/projektdokumentation/Deckblatt.tex +++ b/projektdokumentation/Deckblatt.tex @@ -1,27 +1,27 @@ % !TEX root = Projektdokumentation.tex \begin{titlepage} -\begin{center} -\includegraphics[scale=0.25]{hitec-logo.png}\\[1ex] + \begin{center} + \includegraphics[scale=0.25]{hitec-logo.png}\\[1ex] -\Large{\ausbildungsberuf}\\ -\LARGE{\betreff}\\[4ex] + \Large{\ausbildungsberuf}\\ + \LARGE{\betreff}\\[4ex] -\huge{\textbf{\titel}}\\[1.5ex] -\Large{\textbf{\untertitel}}\\[4ex] + \huge{\textbf{\titel}}\\[1.5ex] + \Large{\textbf{\untertitel}}\\[4ex] -\normalsize -Projektzeitraum: \projektZeitraum\\[3em] -\textbf{Projektteilnehmer:}\\ -Constantin Simonis\\ -Phan Huy Tran\\ -Jan-Marlon Leibl\\ -Jan Klattenhoff\\ -Lea Ziemke\\ + \normalsize + Projektzeitraum: \projektZeitraum\\[3em] + \textbf{Projektteilnehmer:}\\ + Constantin Simonis\\ + Phan Huy Tran\\ + Jan-Marlon Leibl\\ + Jan Klattenhoff\\ + Lea Ziemke\\ -\textbf{Projektaufsicht:}\\ -Katrin Deeken\\ -Bernd Heidemann\\ -\end{center} + \textbf{Projektaufsicht:}\\ + Katrin Deeken\\ + Bernd Heidemann\\ + \end{center} -\end{titlepage} \ No newline at end of file +\end{titlepage} diff --git a/projektdokumentation/Inhalt.tex b/projektdokumentation/Inhalt.tex index 24267a0..b327d8e 100644 --- a/projektdokumentation/Inhalt.tex +++ b/projektdokumentation/Inhalt.tex @@ -1,2 +1,5 @@ % !TEX root = Projektdokumentation.tex -\input{Inhalt/Einleitung} \ No newline at end of file +\input{Inhalt/Einleitung} +\input{Inhalt/Projektarchitektur} +\input{Inhalt/CI} +\input{Inhalt/Dice.tex} diff --git a/projektdokumentation/Inhalt/CI.tex b/projektdokumentation/Inhalt/CI.tex new file mode 100644 index 0000000..340124d --- /dev/null +++ b/projektdokumentation/Inhalt/CI.tex @@ -0,0 +1,53 @@ +% !TEX root = ../Projektdokumentation.tex +\section{Continuous Integration} +\label{sec:CI} + +Das Projekt verwendet Gitea Actions\footnote{Gitea Actions - \url{https://docs.gitea.com/usage/actions/overview}} als \ac{CI/CD}-Pipeline, welche vollständig kompatibel mit GitHub Actions ist. +Entsprechend den Qualitätsanforderungen soll eine hohe Code-Qualität durch automatisierte Tests gewährleistet werden. + +\subsection{Aufbau der CI-Pipeline} +\label{sec:ci-pipeline} + +Die Haupt-\ac{CI}-Pipeline wird durch die Datei \Datei{ci.yml} definiert und bei Pull Requests ausgelöst. Aufgrund der separaten Frontend- und Backend-Komponenten +wurde eine \Fachbegriff{Change Detection} implementiert, welche nur relevante Tests für geänderte Bereiche ausführt. + +Ein initialer Job identifiziert geänderte Dateien und ermöglicht eine selektive Ausführung: +\begin{itemize} + \item Backend-Änderungen: \Datei{backend/**} + \item Frontend-Änderungen: \Datei{frontend/**} + \item Workflow-Änderungen: \Datei{.gitea/workflows/**} +\end{itemize} + +\subsubsection{Backend-Qualitätssicherung} +Für Backend-Änderungen werden folgende Prüfungen durchgeführt: +\begin{itemize} + \item \textbf{Unit Tests:} Ausführung mit \Eingabe{./gradlew test} in OpenJDK 23 Container + \item \textbf{Checkstyle:} Code-Style-Validierung mit Caching-Mechanismus + \item \textbf{Docker Build:} Überprüfung der Build-Funktionalität +\end{itemize} + +\subsubsection{Frontend-Qualitätssicherung} +Für Frontend-Änderungen wird eine umfassende Testsuite ausgeführt: +\begin{itemize} + \item \textbf{ESLint:} Code-Qualitätsprüfung mit \Eingabe{bun run lint} + \item \textbf{Prettier:} Code-Formatierungsvalidierung + \item \textbf{Build-Test:} Produktions-Build-Validierung mit \Eingabe{bun run build} + \item \textbf{Playwright \ac{E2E} Tests:} End-to-End-Tests mit automatischem Backend-Start + \item \textbf{Docker Build:} Validierung der Container-Erstellung +\end{itemize} + +\subsection{Release-Management} +\label{sec:release-pipeline} + +Das Release-Management erfolgt automatisiert durch die \Datei{release.yml} Pipeline bei Pushes auf den \texttt{main}-Branch. +Die Implementierung folgt \Fachbegriff{Semantic Versioning}\footnote{Semantic Versioning - \url{https://semver.org/}} und \Fachbegriff{Conventional Commits}\footnote{Conventional Commits - \url{https://www.conventionalcommits.org/}}. + +Die Release-Pipeline umfasst: +\begin{enumerate} + \item \textbf{Semantic Release:} Automatische Versionierung basierend auf Commit-Nachrichten + \item \textbf{Docker Image Build:} Parallele Erstellung von Backend- und Frontend-Images + \item \textbf{Registry Push:} Upload zur privaten Gitea Docker Registry +\end{enumerate} + +Die \ac{CI/CD}-Pipeline implementiert Performance-Optimierungen wie intelligentes Caching, Concurrency Control und selektive Job-Ausführung. +Diese Automatisierung gewährleistet eine hohe Software-Qualität bei effizienten Entwicklungsprozessen. diff --git a/projektdokumentation/Inhalt/Dice.tex b/projektdokumentation/Inhalt/Dice.tex new file mode 100644 index 0000000..fd346d6 --- /dev/null +++ b/projektdokumentation/Inhalt/Dice.tex @@ -0,0 +1,44 @@ +\clearpage +\section{Dice} + +\subsection{Was ist Dice?} +Das Würfelspiel 'Dice' ist ein originelles Spiel der Casinoplattform Stake.com\footnote{Stake.com ist eine bekannte Online-Glücksspielplattform, die eine Vielzahl von Casinospielen und Sportwetten anbietet.}. Das Spiel dreht sich um einen virtuellen 100-seitigen Würfel, +bei dem Spieler die Parameter ihrer Wette beeinflussen können. Im Kern geht es darum, +einen zuvor festgelegten 'Roll Over'- oder 'Roll Under'-Betrag zu unter- oder überschreiten, +um eine Runde zu gewinnen. Spieler haben die Kontrolle über den Multiplikator und ihre Gewinnchancen: +Durch die Anpassung des Zielwerts können sie das Verhältnis +von Risiko und potenzieller Auszahlung steuern. Ein höherer Multiplikator verspricht zwar größere Gewinne, +reduziert jedoch gleichzeitig die Wahrscheinlichkeit eines erfolgreichen Würfelwurfs. + +\subsubsection{Zufallszahlengenerierung} +Zur Generierung des Würfelwurfs verwendet diese Implementierung die Standardklasse java.util.Random. +Sie erzeugt eine pseudo-zufällige Zahl zwischen 1 und 100 (inklusive), +die das Ergebnis des virtuellen 100-seitigen Würfels darstellt. + + +\subsubsection{Spielablauf und Datenfluss} + +Der zentrale Controller steuert den Spielablauf und empfängt die Anfragen vom Frontend. Jede Anfrage enthält die Eckdaten des gewünschten Würfelwurfs: +\begin{itemize} + \item \textbf{Einsatz:} Der gesetzte Münzbetrag. + \item \textbf{Wettart:} Soll der Würfel ``über'' oder ``unter'' einen Wert fallen? + \item \textbf{Zielwert:} Der vom Spieler festgelegte Referenzwert (1-100). +\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. + +Die Dienstklasse übernimmt die eigentliche Logik des Würfelspiels: +\begin{enumerate} + \item Zieht den Einsatz vom Spielerkonto ab. + \item Erzeugt einen zufälligen Würfelwurf (Wert zwischen 1 und 100). + \item Prüft, ob der Wurf die Gewinnbedingung erfüllt (entsprechend Wettart und Zielwert). + \item Berechnet die Gewinnwahrscheinlichkeit und den sich daraus ergebenden Multiplikator. + \item Schreibt bei einem Gewinn den entsprechenden Betrag (Einsatz $\times$ Multiplikator) dem Spielerkonto gut. +\end{enumerate} + +Das Ergebnis des Spiels wird an das Frontend zurückgesendet und enthält: +\begin{itemize} + \item Gewinnstatus (gewonnen/verloren) + \item Auszahlungsbetrag + \item Gewürfelten Wert +\end{itemize} diff --git a/projektdokumentation/Inhalt/Projektarchitektur.tex b/projektdokumentation/Inhalt/Projektarchitektur.tex new file mode 100644 index 0000000..d560713 --- /dev/null +++ b/projektdokumentation/Inhalt/Projektarchitektur.tex @@ -0,0 +1,40 @@ +% !TEX root = ../Projektdokumentation.tex +\section{Projektarchitektur} +\label{sec:Projektarchitektur} + +\subsection{Überblick} +Das Casino Gaming Platform Projekt folgt einer klassischen Client-Server-Architektur mit einer klaren Trennung zwischen Frontend und Backend. Diese Architektur wurde gewählt, um eine saubere Separation of Concerns zu gewährleisten und die Wartbarkeit sowie Erweiterbarkeit des Systems zu fördern. Die Kommunikation zwischen den beiden Schichten erfolgt über REST-\acs{API}s, die \acs{JSON}-Daten austauschen. + +\subsection{Technologie-Stack} + +\subsubsection{Frontend-Technologien} +Für die Entwicklung der Benutzeroberfläche wurde Angular\footnote{Angular - \url{https://angular.io/}} als Framework gewählt. Angular bietet eine robuste Basis für Single Page Applications und ermöglicht eine komponentenbasierte Entwicklung. Als Package Manager kommt Bun\footnote{Bun - \url{https://bun.sh/}} zum Einsatz, welcher sowohl die Paketinstallation als auch das Bundling übernimmt. Für das Styling wird Tailwind CSS\footnote{Tailwind CSS - \url{https://tailwindcss.com/}} verwendet, welches eine konsistente und effiziente Gestaltung der Benutzeroberfläche ermöglicht. + +Für die Qualitätssicherung werden \acs{E2E}-Tests mit Playwright\footnote{Playwright - \url{https://playwright.dev/}} durchgeführt. Diese Tests stellen sicher, dass die gesamte Anwendung aus Benutzersicht korrekt funktioniert. + +\subsubsection{Backend-Technologien} +Das Backend basiert auf Spring Boot, einem Java-Framework, das eine schnelle Entwicklung von produktionsreifen Anwendungen ermöglicht. Spring Boot wurde gewählt, da es umfangreiche Funktionalitäten out-of-the-box bietet und sich durch eine starke Community-Unterstützung auszeichnet. Als Build-Tool kommt Gradle zum Einsatz, welches flexiblere Konfigurationsmöglichkeiten als Maven bietet. + +Für die Datenpersistierung wird PostgreSQL\footnote{PostgreSQL - \url{https://www.postgresql.org/}} verwendet. + +\subsection{Systemarchitektur} + +\subsubsection{Frontend-Architektur} +Das Frontend wurde als Single Page Application (SPA) konzipiert, um eine flüssige Benutzererfahrung zu gewährleisten. Die Architektur folgt Angulars modularem Ansatz und gliedert sich in verschiedene Bereiche: Feature-Module organisieren die Funktionalitäten nach Geschäftsbereichen wie Spiele und Einzahlungen. Wiederverwendbare UI-Komponenten wurden in einem Shared-Bereich zusammengefasst, um Code-Duplikation zu vermeiden. + +Services übernehmen die Kommunikation mit dem Backend und kapseln die Geschäftslogik. \acs{HTTP}-Interceptors behandeln globale Aspekte wie Fehlerbehandlung zentral. + +\subsubsection{Backend-Architektur} +Das Backend implementiert eine klassische mehrschichtige Architektur, die eine klare Trennung der Verantwortlichkeiten gewährleistet. Die Controller-Schicht stellt die REST-\acs{API}-Endpunkte bereit und behandelt \acs{HTTP}-Anfragen. Die Service-Schicht enthält die Geschäftslogik und orchestriert verschiedene Use Cases. + +Die Repository-Schicht abstrahiert den Datenzugriff und verwendet Spring Data JPA für die Kommunikation mit der Datenbank. Entity-Klassen repräsentieren die Domain-Modelle und bilden die Datenbankstrukturen ab. + +\subsection{Datenarchitektur} +Die Datenbank folgt einem relationalen Design mit klar definierten Entitätsbeziehungen. Das Schema gliedert sich in mehrere Hauptbereiche: Der User Management Bereich verwaltet Benutzerkonten und Benutzerprofile. Spielbezogene Daten wie Spielstände, Wetten und Ergebnisse werden in separaten Tabellen gespeichert, um die Integrität der Spiellogik zu gewährleisten. + +Der Financial Bereich behandelt alle monetären Transaktionen, Guthaben und Einzahlungen mit entsprechenden Audit-Trails für Compliance-Zwecke. Das Loot System verwaltet Lootboxen, deren Belohnungen und die zugehörigen Wahrscheinlichkeitsverteilungen, wobei besonderer Wert auf Transparenz und Fairness gelegt wird. + +\subsection{Deployment-Strategie} +Die Deployment-Strategie wurde so konzipiert, dass sie sowohl lokale Entwicklung als auch produktive Umgebungen unterstützt. Für die lokale Entwicklung wird Docker Compose\footnote{Docker Compose - \url{https://docs.docker.com/compose/}} eingesetzt, welches eine konsistente Entwicklungsumgebung über verschiedene Entwicklerrechner hinweg gewährleistet. + +Frontend und Backend können unabhängig voneinander gebaut und deployed werden, was eine flexible Entwicklung und Wartung ermöglicht. Diese Entkopplung erlaubt es verschiedenen Teams, parallel zu arbeiten, ohne sich gegenseitig zu blockieren. Verschiedene Umgebungskonfigurationen durch Profile stellen sicher, dass entwicklungs- und produktionsspezifische Einstellungen sauber getrennt sind und automatisiert angewendet werden können. \ No newline at end of file diff --git a/projektdokumentation/Projektdokumentation.pdf b/projektdokumentation/Projektdokumentation.pdf index 9081bf8..a3d1545 100644 Binary files a/projektdokumentation/Projektdokumentation.pdf and b/projektdokumentation/Projektdokumentation.pdf differ