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

# Multi-Tenant SaaS Plattform

## Architektur-Konzept für Mandantenfähigkeit

**Version:** 1.0

**Datum:** 14. Januar 2025

**Status:** Konzept

---

## 1. Executive Summary

### Was ist das Ziel?

Wir entwickeln eine **mandantenfähige SaaS-Plattform**, die es verschiedenen Organisationen (Mandanten) ermöglicht, mehrere Geschäftsanwendungen (Features) über ein einziges System zu nutzen, während:

- ✅ **Datenisolation** zwischen Mandanten gewährleistet ist
- ✅ **Flexible Zugriffskontrolle** auf Daten- und Feldebene möglich ist
- ✅ **Ein Benutzer mit einem Account** in mehreren Mandanten arbeiten kann
- ✅ **Self-Service-Onboarding** für neue Benutzer unterstützt wird

### Hauptmerkmale

| Merkmal | Beschreibung |
| --- | --- |
| **Multi-Mandant** | Verschiedene Firmen nutzen die gleiche Plattform isoliert |
| **Multi-Feature** | Pro Mandant können verschiedene Geschäftsanwendungen aktiviert werden |
| **Ein Account, viele Rollen** | Ein Benutzer kann in verschiedenen Mandanten unterschiedliche Rollen haben |
| **Granulare Berechtigungen** | Zugriffskontrolle bis auf Feld-Ebene möglich |
| **Konfigurierbar** | Berechtigungen können als Konfiguration importiert/exportiert werden |

---

## 2. Geschäftsziele & Nutzen

### 2.1 Für die Plattform-Betreiber

**Effizienz:**

- Ein System für alle Kunden (Mandanten)
- Zentrale Wartung und Updates
- Reduzierte Infrastruktur-Kosten

**Skalierbarkeit:**

- Beliebig viele Mandanten onboardbar
- Neue Features können zentral ausgerollt werden
- Pay-per-Use Modelle möglich

**Compliance:**

- Strikte Datentrennung zwischen Mandanten
- Audit-fähige Zugriffskontrollen
- DSGVO-konform durch granulare Berechtigungen

### 2.2 Für Mandanten (Kunden)

**Flexibilität:**

- Nur die Features nutzen, die benötigt werden
- Benutzer können in mehreren Mandanten aktiv sein
- Anpassbare Berechtigungsstrukturen

**Effizienz:**

- Schnelles Onboarding neuer Mitarbeiter
- Self-Service Einladungssystem
- Zentrale Benutzerverwaltung

**Sicherheit:**

- Eigene Daten sind isoliert von anderen Mandanten
- Granulare Kontrolle über Datenzugriffe
- Nachvollziehbare Berechtigungsstruktur

### 2.3 Für End-Benutzer

**Einfachheit:**

- Ein Login für alle Mandanten
- Einfacher Wechsel zwischen Mandanten
- Klare Rollenzuordnungen

**Transparenz:**

- User sieht, in welchen Mandanten er Mitglied ist
- Klare Rollen und Berechtigungen
- Keine versteckten Zugriffe

---

## 3. Kernkonzepte

### 3.1 Was ist ein Mandant?

Ein **Mandant** ist eine Organisation (z.B. eine Firma), die die Plattform nutzt. Jeder Mandant hat:

- Eigene Benutzer
- Eigene Daten
- Eigene Feature-Instanzen

**Beispiele:**

- Treuhandbüro "Soha Treuhand"
- Beratungsfirma "Althaus Consulting"
- Immobilienfirma "Universe Corp"

### 3.2 Was ist ein Feature?

Ein **Feature** ist eine Geschäftsanwendung innerhalb der Plattform. Beispiele:

| Feature | Beschreibung | Typische Nutzer |
| --- | --- | --- |
| **Chatbot** | KI-gestützte Chatbots für verschiedene Anwendungsfälle | Kundenservice, Support |
| **Treuhand** | Buchhaltung und Treuhandverwaltung | Treuhänder, Kunden |
| **Immobilien** | Verwaltung von Immobilienprojekten | Property Manager, Mieter |

