Umstellung automatische Nummerierung

Diplomarbeitsbuch-individueller-teil-Konstantin-Hintermayer.md

@@ -1,10 +1,10 @@
 # Konstantin Hintermayer
 
-## 1. Einleitung des individuellen Teils
+## Einleitung des individuellen Teils
 
 In diesem Abschnitt wird meine persönliche Aufgabenstellung im Rahmen des Projektes (`Alumnihub`) beschrieben.
 
-### 1.1 Auftrag / persönliche Aufgabenstellungen
+### Auftrag / persönliche Aufgabenstellungen
 
 Meine Zuständigkeiten und Verantwortlichkeiten:
 
@@ -14,28 +14,28 @@ Meine Zuständigkeiten und Verantwortlichkeiten:
 - Auswertungen
 - Schwarzes Brett
 
-### 1.2 Motivation
+### Motivation
 
 Gegenstand der Diplomarbeit ist die Entwicklung modularer Webanwendungen mit Blazor und Oqtane. Aufbauend auf fundierten Kenntnissen in der Fullstack-Entwicklung (React, Node.js, Golang), welche privat bei diversen Projekten gesammelt worden sind, fokussiert sich die Arbeit auf die Architekturvorteile des .NET-Stacks. Besonders im Fokus stehen die Konsistenz durch statische Typisierung sowie das Zusammenspiel modularer Komponenten in verteilten Systemen.
 
 Mein Untersuchungsanliegen: Inwieweit optimiert die Integration von Blazor und dem Oqtane-Framework die Konsistenz und Wartbarkeit modularer Web-Architekturen im Vergleich zu den für mich gewohnten Technologie-Stacks (React/Node.js)?
 
-## 2. Anforderungen an das entwickelte Modul bzw. die Funktionalität
+## Anforderungen an das entwickelte Modul bzw. die Funktionalität
 
-### 2.1 Modulanforderungen / funktionale Anforderungen
+### Modulanforderungen / funktionale Anforderungen
 
-### 2.2 Infrastrukturanforderungen / nicht‑funktionale Anforderungen
+### Infrastrukturanforderungen / nicht‑funktionale Anforderungen
 
 - funktionale / nicht‑funktionale Anforderungen
 - Use Cases
 
-## 3. Technisches Umfeld
+## Technisches Umfeld
 
 Mein Aufgabenbereich umfasst einerseits die Entwicklung eigener Module, sowie das Bereitstellen des Services.
 
-### 3.1 Auswahlverfahren
+### Auswahlverfahren
 
-#### 3.1.1 Entscheidungsfindung CMS
+#### Entscheidungsfindung CMS
 
 Auch steht die Wahl der Programmiersprache und des CMS an. Nachdem wir im Unterricht fast ausschließlich mit C# entwickelt haben und nicht in eine komplett unbekannte Entwicklungsumgebung abdriften wollten, haben wir uns für die Webentwicklung mit ASP.NET Core 9 (Upgrade im Lauf der Diplomarbeit auf .NET Core 10) und dem CMS Oqtane entschieden. Auch hier gab es einige Kandidaten:
 
@@ -50,7 +50,7 @@ Auch steht die Wahl der Programmiersprache und des CMS an. Nachdem wir im Unterr
 
 Insbesondere aufgrund seiner sehr hohen Flexibilität, haben wir uns am Ende für Oqtane entschieden.
 
-#### 3.1.2 Entscheidungsfindung restliche Infrastruktur
+#### Entscheidungsfindung restliche Infrastruktur
 
 Als Betriebssystem habe ich mich für Linux entschieden, einfach, da ich mit Linux im Serverumfeld die meisten und besten Erfahrungen gemacht habe.
 
@@ -62,7 +62,7 @@ Im Bereich der Datenbanken musste ich mir ein paar Fragen stellen:
 
 Es war von Anfang an klar, dass es ein SQL-basiertes System wird, da wir im Team nur mit SQL-basierten Systemen Erfahrungen haben. Außerdem unterstützt unser CMS (Oqtane) nur SQL-basierte Systeme. In der Linuxwelt kommen jetzt nur noch ein paar Datenbankmanagementsysteme in die Auswahl: PostgreSQL, MySQL / MariaDB, SQLite. Da ist die Wahl auf PostgreSQL gefallen. Grund dafür war meine Vorerfahrung mit diesem Datenbankmanagementsystem, welche ich in meinem Nebenjob erlangt habe.
 
