PowerOn/wiki
3
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
wiki/c-work/1-plan/2026-04-trustee-workflow-audit-and-run-workspace.md
ValueOn AG 6eeeb962f6 upd
2026-04-29 20:23:03 +02:00

10 KiB
Raw Blame History

Trustee Workflow-Audit (A1) & Generischer Workflow-Run-Workspace (A2)

Beschreibung und Kontext

Der User klickt im Trustee-Dashboard Service-Karten an (Budget-Vergleich, KPI-Dashboard, Cashflow, Forecast, Jahresabschluss-Pruefung) und landet auf Tabs in TrusteeAnalyseView / TrusteeAbschlussView, wo der jeweilige Workflow gestartet wird.

Zwei Themen:

  • A1 Audit: Sind diese Workflows wirklich auf dem aktuellen Pick-not-Push / Typed-Action-Stack? -- JA, alle GREEN (siehe Befund unten). Hier wird nur dokumentiert.
  • A2 Result-Sichtbarkeit: Wenn der User waehrend des Runs die Seite wechselt, ist das Resultat (KI-Antwort + generierte Files) anschliessend weg -- es lebt nur im React-State der Source-View. Persistenz existiert zwar in AutoRun/AutoStepLog, ist aber nirgends als User-UI erschlossen.

Geschaeftstreiber: UX-Bruch ("ich war kurz auf einer anderen Seite, jetzt ist mein Report weg") + fehlende Single-Source-of-Truth fuer Workflow- Outputs. Plus: User-Anforderung, dass jeder Workflow eine FeatureInstance referenziert (auch bei Scheduled-Runs), damit Datenquellen im Editor sauber gefiltert werden koennen.

Fokus und kritische Details

  • POST /api/workflows/{instanceId}/execute ist heute synchron -- der Browser blockiert auf dem Request bis Ende. Der "Workspace" muss diesen Request nicht aendern, er muss nur die persistierten AutoRun-Daten verlinkbar/auffindbar machen.
  • Workflow.featureInstanceId ist heute optional (zumindest historisch). Pflicht-Binding ist breakend fuer existierende Workflows ohne Instanz -- Migration noetig.
  • Scheduler-Pfad muss die Pflicht-Binding respektieren, sonst laufen Cron-Workflows ohne Daten-Scope.
  • Tab-Position: User wuenscht den Workspace explizit unter /automations (Seite "Nutzung > Automation") als zusaetzlichen Tab neben Dashboard + Workflows.

Ziel und Nicht-Ziele

  • Ziel A1: Audit-Befund GREEN dokumentiert (Wiki-Update).
  • Ziel A2: Generische Workflow-Run-Workspace-View; jeder Workflow hat Pflicht-FeatureInstance-Binding; Trustee-Views zeigen Resultate ueber Workspace statt eigenem React-State.
  • NICHT: Async-Umstellung des Execute-Endpoints (eigener Plan, falls noetig).
  • NICHT: Browser-Push-Notification (User wollte nur Workspace).
  • NICHT: Aenderung der Workflow-Engine-Logik selbst.

Betroffene Module

  • Gateway:
    • gateway/modules/features/graphicalEditor/datamodelFeatureGraphicalEditor.py (Workflow.featureInstanceId Pflicht).
    • gateway/modules/features/graphicalEditor/routeFeatureGraphicalEditor.py (Save-Validation, neue Aggregat-Routen unter /api/automations/runs/...).
    • gateway/modules/features/graphicalEditor/mainScheduler.py (Schedule- Erstellung uebernimmt Instanz aus Workflow).
    • gateway/modules/features/trustee/mainTrustee.py (Audit-Notiz, sicherstellen dass Templates featureInstanceId setzen).
  • Frontend:
    • Neuer Tab in frontend_nyla/src/pages/AutomationsDashboardPage.tsx.
    • Neue Komponenten WorkflowRunWorkspaceView, WorkflowRunDetailView.
    • FlowEditor-Toolbar bekommt Pflicht-Selector "Feature-Instanz".
    • frontend_nyla/src/pages/views/trustee/TrusteeAnalyseView.tsx und TrusteeAbschlussView.tsx schlanker (Verlinkung in den Workspace statt eigene Result-Anzeige; Run-State nicht mehr verloren bei Tab- Wechsel weil Persistenz uebernimmt).
  • DB-Migration: ja -- Bestand-Workflows ohne featureInstanceId brauchen ein Migrations-Skript (interaktiv).
  • RBAC: Zugriff auf /automations/workspace -- prueft pro Run die Mandate/FeatureInstance-Rechte des Users.