### 3.3 Was ist eine Feature-Instanz?

Ein Mandant kann **mehrere Instanzen** desselben Features haben:

**Beispiel: Mandant "Althaus"**

- Chatbot-Instanz "Produkt-Support" (für Produktfragen)
- Chatbot-Instanz "HR-Assistent" (für HR-Anfragen)
- Chatbot-Instanz "Management-Tool" (für Strategiediskussionen)

Jede Instanz hat eigene Daten und Benutzer-Berechtigungen.

### 3.4 Benutzer-Zuordnung: Das "Ein Account, viele Rollen"-Prinzip

```
Benutzerin: Shelly (shelly@universe.com)
│
├─ Mandant: Althaus
│  ├─ Rolle im Mandant: Standard-Benutzer
│  └─ Zugriff auf:
│     ├─ Chatbot "Produkt-Support" → Rolle: Administrator
│     └─ Chatbot "HR-Assistent" → Rolle: Benutzer
│
├─ Mandant: Soha Treuhand
│  ├─ Rolle im Mandant: Standard-Benutzer
│  └─ Zugriff auf:
│     └─ Treuhand "Buchhaltung 2025" → Rolle: Kunde (nur eigene Daten)
│
└─ Mandant: Universe Corp
   ├─ Rolle im Mandant: Mandanten-Administrator
   └─ Zugriff auf:
      └─ Alle Features im Mandant

```

**Ergebnis:** Shelly hat **einen Account**, aber **verschiedene Rollen** in **drei Mandanten**.

---

## 4. Benutzerrollen & Verantwortlichkeiten

### 4.1 System-Administrator

**Wer:** Plattform-Betreiber (z.B. IT-Team)

**Verantwortlichkeiten:**

- ✅ Erstellt und verwaltet Mandanten
- ✅ Schaltet Features für Mandanten frei
- ✅ Weist Benutzer zu Mandanten zu
- ✅ Definiert und verwaltet Berechtigungs-Policies
- ✅ Hat Zugriff auf alle Daten (für Support/Wartung)

**Kann NICHT:**

- ❌ Automatisch in Feature-Instanzen arbeiten (muss sich explizit Zugriff geben)

### 4.2 Mandanten-Administrator

**Wer:** Führungsperson oder IT-Verantwortlicher der Organisation

**Verantwortlichkeiten:**

- ✅ Erstellt Feature-Instanzen im eigenen Mandant
- ✅ Erstellt Einladungslinks für neue Benutzer
- ✅ Vergibt Rollen innerhalb des Mandanten
- ✅ Sieht alle Benutzer des eigenen Mandanten
- ✅ Verwaltet Feature-Instanzen

**Kann NICHT:**

- ❌ Benutzer zum Mandanten hinzufügen (nur System-Admin)
- ❌ Features für den Mandanten freischalten (nur System-Admin)
- ❌ Andere Mandanten sehen oder darauf zugreifen

**Isolation:** Ein Mandanten-Administrator sieht nur die Benutzer und Daten seines eigenen Mandanten.

### 4.3 Standard-Benutzer

**Wer:** Mitarbeiter, Kunden, Partner der Organisation

**Verantwortlichkeiten:**

- ✅ Nutzt Feature-Instanzen entsprechend seiner Rollen
- ✅ Arbeitet mit Daten im Rahmen seiner Berechtigungen

**Kann NICHT:**

- ❌ Feature-Instanzen erstellen
- ❌ Andere Benutzer verwalten
- ❌ Berechtigungen vergeben

### 4.4 Rollen innerhalb von Features

Jede Feature-Instanz hat eigene Rollen:

| Rolle | Typische Berechtigungen | Beispiel |
| --- | --- | --- |
| **Administrator** | Voller Zugriff auf alle Daten der Instanz | Chatbot-Admin sieht alle Konversationen |
| **Benutzer** | Zugriff auf Instanz-Daten, kann eigene Daten erstellen | Marketing-Mitarbeiter nutzt Chatbot |
| **Kunde** | Nur Zugriff auf eigene Daten | Treuhand-Kunde sieht nur eigene Buchhaltung |
| **Betrachter** | Nur Lesezugriff | Externer Berater sieht Berichte, kann nichts ändern |