-### 3.2 Beschreibung und Architektur von Oqtane
+### Beschreibung und Architektur von Oqtane
 
 Oqtane ist ein Framework und CMS zur Entwicklung von Webseiten mithilfe von ASP.NET und Blazor. [@oqtane_about] Ein Oqtane-System besteht aus mehreren Komponenten.
 
@@ -70,7 +70,7 @@ In dieser Diplomarbeit fokussieren wir uns hauptsächlich auf `Themes` und `Modu
 
 Ein `Module` (Modul) soll neue Funktionalitäten in das CMS hinzufügen und ein `Theme` soll die ganze Gestaltung der Webseite (die Shell) festlegen. [@oqtane_docs_extensions]
 
-#### 3.2.1 Architektur eines Moduls
+#### Architektur eines Moduls
 
 Ein Modul in Oqtane besteht aus vier Projekten:
 
@@ -84,7 +84,7 @@ Ein Modul in Oqtane besteht aus vier Projekten:
   - Beim Debug werden die DLLs, PDBs und statischen Assets wie Skripte und Stylesheets der drei anderen Projekte in den bereits gebauten Oqtane.Server `oqtane.framework/oqtane.server/bin/debug/net10.0/...` kopiert.
   - Beim Release wird ein NuGet-Paket erstellt und unter oqtane.framework/oqtane.server/Packages abgelegt. Dort abgelegte NuGet-Pakete werden beim nächsten Start des Oqtane Servers installiert (Datenbank Migrationen werden gemacht und die Pakete entpackt).
 
-### 3.3 Zusammenspiel der Infrastruktur
+### Zusammenspiel der Infrastruktur
 
 In diesem Kapitel erkläre ich wie die ausgewählten Komponenten zusammenspielen. Wir verwenden NginX als Reverse Proxy, welcher bei uns die SSL Terminierung macht. Das Zertifikat, welches verwendet wird, wird von Let's Encrypt bereit gestellt und mittels HTTP-Challenges und dem Certbot auf dem Server aktualisiert und verwaltet. Oqtane selber läuft als Systemd-Service im Kestrel Backend. Kestrel ist ein kleiner Webserver, welcher in das ASP.NET Core Framework eingebaut worden ist. Oqtane (bzw. der ASP.NET Core Server "Kestrel") hört auf der Loopback IP und Port 5000. Damit ist Oqtane nur durch NginX erreichbar. PostgreSQL ist die Datenbank in dem System: Sie hört wieder auf der Loopback IP und Port 5432. In der folgenden Grafik ist das System Schematisch dargestellt.
 
@@ -113,9 +113,9 @@ Zusätzlich gab es einen Administrationszugang zu den Servern, welcher über SSH
 
 Die VPN basierten Zugänge sind tendenziell schwieriger zu finden und auszunutzen, während die Lösung in der Schule mittels Highport den SSH Service öffentlich erreichbar macht. Durch den `Highport` ist der SSH Service schwieriger zu finden. Zur Authentifizierung mit SSH verwenden wir SSH-Keys, da diese durch ihre komplexität sicherer sind, als Passwörter.
 
-### 3.4 Entwicklung mit ASP.NET
+### Entwicklung mit ASP.NET
 
-#### 3.4.1 Blazor [@wikipedia_blazor]
+#### Blazor [@wikipedia_blazor]
 
 Blazor ist ein kostenloses und quelloffenes Web-Framework, welches es möglich macht Benutzeroberflächen für Web-Browser, basierend auf C# und HTML, zu erstellen. Es wird von Microsoft als teil des ASP.NET Core Frameworks entwickelt.
 
@@ -158,11 +158,11 @@ Razor hat auch eine Reihe an Keywords, wie zum Beispiel (nur Auszugsweise, bzw.
 - foreach: Für Wiederholungen im Markup
 - if: Für Verzweigungen im Markup
 
-#### 3.4.2 Kommunikation zwischen Front- und Backend
+#### Kommunikation zwischen Front- und Backend
 
 Wie Front- und Backend miteinander interagieren hängt hauptsächlich vom Render-Modus ab. Oqtane kann auf verschiedene Arten betrieben werden. Hierbei ist es dem Modulentwickler ziemlich egal, welche Art der Kommunikation (WebSockets, HTTP Long-Polling, REST) verwendet wird. SignalR ist eine Library aus dem ASP.NET Framework, welche es möglich macht, Server zu Client Kommunikation zu betreiben. Oqtane verwendet SignalR im `Interactive Server (SignalR)` Render-Modus.
 
-### 3.5 Dependency Injection
+### Dependency Injection
 
 Dependency Injection ist ein Entwurfsmuster, bei dem die Abhängigkeiten eines Objekts nicht von diesem selbst erzeugt, sondern von außen „injiziert“ werden.
 
@@ -170,7 +170,7 @@ Wie der Software-Architekt Martin Fowler, der den Begriff im Jahr 2004 maßgebli
 
 In den folgenden beiden Kapiteln wird das Dependency Inversion Principle und das Microsoft Dependency Injection Framework genauer vorgestellt.
 
-#### 3.5.1 Dependency Inversion Principle [@ms_dependency_inversion][@logrocket_dependency_inversion]
+#### Dependency Inversion Principle [@ms_dependency_inversion][@logrocket_dependency_inversion]
 
 Das Dependency-Inversion-Principle (DIP / auf Deutsch: Abhängigkeits-Umkehr-Prinzip) ist eines von den fünf `SOLID` Prinzipien in der Softwareentwicklung.
 
@@ -204,7 +204,7 @@ architecture-beta
 
 Das High-Level-Modul ruft lediglich eine Abstraktion eines Low-Level-Moduls auf, welche von einem, oder mehreren Low-Level-Modulen implementiert wurde. Für das High-Level-Modul ist es hier egal, welches Low-Level-Modul die Implementierung bereitstellt. Dadurch erhält man einen viel modulareren Aufbau in der Software. Die einzelnen Module sind auch leichter austauschbar und testbar. Genau diese Modularität macht Dependency Injection möglich.
 
-#### 3.5.2 Microsoft Dependency Injection Framework
+#### Microsoft Dependency Injection Framework
 
 Dependency Injection ist in .NET genau so wie Konfiguration, Protokollierung und das Optionsmuster ins Framework integriert. [@ms_di_overview]
 
@@ -270,7 +270,7 @@ architecture-beta
 
 ```
 
