# Schritt 3: Feature-Logik implementieren

[← Zurück: Interface erstellen](03-interfaces.md) | [Weiter: Routen erstellen →](05-routes.md)

**Datei:** `modules/features/realEstate/mainRealEstate.py`

Die Feature-Logik enthält die Geschäftslogik für das Feature. Sie wird von den Routen aufgerufen und arbeitet **stateless** ohne Session-Management.

## Übersicht: Stateless Feature-Logik mit AI-Integration

Die Feature-Logik verwendet **AI**, um natürliche Sprache direkt in CRUD-Operationen zu übersetzen - ohne Session-Management:

```
User Input (natürliche Sprache)
    ↓
AI-Analyse (Intent-Erkennung)
    ↓
CRUD-Operation identifizieren
    ↓
Parameter extrahieren
    ↓
Interface CRUD-Methode aufrufen
    ↓
Datenbank-Operation ausführen
    ↓
Ergebnis zurückgeben (keine Session-Speicherung)
```

**Beispiel:**
- User: "Erstelle ein neues Projekt namens 'Hauptstrasse 42'"
- AI analysiert → Intent: CREATE, Entity: Projekt, Parameter: {label: "Hauptstrasse 42"}
- Feature-Logik ruft auf → Interface-Methode `createProjekt()` mit extrahierten Parametern
- Ergebnis wird direkt zurückgegeben (keine Session, keine History)

## AI-Integration: Services initialisieren

Um AI zu verwenden, müssen Sie die **Services** initialisieren. Services sind eine zentrale Schnittstelle zu verschiedenen Systemkomponenten (AI, Chat, Database, etc.).

### Services-Initialisierung

**Wichtig:** 
- Services werden normalerweise im Feature-Logik-Modul initialisiert und an Funktionen weitergegeben
- Für Query-Ausführung wird `getRealEstateInterface()` verwendet, nicht `getChatInterface()`

---

## AI-basierte Intent-Erkennung und CRUD-Operationen

### Schritt 1: Intent-Analyse mit AI

Die AI analysiert User-Input und identifiziert:
- **Intent**: CREATE, READ, UPDATE, DELETE, QUERY
- **Entity**: Projekt, Parzelle, Dokument, etc.
- **Parameter**: Extrahierte Werte aus dem User-Input

### Schritt 2: CRUD-Operation ausführen

Basierend auf der AI-Analyse wird die entsprechende Interface-Methode aufgerufen.

## Wichtige Punkte:

### 1. Services-Initialisierung

- **`getServices(currentUser, workflow=None)`** - Initialisiert Services für AI-Zugriff
- **`services.ai`** - Zugriff auf AI-Service für AI-Aufrufe

### 2. AI-Aufrufe

- **`callAiPlanning()`** - Für strukturierte JSON-Antworten (Intent-Analyse, SQL-Übersetzung)
- **`callAiText()`** - Für einfache Text-Generierung
- **`callAiDocuments()`** - Für Dokumenten-Verarbeitung

### 3. Intent-Analyse

Die AI analysiert User-Input und gibt zurück:
- **Intent**: CREATE, READ, UPDATE, DELETE, QUERY
- **Entity**: Projekt, Parzelle, Dokument, etc.
- **Parameters**: Extrahierte Werte aus dem Input

### 4. CRUD-Operationen

Basierend auf der Intent-Analyse werden folgende Operationen unterstützt:

**Unterstützte Entities:**
- Projekt, Parzelle, Gemeinde, Kanton, Land, Dokument

**CREATE** → `interface.createProjekt()`, `interface.createParzelle()`, `interface.createGemeinde()`, `interface.createKanton()`, `interface.createLand()`, `interface.createDokument()`

**READ** → 
- Einzelne Entität: `interface.getProjekt(id)`, `interface.getParzelle(id)`, etc.
- Liste mit Filtern: `interface.getProjekte(recordFilter)`, `interface.getParzellen(recordFilter)`, etc.
- **Wichtig:** READ-Operationen validieren Filter-Felder gegen das Datenmodell

**UPDATE** → `interface.updateProjekt(id, updateData)`, `interface.updateParzelle(id, updateData)`, etc.

**DELETE** → `interface.deleteProjekt(id)`, `interface.deleteParzelle(id)`, etc.

**QUERY** → `interface.executeQuery(queryText, parameters)` für direkte SQL-Ausführung

### 5. Field Validation

- **READ-Operationen** validieren Filter-Felder gegen das Datenmodell
- Ungültige Felder werden ignoriert und geloggt
- **Wichtig:** Location-Queries sollten Parzelle-Entity verwenden, nicht Projekt direkt

### 6. Error Handling

- Umfassendes Error Handling für AI-Aufrufe
- JSON-Parsing mit Fallback (extrahiert JSON aus Markdown-Code-Blöcken)
- Validierung der AI-Response-Struktur
- Logging für Debugging mit `exc_info=True` für vollständige Stack-Traces
- Entity-Validierung: Prüft ob Entity existiert vor Update/Delete

