Konnektor-Roadmap (v2)¶
Status: Konsolidierter Entwurf — alle offenen Punkte geklärt Zweck: Priorisierte Planung der Konnektor-Implementierungen über mehrere Releases Abhängigkeit: Konnektor-Subsystem aus Multi-Tenancy-Fundament v4 (v1.0.0) Letzte Aktualisierung: 2026-04-24 (MediaWiki-Konnektor firm auf v1.1.0 festgelegt)
Änderungshistorie v1 → v2¶
| Änderung | Grund |
|---|---|
| Konnektoren sind tier-inklusiv, keine separate Abrechnung | Entscheidung aus Dialog — AVS bekommt Vollzugriff, Kurverwaltungen zahlen an AVS |
| AVS-Confluence-Nutzung bestätigt | AVS hat Confluence-Einsatz bestätigt — Confluence in Welle 1 ist direkter Bedarf, keine Annahme mehr |
| Semver-Versionierung mit Auto-Migration festgelegt | Aus Dialog-Block 3 |
| SDK-Stufe 2: AVS als designierter Zweit-Entwickler | Stabile interne API ohne öffentliches SDK — neuer §7.4 |
| Deprecation-Policy verbindlich festgelegt | 6 Monate + 30 Tage Notfall, dreistufig — neuer §7.5 |
Änderungshistorie v2 → v2.1 (2026-04-24)¶
| Änderung | Grund |
|---|---|
| MediaWiki-Konnektor firm auf v1.1.0 festgelegt (vorher "v1.0.0 oder v1.1.0 je nach Zeitbudget") | AVS-Realität zu MediaWiki unbestätigt; Confluence hat Priorität; 24h-Aufwand-Einsparung im v1.0.0-Budget. Siehe §2.3. |
1. Zweck¶
Das Multi-Tenancy-Fundament (v1.0.0) etabliert das Konnektor-Subsystem als echtes Framework und liefert einen ersten konkreten Konnektor (Confluence). Dieses Dokument plant den weiteren Ausbau über ~18-24 Monate.
Leitprinzipien:
- Jeder Konnektor ist eigenständig releasebar (kein Kopplungs-Zwang)
- Priorisierung nach tatsächlichem Tenant-Bedarf, nicht nach technischer Attraktivität
- Permission-Awareness wächst schrittweise
- Konnektoren werden als Python-Module ins Deployment-Paket integriert
- Konnektoren sind tier-inklusiv — kein Zusatz-Pricing, AVS entscheidet als Operator, welche Tenant-Pakete welche Konnektoren nutzen können
2. Welle 1: Kern-Konnektoren (v1.0.0 – v1.1.0)¶
| Konnektor | Version | Aufwand | Permissions | Sync |
|---|---|---|---|---|
| Upload (Refactoring) | v1.0.0 | ~8h | nein | manuell |
| Confluence (Atlassian) | v1.0.0 | ~40h | ja (Infrastruktur) | inkrementell |
| MediaWiki | v1.1.0 | ~24h | nein | inkrementell |
2.1 Upload-Konnektor (v1.0.0)¶
Refactoring des bestehenden Direct-Upload-Verhaltens zu einem Konnektor-konformen Modul. Tenant-UI-mäßig ändert sich nichts, intern läuft es über dasselbe Framework wie andere Konnektoren.
Details:
- Source-Config: {} (keine externe Konfiguration)
- Credentials: keine
- Sync-Logik: manuell getriggert durch Upload-Event
- Dokument-Ingestion: POST-multipart → temporäre Datei → Konnektor verarbeitet → Chunks
2.2 Confluence-Konnektor (v1.0.0)¶
Atlassian Confluence Cloud oder Server/Data Center via REST API.
Details:
- Source-Config: {space_key, include_labels, exclude_pages, max_depth}
- Credentials: {base_url, username, api_token} (API-Token, nicht Passwort)
- Sync-Logik:
- Vollsync: Alle Seiten im Space, paginiert
- Inkrementell: ?cql=space=KUR AND lastmodified > "<since>"
- HTML → Markdown via BeautifulSoup + Turndown-ähnlicher Wrapper
- Attachments: optional (Config-Flag)
- Permissions: restrictions.read pro Page → permissions.read_groups (in Qdrant-Payload)
- Rate-Limits: Cloud ~200 req/min (hart), Server/DC meist keine
Warum in v1.0.0:
AVS hat die Nutzung von Confluence bestätigt — der Konnektor deckt einen direkten, gesicherten Bedarf ab. Kurverwaltungs-Ebene wird durch Produktivbetrieb der Plattform erschlossen; dort ist Confluence-Nutzung optimistisch, aber nicht gesichert. Sollte sich herausstellen, dass Kurverwaltungen überwiegend andere Systeme nutzen, ist das kein Verlust — der Konnektor ist bereits für AVS-intern nützlich.
2.3 MediaWiki-Konnektor (v1.1.0)¶
Einfacher Wiki-Zugriff via MediaWiki API. Keine Permissions (oft öffentlich oder einheitlich authentifiziert).
Details:
- Source-Config: {wiki_base_url, namespace, include_categories}
- Credentials: optional {username, bot_password}
- Sync: query&list=allpages + Revision-Timestamp für Inkrement
- Wikitext → Markdown via mwparserfromhell
Zielversion (festgelegt 2026-04-24): firm v1.1.0. Gegenüber v1.0.0 bewusst in den Backlog der nächsten Minor-Version verschoben, weil die AVS-Realität bezüglich MediaWiki-Nutzung unbestätigt ist und der 24h-Aufwand bei bestätigter Confluence-Priorität vermeidbar ist. Bei bestätigter AVS-Nachfrage nach v1.0.0-Go-Live kann der Konnektor als erste v1.1.0-Lieferung priorisiert werden — Scope, Aufwand und Komponenten bleiben wie oben, nur das Release-Zeitfenster verschiebt sich.
3. Welle 2: Enterprise-Systeme (v1.2.0 – v1.3.0)¶
| Konnektor | Version | Aufwand | Permissions | Sync | Besonderheit |
|---|---|---|---|---|---|
| SharePoint (Microsoft 365) | v1.2.0 | ~80h | ja (komplex) | inkrementell | Microsoft Graph API |
| Jira (Atlassian) | v1.2.0 | ~50h | ja | inkrementell | Tickets als Dokumente |
| SharePoint (On-Premise) | v1.3.0 | +20h zu Cloud | ja | inkrementell | CSOM statt Graph |
3.1 SharePoint-Konnektor¶
Warum wichtig: In Microsoft-Welten dominant. Für AVS-Kurverwaltungen zu diesem Zeitpunkt unklar (abhängig von noch zu erhebenden Realitätsdaten), für zukünftige Kunden in anderen Branchen essenziell.
Technische Herausforderungen:
- Permission-Modell komplex: Site-Groups + Azure AD Groups + Einzelrechte + Vererbung
- Microsoft Graph API: unterschiedliche Endpoints für Lists, Pages, Documents
- Auth: Azure AD App Registration, OAuth2 Client Credentials
- Content-Types: .docx, .xlsx, .pptx, OneNote — jedes eigener Text-Extractor
Aufwand-Aufschlüsselung: - Basis (Auth, List-Traversal, Download): ~30h - Content-Extraction (Office-Formate): ~20h - Permission-Mapping zu Keycloak: ~20h (benötigt Permission-Framework Phase 2) - Testing: ~10h
3.2 Jira-Konnektor¶
Warum wichtig: Tickets enthalten oft kritisches operatives Wissen. Zweithäufigster Atlassian-Use-Case nach Confluence.
Technische Herausforderungen: - Ticket-Struktur: Summary + Description + Kommentare + Custom Fields - Empfehlung: Jedes Ticket wird ein Dokument, Kommentare als Abschnitte - Permissions: via Jira Project Permissions (einfach, wenn Framework steht)
4. Welle 3: Kommunikation (v1.4.0 – v1.5.0)¶
| Konnektor | Version | Aufwand | Permissions | Sync |
|---|---|---|---|---|
| Microsoft Teams | v1.4.0 | ~80h | ja | inkrementell |
| Slack | v1.4.0 | ~60h | ja | inkrementell |
| E-Mail (IMAP/Exchange) | v1.5.0 | ~70h | implizit | inkrementell |
4.1 Teams / Slack¶
Warum erst Welle 3: Chat-Inhalte sind rauschig. 80% der Nachrichten sind belanglos ("ok 👍"), 20% enthalten wertvolles Wissen. Ohne gute Filterung pollutiert das den Index.
Empfohlenes Vorgehen: - Nur Nachrichten mit Mindest-Länge (>20 Worte) - Bevorzugt Thread-Root-Posts - Opt-In pro Channel (nicht default alle) - Optional: LLM-Zusammenfassung eines Threads, statt Einzel-Messages indizieren
4.2 E-Mail¶
DSGVO-kritisch. Nur explizit ausgewählte Shared-Mailboxen (z.B. support@kurverwaltung.de), nie private User-Mailboxen. Opt-In durch Mailbox-Besitzer. Thread-Zusammenführung via References-Header.
5. Welle 4: Strukturierte Systeme (v2.0.0+)¶
| Konnektor | Version | Aufwand | Permissions | Sync |
|---|---|---|---|---|
| CRM (Salesforce) | v2.0.0+ | ~80h | ja (komplex) | inkrementell |
| CRM (HubSpot) | v2.0.0+ | ~60h | ja | inkrementell |
| Generische SQL-Datenbank | v2.1.0 | ~60h | nein | inkrementell |
| Zoom-Meeting-Transkripte | v2.1.0 | ~40h | implizit | pull |
| Notion | v2.2.0 | ~40h | ja | inkrementell |
5.1 Warum erst in Welle 4?¶
Strukturierte Quellen haben ein Schema, keine flachen Dokumente. Das stellt neue Anforderungen:
- Doc-Repräsentation: Wie wird ein Salesforce-Kontakt oder eine SQL-Zeile zu einem "Dokument"? Template-basierte Serialisierung zu Markdown
- Aggregations-Strategien bei hohen Datenmengen nötig
- Update-Häufigkeit oft hoch → Sync-Intervall entscheidend
5.2 Zoom-Transkripte¶
faster-whisper ist ohnehin im Stack (für STT-Modul). Zoom-Audio via API → lokal transkribieren → chunken → indizieren. Nicht Echtzeit, sondern nachgelagert.
6. Permission-Awareness-Ausbau¶
Phase 1 (v1.0.0): Infrastruktur vorhanden, nicht genutzt¶
- Konnektoren füllen
permissions.read_groupsin Qdrant-Payload - Retrieval ignoriert das Feld
- Alle Tenant-User sehen alle Tenant-Dokumente
Phase 2 (v1.1.0 oder v1.2.0): Einfache Group-Filter¶
- Keycloak-Gruppen im JWT
- Retrieval filtert:
permissions.read_groups ∩ user.groups ≠ ∅ - Voraussetzung: Tenant hat Keycloak-Gruppen definiert
Phase 3 (v1.3.0+): Quell-System-Gruppen-Mapping¶
- Confluence/SharePoint/AD-Gruppen werden als Keycloak-Gruppen automatisch provisioniert
- Konnektoren ziehen Gruppenmitgliedschaften bei jedem Sync
- Voraussetzung: AD/LDAP-Integration aktiv (Enterprise-Feature)
Phase 4 (nach v2.0.0): Dynamische Permission-Queries¶
- Live-Check statt Snapshot-basiert
- Aufwändig, präzise für schnell-wechselnde Berechtigungen
- Nur bei explizitem Bedarf
7. Konnektor-Entwicklungs-Framework¶
7.1 Was jeder neue Konnektor bekommt (einmalig aufgebaut in v1.0.0)¶
- Base-Interface (
BaseConnector) - Scheduler (APScheduler, credential-basiertes Rate-Limiting)
- Credential-Storage (AES-GCM verschlüsselt)
- Sync-Job-Logging
- Error-Handling mit Retry/Backoff
- Testing-Helpers (HTTP-Mock-Fixtures)
7.2 Entwicklungs-Workflow pro Konnektor¶
- Research (~4h)
- Config-/Credential-Schema (~2h)
- Authentication (~4-8h)
- Document-Fetching (~8-16h)
- Content-Extraction (~4-12h)
- Incremental-Sync (~4-8h)
- Permission-Extraction (~4-16h)
- Error-Handling/Retry (~2-4h)
- Testing (~4-8h)
- Dokumentation (~2-4h)
Typisch: 40-80h pro Konnektor.
7.3 Versionierung¶
Semver-basiert. PATCH/MINOR transparent, MAJOR mit UI-Hinweis. Bestehende chatbot_sources bleiben auf alter Version verknüpft, connector_version_at_creation hält Snapshot. Auto-Migration bei kompatiblen Updates, manuelle Migration bei Breaking Changes.
Die Semver-Stabilität gilt auch für das BaseConnector-Interface selbst (siehe §7.4 SDK-Stufe 2).
7.4 SDK-Stufe 2 — AVS als designierter Zweit-Entwickler¶
Entscheidung aus Dialog: Das Konnektor-Subsystem wird nicht als öffentliches SDK positioniert, aber das BaseConnector-Interface ist stabiler Contract zwischen luki und AVS.
Was das bedeutet:
- Stabile API: Breaking Changes am
BaseConnector-Interface werden wie Konnektor-Semver gehandhabt (MAJOR-Release, 6 Monate Deprecation-Frist für manuelle Migration) - AVS-Konnektor-Entwickler-Guide als Anhang im Deployment-Paket (Interface-Dokumentation, Beispiel-Implementierungen, Testing-Framework, Security-Checkliste)
- AVS-entwickelte Konnektoren werden als Pull-Requests an luki beigesteuert, durch luki code-reviewed, beim nächsten Release integriert
- Kein öffentliches SDK: Keine PyPI-Veröffentlichung, keine öffentliche Dokumentations-Website, keine Drittzertifizierung
Was das nicht ist:
- Kein Plugin-System mit Zur-Laufzeit-Loading von fremdem Code
- Keine Third-Party-Ökosystem-Strategie
- Keine Support-Verpflichtung für AVS-entwickelte Konnektoren
Wann könnte das erweitert werden?
SDK-Stufe 3 (öffentliches SDK) wäre in v2.x+ überlegenswert, wenn: - Weitere Operator-Partner außer AVS vorhanden sind - Konnektor-Nachfrage den luki-Entwicklungs-Durchsatz übersteigt - Ein kommerzielles Ökosystem-Modell erwogen wird
Für v1.x: Stufe 2 ist die Positionierung.
7.5 Deprecation-Policy¶
Verbindliche Policy, wenn ein Konnektor abgekündigt werden muss (Details in Fundament v4 §13.11):
Zeiträume: - Normal-Deprecation: 6 Monate - Security-Notfall-Deprecation: 30 Tage
Dreistufige Hilfestellung:
| Phase | Zeitpunkt | Aktion |
|---|---|---|
| 1 | Ab Ankündigung | UI-Banner im Tenant-Admin + Migrations-Leitfaden |
| 2 | 50% Frist verstrichen | E-Mail + konkrete Alternativ-Konnektor-Vorschläge |
| 3 | Letzter Monat | Tägliche UI-Warnung + Export-Tool kora-platform connector-export |
Nach Abschaltung:
- Sync gestoppt, Source als deprecated_disabled markiert
- Bereits indexierte Daten bleiben 90 Tage verfügbar
- Hard-Delete nach weiteren 90 Tagen
8. Priorisierungs-Matrix für neue Konnektor-Anfragen¶
| Kriterium | Gewichtung |
|---|---|
| Anzahl zahlende Kunden mit Bedarf | 40% |
| Implementierungs-Aufwand | 20% |
| Strategische Bedeutung (Stack-Ökosystem) | 20% |
| Permission-Komplexität passt zur Phase | 10% |
| API-Stabilität | 10% |
Bei Gleichstand: Konnektor mit besser dokumentierter API vorziehen.
9. Aufwandsgesamt-Übersicht¶
| Welle | Konnektoren | Gesamt | Release |
|---|---|---|---|
| 1 | Upload, Confluence, MediaWiki | ~72h | v1.0.0 – v1.1.0 |
| 2 | SharePoint, Jira | ~150h | v1.2.0 – v1.3.0 |
| 3 | Teams, Slack, E-Mail | ~210h | v1.4.0 – v1.5.0 |
| 4 | CRM ×2, SQL, Zoom, Notion | ~280h | v2.0.0 – v2.2.0 |
| Permissions-Framework-Ausbau | Phasen 2–4 | ~120h | v1.1.0 – v2.0.0 |
| Total 18-24 Monate | ~13 Konnektoren | ~832h |
10. Abhängigkeiten zwischen Konnektoren und Modulen¶
| Modul / Feature | Benötigte Konnektor-Welle |
|---|---|
| Chatbot-Basis (v1.0.0) | Welle 1 (Upload, Confluence) |
| Knowledge-Hub (v2.0.0) | Welle 1 komplett + Teile Welle 2 |
| Ticket-Eskalation | unabhängig (Output statt Input) |
| Analytics/Reporting | unabhängig |
11. Entscheidungs-Log¶
Alle Punkte geklärt¶
- ✅ AVS-Realitätsdaten: Confluence-Nutzung durch AVS bestätigt. Kurverwaltungs-Ebene wird durch Produktivbetrieb erschlossen.
- ✅ Confluence in Welle 1 goldrichtig — keine Annahme mehr, sondern direkte Bedarfsabdeckung
- ✅ Konnektoren tier-inklusiv (keine separate Abrechnung)
- ✅ SDK-Stufe 2 — AVS als designierter Zweit-Entwickler, stabile API, kein öffentliches SDK (Details §7.4)
- ✅ Deprecation-Policy: 6 Monate normal, 30 Tage Security-Notfall, dreistufige Hilfestellung (Details §7.5)
- ✅ AVS-Konnektor-Entwickler-Guide als Anhang im Deployment-Paket (aus SDK-Stufe 2)
Dynamisch erst mit Produktivdaten klärbar¶
Diese Punkte sind kein Konzept-Blocker, sondern werden anhand der echten Nutzung entschieden:
- Welle-2-Priorisierung (SharePoint vs. Jira): wird anhand erster Kunden-Anfragen und AVS-interner Nutzungsmuster entschieden, nicht konzeptionell vorgelegt
- Kurverwaltungs-Systeme: Indirekte Beobachtung aus
tenant_packages-Konfigurationen und Support-Anfragen während Beta-Phase - SDK-Stufe 3 (öffentliches SDK): überdenken ab v2.x, wenn mehrere Operator-Partner vorhanden sind