gateway/docs/real-estate-feature-integration-guide/01-overview.md

# Überblick und Projektstruktur

[← Zurück zum Inhaltsverzeichnis](README.md) | [Weiter: Datenmodell erstellen →](02-datamodels.md)

## Überblick

Das Feature "realEstate" bietet eine **stateless API** für Real Estate-Datenbankoperationen mit AI-basierter natürlicher Sprachverarbeitung:

### Hauptfunktionalität

- **Natürliche Sprache → CRUD-Operationen**: User-Input wird mit AI analysiert und in entsprechende Datenbankoperationen übersetzt
- **Direkte Datenbankabfragen**: SQL-Queries können direkt ausgeführt werden
- **CRUD-Operationen**: Erstellen, Lesen, Aktualisieren und Löschen von Real Estate-Entitäten
- **PostgreSQL-Datenbankzugriff**: Über den bestehenden DatabaseConnector
- **RESTful API-Endpunkte**: Einfache, stateless Endpunkte ohne Session-Management
- **Benutzerauthentifizierung und Zugriffskontrolle**: Integriert in bestehende UAM-Struktur

### Architektur-Ansatz

**Stateless Design:**
- Keine Chat-Sessions notwendig (optional für zukünftige Erweiterungen)
- Jeder Request ist unabhängig
- Direkter Flow: User-Input → AI-Analyse → CRUD-Operation → Ergebnis
- Keine Query-History (kann optional später hinzugefügt werden)

**AI-Integration:**
- Nutzt `serviceAi` für Intent-Erkennung
- Übersetzt natürliche Sprache in CRUD-Operationen
- Unterstützt CREATE, READ, UPDATE, DELETE, QUERY-Intents

**Real Estate-Datenmodell-Entitäten:**
- **Kernentitäten**: Projekt, Parzelle
- **Unterstützend**: Dokument, Kontext
- **Geografisch**: GeoPolylinie, GeoPunkt
- **Administrativ**: Land, Kanton, Gemeinde

### Architektur-Komponenten

Die Architektur folgt dem Muster bestehender Features:
- **Routes** (`modules/routes/`) - API-Endpunkte (stateless)
- **Features** (`modules/features/`) - Geschäftslogik mit AI-Integration
- **Interfaces** (`modules/interfaces/`) - Datenbankzugriff (CRUD-Operationen)
- **DataModels** (`modules/datamodels/`) - Pydantic-Modelle für Real Estate-Entitäten
- **Services** (`modules/services/`) - AI-Service für Intent-Analyse

---

## Projektstruktur

```
gateway/
├── modules/
│   ├── routes/
│   │   └── routeRealEstate.py          # NEU: Stateless API-Endpunkte
│   │       ├── POST /api/realestate/command  # Natürliche Sprache → CRUD
│   │       └── POST /api/realestate/query    # Direkte SQL-Query
│   │
│   ├── features/
│   │   └── realEstate/
│   │       └── mainRealEstate.py       # NEU: Feature-Logik mit AI-Integration
│   │           ├── processNaturalLanguageCommand()  # Hauptfunktion
│   │           ├── analyzeUserIntent()              # AI-basierte Intent-Analyse
│   │           └── executeIntentBasedOperation()    # CRUD-Ausführung
│   │
│   ├── interfaces/
│   │   ├── interfaceDbRealEstateAccess.py    # NEU: Zugriffskontrolle
│   │   ├── interfaceDbRealEstateObjects.py   # NEU: CRUD-Interface
│   │   └── interfaceDbRealEstateChatObjects.py  # OPTIONAL: Für Session-Support
│   │
│   ├── datamodels/
│   │   ├── datamodelRealEstate.py      # NEU: Real Estate Datenmodelle
│   │   │   ├── Projekt, Parzelle, Dokument, etc.
│   │   └── datamodelRealEstateChat.py  # OPTIONAL: Für Session-Support
│   │
│   ├── services/
│   │   └── serviceAi/                  # BEREITS VORHANDEN
│   │       └── mainServiceAi.py        # Wird für Intent-Analyse genutzt
│   │
│   └── connectors/
│       └── connectorDbPostgre.py       # BEREITS VORHANDEN
│
├── app.py                              # Router-Registrierung
├── env_dev.env                         # Environment-Konfiguration
└── modules/features/featuresLifecycle.py  # Feature-Lifecycle
```

### Wichtige Dateien

**Erforderlich:**
- `routeRealEstate.py` - API-Endpunkte (stateless)
- `mainRealEstate.py` - Feature-Logik mit AI-Integration
- `interfaceDbRealEstateAccess.py` - Zugriffskontrolle
- `interfaceDbRealEstateObjects.py` - CRUD-Interface
- `datamodelRealEstate.py` - Datenmodelle

**Optional (für zukünftige Session-Unterstützung):**
- `interfaceDbRealEstateChatObjects.py` - Session-Management
- `datamodelRealEstateChat.py` - Session-Modelle

---

## Datenfluss: User-Input → Ergebnis

### Flow: Natürliche Sprache ohne Session

```
1. User sendet Request
   POST /api/realestate/command
   Body: { "userInput": "Erstelle ein neues Projekt namens 'Hauptstrasse 42'" }

2. Route empfängt Request
   routeRealEstate.process_command()
   → Auth: getCurrentUser()

3. Feature-Logik verarbeitet
   mainRealEstate.processNaturalLanguageCommand()
   → Services initialisieren: getServices(currentUser, workflow=None)

4. AI analysiert Intent
   analyzeUserIntent(services.ai, userInput)
   → services.ai.callAiPlanning(intentPrompt)
   → AI gibt zurück: { "intent": "CREATE", "entity": "Projekt", "parameters": {...} }

5. CRUD-Operation ausführen
   executeIntentBasedOperation(intent, entity, parameters)
   → getRealEstateInterface(currentUser)
   → RealEstateObjects.createProjekt(projekt)
   → DatabaseConnector.recordCreate(Projekt)

6. Ergebnis zurückgeben
   HTTP 200 OK
   { "success": true, "intent": "CREATE", "result": {...} }
```

### Flow: Direkte SQL-Query

```
1. User sendet Request
   POST /api/realestate/query
   Body: { "queryText": "SELECT * FROM Projekt WHERE plz = '8000'" }

2. Route empfängt Request
   routeRealEstate.execute_direct_query()
   → Auth: getCurrentUser()

3. Query ausführen
   getChatInterface(currentUser)
   → RealEstateChatObjects.executeQuery(queryText)
   → DatabaseConnector.executeQuery(sql)

4. Ergebnis zurückgeben
   HTTP 200 OK
   { "rows": [...], "columns": [...], "rowCount": 15 }
```

---

## 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
- **Erweiterbarkeit**: Session-Support kann später optional hinzugefügt werden

---

**Nächster Schritt:** [02-datamodels.md](02-datamodels.md)