updated docs

2026-01-20 00:56:31 +01:00 · 2026-01-20 00:56:31 +01:00 · 5690e64dba
commit 5690e64dba
parent f3191a77d1
2 changed files with 489 additions and 0 deletions
--- a/Mandate/BACKEND_FEATURE_STRUCTURE_ANALYSIS.md
+++ b/Mandate/BACKEND_FEATURE_STRUCTURE_ANALYSIS.md
@ -0,0 +1,367 @@
+# Backend Feature-Struktur Analyse
+
+## 1. Übersicht Aktuelle Architektur
+
+### 1.1 Feature-Hierarchie
+
+```
+Mandate (Mandant)
+    └── FeatureInstance (Feature-Instanz)
+            └── Feature-Datenbank-Tabellen
+                    └── Datensätze mit mandateId + featureInstanceId
+```
+
+### 1.2 Datenbank-Struktur
+
+| Datenbank | Zweck | Feature |
+|-----------|-------|---------|
+| `poweron_app` | Zentrale App-Daten | System (User, Mandate, Roles, Features) |
+| `poweron_trustee` | Treuhand-Feature | Trustee |
+| `poweron_chat` | Chat-Feature | Chatbot/Workflow |
+| `poweron_realestate` | Immobilien-Feature | RealEstate |
+
+---
+
+## 2. Feature-Definitionen
+
+### 2.1 Datenmodelle (`datamodels/`)
+
+| Feature | Datenmodell-Datei | Tabellen |
+|---------|-------------------|----------|
+| **Trustee** | `datamodelTrustee.py` | TrusteeOrganisation, TrusteeRole, TrusteeAccess, TrusteeContract, TrusteeDocument, TrusteePosition, TrusteePositionDocument |
+| **RealEstate** | `datamodelRealEstate.py` | RealEstateProperty, RealEstateUnit, etc. |
+| **Chat/Workflow** | `datamodelChat.py`, `datamodelWorkflow.py` | ChatSession, ChatMessage, WorkflowExecution, etc. |
+| **Files** | `datamodelFiles.py` | StoredFile, FileMetadata |
+| **System** | `datamodelUam.py`, `datamodelMembership.py` | User, Mandate, FeatureAccess |
+| **RBAC** | `datamodelRbac.py` | Role, AccessRule |
+| **Features** | `datamodelFeatures.py` | Feature, FeatureInstance |
+
+### 2.2 Zentrale Feature-Modelle (`datamodelFeatures.py`)
+
+```python
+class Feature:
+    code: str          # PK: "trustee", "chatbot", "realestate"
+    label: dict        # I18n: {"de": "Treuhand", "en": "Trustee"}
+    icon: str          # "mdi-account-group"
+
+class FeatureInstance:
+    id: str            # UUID
+    featureCode: str   # FK → Feature.code
+    mandateId: str     # FK → Mandate.id (CASCADE DELETE)
+    label: str         # "Buchhaltung 2025"
+    enabled: bool      # True/False
+```
+
+---
+
+## 3. Interface-Schicht (`interfaces/`)
+
+### 3.1 Feature-spezifische Interfaces
+
+| Interface-Datei | Feature | Datenbank |
+|-----------------|---------|-----------|
+| `interfaceDbTrusteeObjects.py` | Trustee | poweron_trustee |
+| `interfaceDbChatObjects.py` | Chatbot | poweron_chat |
+| `interfaceDbRealEstateObjects.py` | RealEstate | poweron_realestate |
+| `interfaceDbAppObjects.py` | System | poweron_app |
+| `interfaceFeatures.py` | Feature-Verwaltung | poweron_app |
+
+### 3.2 Trustee-Interface Beispiel
+
+```python
+class TrusteeObjects:
+    def __init__(self, currentUser, mandateId, featureInstanceId):
+        # Verbindet sich mit poweron_trustee Datenbank
+        self.mandateId = mandateId
+        self.featureInstanceId = featureInstanceId
+        # Initialisiert RBAC
+        self.rbac = RbacClass(...)
+    
+    # CRUD mit RBAC + Feature-Level Filterung
+    def createOrganisation(self, data):
+        data["mandateId"] = self.mandateId
+        data["featureInstanceId"] = self.featureInstanceId
+        ...
+```
+
+### 3.3 Multi-Tenant Isolation
+
+Jedes Interface:
+1. Erhält `mandateId` und `featureInstanceId` aus dem Request-Context
+2. Setzt diese Werte automatisch bei CREATE
+3. Filtert bei READ/UPDATE/DELETE nach diesen Werten
+4. Prüft RBAC-Berechtigungen (System + Feature-Level)
+
+---
+
+## 4. Route-Schicht (`routes/`)
+
+### 4.1 Feature-Routes
+
+| Route-Datei | Prefix | Feature |
+|-------------|--------|---------|
+| `routeFeatures.py` | `/api/features` | Feature-Verwaltung |
+| `routeFeatureTrustee.py` | `/api/trustee` | Trustee-CRUD |
+| `routeFeatureChatbot.py` | `/api/chatbot` | Chatbot |
+| `routeFeatureAutomation.py` | `/api/automation` | Workflow |
+| `routeFeatureRealEstate.py` | `/api/realestate` | Immobilien |
+
+### 4.2 Trustee-Routen (mit instanceId im Pfad) ✅
+
+```
+/api/trustee/{instanceId}/organisations          GET, POST
+/api/trustee/{instanceId}/organisations/{id}     GET, PUT, DELETE
+/api/trustee/{instanceId}/roles                  GET, POST
+/api/trustee/{instanceId}/roles/{id}             GET, PUT, DELETE
+/api/trustee/{instanceId}/access                 GET, POST
+/api/trustee/{instanceId}/access/{id}            GET, PUT, DELETE
+/api/trustee/{instanceId}/contracts              GET, POST
+/api/trustee/{instanceId}/contracts/{id}         GET, PUT, DELETE
+/api/trustee/{instanceId}/documents              GET, POST
+/api/trustee/{instanceId}/documents/{id}         GET, PUT, DELETE
+/api/trustee/{instanceId}/positions              GET, POST
+/api/trustee/{instanceId}/positions/{id}         GET, PUT, DELETE
+/api/trustee/{instanceId}/position-documents     GET, POST, DELETE
+```
+
+**Validierung:** Jeder Request validiert automatisch:
+1. Existenz der FeatureInstance
+2. Zugehörigkeit zum Feature "trustee"
+3. User-Zugriff auf die Instance (via FeatureAccess)
+
+### 4.3 Feature-Verwaltungs-Routen
+
+```
+/api/features/                      GET, POST (SysAdmin)
+/api/features/{code}                GET
+/api/features/instances             GET, POST
+/api/features/instances/{id}        GET, DELETE
+/api/features/instances/{id}/sync-roles  POST
+/api/features/my                    GET (User's Instanzen)
+/api/features/templates/roles       GET, POST (SysAdmin)
+```
+
+---
+
+## 5. Status & Verbesserungsbedarf
+
+### 5.1 Erledigte Verbesserungen ✅
+
+| Verbesserung | Status | Beschreibung |
+|--------------|--------|--------------|
+| **URL mit instanceId** | ✅ Erledigt | Trustee Routes haben jetzt `/{instanceId}/` Prefix |
+| **Instance-Validierung** | ✅ Erledigt | Automatische Prüfung von Existenz, Feature-Typ und User-Zugriff |
+| **Frontend API angepasst** | ✅ Erledigt | `trusteeApi.ts` nutzt neue URL-Struktur |
+
+### 5.2 Offene Punkte
+
+| Problem | Beschreibung | Priorität |
+|---------|--------------|-----------|
+| **Andere Features** | Chatbot, Workflow, RealEstate noch ohne instanceId | Mittel |
+| **Keine Feature-Registry** | Feature-Views sind hardcoded | Niedrig |
+
+### 5.3 Aktuelle URL-Struktur (Trustee)
+
+```
+# MIT instanceId im Pfad (implementiert):
+/api/trustee/{instanceId}/organisations
+/api/trustee/{instanceId}/contracts
+/api/trustee/{instanceId}/documents
+/api/trustee/{instanceId}/positions
+...
+```
+
+---
+
+## 6. Empfohlene Feature-Struktur
+
+### 6.1 Neue Route-Struktur pro Feature
+
+```
+/api/{featureCode}/{instanceId}/{entity}
+```
+
+Beispiel Trustee:
+```
+/api/trustee/{instanceId}/organisations
+/api/trustee/{instanceId}/contracts
+/api/trustee/{instanceId}/documents
+/api/trustee/{instanceId}/positions
+```
+
+Beispiel Chatbot:
+```
+/api/chatbot/{instanceId}/sessions
+/api/chatbot/{instanceId}/messages
+```
+
+### 6.2 Feature-Definition in DB (poweron_app.Feature)
+
+```sql
+INSERT INTO "Feature" (code, label, icon) VALUES
+('trustee', '{"de": "Treuhand", "en": "Trustee"}', 'mdi-account-group'),
+('chatbot', '{"de": "Chatbot", "en": "Chatbot"}', 'mdi-robot'),
+('workflow', '{"de": "Workflow", "en": "Workflow"}', 'mdi-sitemap'),
+('realestate', '{"de": "Immobilien", "en": "Real Estate"}', 'mdi-home-city');
+```
+
+### 6.3 Feature-Datenbank-Zuordnung
+
+```python
+FEATURE_DATABASES = {
+    "trustee": "poweron_trustee",
+    "chatbot": "poweron_chat",
+    "workflow": "poweron_chat",  # Gleiche DB wie chatbot
+    "realestate": "poweron_realestate",
+}
+```
+
+---
+
+## 7. Bestehende Feature-Tabellen
+
+### 7.1 Trustee (poweron_trustee)
+
+| Tabelle | Beschreibung | Felder |
+|---------|--------------|--------|
+| `TrusteeOrganisation` | Firmen | id, label, enabled, mandateId, featureInstanceId |
+| `TrusteeRole` | Rollen | id, desc, mandateId, featureInstanceId |
+| `TrusteeAccess` | Zugriffe | id, organisationId, roleId, userId, contractId, mandateId, featureInstanceId |
+| `TrusteeContract` | Verträge | id, organisationId, label, enabled, mandateId, featureInstanceId |
+| `TrusteeDocument` | Dokumente | id, organisationId, contractId, documentName, documentData, mandateId, featureInstanceId |
+| `TrusteePosition` | Positionen | id, organisationId, contractId, valuta, bookingAmount, ..., mandateId, featureInstanceId |
+| `TrusteePositionDocument` | Verknüpfung | id, documentId, positionId, mandateId, featureInstanceId |
+
+### 7.2 Chatbot/Workflow (poweron_chat)
+
+| Tabelle | Beschreibung |
+|---------|--------------|
+| `ChatSession` | Chat-Sitzungen |
+| `ChatMessage` | Nachrichten |
+| `WorkflowExecution` | Workflow-Ausführungen |
+| `WorkflowStep` | Workflow-Schritte |
+
+### 7.3 RealEstate (poweron_realestate)
+
+| Tabelle | Beschreibung |
+|---------|--------------|
+| `RealEstateProperty` | Liegenschaften |
+| `RealEstateUnit` | Einheiten |
+| `RealEstateTenant` | Mieter |
+
+---
+
+## 8. RBAC-Struktur
+
+### 8.1 System-Level RBAC (poweron_app.Role)
+
+```python
+class Role:
+    id: str
+    roleLabel: str          # "admin", "viewer"
+    featureCode: str        # "trustee", None für System-Rollen
+    mandateId: str          # None für globale Templates
+    featureInstanceId: str  # None für Mandate-Level Rollen
+    isSystemRole: bool      # True für system-weite Rollen
+```
+
+### 8.2 Access Rules
+
+```python
+class AccessRule:
+    roleId: str
+    context: str    # "DATA", "UI", "RESOURCE"
+    item: str       # "TrusteeContract", "trustee-contracts"
+    view: bool
+    read: str       # "a" (all), "g" (group), "o" (own), "n" (none)
+    create: str
+    update: str
+    delete: str
+```
+
+### 8.3 Feature-Level RBAC (Trustee-spezifisch)
+
+```python
+# TrusteeAccess definiert Zugriff auf Organisationen
+# Rollen: "admin", "operate", "userreport"
+
+TrusteeAccess:
+    userId → User
+    organisationId → TrusteeOrganisation
+    roleId → TrusteeRole ("admin", "operate", "userreport")
+    contractId → TrusteeContract (optional, für Vertrags-Scope)
+```
+
+---
+
+## 9. Migration / Nächste Schritte
+
+### 9.1 Backend-Änderungen
+
+1. **Routes mit instanceId**
+   - [x] `routeFeatureTrustee.py` erweitern: `/api/trustee/{instanceId}/...` ✅
+   - [ ] Andere Features entsprechend anpassen (Chatbot, Workflow, RealEstate)
+
+2. **Feature-Registry**
+   - [ ] `FEATURE_REGISTRY` in Backend implementieren
+   - [ ] Views und Tabellen pro Feature definieren
+
+3. **Datenbank-Isolation**
+   - [x] Trustee-Tabellen haben `featureInstanceId` ✅
+   - [ ] Prüfen, dass alle anderen Feature-Tabellen `featureInstanceId` haben
+
+### 9.2 Frontend-Anpassungen (bereits implementiert)
+
+- [x] URL-Struktur: `/mandates/{mandateId}/{featureCode}/{instanceId}/...`
+- [x] `useCurrentInstance()` Hook
+- [x] `FeatureStore` mit `/api/features/my`
+- [x] Permission-Hooks für Tabellen und Views
+- [x] `trusteeApi.ts` mit instanceId im URL-Pfad ✅
+
+---
+
+## 10. Zusammenfassung
+
+### Aktuelle Struktur (IST)
+
+```
+Feature → hat eigene Datenbank
+Feature → hat eigene Datenmodelle (datamodel*.py)
+Feature → hat eigene Interface-Klasse (interface*.py)
+Feature → hat eigene Routes (routeFeature*.py)
+FeatureInstance → gehört zu Mandate
+Datensätze → haben mandateId + featureInstanceId
+```
+
+### Empfohlene Struktur (SOLL)
+
+```
+1. Routes mit instanceId im Pfad
+2. Feature-Registry im Backend
+3. Konsistente RBAC-Prüfung in allen Interfaces
+4. View-Definitionen pro Feature
+5. Einheitliche Datenbank-Isolation
+```
+
+### Vorhandene Features
+
+| Feature | Datenbank | Routes | Status |
+|---------|-----------|--------|--------|
+| Trustee | poweron_trustee | `/api/trustee/` | Produktiv |
+| Chatbot | poweron_chat | `/api/chatbot/` | Produktiv |
+| Workflow | poweron_chat | `/api/automation/` | Produktiv |
+| RealEstate | poweron_realestate | `/api/realestate/` | In Entwicklung |
+
+---
+
+*Erstellt: 2026-01-17*
+*Aktualisiert: 2026-01-19*
+*Analyse-Basis: poweron/gateway Backend-Code*
+
+## Änderungshistorie
+
+| Datum | Änderung |
+|-------|----------|
+| 2026-01-19 | Trustee Routes auf instanceId im URL-Pfad umgestellt |
+| 2026-01-19 | Instance-Validierung mit Zugriffsprüfung implementiert |
+| 2026-01-17 | Initiale Analyse erstellt |
--- a/Mandate/FEATURE_NAMING_CONVENTION.md
+++ b/Mandate/FEATURE_NAMING_CONVENTION.md
@ -0,0 +1,122 @@
+# Feature Naming Convention - Analyse & Umsetzung
+
+## 1. Naming Convention Standard
+
+Jedes Feature folgt dieser Namenskonvention:
+
+| Komponente | Dateiname | Beispiel (Feature: Trustee) |
+|------------|-----------|----------------------------|
+| Datenmodell | `datamodelXxx.py` | `datamodelTrustee.py` |
+| Interface | `interfaceDbXxx.py` | `interfaceDbTrustee.py` |
+| Route | `routeFeatureXxx.py` | `routeFeatureTrustee.py` |
+
+---
+
+## 2. Aktuelle Struktur (IST)
+
+### 2.1 Trustee Feature ✅
+
+| Komponente | Dateiname | Status |
+|------------|-----------|--------|
+| Datenmodell | `datamodelTrustee.py` | ✅ |
+| Interface | `interfaceDbTrustee.py` | ✅ |
+| Route | `routeFeatureTrustee.py` | ✅ |
+
+### 2.2 Chat-basierte Features (Chatbot, ChatDynamic, Workflow) ✅
+
+| Komponente | Dateiname | Beschreibung |
+|------------|-----------|--------------|
+| **Core-Datenmodell** | `datamodelChat.py` | Shared Model für alle Chat-Features |
+| Interface | `interfaceDbChatbot.py` | DB-Interface für Chat-Daten |
+| Route Chatbot | `routeFeatureChatbot.py` | Chatbot-Endpoints |
+| Route ChatDynamic | `routeFeatureChatDynamic.py` | Dynamic Chat-Endpoints |
+| Route Workflow | `routeFeatureWorkflow.py` | Workflow-Endpoints |
+
+### 2.3 RealEstate Feature ✅
+
+| Komponente | Dateiname | Status |
+|------------|-----------|--------|
+| Datenmodell | `datamodelRealEstate.py` | ✅ |
+| Interface | `interfaceDbRealEstate.py` | ✅ |
+| Route | `routeFeatureRealEstate.py` | ✅ |
+
+### 2.4 Workflow Feature ✅
+
+| Komponente | Dateiname | Status |
+|------------|-----------|--------|
+| Datenmodell | `datamodelWorkflow.py` | ✅ |
+| Interface | (Teil von Chatbot DB) | ✅ |
+| Route | `routeFeatureWorkflow.py` | ✅ |
+
+---
+
+## 3. Zusammenfassung der Änderungen
+
+### 3.1 Umbenennungen ✅ ERLEDIGT
+
+| Von | Nach | Status |
+|-----|------|--------|
+| `interfaceDbTrusteeObjects.py` | `interfaceDbTrustee.py` | ✅ |
+| `interfaceDbChatObjects.py` | `interfaceDbChatbot.py` | ✅ |
+| `interfaceDbRealEstateObjects.py` | `interfaceDbRealEstate.py` | ✅ |
+| `routeFeatureAutomation.py` | `routeFeatureWorkflow.py` | ✅ |
+
+> **Hinweis:** `datamodelChat.py` wurde **NICHT** umbenannt, da es ein Core-Datenmodell ist,
+> das von mehreren Features verwendet wird (Chatbot, ChatDynamic, Workflow).
+
+### 3.2 Betroffene Import-Stellen
+
+Nach jeder Umbenennung müssen Imports aktualisiert werden in:
+- `app.py` (Router-Registrierung)
+- Andere Route-Dateien (Cross-Imports)
+- Interface-Dateien (Model-Imports)
+- Feature-Module (Interface-Imports)
+
+---
+
+## 4. Feature-Übersicht nach Umbenennung
+
+| Feature | Datenmodell | Interface | Route | Datenbank |
+|---------|-------------|-----------|-------|-----------|
+| **Trustee** | `datamodelTrustee.py` | `interfaceDbTrustee.py` | `routeFeatureTrustee.py` | `poweron_trustee` |
+| **Chatbot** | `datamodelChat.py` (shared) | `interfaceDbChatbot.py` | `routeFeatureChatbot.py` | `poweron_chat` |
+| **ChatDynamic** | `datamodelChat.py` (shared) | `interfaceDbChatbot.py` | `routeFeatureChatDynamic.py` | `poweron_chat` |
+| **Workflow** | `datamodelChat.py` + `datamodelWorkflow.py` | `interfaceDbChatbot.py` | `routeFeatureWorkflow.py` | `poweron_chat` |
+| **RealEstate** | `datamodelRealEstate.py` | `interfaceDbRealEstate.py` | `routeFeatureRealEstate.py` | `poweron_realestate` |
+
+---
+
+## 5. Nicht-Feature Dateien (bleiben unverändert)
+
+Diese Dateien sind **keine Feature-Dateien** und folgen anderen Konventionen:
+
+### Datenmodelle (System/Shared)
+- `datamodelUam.py` - User Access Management
+- `datamodelRbac.py` - Role-Based Access Control
+- `datamodelFeatures.py` - Feature/FeatureInstance Definitionen
+- `datamodelMembership.py` - FeatureAccess
+- `datamodelPagination.py` - Pagination Utilities
+- `datamodelAudit.py` - Audit Logging
+- `datamodelFiles.py` - File Storage
+- `datamodelMessaging.py` - Email/SMS
+- `datamodelInvitation.py` - User Invitations
+
+### Interfaces (System/Shared)
+- `interfaceDbAppObjects.py` - Zentrale App-Datenbank
+- `interfaceFeatures.py` - Feature-Verwaltung
+- `interfaceRbac.py` - RBAC-Operationen
+- `interfaceMessaging.py` - Messaging-Service
+- `interfaceBootstrap.py` - System-Bootstrap
+
+### Routes (System/Admin)
+- `routeDataUsers.py` - User CRUD
+- `routeDataMandates.py` - Mandate CRUD
+- `routeRbac.py` - RBAC-Verwaltung
+- `routeFeatures.py` - Feature-Verwaltung
+- `routeAdmin.py` - Admin-Funktionen
+- `routeSecurity*.py` - Auth-Endpoints
+
+---
+
+*Erstellt: 2026-01-19*
+*Status: ✅ Alle Umbenennungen abgeschlossen*