wiki/c-work/1-plan/2026-04-gateway-int-stability-and-bugfixes.md

Gateway: INT-Stabilität — Analyse (Log) und Fix-Plan

Beschreibung und Kontext

Beim Testen der Applikation auf der Integrations-Instanz (INT) mit mehreren parallelen Nutzern wurden Symptome im Gateway-Log sichtbar (u. a. gateway_log_2026-04-08T11-14-17-514Z.log). Ziel dieses Dokuments ist eine codebezogene Ursachenanalyse und ein Umsetzungs- und Testplan — ohne die Themen mit Architektur-Storys zu vermischen.

Business-Treiber: Zuverlässiger Multi-User-Betrieb (Upload/Index, Workspace-Agent, Outlook-Tools, Knowledge/Neutralisierung) und weniger „sporadische“ Fehler, die Support-Zeit kosten.

Risiko bei Nicht-Umsetzung: Weiterhin nicht reproduzierbar wirkende Permission-Fehler nach erfolgreicher Verarbeitung, fehlgeschlagene OpenAI-Streaming-Calls wegen Tool-Schema, nutzloser Outlook-Tool-Flow bei UUID-Referenzen, Crashes/Fail-Safe-Sprünge bei Bild-only-Indexierung.

Abhängigkeiten: Änderungen betreffen primär gateway; keine zwingende Frontend-Änderung, ausser Tool-Beschreibungen/UX explizit angepasst werden.

Fokus und kritische Details

Thema A — Management-Interface: globaler Singleton

• Fragil: interfaceDbManagement.getInterface() liefert eine gemeinsame ComponentObjects-Instanz ("default"); jeder Aufruf setzt setUserContext auf demselben Objekt.
• Edge Case: Async-Pfade (z. B. _autoIndexFile mit await knowledgeService.indexFile) — zwischen Start und updateFile kann ein anderer Request den Kontext überschreiben → PermissionError auf FileItem.update trotz erfolgreicher Indexierung.
• Code: gateway/modules/interfaces/interfaceDbManagement.py, gateway/modules/routes/routeDataFiles.py (_autoIndexFile).

Thema B — Agent-Tool-JSON-Schema: Arrays ohne items

• Fragil: ActionToolAdapter mappt List[str] auf JSON-Schema type: array ohne items.
• Edge Case: OpenAI lehnt Tools mit HTTP 400 ab (array schema missing items); Failover zu anderen Providern maskiert das Problem.
• Code: gateway/modules/serviceCenter/services/serviceAgent/actionToolAdapter.py; betroffene Aktion u. a. ai.process (methodAi.py, Parameter documentList).

Thema C — Outlook: Referenzformat vs. Lookup

• Fragil: listConnections zeigt u. a. id: <uuid>; getUserConnectionFromConnectionReference parst nur connection:{authority}:{username}.
• Edge Case: Modell übergibt UUID an Outlook-Tools → „Connection not found“.
• Code: coreTools/_connectionTools.py, mainServiceChat.getUserConnectionFromConnectionReference, methodOutlook/helpers/connection.py.

Thema D — Knowledge: _neutralSvc bei nur Bildern

• Bug: _neutralSvc wird nur im Zweig mit Textobjekten gesetzt; Bild-Neutralisierung nutzt _neutralSvc danach — bei keinen Textobjekten → UnboundLocalError (im Log als fail-safe sichtbar).
• Code: gateway/modules/serviceCenter/services/serviceKnowledge/mainServiceKnowledge.py (indexFile).

Thema E — Workspace: Mandats-Kontext aus zwei Quellen

• Fragil: _getChatInterface nutzt context.mandateId; ServiceCenterContext für den Agent nutzt Mandat aus _validateInstanceAccess (Instanz).
• Edge Case: Unterschiedliche interfaceDbChat-Cache-Keys für „denselben“ Workspace → seltene Inkonsistenzen (Workflow sichtbar / nicht sichtbar).
• Code: gateway/modules/features/workspace/routeFeatureWorkspace.py.

Thema F — Chat: createMessage / getWorkflow → None

• Fragil: getWorkflow liefert None bei leerem RBAC-Recordset und bei Exceptions beim Validieren des ChatWorkflow-Modells; createMessage meldet pauschal „No access to workflow“.
• Edge Case: Agent-Lauf endet „complete“, Persistenz der Assistant-Message schlägt fehl — Ursache ohne besseres Logging schwer trennbar.
• Code: gateway/modules/interfaces/interfaceDbChat.py.

Ziel und Nicht-Ziele

• Ziel: Die oben genannten konkreten Defekte/Risiken beheben oder absichern; INT- und Last-Szenarien reproduzierbar testen; Logging dort verbessern, wo die Ursache heute verschleiert wird.
• Explizit NICHT: Grossrefactor des gesamten Service-Centers; neue Features; umfassende Wiki-b-reference Pflege (erst nach Abschluss laut README-Lebenszyklus).

