Trustee Budget Comparison Refactor (Excel-only, Prompt-Klarheit)

Beschreibung und Kontext

Der Trustee-Service "Budget-Vergleich" (gateway/modules/features/trustee/mainTrustee.py 430-461) liefert heute ein Word-Dokument mit teils kaputten Bildern in Tabellenzellen und mit Charts pro Konto statt einem Uebersichts-Chart. Ursachen:

Workflow-Template hat kein resultType -- das Ausgabeformat wird vom Modell entschieden, oft DOCX.
Prompt (Z. 442-454) ist mehrdeutig: "Erstelle ein Abweichungs-Chart" steht direkt neben "pro Konto" -- das LLM waehlt mal Lesart A, mal B.
Bilder-in-Tabellenzellen sind im Markdown->JSON-Pfad (gateway/modules/serviceCenter/services/serviceAgent/coreTools/_mediaTools.py 72-86, 108-127) nicht vorgesehen: Tabellenzellen sind reine Strings, Bilder muessen eine eigene Markdown-Zeile sein. python-docx koennte Bilder in Zellen, aber unsere MD-Pipeline kann es nicht ausdruecken.

User-Entscheid: Excel ist der natuerliche Container fuer einen Soll/Ist-Konten-Vergleich (tabellarische Daten, eingebettete Charts, sortier-/filterbar). Word-Pfad fuer diesen Workflow weg.

Fokus und kritische Details

Format-Festlegung darf NICHT vom LLM ueberschrieben werden -- Workflow muss resultType: "xlsx" hart setzen.
Prompt-Refactor: ein Chart, ueber alle Konten. Few-Shot-Beispiel mit Zielstruktur direkt im Prompt einbauen.
"Bild in Tabellenzelle"-Thema gehoert zum generellen Renderer-Refactor (siehe 2026-04-ai-reports-theming-and-pipeline.md); hier nur den Budget-spezifischen Effekt heilen, indem das Layout Tabelle-darunter-Chart ist (kein Bild in Zelle noetig).

Ziel und Nicht-Ziele

Ziel: Budget-Vergleich liefert konsistent EINE .xlsx mit Tabelle (alle Konten) + 1 Uebersichts-Chart + Management-Summary.
NICHT: Bilder-in-Tabellenzellen technisch loesen (gehoert zu D).
NICHT: native XLSX-Charts via openpyxl (Default bleibt PNG-Embed). Kann in spaeteren Iteration nachgezogen werden.
NICHT: Aenderungen am refreshAccountingData-Node oder ai.process-Action.

Betroffene Module

Gateway:
- gateway/modules/features/trustee/mainTrustee.py -- Budget-Template Z. 430-461 (Prompt + resultType + Output-Schema-Hinweis).
Frontend:
- frontend_nyla/src/pages/views/trustee/TrusteeAnalyseView.tsx -- File-Karten korrekt rendern (xlsx-Icon).
DB-Migration: nein (nur Template-Aenderung; bei naechstem _copyTemplateWorkflows-Lauf greift es).

Entscheidungen

Datum	Entscheidung	Begruendung
2026-04-29	Excel ist primaeres Format, Word-Pfad fuer Budget-Vergleich entfernt	Daten-tabellarisch, Charts in Excel native passend
2026-04-29	Charts via PNG-Embed (kein openpyxl-native), 1 Chart ueber alle Konten	Schon implementiert, kein neuer Renderer-Pfad noetig
2026-04-29	Bilder-in-Zellen wird NICHT in diesem Plan geloest	Layout Tabelle-darunter-Chart reicht; generischer Fix in D

Umsetzungs-Checkliste

Phase 1 -- Workflow-Template

In mainTrustee.py Budget-Template: - Parameter resultType: "xlsx" setzen. - Parameter documentTheme: "finance" setzen (Vorbereitung fuer Plan D, hat heute noch keinen Effekt).
_copyTemplateWorkflows (interfaceFeatures.py 269-338) prueft idempotent ob bestehende User-Workflows mit ID trustee-budget- comparison aktualisiert werden -- falls nicht, separates Migrations-Skript-Stub anlegen.