---

## 5. Anwendungsfälle (Use Cases)

### 5.1 Use Case 1: Patrick mit mehreren Firmen

**Situation:**
Patrick hat 3 eigene Firmen und nutzt für jede ein anderes Treuhandbüro. Gleichzeitig arbeitet er als externer Berater für die Firma Althaus.

**Lösung:**

```
Benutzer: Patrick (patrick@example.com)
│
├─ Mandant: Soha Treuhand (Treuhandbüro 1)
│  └─ Treuhand-Instanz "PamoCreate AG" → Rolle: Kunde
│  └─ Treuhand-Instanz "ValueOn AG" → Rolle: Kunde
│  └─ Treuhand-Instanz "PowerOn GmbH" → Rolle: Kunde
│
├─ Mandant: SwissTreu (Treuhandbüro 2)
│  └─ Treuhand-Instanz "Firma X" → Rolle: Kunde
│
└─ Mandant: Althaus (Beratungsfirma)
   └─ Chatbot-Instanz "Management-Tool" → Rolle: Administrator

```

**Vorteile:**

- Patrick hat **einen Login** für alle Mandanten
- Patrick sieht bei Soha Treuhand nur seine 3 Firmen (nicht die Daten anderer Kunden)
- Patrick ist bei Althaus Administrator und kann dort alles verwalten
- Jeder Mandant sieht nur seine eigenen Daten

### 5.2 Use Case 2: Shelly als Multi-Mandant-Benutzer

**Situation:**
Shelly arbeitet für ihre eigene Firma "Universe Corp", unterstützt aber auch andere Firmen als Freelancerin.

**Lösung:**

```
Benutzerin: Shelly (shelly@universe.com)
│
├─ Mandant: Universe Corp (eigene Firma)
│  ├─ Rolle: Mandanten-Administrator
│  └─ Kann alle Features verwalten und Benutzer einladen
│
├─ Mandant: Althaus (Kunde als Freelancerin)
│  └─ Chatbot-Instanz "Produkt-Support" → Rolle: Administrator
│  └─ Chatbot-Instanz "HR-Assistent" → Rolle: Benutzer (nur für einen spezifischen Bot)
│
└─ Mandant: Soha Treuhand (nutzt deren Treuhand-Service)
   └─ Treuhand-Instanz "Universe Corp 2025" → Rolle: Kunde

```

**Vorteile:**

- Shelly verwaltet ihren eigenen Mandanten vollständig
- Shelly kann bei Althaus als Expertin unterstützen
- Shelly nutzt gleichzeitig Soha Treuhand als Kundin
- Klare Rollentrennung in jedem Mandanten

### 5.3 Use Case 3: Treuhandbüro mit vielen Kunden

**Situation:**
Das Treuhandbüro "Soha Treuhand" betreut 50 kleine Firmen. Jede Firma soll nur ihre eigenen Buchhaltungsdaten sehen.

**Lösung:**

```
Mandant: Soha Treuhand
│
├─ Feature: Treuhand (aktiviert)
│
├─ Feature-Instanz: "Buchhaltung 2025"
│  │
│  ├─ Mitarbeiter "Anna" → Rolle: Administrator (sieht alle Kunden)
│  ├─ Mitarbeiter "Tom" → Rolle: Benutzer (sieht alle Kunden)
│  │
│  ├─ Kunde "Patrick (PamoCreate AG)" → Rolle: Kunde (sieht nur PamoCreate)
│  ├─ Kunde "Shelly (Universe Corp)" → Rolle: Kunde (sieht nur Universe)
│  └─ ... 48 weitere Kunden ...

```

**Datenzugriff:**

