WaiterOrder Backend

Spring Boot REST API für das Restaurant-Bestellsystem.

Gehostet unter: https://waiterorderbackend.olli.info

---

📦 Tech Stack

Technologie	Version	Beschreibung
Java	25	Programmiersprache
Spring Boot	3.5.6	Web-Framework
Spring Data JPA	-	ORM & Datenbankzugriff
H2 Database	-	Eingebettete SQL-Datenbank (file-based)
Gradle	9.2.0	Build-Tool
SpringDoc OpenAPI	2.8.0	Swagger UI & API-Dokumentation

---

🚀 Projekt starten

Voraussetzungen

• Java 25 (oder JDK 21+)
• Gradle 9.2.0+ (oder Gradle Wrapper verwenden)

Lokal starten (ohne Docker)

./gradlew bootRun

Die Anwendung startet standardmäßig auf http://localhost:8080.

Mit Docker

docker compose up -d

Backend verfügbar unter: http://localhost:16181

Tests ausführen

./gradlew test

JAR erstellen

./gradlew bootJar
# Output: build/libs/backend-0.0.1-SNAPSHOT.jar

---

🌐 Startseite & Swagger UI

Nach dem Start ist unter der Root-URL (/) eine Übersichtsseite erreichbar, die Links zu wichtigen Ressourcen bereitstellt:

URL	Beschreibung
/	Index-Seite - Übersicht mit Links zu Swagger UI, DB Schema, H2 Console
/swagger-ui.html	Swagger UI - Interaktive API-Dokumentation zum Testen aller Endpoints
/api-docs	OpenAPI JSON - Maschinenlesbare API-Spezifikation
/db-schema.html	Datenbankschema - Visualisierung der Entity-Struktur
/h2-console	H2 Console - Web-Interface für direkte Datenbankabfragen

Swagger UI Features

• Alle REST-Endpoints dokumentiert mit Request/Response-Beispielen
• Try it out - Endpoints können direkt im Browser getestet werden
• Sortierung nach HTTP-Methode und alphabetisch nach Tags
• Automatisch generiert aus Code-Annotationen

---

📁 Projektstruktur

backend/
├── src/
│   ├── main/
│   │   ├── java/hm/edu/waiter_order/
│   │   │   ├── WaiterOrderApplication.java    # Spring Boot Entry Point
│   │   │   ├── WebConfig.java                 # CORS-Konfiguration
│   │   │   │
│   │   │   ├── config/                        # Konfigurationsklassen
│   │   │   │   └── OpenApiConfig.java         # Swagger/OpenAPI Setup
│   │   │   │
│   │   │   ├── controller/                    # REST Controller (API-Layer)
│   │   │   │   ├── MenuItemController.java    # /menu Endpoints
│   │   │   │   ├── OrderController.java       # /orders Endpoints
│   │   │   │   ├── TableController.java       # /tables Endpoints
│   │   │   │   └── WaiterController.java      # /waiters Endpoints
│   │   │   │
│   │   │   ├── service/                       # Business-Logik (Service-Layer)
│   │   │   │   ├── MenuItemService.java       # Speisekarten-Logik
│   │   │   │   ├── OrderService.java          # Bestellungs-Logik
│   │   │   │   ├── TableService.java          # Tisch-Verwaltung
│   │   │   │   └── WaiterService.java         # Kellner-Verwaltung
│   │   │   │
│   │   │   ├── repository/                    # Datenzugriff (Repository-Layer)
│   │   │   │   ├── ItemRepository.java        # CRUD für Menu-Items
│   │   │   │   ├── OrdersRepository.java      # CRUD für Bestellungen
│   │   │   │   ├── OrderItemRepository.java   # CRUD für Bestellpositionen
│   │   │   │   ├── RestaurantTableRepository.java  # CRUD für Tische
│   │   │   │   └── WaiterRepository.java      # CRUD für Kellner
│   │   │   │
│   │   │   ├── entity/                        # JPA Entities (Datenbankmodelle)
│   │   │   │   ├── Item.java                  # Menu-Item Entity
│   │   │   │   ├── Orders.java                # Bestellung Entity
│   │   │   │   ├── OrderItem.java             # Bestellposition Entity
│   │   │   │   ├── RestaurantTable.java       # Tisch Entity
│   │   │   │   └── Waiter.java                # Kellner Entity
│   │   │   │
│   │   │   ├── dto/                           # Data Transfer Objects
│   │   │   │   ├── *Request.java              # Eingehende Daten (Create/Update)
│   │   │   │   ├── *Response.java             # Ausgehende Daten (API-Antworten)
│   │   │   │   └── ErrorResponse.java         # Fehler-Format
│   │   │   │
│   │   │   └── exception/                     # Exception Handling
│   │   │       └── GlobalExceptionHandler.java  # Zentrale Fehlerbehandlung
│   │   │
│   │   └── resources/
│   │       ├── application.properties         # Anwendungskonfiguration
│   │       ├── import.sql                     # Initialdaten für DB
│   │       └── static/                        # Statische Dateien
│   │           ├── index.html                 # Startseite
│   │           └── db-schema.html             # DB-Schema Visualisierung
│   │
│   └── test/                                  # Unit Tests
│       └── java/hm/edu/waiter_order/
│
├── data/                                      # H2 Datenbank-Dateien (persistent)
├── build.gradle                               # Gradle Build-Konfiguration
├── Dockerfile                                 # Docker Build
└── docker-compose.yml                         # Container-Orchestrierung

