wiki/appdoc/doc_architecture_workflow.html

654 lines
29 KiB
HTML

<!DOCTYPE html>
<html lang="de">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>PowerON - Workflow Engine Dokumentation</title>
<style>
* {
margin: 0;
padding: 0;
box-sizing: border-box;
}
body {
font-family: 'Segoe UI', Tahoma, Geneva, Verdana, sans-serif;
background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
color: #333;
padding: 20px;
line-height: 1.6;
}
.container {
max-width: 1400px;
margin: 0 auto;
background: white;
border-radius: 20px;
padding: 40px;
box-shadow: 0 20px 60px rgba(0,0,0,0.3);
}
h1 {
color: #667eea;
font-size: 2.5em;
margin-bottom: 10px;
text-align: center;
border-bottom: 4px solid #764ba2;
padding-bottom: 20px;
}
h2 {
color: #764ba2;
font-size: 2em;
margin-top: 40px;
margin-bottom: 20px;
border-left: 5px solid #667eea;
padding-left: 15px;
}
h3 {
color: #667eea;
font-size: 1.5em;
margin-top: 30px;
margin-bottom: 15px;
}
.diagram {
background: #f8f9fa;
border: 2px solid #667eea;
border-radius: 10px;
padding: 30px;
margin: 30px 0;
position: relative;
overflow: hidden;
}
.workflow-box {
background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
color: white;
padding: 20px;
border-radius: 10px;
margin: 15px 0;
box-shadow: 0 5px 15px rgba(0,0,0,0.2);
transition: transform 0.3s ease;
}
.workflow-box:hover {
transform: translateY(-5px);
}
.workflow-box h4 {
font-size: 1.3em;
margin-bottom: 10px;
}
.info-box {
background: #d1ecf1;
border: 2px solid #0c5460;
border-radius: 10px;
padding: 20px;
margin: 20px 0;
}
.warning-box {
background: #fff3cd;
border: 2px solid #856404;
border-radius: 10px;
padding: 15px;
margin: 20px 0;
}
.success-box {
background: #d4edda;
border: 2px solid #28a745;
border-radius: 10px;
padding: 15px;
margin: 20px 0;
}
.step-box {
background: white;
border-left: 5px solid #667eea;
border-radius: 5px;
padding: 15px;
margin: 15px 0;
box-shadow: 0 3px 10px rgba(0,0,0,0.1);
}
.action-item {
background: #e8ebf5;
border: 1px solid #764ba2;
border-radius: 5px;
padding: 12px;
margin: 10px 0;
margin-left: 20px;
font-size: 0.95em;
}
.label-box {
background: #f0f7ff;
border: 2px dashed #667eea;
border-radius: 8px;
padding: 15px;
margin: 15px 0;
font-family: 'Courier New', monospace;
font-size: 0.9em;
}
.feature-grid {
display: grid;
grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
gap: 20px;
margin: 20px 0;
}
.feature-card {
background: white;
border: 2px solid #667eea;
border-radius: 10px;
padding: 20px;
transition: all 0.3s ease;
}
.feature-card:hover {
box-shadow: 0 10px 25px rgba(102, 126, 234, 0.3);
transform: translateY(-3px);
}
.feature-card h4 {
color: #764ba2;
margin-bottom: 10px;
font-size: 1.2em;
}
code {
background: #f4f4f4;
padding: 2px 6px;
border-radius: 3px;
font-family: 'Courier New', monospace;
color: #e83e8c;
}
ul, ol {
margin-left: 30px;
margin-top: 10px;
}
li {
margin: 8px 0;
}
.highlight {
background: #fff3cd;
padding: 2px 6px;
border-radius: 3px;
font-weight: bold;
}
.flow-diagram {
display: flex;
flex-direction: column;
align-items: center;
gap: 20px;
margin: 30px 0;
}
.flow-box {
background: white;
border: 3px solid #667eea;
border-radius: 10px;
padding: 20px;
width: 80%;
text-align: center;
}
.flow-arrow {
font-size: 2em;
color: #667eea;
}
.connector-badge {
display: inline-block;
background: #667eea;
color: white;
padding: 5px 12px;
border-radius: 20px;
font-size: 0.9em;
margin: 5px;
}
</style>
</head>
<body>
<div class="container">
<h1>PowerON Workflow Engine</h1>
<div class="info-box">
<strong>📖 Dokumentation:</strong> Diese Dokumentation beschreibt die PowerON Workflow Engine für Kunden. Die Engine ermöglicht es, komplexe Multi-Step Workflows zu erstellen, die automatisch Dokumente verarbeiten, AI-Analysen durchführen und Ergebnisse über verschiedene Kanäle weiterleiten.
</div>
<h2>1. Workflow-Struktur: Tasks und Actions</h2>
<div class="diagram">
<h3>🏗️ Hierarchische Workflow-Struktur</h3>
<div class="workflow-box">
<h4>📦 Workflow</h4>
<p>Ein Workflow ist ein vollständiger Geschäftsprozess, der aus mehreren Tasks besteht.</p>
<p><strong>Status:</strong> running, stopped, completed, failed</p>
</div>
<div class="flow-arrow" style="text-align: center; margin: 20px 0;">⬇️</div>
<div class="step-box">
<h4>📋 Task 1: Dokumente identifizieren</h4>
<p><strong>Objective:</strong> "Finde alle neuen PDF-Belege im SharePoint-Ordner"</p>
<div class="action-item">
<strong>Action 1.1:</strong> <code>sharepoint.listDocuments</code><br>
<span style="font-size: 0.9em; color: #666;">
Listet alle Dokumente im Ordner auf<br>
<strong>Parameter:</strong> folderPath, connectionReference
</span>
</div>
<div class="action-item">
<strong>Action 1.2:</strong> <code>sharepoint.readDocuments</code><br>
<span style="font-size: 0.9em; color: #666;">
Liest die gefundenen Dokumente ein<br>
<strong>Parameter:</strong> documentList (verweis auf Action 1.1), connectionReference
</span>
</div>
</div>
<div class="step-box">
<h4>🤖 Task 2: Daten verarbeiten</h4>
<p><strong>Objective:</strong> "Extrahiere Spesendaten aus PDFs und strukturiere sie"</p>
<div class="action-item">
<strong>Action 2.1:</strong> <code>ai.process</code><br>
<span style="font-size: 0.9em; color: #666;">
Verarbeitet Dokumente mit AI<br>
<strong>Parameter:</strong> aiPrompt, documentList (verweis auf Task 1.2), resultType
</span>
</div>
</div>
<div class="step-box">
<h4>📧 Task 3: Ergebnisse versenden</h4>
<p><strong>Objective:</strong> "Versende Bestätigungsmail mit Übersicht"</p>
<div class="action-item">
<strong>Action 3.1:</strong> <code>outlook.composeAndSendEmailWithContext</code><br>
<span style="font-size: 0.9em; color: #666;">
Sendet E-Mail mit Ergebnissen<br>
<strong>Parameter:</strong> recipientEmail, subject, emailBody, attachments (verweis auf Task 2.1)
</span>
</div>
</div>
</div>
<div class="success-box">
<strong>💡 Wichtige Prinzipien:</strong>
<ul>
<li><strong>1 Task = 1..n Actions</strong> - Ein Task kann mehrere Actions enthalten</li>
<li><strong>Dynamisches AI Planning</strong> - Actions werden automatisch durch AI geplant</li>
<li><strong>Flexible Ausführung</strong> - Tasks werden sequenziell ausgeführt</li>
<li><strong>Automatisches Error Handling</strong> - Fehler werden automatisch behandelt und retries durchgeführt</li>
</ul>
</div>
<h2>2. Dokument-Container-Labels: Generische Dokumentübergabe</h2>
<div class="diagram">
<h3>🏷️ Container-Label System</h3>
<p style="margin-bottom: 20px;">Dokumente werden zwischen Actions über <strong>Container-Labels</strong> generisch weitergegeben. Dies ermöglicht eine vollständige Flexibilität, ohne dass Actions die genaue Struktur der Dokumente kennen müssen.</p>
<div class="label-box">
<strong>Label-Format:</strong><br>
<code>round{round}_task{task}_action{action}_{descriptive_label}</code><br><br>
<strong>Beispiel:</strong><br>
<code>round1_task1_action1_spesen_pdfs</code><br>
<code>round1_task2_action1_extracted_data</code>
</div>
<div class="step-box">
<h4>📤 Action Output: Dokument erzeugen</h4>
<p>Jede Action kann Dokumente als Ergebnis erzeugen. Diese werden automatisch mit einem <code>resultLabel</code> versehen:</p>
<div class="action-item">
<strong>Action 1:</strong> <code>sharepoint.readDocuments</code><br>
<span style="font-size: 0.9em; color: #666;">
<strong>Output:</strong> Liste von PDF-Dokumenten<br>
<strong>resultLabel:</strong> <code>round1_task1_action1_spesen_pdfs</code><br>
<strong>Dokumente:</strong> [Rechnung_1.pdf, Rechnung_2.pdf, ...]
</span>
</div>
</div>
<div class="flow-arrow" style="text-align: center; margin: 20px 0;">⬇️ Weitergabe via documentList</div>
<div class="step-box">
<h4>📥 Action Input: Dokumente verwenden</h4>
<p>Folge-Actions referenzieren Dokumente über das <code>documentList</code> Parameter mit dem Label:</p>
<div class="action-item">
<strong>Action 2:</strong> <code>ai.process</code><br>
<span style="font-size: 0.9em; color: #666;">
<strong>Parameter:</strong><br>
<code>{</code><br>
<code> "aiPrompt": "Extrahiere Spesendaten...",</code><br>
<code> "documentList": ["docList:msg_123:round1_task1_action1_spesen_pdfs"],</code><br>
<code> "resultType": "json"</code><br>
<code>}</code><br><br>
<strong>System:</strong> Das System löst automatisch das Label auf und lädt die Dokumente
</span>
</div>
</div>
<div class="success-box">
<strong>✅ Vorteile des Container-Label Systems:</strong>
<ul>
<li><strong>Vollständige Entkopplung:</strong> Actions müssen nicht wissen, welche Dokumente genau übergeben werden</li>
<li><strong>Flexible Verkettung:</strong> Dokumente können zwischen beliebig vielen Actions weitergegeben werden</li>
<li><strong>Automatische Verwaltung:</strong> Das System verwaltet Dokumente zentral und löst Labels automatisch auf</li>
<li><strong>Type-Safety:</strong> Labels enthalten Metadaten (Round, Task, Action) für bessere Nachverfolgbarkeit</li>
</ul>
</div>
</div>
<h2>3. Key Features</h2>
<div class="feature-grid">
<div class="feature-card">
<h4>🔒 Neutralizer - Datenschutz</h4>
<p><strong>DSGVO-konformer Daten-Neutralisierer</strong> für alle User-Dokumente:</p>
<ul style="margin-top: 10px; font-size: 0.9em;">
<li>Automatische Neutralisierung personenbezogener Daten</li>
<li>Ersetzung durch Platzhalter ({{person}}, {{date}}, {{city}})</li>
<li>Unterstützt: TXT, JSON, CSV, Excel, Word</li>
<li>Mehrsprachig: DE, EN, FR, IT</li>
<li>Konfigurierbare Namen-Listen für spezifische Neutralisierung</li>
</ul>
<p style="margin-top: 15px; font-size: 0.85em; color: #666;">
<strong>Beispiel:</strong><br>
Original: "Max Mustermann, geboren am 01.01.1980 in Berlin"<br>
Neutralisiert: "{{person}}, geboren am {{date}} in {{city}}"
</p>
</div>
<div class="feature-card">
<h4>🚀 Unlimited AI Calls</h4>
<p><strong>Keine Limits bei AI-Verarbeitung:</strong></p>
<ul style="margin-top: 10px; font-size: 0.9em;">
<li><strong>Datenmenge:</strong> Unbegrenzte Input-Datenvolumen</li>
<li><strong>Dateianzahl:</strong> Unbegrenzte Anzahl an Dateien pro Workflow</li>
<li><strong>Formate:</strong> Alle gängigen Formate unterstützt:
<ul style="margin-left: 20px; margin-top: 5px;">
<li>Dokumente: PDF, DOCX, TXT, MD, HTML</li>
<li>Daten: JSON, CSV, XLSX, XML</li>
<li>Bilder: JPG, PNG, GIF, WebP</li>
<li>Audio/Video: MP3, MP4, WAV</li>
</ul>
</li>
<li><strong>Automatisches Chunking:</strong> Große Dateien werden automatisch in handhabbare Blöcke aufgeteilt</li>
<li><strong>Intelligente Modell-Auswahl:</strong> System wählt automatisch das beste AI-Modell basierend auf Anforderung</li>
</ul>
</div>
<div class="feature-card">
<h4>🔌 Connector-Integration</h4>
<p><strong>Einfache Integration ohne Installation:</strong></p>
<ul style="margin-top: 10px; font-size: 0.9em;">
<li><strong>Microsoft (MSFT):</strong>
<ul style="margin-left: 20px; margin-top: 5px;">
<li>SharePoint (Dokumente lesen/schreiben)</li>
<li>Outlook (E-Mails senden/empfangen)</li>
<li>OneDrive Integration</li>
</ul>
</li>
<li><strong>Google:</strong>
<ul style="margin-left: 20px; margin-top: 5px;">
<li>Google Drive</li>
<li>Gmail</li>
<li>Google Cloud Services</li>
</ul>
</li>
<li><strong>OAuth-basiert:</strong> Einfache Authentifizierung über Browser-Popup</li>
<li><strong>Keine Installation:</strong> Alles läuft über Web-Interface</li>
</ul>
</div>
</div>
<h2>4. Workflow-Vorgehen: Playground → Automatische Ausführung</h2>
<div class="diagram">
<h3>🔄 Zwei-Phasen-Workflow</h3>
<div class="flow-diagram">
<div class="flow-box">
<h4>Phase 1: Playground - Dynamisches Testen</h4>
<p style="margin-top: 10px;">Im <strong>Chat Playground</strong> können Sie Workflows dynamisch testen und modellieren:</p>
<ul style="text-align: left; margin-top: 15px;">
<li><strong>Dynamisches AI Planning:</strong> AI generiert automatisch Tasks und Actions basierend auf Ihrer Beschreibung</li>
<li><strong>Interaktives Testen:</strong> Jeder Schritt wird in Echtzeit ausgeführt und sichtbar gemacht</li>
<li><strong>Anpassungen:</strong> Sie können jederzeit stoppen, anpassen und neu starten</li>
<li><strong>Zwei Modi verfügbar:</strong>
<ul style="margin-left: 20px; margin-top: 5px;">
<li><strong>Actionplan Mode:</strong> Alle Actions werden im Voraus geplant, dann sequenziell ausgeführt</li>
<li><strong>React Mode:</strong> Iterative Plan-Act-Observe-Schleife für adaptive Workflows</li>
</ul>
</li>
</ul>
</div>
<div class="flow-arrow">⬇️</div>
<div class="flow-box">
<h4>Phase 2: Automatische Ausführung</h4>
<p style="margin-top: 10px;">Nach erfolgreichem Testen können Sie den Workflow als <strong>fixe Definition</strong> speichern:</p>
<ul style="text-align: left; margin-top: 15px;">
<li><strong>Workflow-Definition:</strong> Getesteter Workflow wird als Template gespeichert</li>
<li><strong>Event Handler:</strong> Workflow kann über Event Handler ausgelöst werden:
<ul style="margin-left: 20px; margin-top: 5px;">
<li>Zeitgesteuert (z.B. täglich um 08:00 Uhr)</li>
<li>Event-basiert (z.B. bei neuen E-Mails)</li>
<li>API-Trigger (z.B. über Webhook)</li>
</ul>
</li>
<li><strong>Automatische Ausführung:</strong> Workflow läuft vollständig automatisch ohne menschliches Eingreifen</li>
<li><strong>Error Handling:</strong> Automatische Retries und Fehlerbenachrichtigungen</li>
</ul>
</div>
</div>
<div class="success-box" style="margin-top: 30px;">
<strong>📋 Beispiel-Workflow: Spesenverarbeitung</strong>
<div style="margin-top: 15px;">
<p><strong>Playground-Phase:</strong></p>
<ol style="margin-left: 20px;">
<li>Beschreibung: "Lese täglich PDF-Spesenbelege aus SharePoint, extrahiere Daten mit AI, und versende Bestätigungsmail"</li>
<li>AI erstellt automatisch Task-Plan: 3 Tasks mit entsprechenden Actions</li>
<li>Sie testen interaktiv jeden Schritt</li>
<li>Sie passen bei Bedarf an (z.B. zusätzliche Validierung)</li>
</ol>
<p style="margin-top: 20px;"><strong>Automatisierungs-Phase:</strong></p>
<ol style="margin-left: 20px;">
<li>Workflow wird als Template gespeichert</li>
<li>Event Handler wird konfiguriert: "Täglich um 08:00 Uhr ausführen"</li>
<li>Workflow läuft automatisch, liest neue Belege, verarbeitet sie, und versendet E-Mails</li>
<li>Sie erhalten Logs und Benachrichtigungen bei Erfolg oder Fehlern</li>
</ol>
</div>
</div>
</div>
<h2>5. Verfügbare Actions</h2>
<div class="diagram">
<h3>🤖 Method: AI</h3>
<div class="feature-grid">
<div class="feature-card">
<h4><span class="connector-badge">ai</span> process</h4>
<p><strong>Parameter:</strong></p>
<ul style="font-size: 0.9em;">
<li>aiPrompt (required)</li>
<li>documentList (optional)</li>
<li>resultType (optional)</li>
</ul>
<p style="margin-top: 10px;">AI-Textverarbeitung mit optionalen Input-Dokumenten</p>
</div>
<div class="feature-card">
<h4><span class="connector-badge">ai</span> webResearch</h4>
<p><strong>Parameter:</strong></p>
<ul style="font-size: 0.9em;">
<li>searchQuery (required)</li>
<li>language (optional)</li>
</ul>
<p style="margin-top: 10px;">Web-Recherche mit AI-gestützter Zusammenfassung</p>
</div>
<div class="feature-card">
<h4><span class="connector-badge">ai</span> generateImage</h4>
<p><strong>Parameter:</strong></p>
<ul style="font-size: 0.9em;">
<li>imagePrompt (required)</li>
<li>style (optional)</li>
</ul>
<p style="margin-top: 10px;">AI-Bildgenerierung basierend auf Textprompt</p>
</div>
</div>
<h3 style="margin-top: 40px;">📁 Method: SharePoint</h3>
<div class="feature-grid">
<div class="feature-card">
<h4><span class="connector-badge">sharepoint</span> findDocumentPath</h4>
<p><strong>Parameter:</strong></p>
<ul style="font-size: 0.9em;">
<li>connectionReference (required)</li>
<li>searchQuery (required)</li>
<li>site (optional)</li>
<li>maxResults (optional)</li>
</ul>
<p style="margin-top: 10px;">Sucht Dokumente und Ordner in SharePoint</p>
</div>
<div class="feature-card">
<h4><span class="connector-badge">sharepoint</span> readDocuments</h4>
<p><strong>Parameter:</strong></p>
<ul style="font-size: 0.9em;">
<li>documentList (required)</li>
<li>connectionReference (required)</li>
</ul>
<p style="margin-top: 10px;">Liest Dokumente aus SharePoint</p>
</div>
<div class="feature-card">
<h4><span class="connector-badge">sharepoint</span> uploadDocument</h4>
<p><strong>Parameter:</strong></p>
<ul style="font-size: 0.9em;">
<li>documentData (required)</li>
<li>targetPath (required)</li>
<li>connectionReference (required)</li>
</ul>
<p style="margin-top: 10px;">Lädt Dokumente in SharePoint hoch</p>
</div>
<div class="feature-card">
<h4><span class="connector-badge">sharepoint</span> listDocuments</h4>
<p><strong>Parameter:</strong></p>
<ul style="font-size: 0.9em;">
<li>folderPath (required)</li>
<li>connectionReference (required)</li>
<li>includeSubfolders (optional)</li>
</ul>
<p style="margin-top: 10px;">Listet Dokumente in einem Ordner auf</p>
</div>
</div>
<h3 style="margin-top: 40px;">📧 Method: Outlook</h3>
<div class="feature-grid">
<div class="feature-card">
<h4><span class="connector-badge">outlook</span> readEmails</h4>
<p><strong>Parameter:</strong></p>
<ul style="font-size: 0.9em;">
<li>connectionReference (required)</li>
<li>folder (optional)</li>
<li>limit (optional)</li>
<li>filter (optional)</li>
</ul>
<p style="margin-top: 10px;">Liest E-Mails aus einem Postfach</p>
</div>
<div class="feature-card">
<h4><span class="connector-badge">outlook</span> searchEmails</h4>
<p><strong>Parameter:</strong></p>
<ul style="font-size: 0.9em;">
<li>connectionReference (required)</li>
<li>searchQuery (required)</li>
</ul>
<p style="margin-top: 10px;">Sucht E-Mails mit spezifischen Kriterien</p>
</div>
<div class="feature-card">
<h4><span class="connector-badge">outlook</span> composeAndSendEmailWithContext</h4>
<p><strong>Parameter:</strong></p>
<ul style="font-size: 0.9em;">
<li>connectionReference (required)</li>
<li>recipientEmail (required)</li>
<li>subject (required)</li>
<li>emailBody (required)</li>
<li>attachments (optional)</li>
</ul>
<p style="margin-top: 10px;">Erstellt und sendet E-Mail mit Kontext</p>
</div>
</div>
</div>
<h2>6. Technische Architektur</h2>
<div class="diagram">
<div class="workflow-box">
<h4>🔧 Core Components</h4>
<p style="margin-top: 10px;"><strong>Workflow Management:</strong></p>
<ul style="font-size: 0.95em;">
<li><code>workflowManager.py</code> - Zentrale Workflow-Koordination</li>
<li><code>workflowProcessor.py</code> - Hauptprozessor mit Mode-Delegation</li>
<li><code>actionExecutor.py</code> - Führt Actions aus</li>
<li><code>messageCreator.py</code> - Erstellt Workflow-Nachrichten</li>
<li><code>taskPlanner.py</code> - Plant Tasks</li>
<li><code>validator.py</code> - Validiert Actions</li>
</ul>
<p style="margin-top: 15px;"><strong>Processing Modes:</strong></p>
<ul style="font-size: 0.95em;">
<li><code>modeActionplan.py</code> - Batch-Planung aller Actions</li>
<li><code>modeReact.py</code> - Iterative Plan-Act-Observe-Schleife</li>
</ul>
<p style="margin-top: 15px;"><strong>Adaptive Features:</strong></p>
<ul style="font-size: 0.95em;">
<li><code>intentAnalyzer.py</code> - Analysiert User-Intents</li>
<li><code>contentValidator.py</code> - Validiert Inhalte</li>
<li><code>adaptiveLearningEngine.py</code> - Lernt aus Feedback</li>
<li><code>progressTracker.py</code> - Verfolgt Fortschritt</li>
</ul>
</div>
</div>
<div class="warning-box" style="margin-top: 30px;">
<strong>⚠️ Wichtige Hinweise:</strong>
<ul>
<li><strong>Dokument-Referenzen</strong> erfolgen über <code>documentList</code> Parameter mit Container-Labels</li>
<li><strong>Connection References</strong> müssen vom User konfiguriert sein (Microsoft/Google OAuth)</li>
<li><strong>Error Handling</strong> erfolgt über Retry-Logik in den Modes</li>
<li><strong>Neutralizer</strong> wird automatisch auf alle User-Uploads angewendet</li>
<li><strong>AI Calls</strong> haben keine Limits - System wählt automatisch passende Modelle</li>
</ul>
</div>
</div>
</body>
</html>