Mandantenfähigkeit & Idempotenz

# gateway.env
# Owner pool — runs migrations and privileged maintenance
AIHUMMER_DATABASE_URL=postgres://aihummer:***@localhost:5432/aihummer?sslmode=disable
# Restricted role — activates RLS for normal request traffic
AIHUMMER_DB_APP_URL=postgres://aihummer_app:***@localhost:5432/aihummer?sslmode=disable

side-effect requested
   └─▶ compute resume-stable ledger key
         └─▶ barrier: key already committed?
               ├─ yes ─▶ skip (no double-send)
               └─ no  ─▶ perform effect ─▶ commit key

AiHummer ist **Mehrmandantenfähig**: Ein Gateway kann viele Arbeitsbereiche aus einer einzigen Datenbank bedienen, während ihre Daten getrennt bleiben. Zwei Mechanismen machen das sicher — **Postgres Zeilen-Level-Sicherheit (RLS)** für Lese-/Schreib-Isolation und ein **Idempotenzschicht** damit Wiederholungen und Wiederherstellungen der Runde niemals einen realen Nebeneffekt duplizieren. **Tier:** Die mandantenübergreifende Isolation auf Zeilenebene wird durch die kostenpflichtige Version gesteuert **Unternehmen** Tier — nicht Teil der kostenlosen/Community-Plattform; die Idempotenzschicht ist Teil des Kerns. ## Mandantenisolation mit Zeilenebensicherheitsstufe Isolation wird auf der Datenbank durchgesetzt, nicht nur im Anwendungscode. AiHummer führt Abfragen durch eine **eingeschränkte Postgres-Rolle** (`aihummer_app`) auf die RLS-Richtlinien angewendet wurden, sodass die Datenbank selbst Zeilen ablehnt, die nicht zum aktiven Mandanten gehören. RLS ist **zustimmen**. Sie aktivieren es, indem Sie dem Gateway eine zweite Verbindungszeichenfolge für die eingeschränkte Rolle geben: ```ini # gateway.env # Owner pool — runs migrations and privileged maintenance AIHUMMER_DATABASE_URL=postgres://aihummer:***@localhost:5432/aihummer?sslmode=disable # Restricted role — activates RLS for normal request traffic AIHUMMER_DB_APP_URL=postgres://aihummer_app:***@localhost:5432/aihummer?sslmode=disable ``` > [!NOTE] > Für host-native Installationen setzt der Installer `AIHUMMER_DB_APP_URL` > automatisch, sodass RLS standardmäßig in einer Standardbereitstellung aktiviert ist. Wenn die > Variable fehlt, das Gateway läuft nur im Besitzer-Pool und RLS ist nicht aktiviert > aktiv. ### Pro-Mandanten-Abgrenzung Innerhalb der eingeschränkten Rolle ist jede Anfrage auf ihren Mandanten beschränkt: Das Gateway setzt den aktuellen Mandantenkontext auf der Verbindung, sodass RLS-Richtlinien im richtigen Arbeitsbereich aufgelöst werden. `WHERE tenant_id = …` Filter werden nicht überall von Hand erstellt; die Richtlinie erzwingt dies zentral, was bedeutet, dass ein verpasster Filter nicht die Zeilen eines anderen Mandanten durchsickern lassen kann. ### System / Umgehungsmodus Einige Arbeiten sind legitim mandantenübergreifend – Hintergrundarbeiter, Planer und Wartungsaufgaben, die über die gesamte Instanz hinweg arbeiten. Diese laufen in einem **System / Umgehungsmodus** damit sie sehen können, was sie sehen müssen. Umgehung ist für vertrauenswürdige interne Mitarbeiter reserviert, nicht für Anforderungspfadbearbeitung. > [!WARNING] > **Migrationen laufen immer im Besitzer-Pool**, niemals unter der eingeschränkten Rolle. > Die Eigentümerverbindung hat die Rechte, das Schema zu ändern und RLS anzuwenden > Richtlinien; die eingeschränkte Rolle bewusst nicht. Halten Sie die beiden Verbindungen > unterscheidbare Zeichenketten und gewähren die `aihummer_app` Rolle nur, was es braucht. ## Idempotente Nebeneffekte Eine Runde kann reale Nebeneffekte erzeugen: E-Mails senden, eine Nachricht zurück an einen Kanal posten. Wenn eine Runde erneut ausgeführt wird – wegen eines vorübergehenden Fehlers oder weil das Gateway mitten in der Runde neu gestartet wurde und die Wiederherstellung sie erneut abspielt – müssen diese Nebeneffekte **nicht** Passieren zweimal. AiHummer garantiert dies mit zwei zusammenarbeitenden Teilen. ### Ein fortsetzbarer Hauptbuchschlüssel Jede Nebenwirkung wird gegen eine aufgezeichnet **Stabile Hauptbuchschlüssel fortsetzen**: ein Schlüssel, der deterministisch aus dem Zug abgeleitet wird, sodass bei einer Wiederholung desselben Zugs derselbe Schlüssel berechnet wird und nicht ein neuer. Das Hauptbuch merkt sich, welche Schlüssel bereits verwendet wurden. ### Eine Nebenwirkungsbarriere Vor einem Effekt wie **E-Mail** oder **Kanal-senden** wird durchgeführt, durchläuft es ein **Nebenwirkungsbarriere** das das Hauptbuch überprüft. Wenn dieser Schlüssel bereits ausgelöst wurde, wird die Barriere kurzgeschlossen und die Wirkung übersprungen; wenn nicht, wird die Wirkung ausgeführt und der Schlüssel festgeschrieben. ```text side-effect requested └─▶ compute resume-stable ledger key └─▶ barrier: key already committed? ├─ yes ─▶ skip (no double-send) └─ no ─▶ perform effect ─▶ commit key ``` Das Ergebnis ist **genau-einmal externes Verhalten, obwohl die Zustellung intern mindestens-einmal erfolgt**. Wiederholungen sind per Konstruktion sicher, was die Wiederherstellung von Drehungen ermöglicht (siehe [Zuverlässige Lieferung und Wiederherstellung](/de/v1.0/architecture/delivery-outbox)) eine unterbrochene Runde erneut abspielen, ohne dass ein Kunde dieselbe E-Mail oder dieselbe Antwort zweimal erhält. > [!TIP] > Deshalb kann AiHummer garantierte Lieferung und automatische Richtungswiederherstellung anbieten > ohne das übliche Risiko doppelter Nachrichten — Idempotenz ist die Grundlage > Die Liefergarantien basieren auf. ## Wohin als Nächstes - Die Laufzeit, die eine Drehung antreibt: [Gateway- und Drehmotor](/de/v1.0/architecture/gateway-turn-engine). - Wie Antworten genau einmal zurückgegeben werden: [Zuverlässige Lieferung und Wiederherstellung](/de/v1.0/architecture/delivery-outbox).