Befund A1 (Audit) -- bereits GREEN

Service Workflow-ID Backend-Definition Status Beleg
Budget-Vergleich trustee-budget-comparison mainTrustee.py 430-461 GREEN DataRef Trigger-Payload + Refresh-Output, modern
KPI-Dashboard trustee-kpi-dashboard mainTrustee.py 463-478 GREEN _buildAnalysisWorkflowGraph 364-381
Cashflow-Rechnung trustee-cashflow mainTrustee.py 480-492 GREEN dito
Prognose trustee-forecast mainTrustee.py 494-507 GREEN dito
Jahresabschluss-Pruefung trustee-year-end-check mainTrustee.py 509-522 GREEN dito

Engine-Pipeline: executeGraph ruft materializeFeatureInstanceRefs + validateGraph vor jedem Lauf auf (gateway/modules/features/graphicalEditor/executionEngine.py 341-350). Persistierte Graphs nutzen zunaechst nackte UUID fuer featureInstanceId (Bootstrap interfaceFeatures.py 336-338), Laufzeit-Envelope erfolgt in executeGraph.

Entscheidungen

Datum Entscheidung Begruendung
2026-04-29 Workspace ist GENERISCH plattformweit, nicht Trustee-spezifisch Doppelt-Bauen vermeiden; ComCoach/TeamsBot/Workspace profitieren auch
2026-04-29 Workspace lebt unter /automations als Tab "Workspace" User-Vorgabe; Nutzungspfad "Nutzung > Automation > Workspace"
2026-04-29 Workflow-Speicherung verlangt featureInstanceId Datenquellen-Tools im Editor sind nur dann sinnvoll filterbar
2026-04-29 Bestehende Workflows ohne Instanz: interaktives Migrations-Skript pro Mandate Kein automatischer Default -- der User soll bewusst zuordnen
2026-04-29 Browser-Push-Notification NICHT umgesetzt User hat nur Workspace gewaehlt; Toast bei Run-Ende reicht

Umsetzungs-Checkliste

Phase 1 -- FeatureInstance-Pflicht-Binding

  • Backend: Workflow.featureInstanceId NOT NULL (Pydantic + DB-Constraint via Connector-Auto-Init).
  • Save-Validation in routeFeatureGraphicalEditor.py: Workflow ohne featureInstanceId -> 400 mit Error-Detail "Feature-Instanz fehlt". Save-with-errors (AC-9 vom Typed-Action-Plan) bleibt erlaubt -- nur Run-Start blockt.
  • Run-Start (POST .../execute): Vorab-Check, dass Workflow eine Instanz hat.
  • Migrations-Skript gateway/scripts/script_db_migrate_workflow_feature_instance.py: listet pro Mandate alle Workflows ohne Instanz, bietet pro Workflow eine Auswahl (CLI prompt).
  • Scheduler: Schedule-Erstellung uebernimmt Instanz aus Workflow, Override nicht moeglich.
  • FlowEditor-Toolbar: Pflicht-Dropdown "Feature-Instanz" oben links. Datenquellen-Tools (z.B. UDB-Listen, FileItems, SourcesTab) filtern automatisch auf diese Instanz.
  • Trustee-Templates pruefen: alle Workflows haben in mainTrustee.py bereits featureInstanceId als {{featureInstanceId}}-Placeholder, der beim _copyTemplateWorkflows ersetzt wird (interfaceFeatures.py 269-338) -- nur sicherstellen dass jetzt nichts haengen bleibt.