-### 3.6 Continuous Integration
+### Continuous Integration
 
 Gitea, das Versionskontrollsystem dieser Diplomarbeit, hat einen Continuous-Integration-System eingebaut. Im Kern ist es baugleich zu den GitHub-Pipelines. Man kann im `.gitea/workflow` Ordner `.yml` Dateien ablegen, welche dann das Verhalten der Workflows definieren.
 
@@ -290,17 +290,17 @@ Anwendungen von Gitea Actions bei dieser Diplomarbeit:
 - PM Repository:
   > Zum automatischen Überprüfen der Dokumente, unter anderem, mithilfe von KI, wie zum Beispiel Gemini.
 
-### 3.7 Debian Paket
+### Debian Paket
 
 TODO
 
-## 4 Projektmanagement & Tools
+## Projektmanagement & Tools
 
-### 4.1 Scrum
+### Scrum
 
-### 4.2 YouTrack
+### YouTrack
 
-### 4.3 Git
+### Git
 
 Git fungierte im Rahmen dieser Diplomarbeit als zentrales Werkzeug zur Versionskontrolle und Koordination sämtlicher Entwicklungsschritte. Die wichtigste Komponente stellt dabei der Commit dar, welcher als eindeutiger Snapshot des Projektzustands dient und über eine spezifische Commit-SHA (Secure Hash Algorithm) referenziert werden kann. Um eine lückenlose Nachvollziehbarkeit zu gewährleisten, wurde für jeden abgeschlossenen Arbeitsschritt ein eigener Commit erstellt.
 
