merged readme
This commit is contained in:
parent
7017df5fa3
commit
cb52732b00
4 changed files with 256 additions and 726 deletions
|
|
@ -1,371 +0,0 @@
|
|||
# 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`
|
||||
Loading…
Add table
Add a link
Reference in a new issue