Compare commits

Author SHA1 Message Date
Technoir 179ec1206b update
zeilenlänge, LEerzeilen und verweis auf docs hinzugefügt
2026-10-19 16:04:24 +02:00
Technoir e22cd8c650 zeilenlänge und so angepasst weil nvim heult 2026-10-19 16:03:20 +02:00
Technoir bb60da6aaa leerzeieln weil nvim heult 2026-10-19 16:03:06 +02:00
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
4 changed files with 263 additions and 32 deletions

No files matched your search

+26 -8
View File
@@ -1,22 +1,39 @@
# Einkaufsliste
Repository für das Webapp-Projekt, was eine Einkaufsliste zur Verfügung stellt.
Es ist möglich, mehrere Listen anzulegen. In einer Liste kann man Gegenstände und Kategorien erstellen. Gegenständen können, aber müssen nicht Kategorien gehören.
Es ist möglich, mehrere Listen anzulegen. In einer Liste kann man
Gegenstände und Kategorien erstellen.
Gegenständen können, aber müssen nicht Kategorien gehören.
## Dokumentation
### Entwicklungsverlauf und User Stories
Dieses Projekt hat seine Dokumentation über Gitea vorgenommen. Die Entwicklungshistorie ist über die Commitliste einsehbar, User-Stories und andere Entwicklungsentscheidungen wurden über Issues abgewickelt. Es wurden auch Meilensteine verwendet um die Issues zu organisieren.
Dieses Projekt hat seine Dokumentation über Gitea vorgenommen.
Die Entwicklungshistorie ist über die Commitliste einsehbar,
User-Stories, Erweiterungen/Änderungen am Projekt und andere
Entwicklungsentscheidungen wurden über Issues abgewickelt.
Es wurden auch Meilensteine verwendet um die Issues zu organisieren.
Bugs und Fehler wurden nicht mit Issues dokumentiert, da
sie entweder während der Entwicklung auf einem anderen Branch beseitigt worden sind
(wenn der Fehler von der Entwicklung des Branches kam) oder spontan gefixt.
Die Commits, welche Bugs fixen sind mit `bug:` bzw. `bugfix:`
gekennzeichnet und in der Commit-Historie auffindbar.
## Architektur
Die Seite verfolgt einen clientseitig gerenderter Ansatz. Das Backend schickt dem Browser eine HTML-Datei, welche in Teilen mit Attributen bei Custom Elementen und Daten befüllt sind. Der Client rendert dann die Custom Elemente.
Die Webseite selbst ist so ziemlich im Frontend benutzbar. Ein Neuladen der Seite ist nicht nötig, mit Ausnahme wenn man zwischen Listen und der Listenübersicht wechselt.
Die Seite verfolgt einen hybriden Ansatz. Das Backend schickt dem Browser eine HTML-Datei,
welche in Teilen mit Attributen bei Custom Elementen und Daten befüllt sind.
Der Client rendert dann die Custom Elemente.
Die Webseite selbst ist so ziemlich im Frontend benutzbar.
Ein Neuladen der Seite ist nicht nötig, mit Ausnahme wenn man
zwischen Listen und der Listenübersicht wechselt.
### Backend
Für das Backend wurde Spring mit Thymeleaf für das Bereitstellen von Seiten genutzt (`src/main/java/de/timaldinger/einkaufsliste`). Das Backend ist über eine RESTful-API ansprechbar. Die Datenbank ist H2.
Für das Backend wurde Spring mit Thymeleaf für das Bereitstellen von Seiten genutzt (`src/main/java/de/timaldinger/einkaufsliste`).
Das Backend ist über eine RESTful-API ansprechbar. Die Datenbank ist H2.
### Frontend
@@ -31,7 +48,7 @@ Hinweis: Kategorien und Gegenstände können bearbeitet werden indem man auf sie
| `/api/categories` | GET, POST, DELETE, PATCH | Kategorien |
| `/api/items` | GET, POST, DELETE, PATCH | Gegenstände |
Die vollständige API-Dokumentation befindet sich unter `/docs/`.
Die vollständige API-Dokumentation befindet sich unter [`/docs/`](/docs/API.md)
## Aufsetzen
@@ -50,10 +67,11 @@ Nun kann man im Browser `localhost:8080` aufrufen.
### Weitere Dokumentation
Weitere Dokumentation befindet sich unter `/docs/`
Weitere Dokumentation befindet sich unter [`/docs/`](/docs)
### Nutzung von KI
Es wurde Claude Code Opus 4.8 genutzt. Die KI wurde benutzt zum Debuggen bei scheinbar nicht erkennbaren Fehlern, großen Refactors und als Nachschlagwerk genutzt.
Es wurde Claude Code Opus 4.8 genutzt. Die KI wurde zum Debuggen,
bei scheinbar nicht erkennbaren Fehlern, großen Refactors und als Nachschlagewerk genutzt.
Konzept-, Architekturentscheidungen und Umsetzung des Projekts liegen an mir.
Vorschläge von KI wurden geprüft und bewusst übernommen oder verworfen.
+163
View File
@@ -0,0 +1,163 @@
# Datenmodell und Architektur
Das Projekt nutzt die Modelle `ShoppingList`, `ShoppingItem` und `ShoppingCategory`.
Neben den Spring und Thymeleaf Bibliotheken wurde noch zusätzlich lombok genutzt.
Lombok stellt Annotationen bereit um Boilerplatecode zu vermeiden.
## Diagramm
```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 greift, wenn ein Fehler von
einer Controllerklasse aus propagiert. 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.
Die CustomException-Klassen erben von `RuntimeException`.
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 (`Models/`)
Unter `Models/` liegen die Modelle. Die Modelle werden in der Datenbank
so abgebildet wie sie in der Klasse definiert sind. Auch sind Relationen
der Entities wie sie in der Datenbank seien sollen abgebildet mit
Annotationen wie `@ManyToOne`. Es gibt eine abstrakte Klasse `ShoppingElement`,
von welcher alle anderen Entities erben. Die Klasse hat eine Variable `id`,
welche ihre Unterklassen dann auch haben.
### Repository (`Repository/`)
Interfaces, die das JpaRepositories-Interface implementieren. Das JPARep wurde genommen,
da man dort Bulkfunktionen wie `saveAll` und `findAll` 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 `frontend/`.
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/pages/index`)
Hier liegen nötige Javascriptdateien für die Root Seite `/`.
Unter `/api` liegen die API Methoden, unter `/frontend` UI Methoden
### List Seite (`static/js/pages/list`)
Hier liegen nötige Javascriptdateien für die Seite `/list/{id}`.
Unter `/api` liegen die API Methoden, unter `/frontend` 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
```
+74 -12
View File
@@ -1,5 +1,7 @@
# API
Die API versucht möglichst RESTful zu sein. Es hat:
- Ressourcen im Plural
- Client-Server Trennung, Änderung der Daten auf der Oberfläche geschieht über `fetch()` an die API
- Einheitliche Schnittstelle
@@ -9,6 +11,7 @@ Die Schnittstelle erfolgt vollständig über JSON.
Es wurde auf Cache-fähigkeit verzichtet aus Zeitgründen. HATEOAS ist auch nicht vorhanden, da Zeitgründe und fragwürdig, ob es für ein Projekt diesen Umfang nötig ist.
## API Pfade
IDs sind im UUID Format
### Listen `/api/lists`
@@ -17,10 +20,15 @@ IDs sind im UUID Format
| ------------ | -------- | --------------------------------------------------- | ----------------------------------------- | ------------ |
| `/api/lists` | `GET` | Gibt alle vorhandenen Listen zurück mit Name und ID | / | 200 |
| | `POST` | Erlaubt es eine neue Liste zu erstellen | `listName` für den gewünschten Listenname | 201 |
#### `GET /api/lists` - Alle Listen
##### Body Beispiel
Leer
##### Response Beispiel
```json
[
{
@@ -34,21 +42,26 @@ Leer
...
]
```
#### `POST /api/lists` - Erstellen einer Liste
##### Body Beispiel
```json
{
"listName": "Listenname"
"listName": "Listenname"
}
```
##### Response Beispiel
```json
{
"listName": "Listenname",
"listID": "ddb3ac36-8213-4f9d-bf1e-39c836768e57"
"listName": "Listenname",
"listID": "ddb3ac36-8213-4f9d-bf1e-39c836768e57"
}
```
### Liste `/api/lists`
| Pfad | Methoden | Beschreibung | Parameter | Codes Erfolg |
@@ -56,10 +69,15 @@ Leer
| `/api/lists/{id}` | GET | Gibt alle Gegenstände und Kategorien (mit ihren Gegenständen) in der Liste mit der UUID id zurück | `id`: UUID der Liste in der URL | 200 |
| | PATCH | Verändert den Namen der Liste | `id`: UUID der Liste in der URL. Im Body `listName` für den neuen Namen | 204 |
| | DELETE | löscht eine Liste | `id`: UUID Der Liste in der URL | 204 |
#### GET `/api/lists/{id}` - Inhalt der Liste
##### Body Beispiel
/
##### Response Beispiel
```json
{
"categories": [
@@ -98,25 +116,33 @@ Leer
]
}
```
#### `PATCH /api/lists/{id}` - Bearbeiten der Liste
##### Body
```json
{
"listName": "neuer Listname"
"listName": "neuer Listname"
}
```
##### Response
/
#### `DELETE /api/lists/{id}` - Löschen einer Liste
##### Body
/
##### Response
/
#### `DELETE /api/lists/{id}` - Löschen einer Liste
##### Body
/
##### Response
/
### Kategorien `/api/categories`
| Pfad | Methoden | Beschreibung | Parameter | Codes Erfolg |
| ---------------------- | -------- | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | ------------ |
| `/api/categories/{id}` | `GET` | Gibt den Inhalt der Kategorie zurück | / | 200 |
@@ -124,11 +150,14 @@ Leer
| | `PATCH` | Ändern vom Namen der Liste | `categoryName` im Body für neuen Kategorienamen | 204 |
| | `DELETE` | Löschen einer Liste | `deleteAllItems=(true\|false)` als Queryparameter. Entscheidet, ob Gegenstände in der Kategorie mitgelöscht werden sollen | 204 |
#### `GET /api/categories/{id}` - Inhalt der Kategorie
##### Body Beispiel
/
##### Response Beispiel
```json
{
"categoryName": "testkategorie",
@@ -145,38 +174,53 @@ Leer
"categoryID": "08bedce1-9b25-4fe6-9ede-4d9ee3a904d4"
}
```
#### `POST /api/categories` - Erstellen einer Kategorie
##### Body Beispiel
```json
{
"categoryName": "testKategorie",
"listID": "9038b8ef-7be8-4dcb-9229-6f51b11be137"
}
```
##### Response Beispiel
```json
{
"categoryName": "testKategorie",
"categoryID": "08bedce1-9b25-4fe6-9ede-4d9ee3a904d4"
}
```
#### `PATCH /api/categories/{id}` - Bearbeiten der Kategorie
##### Body Beispiel
```json
{
"categoryName": "Gemüse"
}
```
##### Response
/
#### `DELETE /api/categories/{id}?deleteAllItems=(true|false)`
##### Body
##### Body
/
##### Response
/
### Gegenstände `/api/items`
| Pfad | Methoden | Beschreibung | Parameter | Codes Erfolg |
| ----------------- | -------- | ----------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | ------------ |
| `/api/items/{id}` | `GET` | Gibt den Inhalt des Gegenstands zurück | / | 200 |
@@ -185,9 +229,13 @@ Leer
| | `DELETE` | Löschen eines Gegenstands | / | 204 |
#### `GET /api/items/{id}` - Inhalt des Gegenstands
##### Body Beispiel
/
##### Response Beispiel
```json
{
"status": false,
@@ -198,9 +246,11 @@ Leer
"listID": "9038b8ef-7be8-4dcb-9229-6f51b11be137"
}
```
#### `POST /api/items` - Erstellen eines Gegenstands
##### Body Beispiel
```json
{
"itemName": "Milch",
@@ -209,7 +259,9 @@ Leer
"listID": "9038b8ef-7be8-4dcb-9229-6f51b11be137"
}
```
##### Response Beispiel
```json
{
"itemName": "Milch",
@@ -218,17 +270,27 @@ Leer
"categoryID": "08bedce1-9b25-4fe6-9ede-4d9ee3a904d4"
}
```
#### `PATCH /api/items/{id}` - Bearbeiten eines Gegenstands
##### Body Beispiel
```json
{
"isDone": true
}
```
##### Response
/
#### `DELETE /api/items/{id}` - Löschen eines Gegenstands
##### Body
/
##### Response
/