# 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)