Compare commits

...
3 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
3 changed files with 119 additions and 30 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.
+19 -10
View File
@@ -1,8 +1,10 @@
# 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.
## Diagram
## Diagramm
```mermaid
erDiagram
@@ -57,11 +59,14 @@ 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
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.
@@ -70,15 +75,19 @@ zu bauen die an das Frontend geschickt wird.
Klassen, welche die Models aus der Datenbank zu DTOs mappen. Nötig um GET
Anfragen zu nutzen.
### Models (`Model/`)
### Models (`Models/`)
Unter `Models/` liegen die Modelle. Die Modelle werden in der Datenbank
so abgebildet wie sie in der Klasse definiert sind.
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` nutzen kann,
da man dort Bulkfunktionen wie `saveAll` und `findAll` nutzen kann,
Rückgabetypen wie `List` erlaubt sind und diese auch eine `h2`-db
Implementierung aufweist.
@@ -97,7 +106,7 @@ stellt diese bereit.
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/`.
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
@@ -113,15 +122,15 @@ sich für ein LightDOM Ansatz entschieden, da zum einen die Eventpropagation ein
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`)
### Index Seite (`/static/js/pages/index`)
Hier liegen nötige Javascriptdateien für die Root Seite `/`.
Unter `/api` liegen die API Methoden, unter `/ui` UI Methoden
Unter `/api` liegen die API Methoden, unter `/frontend` UI Methoden
### List Seite (`static/js/list`)
### List Seite (`static/js/pages/list`)
Hier liegen nötige Javascriptdateien für die Seite `/list/{id}`.
Unter `/api` liegen die API Methoden, unter `/ui` UI Methoden.
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.
+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
/