Betroffene Module

• Gateway: interfaceDbManagement, routeDataFiles, actionToolAdapter, mainServiceChat, mainServiceKnowledge, routeFeatureWorkspace, interfaceDbChat, Agent-Core-Tools (_connectionTools), optional connection.py (Outlook).
• Frontend: nein (ausser spätere Texte/Hinweise für Connection-Referenz — optional).
• DB-Migration: nein (für diese Fixes nicht erwartet).
• Andere Komponenten: nein.

Entscheidungen

Datum	Entscheidung	Begründung
2026-04-08	Plan-Dokument angelegt	INT-Log + Code-Review; Umsetzung folgt in 2-build.

Umsetzungs-Checkliste (Fix-Reihenfolge empfohlen)

• D _neutralSvc / Bildpfad in mainServiceKnowledge.indexFile absichern (klein, klar).
• B JSON-Schema für List[str] / List[int] (und ggf. weitere Array-Typen) in actionToolAdapter ergänzen.
• C Connection-Lookup UUID oder einheitliche Ausgabe/Beschreibung in listConnections + Parser in getUserConnectionFromConnectionReference.
• A Management-Interface: Request-scoped Instanz statt globalem Singleton oder dokumentierter alternativer Ansatz (kein geteilter mutable User-Kontext über await-Grenzen).
• E Workspace: einheitliche mandateId-Quelle für Chat-Interface und ServiceCenterContext nach Instanz-Validierung.
• F getWorkflow / createMessage: präziseres Logging bei Validierungsfehlern; ggf. Unterscheidung „nicht gefunden“ vs. „Daten ungültig“.

Weitere Checkliste aus Template:

• API-Endpunkte (nur falls Signatur/Kontrakt ändert)
• DB-Schema / Migration — nein
• Frontend-Komponenten — nein (optional)
• RBAC / Permissions — prüfen nach Fix A/E
• Neutralisierung betroffen? — ja (Thema D)
• Navigation / Routing — nein
• Billing-Impact? — nein (keine bewusste Änderung der Abrechnungslogik)

Akzeptanzkriterien

#	Kriterium (Given-When-Then)	Prio
AC1	Given eine Datei mit nur Bild-contentObjects und aktiver Neutralisierung, When indexFile läuft, Then kein UnboundLocalError und definiertes Verhalten (OK/skip mit Log).	must
AC2	Given generiertes Tool-Schema für ai_process, When es an die OpenAI-kompatible API geht, Then documentList ist ein array mit items (kein 400 wegen fehlender items).	must
AC3	Given listConnections liefert eine Verbindungs-UUID, When ein Outlook-Tool dieselbe Referenz nutzt, Then Verbindung wird aufgelöst oder die Tool-Konvention verbietet UUID explizit und der Agent folgt zuverlässig der Konvention.	must
AC4	Given zwei parallele Uploads/Auto-Index-Läufe unterschiedlicher User, When Indexierung endet, Then updateFile(..., active) schlägt nicht wegen fremdem User-Kontext fehl.	must
AC5	Given Workspace-Stream mit gültiger Instanz, When Chat-Interface und Agent-Chat-Service erzeugt werden, Then identische effektive mandateId/featureInstanceId-Kombination für den Chat-Cache.	should
AC6	Given getWorkflow scheitert an Datenvalidierung, When createMessage läuft, Then Log enthält ursächliche Exception, nicht nur „No access“.	should

Testplan

ID	AC	Art	Automatisiert	Repo-Pfad / Methode	Status
T1	AC1	unit	ja	gateway/tests/... — indexFile mit Mock neutralization, nur image contentObjects	pending
T2	AC2	unit	ja	Test: _buildToolDefinition / Schema für ai_process → assert properties.documentList.items	pending
T3	AC3	unit/integration	ja/teils	getUserConnectionFromConnectionReference(uuid) vs. connection:msft:user@…	pending
T4	AC4	integration	empfohlen	Zwei parallele Requests gegen INT oder lokaler Stress-Skript + assert File-Status	pending
T5	AC5	integration	optional	Request ohne Header-Mandat, mit Instanz-ID — ein Log-Punkt für effektive Chat-Keys	pending
T6	AC6	manuell/log	teils	Nach Fix: künstlich kaputtes Workflow-Datum in DB oder temporärer Log-Level	pending

Links

• PR: (nach Umsetzung)
• Issue: (falls extern getrackt)
• Ausgangs-Log (lokal): local/debug/gateway_log_2026-04-08T11-14-17-514Z.log

Abschluss

• b-reference/ aktualisiert — z. B. b-reference/gateway/architecture.md nur wenn Architektur-Entscheid (Singleton) dauerhaft geändert wird
• TOPICS.md aktualisiert (falls neues Thema)
• Dieses Dokument bei Umsetzungsbeginn nach c-work/2-build/ verschieben; nach Release nach 4-done/ bzw. z-archive/