gateway/docs/real-estate-feature-integration-guide/04-feature-logic.md

Schritt 3: Feature-Logik implementieren

← Zurück: Interface erstellen | Weiter: Routen erstellen →

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 | Weiter: Routen erstellen →