wiki/archiv/spec.md

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:

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):

{
  "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