206 lines
10 KiB
Markdown
206 lines
10 KiB
Markdown
<!-- status: plan -->
|
|
<!-- started: 2026-04-29 -->
|
|
<!-- component: gateway, frontend-nyla -->
|
|
|
|
# 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
|