This commit is contained in:
@@ -47,10 +47,75 @@ Zusätzlich zur Infrastruktur habe ich drei zentrale Module für den Alumnihub e
|
||||
|
||||
### Modulanforderungen / funktionale Anforderungen
|
||||
|
||||
### Infrastrukturanforderungen / nicht‑funktionale Anforderungen
|
||||
Die funktionalen Anforderungen beschreiben die spezifischen Dienste und Funktionen, die das System für die Benutzer bereitstellen muss. Im Rahmen der individuellen Aufgabenstellung wurden Anforderungen für fünf Teilbereiche definiert:
|
||||
|
||||
#### Anmeldetool (EventRegistration)
|
||||
|
||||
\
|
||||
|
||||
Das Ziel des Anmeldetools ist die effiziente Organisation von Vereinsveranstaltungen.
|
||||
|
||||
- **Veranstaltungsmanagement**: Administratoren müssen in der Lage sein, neue Veranstaltungen anzulegen. Dabei müssen Name, Beschreibung, Datum, Zeit und Ort festlegbar sein.
|
||||
- **Anmeldeprozess**: Registrierte Benutzer müssen sich für eine Veranstaltung an- oder abmelden können.
|
||||
- **Teilnehmerliste**: Für jede Veranstaltung muss eine Übersicht der Rückmeldungen (Anmeldungen/Absagen) für Administratoren einsehbar sein.
|
||||
- **Statistische Auswertung**: Die Rückmeldungen sollen grafisch (z. B. als Tortendiagramm) aufbereitet werden, um die Planung zu erleichtern.
|
||||
|
||||
#### Globales Reporting System
|
||||
|
||||
\
|
||||
|
||||
Das Reporting System dient der Qualitätssicherung von Benutzerinhalten über alle Module hinweg.
|
||||
|
||||
- **Inhalte melden**: Benutzer müssen die Möglichkeit haben, unangemessene Einträge (z. B. am Schwarzen Brett) zu melden. Dabei muss ein Grund für die Meldung angegeben werden können.
|
||||
- **Generische Schnittstelle**: Das System muss so entworfen sein, dass beliebige andere Module (z. B. Hall of Fame) die Meldefunktion ohne Änderungen am Kern des Reporting-Systems einbinden können.
|
||||
- **Administrations-Dashboard**: Gemeldete Inhalte müssen in einer zentralen Übersicht für Administratoren aufgelistet werden.
|
||||
- **Moderationsaktionen**: Administratoren müssen gemeldete Inhalte löschen, die Meldung ignorieren oder den Ersteller verwarnen/sperren können.
|
||||
|
||||
#### Schwarzes Brett (BlackBoard)
|
||||
|
||||
\
|
||||
|
||||
Das Schwarze Brett fungiert als digitale Kommunikationsplattform für den Verein.
|
||||
|
||||
- **Beiträge erstellen**: Benutzer müssen Textbeiträge erstellen können. Die Formatierung der Texte soll über einen Rich-Text-Editor möglich sein.
|
||||
- **Bilder-Upload**: Zu jedem Beitrag soll optional ein Bild hochgeladen werden können, welches automatisch für die Vorschau skaliert wird.
|
||||
- **Benachrichtigungs-System**: Das System soll regelmäßig (täglich/wöchentlich) eine Zusammenfassung neuer Beiträge per E-Mail an alle interessierten Mitglieder versenden.
|
||||
|
||||
#### Mass Mailing (Admin)
|
||||
|
||||
\
|
||||
|
||||
Dieses Modul ermöglicht die direkte Kommunikation des Vorstands mit allen Mitgliedern.
|
||||
|
||||
- **Rundmails verfassen**: Administratoren müssen E-Mails mit Betreff und Inhalt an alle registrierten Benutzer verfassen können.
|
||||
- **Personalisierung**: Die E-Mails sollen automatisch mit dem Namen des Empfängers personalisiert werden können.
|
||||
- **Verspätetes Senden**: Aufgrund von Versandlimits des Providers (Brevo) müssen die E-Mails in eine Warteschlange eingereiht und zeitversetzt in Batches versendet werden.
|
||||
|
||||
#### Token Lifetime Management (Admin)
|
||||
|
||||
\
|
||||
|
||||
Dies dient der Konfiguration sicherheitsrelevanter Parameter.
|
||||
|
||||
- **Gültigkeitsdauer**: Administratoren müssen die Gültigkeitsdauer für temporäre Links (z. B. Passwort-Reset, E-Mail-Bestätigung) über eine grafische Oberfläche anpassen können.
|
||||
- **Einstellungs-Persistenz**: Die geänderten Werte müssen dauerhaft gespeichert werden und sofort für neue Token-Generierungen wirksam sein.
|
||||
|
||||
### Use Cases
|
||||
|
||||
Um die Interaktion der Benutzer mit den Modulen zu verdeutlichen, wurden folgende Use Cases definiert:
|
||||
|
||||
| ID | Name | Akteur | Beschreibung |
|
||||
| --- | --- | --- | ------ |
|
||||
| UC-01 | Veranstaltung erstellen | Administrator | Ein Administrator legt ein neues Absolvententreffen mit Ort und Datum an. |
|
||||
| UC-02 | Zu Event anmelden | Mitglied | Ein Absolvent bestätigt seine Teilnahme an einem Event über die Weboberfläche. |
|
||||
| UC-03 | Inhalt melden | Mitglied | Ein Benutzer meldet einen beleidigenden Post am Schwarzen Brett über den "Melden"-Button. |
|
||||
| UC-04 | Meldung bearbeiten | Moderator | Ein Vorstandsmitglied sichtet eine Meldung und löscht den entsprechenden Beitrag. |
|
||||
| UC-05 | Rundmail versenden | Administrator | Der Vorstand erstellt eine Einladung zur Generalversammlung für alle 500 Mitglieder. |
|
||||
|
||||
Table: Wesentliche Use Cases der entwickelten Module
|
||||
|
||||
Es ist zu beachten, dass es sich hierbei um eine Auswahl handelt und nicht alle Use Cases der Module abgebildet werden.
|
||||
|
||||
- funktionale / nicht‑funktionale Anforderungen
|
||||
- Use Cases
|
||||
|
||||
## Technisches Umfeld
|
||||
|
||||
@@ -60,6 +125,8 @@ Mein Aufgabenbereich umfasst einerseits die Entwicklung eigener Module, sowie da
|
||||
|
||||
#### 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:
|
||||
|
||||
- Piranha CMS
|
||||
@@ -75,6 +142,8 @@ Insbesondere aufgrund seiner sehr hohen Flexibilität, haben wir uns am Ende fü
|
||||
|
||||
#### 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.
|
||||
|
||||
Im Bereich der Datenbanken musste ich mir ein paar Fragen stellen:
|
||||
@@ -95,6 +164,8 @@ Ein `Module` (Modul) soll neue Funktionalitäten in das CMS hinzufügen und ein
|
||||
|
||||
#### Architektur eines Moduls
|
||||
|
||||
\
|
||||
|
||||
Ein Modul in Oqtane besteht aus vier Projekten:
|
||||
|
||||
- Im Server-Projekt liegt Sourcecode, welcher serverseitig ausgeführt werden soll. Dazu gehören unter anderem alle Repositories, Controller, Manager, Migrationen und Server-Services und Server-Startuplogik.
|
||||
@@ -113,6 +184,8 @@ In diesem Kapitel erkläre ich wie die ausgewählten Komponenten zusammenspielen
|
||||
|
||||
#### NginX as Reverse Proxy
|
||||
|
||||
\
|
||||
|
||||
NginX fungiert in unserer Infrastruktur als `Reverse Proxy`. Ein Reverse Proxy nimmt Anfragen aus dem Internet entgegen und leitet sie an interne Server (wie Kestrel) weiter. Dies bietet mehrere Vorteile:
|
||||
|
||||
- **Sicherheit**: Die interne Applikation ist nicht direkt dem Internet ausgesetzt.
|
||||
@@ -176,6 +249,8 @@ Die VPN basierten Zugänge sind tendenziell schwieriger zu finden und auszunutze
|
||||
|
||||
#### 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.
|
||||
|
||||
Blazor hat mehrere Hosting-Modelle:
|
||||
@@ -224,6 +299,8 @@ Razor hat auch eine Reihe an Keywords, wie zum Beispiel (nur Auszugsweise, bzw.
|
||||
|
||||
#### Kommunikation zwischen Front- und Backend
|
||||
|
||||
\
|
||||
|
||||
Die Interaktion zwischen Client und Server folgt in Oqtane einem klaren Architekturmuster, das je nach Render-Modus unterschiedliche Technologien nutzt.
|
||||
|
||||
- **SignalR (Interactive Server)**: Für Echtzeit-Interaktionen nutzt Oqtane SignalR. Dabei wird eine persistente WebSocket-Verbindung (oder Fallbacks wie Long-Polling) aufgebaut. Zustandsänderungen im UI lösen C#-Events auf dem Server aus, und das resultierende "Diff" des DOMs wird zurück an den Client gestreamt.
|
||||
@@ -259,6 +336,8 @@ In den folgenden beiden Kapiteln wird das Dependency Inversion Principle und das
|
||||
|
||||
#### 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.
|
||||
|
||||
Das DIP unterscheidet zwischen high-level und low-level Modulen.
|
||||
@@ -293,6 +372,8 @@ Das High-Level-Modul ruft lediglich eine Abstraktion eines Low-Level-Moduls auf,
|
||||
|
||||
#### Microsoft Dependency Injection Framework
|
||||
|
||||
\
|
||||
|
||||
Dependency Injection ist in .NET genau so wie Konfiguration, Protokollierung und das Optionsmuster ins Framework integriert. [@ms_di_overview]
|
||||
|
||||
Alle Dependencies werden in einem `Service-Container` zur Verwaltung registriert. .NET hat einen eingebauten `Service-Container` (eine Implementierung des `IServiceProvider`). [@ms_di_overview]
|
||||
@@ -383,6 +464,8 @@ Um die Anwendung und ihre Abhängigkeiten konsistent auf dem Zielserver (Linux/H
|
||||
|
||||
#### Struktur eines Debian-Pakets
|
||||
|
||||
\
|
||||
|
||||
Ein `.deb`-Paket ist im Grunde ein `ar`-Archiv, das drei wesentliche Bestandteile enthält:
|
||||
|
||||
- **debian-binary**: Eine Textdatei mit der Versionsnummer des Paketformats.
|
||||
@@ -391,6 +474,8 @@ Ein `.deb`-Paket ist im Grunde ein `ar`-Archiv, das drei wesentliche Bestandteil
|
||||
|
||||
#### Automatisierung im Build-Prozess
|
||||
|
||||
\
|
||||
|
||||
Der Bau des Pakets erfolgt vollautomatisch in der Gitea-CI-Pipeline. Dabei werden die folgenden Schritte durchlaufen:
|
||||
|
||||
1. **Dotnet Publish**: Kompilieren der Anwendung für Linux-x64.
|
||||
@@ -448,26 +533,38 @@ Als schlanke und selbst gehostete Open-Source-Alternative zu Plattformen wie Git
|
||||
|
||||
#### Repositories
|
||||
|
||||
\
|
||||
|
||||
Ein Repository bildet den zentralen Speicherort für einen Projektteil. In Gitea wurden separate Repositories für die einzelnen Module und Themes, das Oqtane Framework, Skripte, die Dokumentation angelegt. Ein zusätzliches Repository bindet alle übrigen Quellcode-Repositories als Submodule ein, das macht die Einrichtung einer neuen Entwicklungsumgebung sehr kompfortabel. Dies ermöglichte eine saubere Trennung der verschiedenen Projektkomponenten. [@gitea_docs]
|
||||
|
||||
#### Issues
|
||||
|
||||
\
|
||||
|
||||
Zur Aufgabenplanung und Fehlerverfolgung wurde das integrierte Issue-System genutzt. Jede anstehende Aufgabe oder entdeckte Schwachstelle wurde als „Issue“ erfasst, einem Verantwortlichen zugewiesen und mit Labels (z. B. „Bug“, „Feature“ oder „Dokumentation“) versehen. Dies half dabei, den Überblick über den Projektfortschritt zu behalten und die Anforderungen aus dem Lastenheft strukturiert abzuarbeiten. [@gitea_docs][@gitea_issue_tracker]
|
||||
|
||||
#### Pull Requests
|
||||
|
||||
\
|
||||
|
||||
Um die Qualität des Codes zu sichern, wurden Änderungen nicht direkt in den Hauptzweig eingespielt, sondern über Pull Requests eingereicht. Ein Teammitglied konnte so die Änderungen eines anderen sichten, kommentieren und bei Bedarf Korrekturen anfordern. Erst nach einer erfolgreichen Überprüfung wurde der Code in den main-Branch gemergt. [@gitea_docs][@gitea_pull_requests]
|
||||
|
||||
#### Actions
|
||||
|
||||
\
|
||||
|
||||
Gitea Actions wurden eingesetzt, um CI/CD-Pipelines (Continuous Integration / Continuous Deployment) zu realisieren. Bei jedem Push oder Pull Request wurden automatisierte Skripte ausgeführt, die das Projekt bauten. Dies reduzierte manuelle Fehlerquellen erheblich. Außerdem konnten wir mithilfe von CI/CD den Release Prozess einmalig festlegen und automatisieren, ohne bei jedem Update manuell den selben Prozess wiederholt durchgehen zu müssen. Das APT-Package Projekt enthält die CI/CD Konfiguration für das bauen von Oqtane, der Module und Themes, sowie das verpacken in ein APT Paket und dem veröffentlichen aller Pakete als eingenes Gitea Release. [@gitea_docs][@gitea_actions]
|
||||
|
||||
#### Releases
|
||||
|
||||
\
|
||||
|
||||
Über die Release-Funktion wurden wichtige Meilensteine der Diplomarbeit festgeschrieben. Hierbei wird ein spezifischer Git-Tag mit einer Versionsnummer versehen und die dazugehörigen Binärdateien, Pakete und Dokumente archiviert. So lässt sich jederzeit auf einen stabilen, abgabebereiten Stand des Projekts zugreifen. [@gitea_docs]
|
||||
|
||||
#### Package Repositories
|
||||
|
||||
\
|
||||
|
||||
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]
|
||||
|
||||
### Kommunikation
|
||||
@@ -480,6 +577,8 @@ Eine C#-Solution, welche einige Module, welche für den Admineinsatz geschrieben
|
||||
|
||||
#### Mass Mailing
|
||||
|
||||
\
|
||||
|
||||
Das Mass Mailer Modul ist eine administrative Erweiterung für den Alumnihub, die es dem Vorstand ermöglicht, personalisierte Rundschreiben an alle registrierten Mitglieder zu versenden. Da die Pflege der Mitgliederdaten direkt im CMS erfolgt, bietet dieses Modul eine nahtlose Integration ohne den Export von CSV-Listen in externe Newsletter-Tools.
|
||||
|
||||
Integration von Brevo
|
||||
@@ -490,6 +589,8 @@ Für den tatsächlichen Versand der E-Mails nutzen wir den Cloud-Dienst Brevo. D
|
||||
|
||||
#### Token Lifetime
|
||||
|
||||
\
|
||||
|
||||
Das Token Lifetime Modul wurde geschrieben, um die Token-Lebenszeit konfigurierbar zu machen. Notwendig war das, um die Passwort Reset Links im initialen Mail versand länger gültig sein zu lassen. Durch das `Batch Processing` war es möglich, dass eine Mail erst Tage nach erstellen des Links hinaus geschickt wird und bei einer Standard Ablaufdauer von 2 Tagen sind manche Links schon ungültig, bis sie den Mail Server erreichen. Ziel war es, die Änderung der Lebenszeit für Administratoren im User Interface im Admin Bereich möglich zu machen.
|
||||
|
||||
Technisch bedeutet das, dass die standardmäßig vorkonfigurierten `DataProtectionTokenProviderOptions` explizit konfiguriert werden müssen. [@andrewlock_token_lifetime] Der ASP.NET Core `UserManager`, welcher das generieren der Tokens übernimmt, verwendet einen `DataProtectorTokenProvider` und dieser wiederum kann mithilfe der `DataProtectionTokenProviderOptions` konfiguriert werden.
|
||||
@@ -503,6 +604,8 @@ Es gibt 2 Möglichkeiten, wie man dieses Problem Lösen kann:
|
||||
|
||||
#### Reporting System
|
||||
|
||||
\
|
||||
|
||||
Eine weitere Anforderung der Diplomarbeit war es Einträge in Modulen wie der `Hall of Fame`, dem `Schwarzen Brett` und dem Premium Bereich (`Engineer Applications`) melden zu können. Am Anfang war es wichtig, dass jeder schnell vorankommt, allerdings haben wir die Kommunikation Teamintern ein wenig verschlafen und dadurch ein paar Funktionen doppelt geschrieben. Dadurch kam es zu Inkonsistenzen in der Verwendung der unterschiedlichen Reporting Systeme. Deswegen haben wir uns am Ende für eine globales Reporting System entschieden.
|
||||
|
||||
Angestrebt wurde folgender Ablauf für das Melden eines Eintrags:
|
||||
@@ -554,6 +657,8 @@ Dieses Modul ermöglicht es Administratoren und Absolventen, Veranstaltungen zu
|
||||
|
||||
#### Backend und Datenhaltung
|
||||
|
||||
\
|
||||
|
||||
Die serverseitige Implementierung basiert auf dem Repository-Pattern des Oqtane-Frameworks. Hierbei kommen zwei zentrale Repositories zum Einsatz:
|
||||
|
||||
Das `EventRepository` verwaltet die Metadaten der Veranstaltungen wie Name, Beschreibung, Datum und Ort.
|
||||
@@ -601,6 +706,8 @@ erDiagram
|
||||
|
||||
#### Statistik und Visualisierung
|
||||
|
||||
\
|
||||
|
||||
Ein wesentlicher Teil der administrativen Ansicht ist die Visualisierung der Anmeldezahlen. Hierfür wurde eine Integration von Chart.js realisiert, um den aktuellen Stand der Rückmeldungen grafisch aufzubereiten.
|
||||
|
||||
Um die Brücke zwischen dem C#-basierten Blazor-Frontend und der JavaScript-Bibliothek Chart.js zu schlagen, wurde ein dedizierter Interop-Service implementiert. Der Ablauf der grafischen Darstellung gestaltet sich wie folgt:
|
||||
@@ -617,6 +724,8 @@ Das Modul "Schwarzes Brett" dient als digitale Anschlagtafel für den Absolvente
|
||||
|
||||
#### Struktur und Anzeige
|
||||
|
||||
\
|
||||
|
||||
{ latex-placement="ht" }
|
||||
|
||||
<!-- ![Detailansicht eines Eintrags auf dem Schwarzen Brett][img-ref] -->
|
||||
@@ -630,6 +739,8 @@ Die Anzeige der Einträge erfolgt in einer responsiven Grid-Ansicht (Index-Kompo
|
||||
|
||||
#### Automatisierter E-Mail-Digest
|
||||
|
||||
\
|
||||
|
||||
Um die Mitglieder regelmäßig über neue Inhalte zu informieren, wurde ein automatisierter `Cronjob` implementiert. Dieser Job läuft im Hintergrund des Oqtane-Frameworks und führt folgende Schritte aus:
|
||||
|
||||
- Filterung: Der Job identifiziert alle Einträge, die seit dem letzten Versand erstellt wurden.
|
||||
@@ -640,10 +751,14 @@ Um die Mitglieder regelmäßig über neue Inhalte zu informieren, wurde ein auto
|
||||
|
||||
#### Reporting System
|
||||
|
||||
\
|
||||
|
||||
Ein wichtiges Merkmal des Schwarzen Bretts zur Sicherstellung der Inhaltsqualität ist die Anbindung an das globale Reporting-System (siehe 5.4). In der Detailansicht wird über Dependency Injection die IReportUI-Komponente eingebunden. Mithilfe der DynamicComponent von Blazor wird die Melde-Funktion nahtlos in die Oberfläche des Moduls integriert. Dadurch können unangemessene Inhalte direkt von Benutzern gemeldet werden.
|
||||
|
||||
#### Technischer Hintergrund
|
||||
|
||||
\
|
||||
|
||||
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.
|
||||
|
||||
## Learnings
|
||||
@@ -664,6 +779,8 @@ Es gibt mehrere Gründe dafür:
|
||||
|
||||
#### Fehlende Dokumentation {#fehlende-dokumentation}
|
||||
|
||||
\
|
||||
|
||||
- `Fehlende oder nur schlechte Dokumentation von Oqtane`: Einige Probleme im Deployment wurden in langer und mühseliger Arbeit auseinander gebrochen und in weitere immer kleinere Probleme unterteilt. Dadurch, dass wir alle keine Erfahrung mit der Entwicklung und dem Deployment von ASP.NET Code Anwendungen hatten und die Dokumentation doch schlecht war, blieb uns manchmal nichts anderes übrig als mit WireShark den Netzwerktraffic mit zu schneiden und nebenbei im Git Repository die geloggten Zeilen Code zu finden und so das Framework von innen heraus kennen zu lernen. Dadurch hatte ich dann nach einer Einarbeitungszeit von 4 Monaten ziemlich jede Stelle im Sourcecode von Oqtane gesehen und finde mich um das schneller zurecht.
|
||||
- `Team-Konsolidierung`: Durch das notwendige Downsizing des Teams mussten Aufgaben neu verteilt werden, was die individuelle Arbeitslast erhöhte und die Konzentration auf die Kernentwicklung zeitweise verzögert hat.
|
||||
- `Abhängigkeit von der Infrastruktur`: Dadurch, dass wir bis in den Oktober / November hinein nicht wussten, ob wir weiter bei Oqtane bleiben können, haben die anderen Teammitglieder nicht mit der sinnvollen Entwicklung ihrer Module starten können. Zitat: "Und was wenn wir am Ende doch noch das CMS umstellen müssen?" => Auch wenn der Auftrag war, mit der Modulentwicklung zu starten war die Motivation meiner Teammitglieder nicht so hoch. Selbst wenn sie nicht direkt von der Infrastruktur mit der Ausführung ihrer Aufgaben abhängig waren, motiviert waren sie wegen der Umstände auch nicht.
|
||||
|
||||
Reference in New Issue
Block a user