- **Anna** (Administrator): Sieht alle 50 Firmen und deren Daten
- **Tom** (Benutzer): Sieht alle 50 Firmen und deren Daten
- **Patrick** (Kunde): Sieht **nur** Daten von PamoCreate AG
- **Shelly** (Kunde): Sieht **nur** Daten von Universe Corp

**Technische Umsetzung:** Automatische Filterung basierend auf "Eigentümer"-Feld in der Datenbank.

---

## 6. Datensicherheit & Isolation

### 6.1 Mandanten-Isolation

**Prinzip:** Jeder Mandant ist vollständig von anderen Mandanten getrennt.

**Konkret:**

- Mandant A sieht **keine Daten** von Mandant B
- Mandant A sieht **keine Benutzer** von Mandant B
- Mandant A kann **nicht auf Feature-Instanzen** von Mandant B zugreifen

**Ausnahme:** System-Administrator (für Support und Wartung)

### 6.2 Zugriffskontrolle: Das "n/m/g/a"-System

Für jede Rolle in einer Feature-Instanz wird der **Datenzugriff** definiert:

| Scope | Name | Beschreibung | Beispiel |
| --- | --- | --- | --- |
| **n** | None | Kein Zugriff | Kunde sieht keine Admin-Einstellungen |
| **m** | My | Nur eigene Daten | Kunde sieht nur eigene Rechnungen |
| **g** | Group | Alle Daten der Instanz | Mitarbeiter sieht alle Kunden der Instanz |
| **a** | All | Alle Daten des Features | Super-Admin sieht alle Instanzen |

**Anwendungsbeispiel:**

```
Feature: Chatbot
Instanz: "Produkt-Support"

Rolle "Kunde":
  - Konversationen: Scope "m" (my) → Nur eigene Chats
  - Einstellungen: Scope "n" (none) → Kein Zugriff

Rolle "Benutzer":
  - Konversationen: Scope "g" (group) → Alle Chats der Instanz
  - Einstellungen: Scope "n" (none) → Kein Zugriff

Rolle "Administrator":
  - Konversationen: Scope "g" (group) → Alle Chats der Instanz
  - Einstellungen: Scope "g" (group) → Voller Zugriff auf Einstellungen

```

### 6.3 Feld-Level-Sicherheit

Zusätzlich zur Tabellen-Ebene können einzelne **Datenfelder** geschützt werden:

**Beispiel: Benutzer-Tabelle**

| Feld | System-Admin | Mandanten-Admin | Standard-Benutzer |
| --- | --- | --- | --- |
| Name | Lesen/Schreiben | Lesen | Lesen (nur eigener) |
| Email | Lesen/Schreiben | Lesen | Lesen/Schreiben (nur eigene) |
| Passwort-Hash | Lesen/Schreiben | Kein Zugriff | Kein Zugriff |
| isSystemAdmin | Lesen/Schreiben | Kein Zugriff | Kein Zugriff |

**Vorteil:** Sehr granulare Kontrolle über sensible Daten.

### 6.4 Berechtigungs-Policies (Regelsets)

**Was sind Policies?**
Policies sind **konfigurierbare Regelsets**, die definieren, wer auf welche Daten zugreifen kann.

**Beispiel-Policy: "Chatbot Kunde"**

```
Policy-Name: chatbot_customer_policy
Gilt für: Rolle "Kunde" im Feature "Chatbot"

Regeln:
1. Tabelle "Konversationen" → Lesen erlaubt (Scope: my)
2. Tabelle "Konversationen" → Erstellen erlaubt (Scope: my)
3. Tabelle "Nachrichten" → Lesen erlaubt (Scope: my)
4. Tabelle "Admin-Einstellungen" → Kein Zugriff (Scope: none)

```

**Vorteile:**

- ✅ Policies können als Konfiguration exportiert/importiert werden
- ✅ Änderungen benötigen keine Code-Anpassungen
- ✅ Nachvollziehbar und audit-fähig
- ✅ Wiederverwendbar über verschiedene Mandanten

---

## 7. Onboarding-Prozesse

### 7.1 Neuer Mandant wird erstellt

