wiki/implementation/Saas Multi Tenant Mandate/BACKEND_FEATURE_STRUCTURE_ANALYSIS.md

# 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 |