Phase 2 -- Prompt klarziehen

Neuer Prompt-Text in mainTrustee.py:

Fuehre einen Budget-Soll/Ist-Vergleich durch und liefere EIN Excel-Dokument
mit folgender Struktur:

1. Tabelle "Konten-Vergleich" -- EINE Tabelle, EINE Zeile pro Konto:
   Spalten: Konto-Nr | Konto-Name | Soll | Ist | Abweichung absolut |
            Abweichung % | Status (OK / Warnung / Kritisch).
2. EINE Visualisierung "Soll vs. Ist gesamt" -- ein einziges
   Balkendiagramm UNTER der Tabelle, das ALLE Konten in einer Grafik
   gegenueberstellt (gruppierte Balken: Soll und Ist je Konto).
3. Kurzer Management-Summary-Absatz (3-5 Saetze) UNTER dem Chart
   mit den 3 groessten Abweichungen (>10%) und einer fachlichen
   Einschaetzung.

Verwende die uebergebene Budget-Datei als Soll-Quelle und die im
Kontext bereitgestellten Buchhaltungsdaten als Ist-Quelle.
WICHTIG: Erstelle KEINEN separaten Chart pro Konto. Nur EIN
Uebersichts-Chart ueber alle Konten ist gewuenscht.

Few-Shot-Beispiel als zweites System-Block-Append: minimaler JSON-Stub mit metadata.documents[0].sections = [table, image, paragraph].

Phase 3 -- Excel-Renderer-Sicht

Verifizieren dass rendererXlsx PNG-Bilder unter Tabellen korrekt rendert (vorhanden, _renderJsonImage-Pfad).
Default-Bildbreite checken (heute hardcoded maxWidth=800 in gateway/modules/serviceCenter/services/serviceGeneration/renderers/rendererXlsx.py ~ 1427-1428) -- ok fuer A4-druckbares Diagramm; spaeter via Theme-System (Plan D) konfigurierbar.

Phase 4 -- Frontend

TrusteeAnalyseView.tsx Budget-Tab: Hinweistext "Excel-Bericht" statt generisch "Datei", File-Icon description statt generisch.
Wenn Plan A2 vorher gemerged ist: "Im Workspace ansehen"-Button.

Phase 5 -- Test

Smoke-Test: 1 Run mit Demo-Budget-File -> 1 .xlsx mit genau einer table-Section + einer image-Section + einer paragraph-Section.
Snapshot des produzierten .xlsx in gateway/tests/features/trustee/snapshots/.

Akzeptanzkriterien

#	Kriterium (Given-When-Then)	Prio
1	Given Budget-Vergleich-Run, When er fertig ist, Then liefert er genau eine .xlsx (kein .docx)	must
2	Given die .xlsx wird geoeffnet, When User die erste Tabelle sieht, Then sind alle Konten als Zeilen vorhanden	must
3	Given die .xlsx, When User runter scrollt, Then findet er EIN Uebersichts-Chart (nicht eines pro Konto)	must
4	Given die .xlsx, When User zum Ende scrollt, Then steht ein Management-Summary-Absatz	should
5	Given Budget-Vergleich-Karte im Trustee-Dashboard, When der File-Link erscheint, Then zeigt das UI ein Excel-Icon und Label "Excel-Bericht"	should

Testplan

ID	AC	Art	Automatisiert	Repo-Pfad	Status
T1	1	integration	ja	gateway/tests/features/trustee/test_budget_comparison_format.py	pending
T2	2,3,4	integration	ja	gateway/tests/features/trustee/test_budget_comparison_structure.py	pending
T3	5	unit	ja	frontend_nyla/src/pages/views/trustee/tests/TrusteeAnalyseView.test.tsx	pending

Abschluss

wiki/b-reference/gateway/features/trustee.md Budget-Service-Sektion aktualisieren
Dieses Dokument -> z-archive/ verschoben

7.1 KiB Raw Blame History