```
1. System-Administrator erstellt Mandant
   └─ Mandant-Name: "Althaus"
   └─ Mandant-Typ: "Enterprise"

2. System-Administrator schaltet Features frei
   └─ Feature "Chatbot": Aktiviert
   └─ Feature "Treuhand": Nicht aktiviert

3. System-Administrator weist ersten Benutzer als Mandanten-Admin zu
   └─ User: admin@althaus.com
   └─ Rolle: Mandanten-Administrator

4. Mandanten-Administrator übernimmt
   └─ Erstellt Feature-Instanzen
   └─ Lädt weitere Benutzer ein

```

### 7.2 Neuer Benutzer wird eingeladen (Self-Service)

```
1. Mandanten-Administrator erstellt Einladungslink
   └─ Feature-Instanz: "Chatbot Produkt-Support"
   └─ Rolle: "Benutzer"
   └─ Link: https://app.example.com/register?invite=abc123
   └─ Gültigkeit: 24 Stunden

2. Administrator sendet Link an neue Mitarbeiterin

3. Neue Mitarbeiterin öffnet Link und registriert sich
   └─ Benutzername: "anna"
   └─ Email: "anna@althaus.com"
   └─ Passwort: ***

4. System erstellt automatisch:
   └─ Benutzer-Account
   └─ Zuordnung zum Mandanten "Althaus"
   └─ Rolle "Benutzer" in "Chatbot Produkt-Support"

5. Anna kann sich sofort einloggen und arbeiten

```

### 7.3 Bestehender Benutzer wird zu weiterem Mandanten hinzugefügt

```
1. System-Administrator weist Shelly zu neuem Mandanten zu
   └─ User: shelly@universe.com (besteht bereits)
   └─ Neuer Mandant: "Soha Treuhand"
   └─ Rolle: "Standard-Benutzer"

2. Mandanten-Admin von "Soha Treuhand" vergibt Feature-Rolle
   └─ Feature-Instanz: "Buchhaltung 2025"
   └─ Rolle: "Kunde"

3. Shelly erhält Email-Benachrichtigung

4. Shelly loggt sich ein und sieht neuen Mandanten im Menü
   └─ Kann zwischen "Universe Corp" und "Soha Treuhand" wechseln

```

---

## 8. Skalierbarkeit & Flexibilität

### 8.1 Skalierung von Mandanten

**Horizontal:**

- Beliebig viele Mandanten können hinzugefügt werden
- Jeder Mandant ist isoliert → keine Auswirkungen auf andere
- Neue Mandanten können in Minuten onboardet werden

**Vertikal:**

- Pro Mandant können beliebig viele Feature-Instanzen erstellt werden
- Pro Feature-Instanz können beliebig viele Benutzer hinzugefügt werden

### 8.2 Neue Features hinzufügen

```
1. Entwicklung eines neuen Features (z.B. "CRM")

2. System-Administrator erstellt Feature-Definition
   └─ Feature-Code: "crm"
   └─ Verfügbare Rollen: ["admin", "user", "viewer"]

3. System-Administrator importiert Berechtigungs-Policies
   └─ Import von JSON-Konfiguration

4. System-Administrator schaltet Feature für Mandanten frei
   └─ Mandant "Althaus" → CRM aktiviert
   └─ Mandant "Soha Treuhand" → CRM nicht aktiviert

5. Mandanten-Administratoren können Feature nutzen
   └─ Erstellen CRM-Instanzen
   └─ Laden Benutzer ein

```

**Vorteil:** Neue Features können zentral entwickelt und flexibel ausgerollt werden.

### 8.3 Anpassbare Berechtigungen

**Szenario:** Mandant "Althaus" benötigt spezielle Berechtigungsstruktur.

**Lösung:**

1. System-Administrator exportiert Standard-Policies
2. Mandanten-Administrator passt Policies an (mit Freigabe)
3. System-Administrator importiert angepasste Policies für diesen Mandanten
4. Nur "Althaus" nutzt angepasste Policies, andere Mandanten Standard