---

## Vollständiger Flow: User-Input → CRUD-Operation (stateless)

### Beispiel: "Erstelle ein neues Projekt namens 'Hauptstrasse 42'"

```
1. User sendet HTTP POST Request
   POST /api/realestate/command
   Body: {"userInput": "Erstelle ein neues Projekt namens 'Hauptstrasse 42'"}
   
2. Route ruft Feature-Logik auf
   → processNaturalLanguageCommand() wird aufgerufen
   → Keine Session-ID notwendig!
   
3. Feature-Logik initialisiert Services
   → Services werden für den aktuellen User initialisiert
   → AI-Service wird aus Services abgerufen
   
4. AI analysiert User-Input
   → analyzeUserIntent() wird aufgerufen
   → AI gibt zurück: Intent "CREATE", Entity "Projekt", Parameter {"label": "Hauptstrasse 42"}
   
5. Feature-Logik führt CRUD-Operation aus
   → executeIntentBasedOperation() wird mit Intent und Parametern aufgerufen
   → Real Estate Interface wird initialisiert
   → Projekt-Objekt wird aus Parametern erstellt
   → createProjekt() wird aufgerufen
   
6. Interface speichert in Datenbank
   → Datenbank-Operation wird über Interface ausgeführt
   → PostgreSQL INSERT wird durchgeführt
   
7. Ergebnis wird direkt zurückgegeben
   → Route gibt HTTP Response zurück
   → Keine Session-Speicherung, keine History
   → Frontend zeigt Erfolg
```

---

## AI-Service Methoden im Detail

### `callAiPlanning()` - Für strukturierte Antworten

**Verwendung:** Intent-Analyse, SQL-Übersetzung, strukturierte Daten-Extraktion

**Vorteile:**
- Optimiert für strukturierte JSON-Antworten
- Verwendet beste Modelle für Planungs-Aufgaben
- Automatisches Debug-File-Writing

### `callAiText()` - Für einfache Text-Generierung

**Verwendung:** Text-Generierung, Zusammenfassungen, Erklärungen

**Hinweis:** Response ist direkt ein Text-String (kein JSON-Parsing nötig)

### `callAiDocuments()` - Für Dokumenten-Verarbeitung

**Verwendung:** Dokumenten-Analyse, Extraktion, Generierung mit Dokumenten-Kontext

**Hinweis:** Unterstützt optionales `outputFormat` Parameter für strukturierte Ausgaben (z.B. "json")

---

## Best Practices für AI-Integration

### 1. Prompt-Engineering

- **Klare Struktur**: Definieren Sie genau, welche Antwort Sie erwarten
- **Beispiele**: Geben Sie Beispiele für bessere Ergebnisse
- **Format**: Spezifizieren Sie das erwartete Format (JSON, SQL, etc.)

### 2. Error Handling

- **JSON-Parsing**: Immer try/except für JSON-Parsing
- **Fallback**: Planen Sie Fallback-Strategien bei AI-Fehlern
- **Validierung**: Validieren Sie AI-Antworten vor Verwendung

### 3. Sicherheit

- **Query-Validierung**: Validieren Sie SQL-Queries vor Ausführung
- **Parameter-Sanitization**: Sanitizen Sie alle Parameter
- **MandateId-Filter**: Stellen Sie sicher, dass MandateId immer gefiltert wird

### 4. Performance

- **Caching**: Cache häufige AI-Antworten wenn möglich
- **Model-Auswahl**: Lassen Sie das System automatisch das beste Modell wählen
- **Async**: Nutzen Sie async/await für nicht-blockierende Operationen

### 5. Debugging

- **Debug-Files**: Nutzen Sie `debugType` Parameter für Debug-Dateien
- **Logging**: Loggen Sie alle AI-Aufrufe und Antworten
- **Confidence-Scores**: Nutzen Sie Confidence-Scores für Fehlerbehandlung

---

## Erweiterte Features

### Schema-Aware Prompting

Sie können das Datenbank-Schema in Prompts einbinden, um der AI besseren Kontext zu geben. Laden Sie Schema-Informationen dynamisch und fügen Sie diese in den Prompt ein.

### Context-Aware Operations (Optional)

Falls Sie später Kontext zwischen Queries benötigen, können Sie optional eine Session verwenden. Für stateless Operationen ist dies normalerweise nicht notwendig. Falls gewünscht, können Sie vorherige Queries aus einer Session laden und als Kontext in den Prompt einbinden.

### Multi-Step Operations

Für komplexe Operationen können Sie mehrere AI-Calls machen:
1. **Intent-Analyse**: Zuerst den User-Intent analysieren
2. **Parameter-Validierung**: Optional Parameter mit AI validieren
3. **CRUD-Operation**: Die eigentliche Operation ausführen

---

[← Zurück: Interface erstellen](03-interfaces.md) | [Weiter: Routen erstellen →](05-routes.md)