From 5690e64dba3f3f7c4668883ff54bc7709817f9a6 Mon Sep 17 00:00:00 2001 From: ValueOn AG Date: Tue, 20 Jan 2026 00:56:31 +0100 Subject: [PATCH] updated docs --- .../BACKEND_FEATURE_STRUCTURE_ANALYSIS.md | 367 ++++++++++++++++++ .../FEATURE_NAMING_CONVENTION.md | 122 ++++++ 2 files changed, 489 insertions(+) create mode 100644 implementation/Saas Multi Tenant Mandate/BACKEND_FEATURE_STRUCTURE_ANALYSIS.md create mode 100644 implementation/Saas Multi Tenant Mandate/FEATURE_NAMING_CONVENTION.md diff --git a/implementation/Saas Multi Tenant Mandate/BACKEND_FEATURE_STRUCTURE_ANALYSIS.md b/implementation/Saas Multi Tenant Mandate/BACKEND_FEATURE_STRUCTURE_ANALYSIS.md new file mode 100644 index 0000000..f24e4e3 --- /dev/null +++ b/implementation/Saas Multi Tenant 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 | diff --git a/implementation/Saas Multi Tenant Mandate/FEATURE_NAMING_CONVENTION.md b/implementation/Saas Multi Tenant Mandate/FEATURE_NAMING_CONVENTION.md new file mode 100644 index 0000000..bffe234 --- /dev/null +++ b/implementation/Saas Multi Tenant 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*