371 lines
No EOL
8.6 KiB
Markdown
371 lines
No EOL
8.6 KiB
Markdown
# Tschunk Order API
|
|
|
|
Eine RESTful API für Tschunk-Bestellungen, entwickelt mit FastAPI.
|
|
|
|
## Features
|
|
|
|
- Bestellungen mit mehreren Getränken erstellen
|
|
- Alle Bestellungen abrufen
|
|
- Spezifische Bestellungen löschen
|
|
- Unterstützung für verschiedene Tschunk-Varianten
|
|
- Wahl zwischen Flora Mate und Club Mate
|
|
- Mengenangabe für jedes Getränk (Standard: 1)
|
|
- Anmerkungen und Sonderwünsche für jedes Getränk
|
|
- **WebSocket-Unterstützung für Echtzeit-Updates**
|
|
- **Automatisierte Tests mit pytest**
|
|
|
|
## Verfügbare Getränke
|
|
|
|
- **Tschunk**
|
|
- **Tschunk Hannover-Mische**
|
|
- **Tschunk alkoholfreier Rum**
|
|
- **Virgin Tschunk**
|
|
|
|
## Mate-Sorten
|
|
|
|
- **Flora Mate**
|
|
- **Club Mate**
|
|
|
|
## Installation
|
|
|
|
### Voraussetzungen
|
|
|
|
- Python 3.8+ installiert
|
|
|
|
### Setup
|
|
|
|
1. **Virtuelles Environment erstellen und aktivieren:**
|
|
|
|
```bash
|
|
cd backend
|
|
|
|
# Virtuelles Environment erstellen
|
|
python -m venv venv
|
|
|
|
# Virtuelles Environment aktivieren
|
|
# Unter Linux/macOS:
|
|
source venv/bin/activate
|
|
|
|
# Unter Windows:
|
|
# venv\Scripts\activate
|
|
```
|
|
|
|
2. **Abhängigkeiten installieren:**
|
|
|
|
```bash
|
|
pip install -r requirements.txt
|
|
```
|
|
|
|
## Verwendung
|
|
|
|
### Server starten
|
|
|
|
```bash
|
|
# Stelle sicher, dass das virtuelle Environment aktiviert ist
|
|
source venv/bin/activate # Linux/macOS
|
|
# venv\Scripts\activate # Windows
|
|
|
|
# Server starten
|
|
python main.py
|
|
```
|
|
|
|
Oder mit uvicorn:
|
|
|
|
```bash
|
|
uvicorn main:app --reload
|
|
```
|
|
|
|
Der Server läuft dann auf `http://localhost:8000`
|
|
|
|
### API-Dokumentation
|
|
|
|
Die automatisch generierte API-Dokumentation ist verfügbar unter:
|
|
- Swagger UI: `http://localhost:8000/docs`
|
|
- ReDoc: `http://localhost:8000/redoc`
|
|
|
|
## API-Endpunkte
|
|
|
|
### 1. Bestellung erstellen
|
|
```
|
|
POST /orders
|
|
```
|
|
|
|
Beispiel-Request:
|
|
```json
|
|
{
|
|
"drinks": [
|
|
{
|
|
"drink_type": "Tschunk",
|
|
"mate_type": "Club Mate",
|
|
"quantity": 2,
|
|
"notes": "Bitte extra kalt servieren"
|
|
},
|
|
{
|
|
"drink_type": "Virgin Tschunk",
|
|
"mate_type": "Flora Mate",
|
|
"notes": "Ohne Eiswürfel"
|
|
},
|
|
{
|
|
"drink_type": "Tschunk Hannover-Mische",
|
|
"mate_type": "Club Mate",
|
|
"quantity": 1
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
**Hinweise:**
|
|
- Das `quantity`-Feld ist optional. Falls nicht angegeben, wird automatisch 1 verwendet.
|
|
- Das `notes`-Feld ist optional und kann für Sonderwünsche oder Anmerkungen verwendet werden (max. 500 Zeichen).
|
|
- **Alle verbundenen WebSocket-Clients erhalten automatisch ein Update.**
|
|
|
|
### 2. Alle Bestellungen abrufen
|
|
```
|
|
GET /orders
|
|
```
|
|
|
|
### 3. Bestellung löschen
|
|
```
|
|
DELETE /orders/{order_id}
|
|
```
|
|
|
|
**Hinweis:** Alle verbundenen WebSocket-Clients erhalten automatisch ein Update.
|
|
|
|
### 4. Verfügbare Getränke anzeigen
|
|
```
|
|
GET /drinks
|
|
```
|
|
|
|
### 5. WebSocket für Echtzeit-Updates
|
|
```
|
|
WS /ws
|
|
```
|
|
|
|
**WebSocket-Nachrichten-Formate:**
|
|
|
|
#### Neue Bestellung:
|
|
```json
|
|
{
|
|
"type": "order_created",
|
|
"timestamp": "2024-01-15T10:30:00",
|
|
"order": {
|
|
"id": "uuid-here",
|
|
"order_date": "2024-01-15T10:30:00",
|
|
"drinks": [...]
|
|
}
|
|
}
|
|
```
|
|
|
|
#### Bestellung gelöscht:
|
|
```json
|
|
{
|
|
"type": "order_deleted",
|
|
"timestamp": "2024-01-15T10:35:00",
|
|
"order_id": "uuid-here"
|
|
}
|
|
```
|
|
|
|
#### Alle Bestellungen (bei Verbindung):
|
|
```json
|
|
{
|
|
"type": "all_orders",
|
|
"timestamp": "2024-01-15T10:30:00",
|
|
"orders": [...]
|
|
}
|
|
```
|
|
|
|
## Beispiel-Verwendung mit curl
|
|
|
|
### Bestellung erstellen:
|
|
```bash
|
|
curl -X POST "http://localhost:8000/orders" \
|
|
-H "Content-Type: application/json" \
|
|
-d '{
|
|
"drinks": [
|
|
{
|
|
"drink_type": "Tschunk",
|
|
"mate_type": "Club Mate",
|
|
"quantity": 3,
|
|
"notes": "Bitte mit Limettenscheibe garnieren"
|
|
},
|
|
{
|
|
"drink_type": "Virgin Tschunk",
|
|
"mate_type": "Flora Mate",
|
|
"notes": "Allergie gegen Zitrusfrüchte"
|
|
}
|
|
]
|
|
}'
|
|
```
|
|
|
|
### Alle Bestellungen abrufen:
|
|
```bash
|
|
curl -X GET "http://localhost:8000/orders"
|
|
```
|
|
|
|
### Bestellung löschen:
|
|
```bash
|
|
curl -X DELETE "http://localhost:8000/orders/{order_id}"
|
|
```
|
|
|
|
## WebSocket-Client Beispiel
|
|
|
|
### JavaScript (Browser):
|
|
```javascript
|
|
const ws = new WebSocket('ws://localhost:8000/ws');
|
|
|
|
ws.onopen = function() {
|
|
console.log('WebSocket verbunden');
|
|
};
|
|
|
|
ws.onmessage = function(event) {
|
|
const data = JSON.parse(event.data);
|
|
|
|
switch(data.type) {
|
|
case 'order_created':
|
|
console.log('Neue Bestellung:', data.order);
|
|
break;
|
|
case 'order_deleted':
|
|
console.log('Bestellung gelöscht:', data.order_id);
|
|
break;
|
|
case 'all_orders':
|
|
console.log('Alle Bestellungen:', data.orders);
|
|
break;
|
|
}
|
|
};
|
|
|
|
ws.onclose = function() {
|
|
console.log('WebSocket getrennt');
|
|
};
|
|
```
|
|
|
|
### Python:
|
|
```python
|
|
import asyncio
|
|
import websockets
|
|
import json
|
|
|
|
async def websocket_client():
|
|
async with websockets.connect('ws://localhost:8000/ws') as websocket:
|
|
while True:
|
|
message = await websocket.recv()
|
|
data = json.loads(message)
|
|
print(f"Empfangen: {data}")
|
|
|
|
asyncio.run(websocket_client())
|
|
```
|
|
|
|
## Testing
|
|
|
|
Das Projekt enthält mehrere Test-Optionen:
|
|
|
|
### 1. Automatisierte Tests (Empfohlen)
|
|
```bash
|
|
# Stelle sicher, dass das virtuelle Environment aktiviert ist
|
|
source venv/bin/activate
|
|
|
|
# Führe alle Tests automatisch aus
|
|
python run_tests.py
|
|
```
|
|
|
|
**Features der automatisierten Tests:**
|
|
- ✅ **Kein Server-Start nötig** - Tests laufen automatisch
|
|
- ✅ **Vollständige API-Abdeckung** - Alle Endpunkte getestet
|
|
- ✅ **WebSocket-Tests** - Echtzeit-Funktionalität getestet
|
|
- ✅ **Datenbank-Tests** - CRUD-Operationen getestet
|
|
- ✅ **Validierung-Tests** - Pydantic-Modelle getestet
|
|
- ✅ **Fehlerbehandlung** - Edge Cases getestet
|
|
|
|
### 2. Manuelle API-Tests
|
|
```bash
|
|
# Stelle sicher, dass das virtuelle Environment aktiviert ist
|
|
source venv/bin/activate
|
|
|
|
# Test-Skript ausführen
|
|
python test_api.py
|
|
```
|
|
|
|
### 3. WebSocket-Tests
|
|
```bash
|
|
# Stelle sicher, dass das virtuelle Environment aktiviert ist
|
|
source venv/bin/activate
|
|
|
|
# WebSocket-Test ausführen
|
|
python test_websocket.py
|
|
```
|
|
|
|
### 4. Erweiterte Test-Optionen
|
|
```bash
|
|
# Detaillierte pytest-Ausgabe
|
|
python -m pytest test_automated.py -v
|
|
|
|
# Nur bestimmte Tests ausführen
|
|
python -m pytest test_automated.py -k "test_create"
|
|
|
|
# Tests mit Coverage
|
|
python -m pytest test_automated.py --cov=.
|
|
|
|
# Tests parallel ausführen
|
|
python -m pytest test_automated.py -n auto
|
|
```
|
|
|
|
## Projektstruktur
|
|
|
|
```
|
|
backend/
|
|
├── main.py # FastAPI-Anwendung
|
|
├── models.py # Pydantic-Modelle
|
|
├── database.py # In-Memory-Datenbank
|
|
├── websocket_manager.py # WebSocket-Management
|
|
├── test_automated.py # Automatisierte Tests (pytest)
|
|
├── test_api.py # Manueller API-Test
|
|
├── test_websocket.py # WebSocket-Test
|
|
├── run_tests.py # Test-Runner
|
|
├── pytest.ini # pytest-Konfiguration
|
|
├── requirements.txt # Python-Abhängigkeiten
|
|
├── .gitignore # Git-Ignore-Datei
|
|
├── venv/ # Virtuelles Environment (wird ignoriert)
|
|
└── README.md # Diese Datei
|
|
```
|
|
|
|
## Hinweise
|
|
|
|
- **Virtuelles Environment**: Das Projekt verwendet ein virtuelles Environment, um Abhängigkeiten zu isolieren
|
|
- **In-Memory-Datenbank**: Die API verwendet eine In-Memory-Datenbank, d.h. alle Daten gehen beim Neustart verloren
|
|
- **Produktionsumgebung**: Für Produktionsumgebungen sollte eine persistente Datenbank verwendet werden
|
|
- **Validierung**: Die API validiert automatisch alle Eingaben mit Pydantic
|
|
- **Mengenangabe**: Jedes Getränk kann eine Menge haben (mindestens 1, Standard: 1)
|
|
- **Anmerkungen**: Jedes Getränk kann optionale Anmerkungen haben (max. 500 Zeichen)
|
|
- **Echtzeit-Updates**: WebSocket-Clients erhalten automatisch Updates bei Änderungen
|
|
- **Automatisierte Tests**: Vollständige Test-Suite mit pytest für alle Funktionen
|
|
|
|
## Troubleshooting
|
|
|
|
### Virtuelles Environment aktivieren
|
|
Falls du eine Fehlermeldung bezüglich fehlender Module erhältst, stelle sicher, dass das virtuelle Environment aktiviert ist:
|
|
|
|
```bash
|
|
# Status prüfen
|
|
which python # Sollte auf venv/bin/python zeigen
|
|
|
|
# Falls nicht aktiviert:
|
|
source venv/bin/activate
|
|
```
|
|
|
|
### Port bereits belegt
|
|
Falls Port 8000 bereits belegt ist, kannst du einen anderen Port verwenden:
|
|
|
|
```bash
|
|
uvicorn main:app --reload --port 8001
|
|
```
|
|
|
|
### WebSocket-Verbindungsprobleme
|
|
Falls WebSocket-Verbindungen nicht funktionieren:
|
|
- Stelle sicher, dass der Server läuft
|
|
- Prüfe Firewall-Einstellungen
|
|
- Verwende `ws://` für lokale Verbindungen, `wss://` für HTTPS
|
|
|
|
### Test-Probleme
|
|
Falls Tests fehlschlagen:
|
|
- Stelle sicher, dass alle Abhängigkeiten installiert sind: `pip install -r requirements.txt`
|
|
- Aktiviere das virtuelle Environment: `source venv/bin/activate`
|
|
- Führe Tests mit detaillierter Ausgabe aus: `python -m pytest test_automated.py -v` |