Compare commits

..
2 Commits
Author SHA1 Message Date
Technoir af46c19651 updated 2026-10-19 15:16:21 +02:00
Technoir ea6a330fab datenmodell-archtiektur doc hinzugefügt 2026-10-19 14:18:39 +02:00
2 changed files with 154 additions and 12 deletions

No files matched your search

+154
View File
@@ -0,0 +1,154 @@
# Datenmodell und Architektur
Das Projekt nutzt die Modelle `ShoppingList`, `ShoppingItem` und `ShoppingCategory`.
## Diagram
```mermaid
erDiagram
ShoppingList ||--o{ ShoppingCategory : hat
ShoppingList ||--o{ ShoppingItem : hat
ShoppingCategory ||--o{ ShoppingItem : enthält
```
## Modelle
### ShoppingList
Eine ShoppingList hat beliebige ShoppingCategory und ShoppingItem.
Der Name darf nicht leer sein.
### ShoppingCategory
Eine ShoppingCategory hat beliebige ShoppingItem.
Der Name darf nicht leer sein.
### ShoppingItem
Ein ShoppingItem hat sowohl einen Namen als auch eine Menge.
Der Nutzer hat und sollte die Freiheit haben,
die Felder so zu befüllen wie er will.
Es findet deshalb keine Eingabevalidierung in dem Sinne statt,
dass bei Menge nur Mengeneinheiten stehen dürfen oder im Namen keine Zahlen.
Die einzige Anforderung ist es, dass der Nutzer einen der beiden Felder
ausfüllen muss.
## Architektur Backend (`src/main/java/de/timaldinger/einkaufsliste/`)
### Controller (`Controller/`)
`PageController` ist zuständig für das Bereitstellen von den einzelnen Seiten.
Die restlichen Controller sind RESTController, welche die API-Schnittstelle
behandeln. Sie sind nach der betroffenen Ressource aufgeteilt.
### Data Transfer Objects (`Dto/`)
Die Webapp nutzt sogenannte DTOs (Data transfer objects)
um die geschickten JSON-Daten auf das Model abzubilden. Diese liegen unter `Dto/`.
Dort sind die DTOs nochmal nach den HTTP-Methoden aufgeteilt, da je nach Methode
der Nutzer unterschiedliche Daten mitschicken tut.
### Exceptions (`Exceptions/`)
Hier liegen benutzerdefinierte Fehlermeldungen, die an das Frontend geschickt werden
(hauptsächlich für 400 und 404)
und ein eigener Exception Handler `GlobalExceptionHandler.java`.
Dieser wurde erstellt damit Fehlermeldungen
besser dargestellt werden können und keine Spring-Fehlermeldungen an das Frontend
geschickt werden.
Er ist mit `@RestControllerAdvice` annotiert, das heißt,
dass er für alle anderen Controller gilt. Er implementiert Methoden annotiert
mit `@ExceptionHandler`, welche angibt, für welche Funktion ein geworfener Fehler
in einer Funktion des Controllers greift. Es werden in den Controllern die
Custom Exceptions geworfen.
Das Record `ErrorResponse.java` stellt einen JSON-Body dar um daraus die Fehlermeldung
zu bauen die an das Frontend geschickt wird.
### Mapper (`Mapper/`)
Klassen, welche die Models aus der Datenbank zu DTOs mappen. Nötig um GET
Anfragen zu nutzen.
### Models (`Model/`)
Unter `Models/` liegen die Modelle. Die Modelle werden in der Datenbank
so abgebildet wie sie in der Klasse definiert sind.
### Repository (`Repository/`)
Interfaces, die das JpaRepositories-Interface implementieren. Das JPARep wurde genommen,
da man dort Bulkfunktionen wie `saveAll` nutzen kann,
Rückgabetypen wie `List` erlaubt sind und diese auch eine `h2`-db
Implementierung aufweist.
### Services (`Service/`)
Serviceklassen, welche Methoden für die Controller zur Verfügung stellen,
um die jeweile HTTP-Request erfüllen zu können. Sie kapseln die Logik von den Controllern.
### Templating (`src/main/resources/templates`)
Da die Webapp einen Hybridansatz beim Rendering verfolgt, wurden Thymeleaf-Templates
genutzt um die Seite beim Aufrufen bereitzustellen. Die `PageController` Klasse
stellt diese bereit.
## Architektur Frontend (`src/main/resources/static`)
Genutzt wurde Vanilla-JS und CSS. Das CSS liegt unter `static/css` und das JS unter `static/js`.
Jede aufrufbare Seite (`/` und `/list`) hat seinen eigenen Ordner, wo für die Seite
spezifische JS Dateien liegen. Hier finden sich zwei Unterordner: `api/` und `ui/`.
Unter jenen Ordner befinden sich Funktionen die jeweils API und UI abwickeln.
Die `.js` Datei die in dem Ordnerroot liegt, nutzt und bündelt diese.
Die Trennung wurde getätigt um bessere Übersicht und
sauberere Entwicklung zu ermöglichen.
Unter `shared/` liegen Dateien, die von alle Seiten
genutzt werden. Unter Models liegen die Implementierungen der CustomHTML-Elemente.
### Custom Elemente (`/static/js/models`)
Im Laufe der Entwicklung wurden CustomHTML Elemente genommen, um die ShoppingList,
ShoppingCategory und ShoppingItems darzustellen und besser zu handhaben. Es wurde
sich für ein LightDOM Ansatz entschieden, da zum einen die Eventpropagation einfacher
zu gestalten ist (EventListener auf `div`) und zum anderen die CSS Klassen greifen.
Mit einem Shadow-DOM Ansatz mit zB `templates` wäre das umständlicher.
### Index Seite (`/static/js/index`)
Hier liegen nötige Javascriptdateien für die Root Seite `/`.
Unter `/api` liegen die API Methoden, unter `/ui` UI Methoden
### List Seite (`static/js/list`)
Hier liegen nötige Javascriptdateien für die Seite `/list/{id}`.
Unter `/api` liegen die API Methoden, unter `/ui` UI Methoden.
Da die Seite sowohl Kategorien als auch Gegenstände
behandelt sind in den Ordnern jeweils API und UI Dateien für die beiden Elemente.
Diese sind dann in den jeweilen `listUI.js` und `listAPI.js` gebündelt.
### Shared Module (`static/js/shared`)
#### editing.js
Hier liegt die Logik, welche genutzt wird um eines
der Elemente (Liste, Kategorie, Gegenstand) zu bearbeiten.
Zusammen mit `sharedUI.js` bildet sie den Ablauf ab.
Die beiden Dateien sind bewusst getrennt,
da die Funktion `editElement()` eine Mischung aus UI und API Aufrufe hat.
Das Muster, dass API und UI Funktionen in getrennten Dateien leben,
sollte beibehalten werden.
#### error.js
Globale Fehlermeldungsdarstellung. Eine Clientseitige Validierung findet
nicht statt, da sie serverseitig behandelt werden.
#### helper.js
Hilfsfunktion für das Abwickeln von `fetch()` Anfragen.
Zur Vereinheitlichung der Funktionen die API calls nutzen.
#### sharedUI.js
Stellt UI-Funktionen bereit, die alle Seiten nutzen. Momentan nur für
Bearbeitung der Elemente.
-12
View File
@@ -1,12 +0,0 @@
# Datenmodell
Das Projekt nutzt die Modelle `ShoppingList`, `ShoppingItem` und `ShoppingCategory`.
## Diagram
```mermaid
erDiagram
ShoppingList ||--o{ ShoppingCategory : hat
ShoppingList ||--o{ ShoppingItem : hat
ShoppingCategory ||--o{ ShoppingItem : enthält
```