gateway/docs/real-estate-feature-integration-guide/05-routes.md

Schritt 4: Routen erstellen

← Zurück: Feature-Logik implementieren | Weiter: Router registrieren →

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 | Weiter: Router registrieren →