---

🏗️ Architektur & Schichten

Das Projekt folgt einer 3-Schichten-Architektur:

1. Controller-Layer (controller/)

• Verantwortung: HTTP Request/Response Handling
• Nimmt Anfragen entgegen, validiert Input, ruft Services auf
• Verwendet DTOs für Request/Response
• Annotiert mit @RestController, @RequestMapping

@RestController
@RequestMapping("/menu")
public class MenuItemController {
    private final MenuItemService menuItemService;
    
    @GetMapping
    public ResponseEntity<List<MenuItemResponse>> getMenuItems(...) { ... }
}

2. Service-Layer (service/)

• Verantwortung: Business-Logik
• Enthält die eigentliche Anwendungslogik
• Transaktionsmanagement (@Transactional)
• Validierung und Verarbeitung von Daten
• Kommuniziert mit Repositories

@Service
@Transactional(readOnly = true)
public class MenuItemService {
    private final ItemRepository itemRepository;
    
    public List<MenuItemResponse> getMenuItems(String type, String search) { ... }
    
    @Transactional
    public MenuItemResponse createItem(CreateMenuItemRequest request) { ... }
}

3. Repository-Layer (repository/)

• Verantwortung: Datenbankzugriff
• Erweitert JpaRepository für CRUD-Operationen
• Custom Query Methods nach Spring Data Naming Convention
• Native Queries mit @Query Annotation

@Repository
public interface ItemRepository extends JpaRepository<Item, Long> {
    List<Item> findByActiveTrue();
    List<Item> findByTypeAndActive(String type, Boolean active);
    List<Item> findByNameContainingIgnoreCaseAndActiveTrue(String searchTerm);
}

Entities (entity/)

• JPA-Entities mit @Entity, @Table Annotationen
• Definieren die Datenbankstruktur
• Beziehungen mit @ManyToOne, @OneToMany, etc.

DTOs (dto/)

• Request-DTOs: Eingehende Daten bei POST/PUT (CreateMenuItemRequest, UpdateOrderRequest)
• Response-DTOs: Strukturierte API-Antworten (MenuItemResponse, OrderResponse)
• Trennung von Entity und API-Repräsentation

Exception Handling (exception/)

• GlobalExceptionHandler mit @ControllerAdvice
• Einheitliche Fehlerformate mit ErrorResponse
• HTTP-Statuscodes für verschiedene Fehlertypen

---

⚙️ Konfiguration

application.properties

Die wichtigsten Konfigurationsoptionen:

# Server
spring.application.name=backend

# Datenbank
spring.datasource.url=jdbc:h2:file:./data/items    # Pfad zur DB-Datei
spring.datasource.username=item_user
spring.datasource.password=secret_pwd
spring.h2.console.enabled=true                      # H2 Web-Console aktivieren

# JPA/Hibernate
spring.jpa.hibernate.ddl-auto=create-drop          # Schema bei Start neu erstellen
spring.jpa.show-sql=true                           # SQL-Queries loggen

# Swagger/OpenAPI
springdoc.swagger-ui.path=/swagger-ui.html
springdoc.swagger-ui.try-it-out-enabled=true
springdoc.api-docs.path=/api-docs

# CORS
cors.allowed-origins=*                             # Erlaubte Origins (kommasepariert)
cors.allowed-methods=GET,POST,PUT,DELETE,OPTIONS,PATCH

Umgebungsvariablen

Können zum Überschreiben der Properties verwendet werden:

Variable	Beschreibung	Default
SERVER_PORT	Server-Port	8080
SPRING_DATASOURCE_URL	JDBC-URL für H2	jdbc:h2:file:./data/items
SPRING_DATASOURCE_USERNAME	DB-Benutzer	item_user
SPRING_DATASOURCE_PASSWORD	DB-Passwort	secret_pwd
CORS_ALLOWED_ORIGINS	Erlaubte CORS Origins	*

CORS-Konfiguration

CORS wird in WebConfig.java konfiguriert und erlaubt Frontend-Zugriff von anderen Domains:

@Override
public void addCorsMappings(CorsRegistry registry) {
    registry.addMapping("/**")
            .allowedOrigins(parseCommaSeparated(allowedOrigins))
            .allowedMethods("GET", "POST", "PUT", "DELETE", "OPTIONS", "PATCH")
            .allowedHeaders("Content-Type", "Authorization", ...)
            .maxAge(3600);
}

---

📋 API Endpoints

Vollständige API-Dokumentation: Swagger UI unter /swagger-ui.html

---

🗄️ Datenbankschema

Die Anwendung verwendet eine H2-Datenbank mit folgenden Entitäten:

• Item - Menu-Items (Speisen/Getränke) mit Versionierung
• Orders - Bestellungen mit Tisch- und Kellner-Zuordnung
• OrderItem - Einzelne Positionen einer Bestellung
• RestaurantTable - Tische im Restaurant
• Waiter - Kellner/Servicepersonal

Initialdaten werden beim Start aus import.sql geladen.

---

🔬 CI/CD

Mirror: https://git.olli.info/Oliver/WaiterOrder_Backend
CI Pipeline: https://ci.olli.info/repos/3

Pipeline-Schritte:

1. Unit Tests (gradle clean test)
2. JAR bauen (gradle bootJar)
3. Integration Tests (JAR starten und Endpoints testen)