@@ -318,7 +318,7 @@ Sobald eine Änderung erfolgreich getestet wurde, wird sie durch einen Merge wie
 
 Für die Sicherung und Zusammenarbeit wurde im Rahmen dieser Arbeit Remote-Repositories auf einer Gitea Instanz verwendet. Durch die Befehle push und pull wird der lokale Stand mit dem Server synchronisiert. Dies gewährleistet eine konsistente Datenbasis und dient gleichzeitig als kontinuierliches Backup des Projektfortschritts.
 
-### 4.4 Gitea
+### Gitea
 
 Als schlanke und selbst gehostete Open-Source-Alternative zu Plattformen wie GitHub oder GitLab wurde für die Verwaltung der Repositories Gitea eingesetzt. Hauptgrund für die Benutzung von Gitea war meine bereits aufgesetzte Instanz, welche schon mehrere Jahre in Verwendung war und mit der es im Team auch schon Erfahrungen gab. Gitea bietet neben der reinen Git-Verwaltung essenzielle Werkzeuge für den Software-Lebenszyklus, wie ein integriertes Issue-Tracking, Code-Reviews über Pull-Requests sowie eine Benutzerverwaltung, und unterstützt somit die strukturierte Umsetzung der Diplomarbeit im Team.[@gitea_docs]
 
