176 lines
No EOL
9.9 KiB
Markdown
176 lines
No EOL
9.9 KiB
Markdown
# PowerOn Frontend Architektur & Spezifikation
|
|
|
|
## 1. Funktionsumfang des Frontends
|
|
|
|
Das Frontend der PowerOn-Plattform bietet folgende Kernfunktionen:
|
|
|
|
- **Multi-Agent Chat-Workflow**: Interaktive Chat-Oberfläche für die Steuerung von Workflows mit mehreren KI-Agenten.
|
|
- **Datei-Upload & -Verwaltung**: Nutzer können Dateien hochladen, anhängen, einsehen und herunterladen.
|
|
- **Prompt-Verwaltung**: Verwaltung und Nutzung von Prompt-Vorlagen für wiederkehrende Aufgaben.
|
|
- **Log- und Statusanzeige**: Fortschrittsanzeige, Fehler- und Statusmeldungen für Workflows.
|
|
- **Benutzer- und Mandantenverwaltung**: Admin-Funktionen zur Verwaltung von Usern und Mandanten.
|
|
- **Dynamische Datentabellen**: CRUD-Operationen (Create, Read, Update, Delete) für beliebige Entitäten über generische Tabellen und Formulare.
|
|
- **Authentifizierung**: Login via klassischem Account oder Microsoft-Account.
|
|
|
|
## 2. Struktur des Frontends
|
|
|
|
Das Frontend ist modular aufgebaut und besteht aus folgenden Hauptmodulen und -bereichen:
|
|
|
|
- **js/main.js**: Einstiegspunkt, Initialisierung der App und Navigation.
|
|
- **js/shared/**: Gemeinsame Module für State-Management, API-Calls, Navigation, Utilities, Authentifizierung, Formulargenerierung.
|
|
- **globalState.js**: Zentrale State-Verwaltung und Navigation.
|
|
- **apiCalls.js**: Konsolidierte Schnittstelle für Backend-Kommunikation.
|
|
- **formGeneric.js**: Generisches Modul für CRUD-Tabellen und Formulare.
|
|
- **msftCalls.js**: Microsoft-Authentifizierung und Status.
|
|
- **navigation.js**: Dynamische Navigation und Menü-Rendering.
|
|
- **utils.js**: Hilfsfunktionen (z.B. Toasts, UI-Feedback).
|
|
- **js/modules/**: Feature-spezifische Module (z.B. prompts.js, users.js, files.js).
|
|
- **public/htmlparts/**: HTML-Teile und Stylesheets für Layout, Navigation, Workflow, Formulare.
|
|
- **public/docu/**: Dokumentation und Spezifikationen.
|
|
|
|
## 3. Kommunikation mit dem Backend
|
|
|
|
Die gesamte Kommunikation mit dem Backend erfolgt konsolidiert über das Modul **apiCalls.js**. Dieses Modul bietet Funktionen für alle relevanten API-Endpunkte:
|
|
|
|
- **Workflows**: Starten, Fortsetzen, Stoppen, Status, Logs, Nachrichten, Löschen
|
|
- **Dateien**: Upload, Download, Löschen, Anhängen/Entfernen an Nachrichten
|
|
- **Prompts**: CRUD-Operationen für Prompt-Vorlagen
|
|
- **User/Mandanten**: Verwaltung von Benutzern und Mandanten
|
|
- **Generische Entitäten**: CRUD für beliebige Datentabellen
|
|
|
|
Alle API-Aufrufe sind asynchron und liefern Promises zurück. Fehlerbehandlung und Statusmeldungen werden zentral im Modul und über UI-Feedback (Toasts) gehandhabt.
|
|
|
|
## 4. Workflow-States (State Machine)
|
|
|
|
Die States eines Workflows sind in den Dateien @doc_statemachine_backend.md und @doc_statemachine_frontend.md ausführlich beschrieben. Die wichtigsten States sind:
|
|
|
|
- **null**: Kein Workflow aktiv
|
|
- **running**: Workflow läuft, Polling aktiv
|
|
- **completed**: Workflow abgeschlossen, UI bereit für neue Eingabe
|
|
- **failed**: Fehler aufgetreten, UI zeigt Fehler und Retry-Option
|
|
- **stopped**: Workflow wurde gestoppt, UI bietet Fortsetzen/Reset
|
|
|
|
Transitions und State-Änderungen werden sowohl im Backend als auch im Frontend synchronisiert und über Polling-Mechanismen aktuell gehalten.
|
|
|
|
## 5. Administrierung von Usern, Mandanten und Datentabellen
|
|
|
|
Die Administration erfolgt konsolidiert über das generische Modul **formGeneric.js**:
|
|
|
|
- **User- und Mandantenverwaltung**: CRUD-Tabellen und Formulare für Benutzer und Mandanten, inklusive Rechteverwaltung.
|
|
- **Datentabellen**: Beliebige Entitäten (z.B. Prompts, Dateien, Workflows) können als Tabelle mit Formularen verwaltet werden.
|
|
- **Features**:
|
|
- Tabellenansicht mit Filter, Sortierung, Pagination, Massenaktionen
|
|
- Formulare für Erstellen/Bearbeiten mit dynamischer Feldgenerierung
|
|
- Validierung und Transformation der Formulardaten
|
|
- Externe Buttons für "+ Neuen ... erstellen" können einfach angebunden werden
|
|
- Felder, die mit "_" beginnen oder Zeitstempel wie "created_at" werden automatisch ausgeblendet
|
|
|
|
## 6. Implementierung & Datenstruktur für das formGeneric Modul
|
|
|
|
**Hinweis:** Die folgenden Beispiele und Erklärungen beziehen sich exemplarisch auf die Tabelle **"prompt"**. Das Prinzip ist jedoch für alle mit formGeneric verwalteten Entitäten identisch.
|
|
|
|
### Was macht das Modul formGeneric?
|
|
|
|
Das Modul **formGeneric.js** stellt eine generische Lösung für die Verwaltung beliebiger Datentabellen im Frontend bereit. Es übernimmt:
|
|
|
|
- Das Laden, Anzeigen, Erstellen, Bearbeiten und Löschen (CRUD) von Datensätzen
|
|
- Die dynamische Generierung von Tabellen und Formularen anhand der gelieferten Datenstruktur
|
|
- Die Filterung, Sortierung, Paginierung und Massenaktionen in der Tabellenansicht
|
|
- Die Validierung und Transformation von Formulardaten (optional)
|
|
- Die Anbindung externer Buttons (z.B. "+ Neuen Prompt erstellen")
|
|
- Die automatische Ausblendung von Feldern, die mit "_" beginnen oder Zeitstempel wie "created_at" enthalten
|
|
- Die Berücksichtigung von Berechtigungen: Felder wie `_hideEdit`, `_hideDelete`, `_hideView` steuern, ob die jeweiligen Aktionen für einen Datensatz im UI angezeigt werden
|
|
- Die Rendering-Logik: Längere Felder wie "content" oder "description" werden als Textarea dargestellt, boolesche Felder als Checkbox, numerische Felder als Zahlenfeld
|
|
- Die dynamische Anpassung an die Datenstruktur: Die Felder werden aus dem ersten Element der Datenliste abgeleitet
|
|
|
|
### Immer vorhandene/unterstützte Parameter (pro Datensatz)
|
|
|
|
- **id**: Eindeutige ID des Datensatzes (wird immer angezeigt)
|
|
- **_**-Felder: Interne Felder, die mit "_" beginnen, werden in Tabellen und Formularen ausgeblendet
|
|
- **createdAt, updatedAt, created_at**: Zeitstempel werden automatisch ausgeblendet
|
|
- **_hideEdit, _hideDelete, _hideView**: Steuern, ob die jeweiligen Aktionen (Bearbeiten, Löschen, Anzeigen) im UI für diesen Datensatz angezeigt werden
|
|
- **Weitere Felder**: Werden dynamisch als Spalten und Formularfelder generiert, sofern sie nicht explizit ausgeschlossen sind
|
|
|
|
### Integration
|
|
|
|
Das Modul wird wie folgt initialisiert:
|
|
|
|
```js
|
|
window.genericEntityModule.init(globalState, {
|
|
entityType: 'prompt', // oder 'user', 'mandate', ...
|
|
apiEndpoint: {
|
|
get: api.getPrompts,
|
|
create: api.createPrompt,
|
|
update: api.updatePrompt,
|
|
delete: api.deletePrompt
|
|
},
|
|
listContainerId: 'prompts-list',
|
|
addButtonId: 'add-prompt-btn',
|
|
transformFormData: function(formData) { /* optional */ },
|
|
onItemCreated: function(item) { /* optional */ },
|
|
onItemUpdated: function(item) { /* optional */ },
|
|
onItemDeleted: function(id) { /* optional */ }
|
|
});
|
|
```
|
|
|
|
### Erwartete Datenstruktur (aus der Route/API)
|
|
|
|
Das Modul erwartet, dass die API-Endpoints Objekte mit folgender Struktur liefern (Beispiel Prompt):
|
|
|
|
```json
|
|
{
|
|
"id": 123,
|
|
"name": "Prompt-Name",
|
|
"description": "Beschreibung",
|
|
"content": "Prompt-Inhalt",
|
|
"createdAt": "2024-05-11T12:34:56Z",
|
|
"updatedAt": "2024-05-11T12:34:56Z",
|
|
"_internal": "...", // wird ignoriert
|
|
"_hideEdit": false, // steuert Bearbeiten-Button
|
|
"_hideDelete": false, // steuert Löschen-Button
|
|
"_hideView": false // steuert Anzeigen-Button
|
|
}
|
|
```
|
|
|
|
- Felder mit "_" am Anfang sowie Zeitstempel wie "createdAt", "updatedAt", "created_at" werden automatisch in Tabellen und Formularen ausgeblendet.
|
|
- Die Felder werden dynamisch aus dem ersten Element der Datenliste generiert.
|
|
- Für längere Felder wie "content" oder "description" wird automatisch ein Textarea verwendet.
|
|
- Checkboxen für boolesche Felder, Zahlenfelder für numerische Werte.
|
|
- Die Sichtbarkeit von Aktionen (Bearbeiten, Löschen, Anzeigen) wird pro Datensatz über die _hide*-Felder gesteuert.
|
|
|
|
### Erweiterbarkeit
|
|
|
|
- Das Modul kann für beliebige Entitäten verwendet werden, solange die API die Standard-CRUD-Methoden bereitstellt.
|
|
- Zusätzliche Aktionen (z.B. "Vorschau", "Spezial-Buttons") können über die Option `getItemActions` ergänzt werden.
|
|
- Die UI ist vollständig dynamisch und passt sich der gelieferten Datenstruktur an.
|
|
|
|
---
|
|
|
|
## 7. Workflow-UI: Darstellung und Datenfluss
|
|
|
|
Das Workflow-Modul im Frontend bildet die zentrale Chat- und Prozessansicht ab. Die wichtigsten UI-Elemente und deren Datenquellen sind:
|
|
|
|
- **Chatbereich**: Zeigt alle Nachrichten (user, agent, system) als Chat-Bubbles an. Die Nachrichten werden aus dem Backend über `/api/workflows/{workflowId}/messages` geladen und enthalten:
|
|
- `content`: Text der Nachricht
|
|
- `role`: user, assistant, agentName
|
|
- `documents`: Anhänge (Dateien, die angezeigt oder heruntergeladen werden können)
|
|
- `timestamp`, `status` (first, step, last)
|
|
- **Logpanel**: Zeigt den Fortschritt und Status des Workflows an. Die Logs werden aus `/api/workflows/{workflowId}/logs` geladen und enthalten:
|
|
- `message`: Logtext
|
|
- `progress`: Fortschritt (0-100%)
|
|
- `type`: info, warning, error
|
|
- `agentName`, `timestamp`
|
|
- **Prompt-Eingabe**: Textfeld für Nutzereingaben, Datei-Upload-Bereich, Start/Send-Button, Stop-Button
|
|
- **Dateianhänge**: Hochgeladene Dateien werden im UI angezeigt und können entfernt werden. Die Metadaten kommen aus `/api/files/upload` und den Nachrichtenobjekten.
|
|
- **Statusanzeige**: Zeigt den aktuellen Workflow-Status (running, completed, failed, stopped) an, basierend auf `/api/workflows/{workflowId}/status`.
|
|
- **Polling-Mechanismus**: Das Frontend pollt periodisch die Status-, Log- und Nachrichtenendpunkte, um die UI aktuell zu halten. Neue Nachrichten und Logs werden automatisch ergänzt.
|
|
- **Fehler- und Abschlusszustände**: Bei Fehlern oder Abschluss werden entsprechende UI-Elemente (z.B. Retry, Reset, neue Eingabe) angezeigt.
|
|
|
|
**Datenfluss:**
|
|
- Nach Start eines Workflows werden alle relevanten Daten (Nachrichten, Logs, Status) regelmäßig vom Backend geladen und im UI aktualisiert.
|
|
- Die Zuordnung von Nachrichten, Logs und Dateien erfolgt über IDs und Statusfelder.
|
|
- Die UI ist so gestaltet, dass sie den aktuellen Stand des Workflows und alle relevanten Aktionen für den Nutzer transparent darstellt.
|
|
|
|
---
|
|
|
|
**Letzte Aktualisierung:** 2024-05-11 |