225 lines
6.5 KiB
Markdown
225 lines
6.5 KiB
Markdown
# Schritt 4: Routen erstellen
|
|
|
|
[← Zurück: Feature-Logik implementieren](04-feature-logic.md) | [Weiter: Router registrieren →](06-router-registration.md)
|
|
|
|
**Datei:** `modules/routes/routeRealEstate.py`
|
|
|
|
Die Routen definieren die REST-API-Endpunkte für das Feature. Das Feature arbeitet **stateless** ohne Session-Management.
|
|
|
|
## Route-Struktur
|
|
|
|
```
|
|
/api/realestate/
|
|
├── POST /command → Natürliche Sprache → CRUD-Operation
|
|
├── POST /query → Direkte SQL-Query
|
|
├── GET /tables → Liste aller verfügbaren Tabellen
|
|
├── GET /table/{table} → Daten aus einer Tabelle (mit optionaler Pagination)
|
|
└── POST /table/{table} → Neuen Datensatz in einer Tabelle erstellen
|
|
```
|
|
|
|
## Wichtige Punkte:
|
|
|
|
### 1. Stateless Design
|
|
|
|
- **Keine Session-Management**: Alle Endpunkte arbeiten stateless
|
|
- **Direkte Verarbeitung**: User-Input wird direkt verarbeitet und Ergebnis zurückgegeben
|
|
- **Keine History**: Queries werden nicht gespeichert (kann optional später hinzugefügt werden)
|
|
|
|
### 2. API-Endpunkte
|
|
|
|
**`POST /api/realestate/command`**
|
|
- Verarbeitet natürliche Sprache
|
|
- Nutzt AI für Intent-Analyse
|
|
- Führt CRUD-Operationen aus
|
|
- Gibt Ergebnis direkt zurück
|
|
- **CSRF-Token erforderlich** (X-CSRF-Token Header)
|
|
|
|
**`POST /api/realestate/query`**
|
|
- Führt direkte SQL-Queries aus
|
|
- Request Body: `{"queryText": "...", "parameters": {...}}`
|
|
- Keine Session notwendig
|
|
- Gibt Query-Ergebnis direkt zurück
|
|
- **CSRF-Token erforderlich** (X-CSRF-Token Header)
|
|
|
|
**`GET /api/realestate/tables`**
|
|
- Gibt Liste aller verfügbaren Tabellen zurück
|
|
- Enthält Tabellennamen, Beschreibungen und Model-Namen
|
|
- **CSRF-Token erforderlich** (X-CSRF-Token Header)
|
|
|
|
**`GET /api/realestate/table/{table}`**
|
|
- Gibt alle Daten aus einer spezifischen Tabelle zurück
|
|
- Unterstützt optionale Pagination über Query-Parameter
|
|
- Sortierung und Filterung möglich
|
|
- Leere Tabellen geben ein leeres Modell-Instanz zurück (für Schema-Extraktion)
|
|
- **CSRF-Token erforderlich** (X-CSRF-Token Header)
|
|
|
|
**`POST /api/realestate/table/{table}`**
|
|
- Erstellt einen neuen Datensatz in einer spezifischen Tabelle
|
|
- Request Body enthält die Datensatz-Daten
|
|
- mandateId wird automatisch gesetzt falls nicht vorhanden
|
|
- **CSRF-Token erforderlich** (X-CSRF-Token Header)
|
|
|
|
### 3. Sicherheit
|
|
|
|
- **Rate Limiting**: 120 Requests pro Minute für alle Endpunkte
|
|
- **Authentication**: Alle Endpunkte erfordern authentifizierte User
|
|
- **CSRF-Token-Validierung**: Alle Endpunkte validieren CSRF-Token im X-CSRF-Token Header
|
|
- Token muss hexadezimaler String sein
|
|
- Token-Länge: 16-64 Zeichen
|
|
- Fehlende oder ungültige Token führen zu 403 Forbidden
|
|
- **Query-Validierung**: WICHTIG - Validieren Sie SQL-Queries vor Ausführung
|
|
- **MandateId-Filter**: Wird automatisch durch Interfaces angewendet
|
|
|
|
### 4. Error Handling
|
|
|
|
- Umfassendes Error Handling mit HTTPException
|
|
- Unterschiedliche Status-Codes:
|
|
- **400 Bad Request**: Validierungsfehler (z.B. fehlende Parameter, ungültige Daten)
|
|
- **403 Forbidden**: CSRF-Token fehlt oder ist ungültig
|
|
- **404 Not Found**: Ressource nicht gefunden
|
|
- **500 Internal Server Error**: Server-Fehler
|
|
- Detaillierte Fehlermeldungen für Debugging
|
|
- Logging mit vollständigen Stack-Traces (`exc_info=True`)
|
|
|
|
### 5. Response-Struktur
|
|
|
|
**Command-Endpunkt:**
|
|
- Erfolgreiche Response enthält: `success`, `intent`, `entity`, `result`
|
|
- Result enthält die Operation-Details und das erstellte/aktualisierte/gelesene Objekt
|
|
|
|
**Query-Endpunkt:**
|
|
- Response enthält: `status`, `rows`, `columns`, `rowCount`, `executionTime`
|
|
|
|
**Tables-Endpunkt:**
|
|
- Response enthält: `tables` (Array mit Tabellen-Informationen), `count`
|
|
|
|
**Table GET-Endpunkt:**
|
|
- Response ist eine `PaginatedResponse` mit `items` und `pagination` Metadata
|
|
- Ohne Pagination: Alle Items werden zurückgegeben
|
|
- Mit Pagination: Enthält `currentPage`, `pageSize`, `totalItems`, `totalPages`, `sort`, `filters`
|
|
|
|
**Table POST-Endpunkt:**
|
|
- Response ist das erstellte Objekt als Dictionary (model_dump())
|
|
|
|
---
|
|
|
|
## Flow: Route → Feature-Logik
|
|
|
|
### Command-Endpunkt Flow
|
|
|
|
```
|
|
POST /api/realestate/command
|
|
↓
|
|
CSRF-Token-Validierung
|
|
↓
|
|
routeRealEstate.process_command()
|
|
↓
|
|
getCurrentUser() # Auth
|
|
↓
|
|
processNaturalLanguageCommand(currentUser, userInput)
|
|
↓
|
|
mainRealEstate.processNaturalLanguageCommand()
|
|
↓
|
|
analyzeUserIntent() → executeIntentBasedOperation()
|
|
↓
|
|
return Dict mit Ergebnis
|
|
```
|
|
|
|
### Query-Endpunkt Flow
|
|
|
|
```
|
|
POST /api/realestate/query
|
|
↓
|
|
CSRF-Token-Validierung
|
|
↓
|
|
routeRealEstate.execute_query()
|
|
↓
|
|
getCurrentUser() # Auth
|
|
↓
|
|
Body-Parsing (queryText, parameters)
|
|
↓
|
|
executeDirectQuery(currentUser, queryText, parameters)
|
|
↓
|
|
mainRealEstate.executeDirectQuery()
|
|
↓
|
|
getRealEstateInterface(currentUser)
|
|
↓
|
|
Interface.executeQuery(queryText, parameters)
|
|
↓
|
|
return Dict mit rows, columns, rowCount
|
|
```
|
|
|
|
### Table-Endpunkte Flow
|
|
|
|
**GET /api/realestate/table/{table}:**
|
|
```
|
|
GET /api/realestate/table/{table}
|
|
↓
|
|
CSRF-Token-Validierung
|
|
↓
|
|
getCurrentUser() # Auth
|
|
↓
|
|
Tabellen-Name validieren
|
|
↓
|
|
getRealEstateInterface(currentUser)
|
|
↓
|
|
Interface.getProjekte() / getParzellen() / etc.
|
|
↓
|
|
Pagination anwenden (falls angegeben)
|
|
↓
|
|
return PaginatedResponse
|
|
```
|
|
|
|
**POST /api/realestate/table/{table}:**
|
|
```
|
|
POST /api/realestate/table/{table}
|
|
↓
|
|
CSRF-Token-Validierung
|
|
↓
|
|
getCurrentUser() # Auth
|
|
↓
|
|
Tabellen-Name validieren
|
|
↓
|
|
Model-Instanz aus Body-Daten erstellen
|
|
↓
|
|
getRealEstateInterface(currentUser)
|
|
↓
|
|
Interface.createProjekt() / createParzelle() / etc.
|
|
↓
|
|
return erstelltes Objekt
|
|
```
|
|
|
|
---
|
|
|
|
## Verfügbare Tabellen
|
|
|
|
Die folgenden Tabellen sind verfügbar:
|
|
- **Projekt**: Real estate projects
|
|
- **Parzelle**: Plots/parcels
|
|
- **Dokument**: Documents
|
|
- **Gemeinde**: Municipalities
|
|
- **Kanton**: Cantons
|
|
- **Land**: Countries
|
|
|
|
## Pagination
|
|
|
|
Der `GET /api/realestate/table/{table}` Endpunkt unterstützt Pagination über einen Query-Parameter:
|
|
|
|
- **Parameter**: `pagination` (JSON-encoded string)
|
|
- **Format**: `{"page": 1, "pageSize": 10, "sort": [{"field": "label", "direction": "asc"}], "filters": []}`
|
|
- **Ohne Pagination**: Alle Datensätze werden zurückgegeben
|
|
|
|
## Vorteile des stateless Ansatzes
|
|
|
|
- **Einfachheit**: Kein Session-Management notwendig
|
|
- **Performance**: Weniger Datenbank-Operationen pro Request
|
|
- **Skalierbarkeit**: Stateless Requests sind einfacher zu skalieren
|
|
- **Flexibilität**: Jeder Request ist unabhängig
|
|
- **Schnell**: Direkte Verarbeitung ohne Overhead
|
|
|
|
---
|
|
|
|
[← Zurück: Feature-Logik implementieren](04-feature-logic.md) | [Weiter: Router registrieren →](06-router-registration.md)
|
|
|
|
|
|
|