@@ -346,11 +346,11 @@ Gitea Actions wurden eingesetzt, um CI/CD-Pipelines (Continuous Integration / Co
 
 Gitea fungierte zusätzlich als Register für Pakete und Container-Images. Selbst erstellte Artefakte, wie das Debian Paket für die Bereitstellung der Anwendung, wurden direkt in der Gitea-Instanz versioniert gespeichert. Dadurch waren alle notwendigen Komponenten für das Deployment an einem zentralen Ort verfügbar und abrufbar. Gitea selbst unterstützt verschiedenste Pakettypen. Darunter fallen unteranderem NuGet- und Debianpakete. Für beide haben wir in dieser Arbeit verwendung gefunden. [@gitea_docs][@gitea_packages]
 
-### 4.5 Kommunikation
+### Kommunikation
 
-## 5 Module
+## Module
 
-### 5.1 Admin Modules
+### Admin Modules
 
 Eine C#-Solution, welche einige Module, welche für den Admineinsatz geschrieben worden sind beinhaltet. Dieses Modul besteht aus 3 Teilmodulen. Einem Modul für den Versand von Rundmails, eines für die Einstellung von der Token Lebenszeit bei Tokens, welche per E-Mail verschickt werden und eines, welches das Reporting-System übernimmt.
 
@@ -419,7 +419,7 @@ Die Implementierung des IReportingComponents stellt nur eine Property (`ReportTy
 
 Die Bereitstellung des Moduls geschieht im `AdminModules` Modul.
 
-### 5.2 Event Registration
+### Event Registration
 
 Dieses Modul ermöglicht es Administratoren und Absolventen, Veranstaltungen zu erstellen, auf der Seite zu veröffentlichen und zu verwalten, während Mitglieder ihre Teilnahme direkt über das Portal bestätigen oder absagen können. Dieses Modul dient der organisatorischen Unterstützung von Absolvententreffen und anderen Vereinsaktivitäten. Dieses Modul wurde gemeinsam mit Adam Gaiswinkler geschrieben, wobei er sich um die Darstellung der Events im Frontend gekümmert hat, während ich mich der Infrastruktur im Hintergrund angenommen habe.
 
@@ -443,7 +443,7 @@ Um die Brücke zwischen dem C#-basierten Blazor-Frontend und der JavaScript-Bibl
 
 Durch diese Trennung bleibt die Geschäftslogik im C#-Code, während für die performante und ansprechende Darstellung auf etablierte Web-Technologien zurückgegriffen wird.
 
-### 5.3 Schwarzes Brett
+### Schwarzes Brett
 
 Das Modul "Schwarzes Brett" dient als digitale Anschlagtafel für den Absolventenverein. Mitglieder können hier Gesuche, Angebote oder allgemeine Informationen veröffentlichen. Es stellt eine zentrale Informationsdrehscheibe dar, die den informellen Austausch innerhalb des Vereins fördern soll.
 
@@ -472,17 +472,17 @@ Ein wichtiges Merkmal des Schwarzen Bretts zur Sicherstellung der Inhaltsqualit
 
 Auf der Serverseite folgt das Modul dem etablierten Muster mit einem `BlackBoardRepository` für den effizienten Datenbankzugriff und einem `BlackBoardController` für die API-Bereitstellung. Die Implementierung des Scheduled Jobs als HostedServiceBase ermöglicht eine tiefe Integration in die Oqtane-Infrastruktur bei gleichzeitig geringem Ressourcenverbrauch.
 
-## 6 Learnings
+## Learnings
 
-### 6.1 Produktion != Staging
+### Produktion != Staging
 
 Ein Learning, welches doch relativ schnell aufkam ist im Bereich der IT eigentlich kein unbekanntes. Wir hatten dieses Learning relativ bald, im Frühling 2025, als die ersten Probleme mit dem Deployment von Oqtane aufkamen. Oqtane war zwar in unserer Entwicklungsumgebung sehr einfach zum einrichten gewesen, das Deployment in der Cloud vom Hetzner war jedoch geplagt von Problemen. Im Zeitraum von Mai bis Okober hatten wir keine laufende Produktivumgebung. Dadurch sind wir mit dieser Diplomarbeit auch in [Zeitverzug](#arbeitszeiteinschätzung-zeitverzug) gekommen. Hätte ich mich vor dem Start der Diplomarbeit mit dem Deployment von Oqtane auseinander gesetzt, dann wäre das in [Probleme mit Oqtane](#fehlende-oder-nur-schlechte-dokumentation-von-oqtane) beschriebene Problem früher aufgekommen und der Zeitverzug wäre nicht so groß, oder noch ganz vermeidbar gewesen.
 
-### 6.2 Teamleitung (Motivation / Downsizing)
+### Teamleitung (Motivation / Downsizing)
 
 Nachdem ich mich von Anfang an volkommen in das Deploymentproblem von Oqtane gestürzt habe, habe ich meine Rolle als Teamleitung etwas schleifen lassen. Dadurch fehlte bei einigen Teammitgliedern initial die Identifikation mit dem Projekt und in weitererfolge auch die Motivation an diesem Projekt mitzuarbeiten. Nachdem im Verlauf des Frühlings und über den Sommer von der hälfte des Teams trotz Besprechungen und Mahnungen keine Beiträge zu dem Projekt kamen, haben Hr. Prof. Gürth und ich uns dazu entschieden uns von 2 Personen vor unterschreiben des Projektantrages zu trennen. Grund dazu war die Angst, die mangelnde Motivation zieht das restliche Team mit hinunter. Wir wollten uns trotz des Downsizings nicht an Funktionalitäten sparen und haben uns für das nächste halbe bis dreiviertel Jahr einen ziemlich strikten Zeitplan vorgenommen.
 
-### 6.3 Arbeitszeiteinschätzung (Zeitverzug)
+### Arbeitszeiteinschätzung (Zeitverzug)
 
 Ein wesentliches Learning aus dem Projektverlauf war die Diskrepanz zwischen der initialen Planung und dem tatsächlichen Aufwand. Ursprünglich wurde der Zeitaufwand für das Aufsetzen der Infrastruktur und die Einarbeitung in das Oqtane-Framework auf etwa drei Wochen geschätzt. In der Realität nahm dieser Prozess jedoch mehrere Monate in Anspruch.
 
@@ -503,7 +503,7 @@ Um das Projektziel dennoch zu erreichen, wurde der Zeitplan im Herbst 2025 massi
 > (Jon Bentley. 1985. Programmimg pearls. Commun. ACM 28, 9 (Sept. 1985), 896–901. https://doi.org/10.1145/4284.315122) [@bentley1985programming]
 > Diese Diplomarbeit liefert weitere Evidenz, dass diese Faustregel stimmt.
 
-### 6.4 Sprints und Meetings (in Zukunft ja asynchron)
+### Sprints und Meetings (in Zukunft ja asynchron)
 
 Ein zentrales Problem in unserer ursprünglichen Arbeitsweise war die Kopplung von Besprechungsterminen mit festen „Commit-Deadlines“ (dem Ende des aktuellen Sprint zyklusses). Da wir uns einmal pro Woche für sechs Stunden am Stück trafen, entstand ein destruktives Muster: