diff --git a/README.md b/README.md index ebc38fe..dff3089 100644 --- a/README.md +++ b/README.md @@ -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. diff --git a/docs/DATENMODELL-ARCHITEKTUR.md b/docs/DATENMODELL-ARCHITEKTUR.md new file mode 100644 index 0000000..c90183c --- /dev/null +++ b/docs/DATENMODELL-ARCHITEKTUR.md @@ -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. diff --git a/docs/api.md b/docs/api.md index 0af59ea..99e5e8b 100644 --- a/docs/api.md +++ b/docs/api.md @@ -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 + /