Überblick und Projektstruktur

← Zurück zum Inhaltsverzeichnis | Weiter: Datenmodell erstellen →

Ü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

6.1 KiB Raw Blame History