Compare commits
3
Commits
af46c19651
...
179ec1206b
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
179ec1206b | ||
|
|
e22cd8c650 | ||
|
|
bb60da6aaa |
No files matched your search
@@ -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.
|
||||
@@ -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
@@ -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
|
||||
|
||||
/
|
||||
Reference in new issue
Block a user