**Vorteil:** Flexibilität für Sonderanforderungen ohne Code-Änderungen.

---

## 9. Frequently Asked Questions (FAQ)

### F: Kann ein Benutzer wirklich mit einem Account in mehreren Mandanten arbeiten?

**A:** Ja, das ist ein Kernfeature. Ein Benutzer hat einen globalen Account und kann in beliebig vielen Mandanten Mitglied sein. In jedem Mandanten kann er unterschiedliche Rollen haben.

### F: Was passiert, wenn zwei Mandanten den gleichen Benutzer einladen wollen?

**A:** Da Benutzernamen eindeutig sind, Email-Adressen aber nicht, kann ein Benutzer:

- Entweder seinen bestehenden Account nutzen (System-Admin weist zu)
- Oder ein zweiter Account wird mit anderem Benutzernamen erstellt

**Empfehlung:** System-Admin weist bestehenden Account zu, sodass ein Benutzer wirklich nur einen Account benötigt.

### F: Können Mandanten-Administratoren Benutzer von anderen Mandanten sehen?

**A:** Nein, strikte Isolation. Ein Mandanten-Admin sieht nur:

- Benutzer seines eigenen Mandanten
- Feature-Instanzen seines eigenen Mandanten
- Daten seines eigenen Mandanten

### F: Wie wird sichergestellt, dass Daten zwischen Mandanten getrennt bleiben?

**A:** Mehrschichtige Sicherheit:

1. **Architektur-Ebene:** Jede Datenabfrage filtert automatisch nach Mandant
2. **Berechtigungs-Ebene:** Policies prüfen Zugriff auf Tabellen-/Feldebene
3. **Datenbank-Ebene:** Row-Level Security kann zusätzlich aktiviert werden

### F: Was ist der Unterschied zwischen "Mandanten-Admin" und "Feature-Administrator"?

**A:**

- **Mandanten-Admin:** Verwaltet den gesamten Mandanten (erstellt Feature-Instanzen, lädt Benutzer ein)
- **Feature-Administrator:** Hat Admin-Rolle in einer spezifischen Feature-Instanz (z.B. Chatbot-Admin)

Ein Benutzer kann beides gleichzeitig sein.

### F: Können Berechtigungen für einzelne Benutzer individuell angepasst werden?

**A:** Ja, über "Custom Permissions". Standard sind Rollen-basierte Policies, aber für Sonderfälle können individuelle Überschreibungen definiert werden.

### F: Wie werden neue Features ausgerollt?

**A:** Zentral und kontrolliert:

1. Feature wird entwickelt
2. System-Admin schaltet Feature für ausgewählte Mandanten frei
3. Mandanten-Admins können Feature-Instanzen erstellen
4. Schrittweises Rollout möglich (Beta-Mandanten zuerst)

### F: Was passiert, wenn ein Mandant gekündigt wird?

**A:**

1. System-Admin deaktiviert Mandanten
2. Alle Benutzer verlieren Zugriff auf diesen Mandanten
3. Daten können archiviert oder gelöscht werden (nach DSGVO)
4. Benutzer, die nur in diesem Mandanten waren, verlieren Zugriff
5. Benutzer, die in anderen Mandanten sind, behalten diese Zugriffe

---

## 10. Glossar

| Begriff | Erklärung |
| --- | --- |
| **Mandant** | Organisation (Firma), die die Plattform nutzt |
| **Feature** | Geschäftsanwendung (z.B. Chatbot, Treuhand, CRM) |
| **Feature-Instanz** | Konkrete Instanz eines Features in einem Mandanten |
| **System-Administrator** | Plattform-Betreiber mit globalen Rechten |
| **Mandanten-Administrator** | Verwalter eines spezifischen Mandanten |
| **Policy** | Konfigurierbare Berechtigungsregel |
| **Scope (n/m/g/a)** | Datenzugriffs-Bereich (None/My/Group/All) |
| **Isolation** | Strikte Trennung zwischen Mandanten |
| **Onboarding** | Prozess der Neukundenaufnahm |