Phase 2 -- Generischer WorkflowRunWorkspace

  • Neue Aggregat-API: GET /api/automations/runs?scope=mine|mandate|all&status=...&limit=... und GET /api/automations/runs/{runId}/detail. Detail-Payload kombiniert AutoRun + AutoStepLog + Outputs + verlinkte FileItems (joined mit RBAC-Filter).
  • Tab "Workspace" in frontend_nyla/src/pages/AutomationsDashboardPage.tsx (neben Dashboard, Workflows).
  • Komponente WorkflowRunWorkspaceView: Liste mit Filter (Status, Workflow-Template, Mandate, Zeitraum), 50-er Pagination.
  • Komponente WorkflowRunDetailView: Chat-aehnliche Ansicht - Header: Workflow-Name, Status, Start/Ende, FeatureInstance. - Eingabe-Bubble: Trigger-Payload (formatiert). - Step-Bubbles: chronologisch, pro Step-Output kollabierbar. - Final-Bubble: KI-Antwort als Markdown. - Documents-Sektion: alle generierten FileItems als Karten mit Direkt-Download (a href="/api/files/{id}/download").
  • Trustee-Views umbauen: - TrusteeAnalyseView: Result-Anzeige raus (resultText / resultDocuments State), stattdessen "Im Workspace ansehen"- Button mit runId. - TrusteeAbschlussView: dasselbe (heute zeigt der gar nichts).

Phase 3 -- Notifications

  • Toast bei Run-Ende ist heute schon da -- erweitern um Klick-Action zum Detail-View des Runs.
  • Sidebar-Badge auf Eintrag "Automation" (Counter "neu seit letztem Besuch", localStorage-basiert).

Akzeptanzkriterien

# Kriterium (Given-When-Then) Prio
1 Given Workflow ohne Instanz, When User Save klickt, Then 400 mit klarer Error-Message must
2 Given Bestand-Workflow ohne Instanz, When Migrations-Skript laeuft, Then User waehlt interaktiv pro Workflow eine Instanz und das Feld wird gesetzt must
3 Given Trustee-Run gestartet, When User waehrend Lauf die Seite wechselt und zurueck zum Tab "Workspace" geht, Then Run mit allen Outputs sichtbar must
4 Given Run mit generiertem File, When User auf Document-Karte klickt, Then File wird direkt heruntergeladen must
5 Given Run-Ende, When Toast erscheint, Then Klick fuehrt direkt zum WorkflowRunDetailView should
6 Given neue Runs seit letztem Besuch, When User die Sidebar sieht, Then "Automation" hat einen Counter-Badge should
7 Given FlowEditor offen ohne Instanz-Auswahl, When User Datenquellen-Tool oeffnen will, Then Hinweis "Bitte Feature-Instanz waehlen" should

Testplan

ID AC Art Automatisiert Repo-Pfad Status
T1 1 api ja gateway/tests/features/graphicalEditor/test_workflow_save_requires_instance.py pending
T2 2 manual nein gateway/scripts/script_db_migrate_workflow_feature_instance.py pending
T3 3 e2e ja frontend_nyla/tests/e2e/workflow-run-workspace.spec.ts pending
T4 4 e2e ja wie T3 pending
T5 5 manual nein -- pending
T6 6 unit ja frontend_nyla/src/pages/tests/AutomationsDashboardPage.test.tsx pending
T7 7 unit ja frontend_nyla/src/components/flowEditor/tests/Toolbar.test.tsx pending

Links

  • Audit-Quelle: Subagent-Report 2026-04-29.
  • Wiki: wiki/b-reference/gateway/workflow.md, wiki/b-reference/gateway/features/trustee.md, wiki/c-work/4-done/2026-04-typed-action-architecture.md, wiki/c-work/4-done/2026-04-automation-central-admin.md.

Abschluss

  • wiki/b-reference/gateway/workflow.md Abschnitt "Workflow-Run-Workspace" anlegen
  • wiki/b-reference/gateway/features/trustee.md Result-UX-Sektion aktualisieren
  • wiki/TOPICS.md ggf. Tab-Beschreibung
  • Dieses Dokument -> z-archive/ verschoben