<!-- status: plan -->
<!-- started: 2026-04-29 -->
<!-- component: gateway, ui-nyla -->

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

## Beschreibung und Kontext

Der Trustee-Service "Budget-Vergleich"
(`platform-core/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
  (`platform-core/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:
  - `platform-core/modules/features/trustee/mainTrustee.py` -- Budget-Template
    Z. 430-461 (Prompt + `resultType` + Output-Schema-Hinweis).
- Frontend:
  - `ui-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`:

```text
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
      `platform-core/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
      `platform-core/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 | platform-core/tests/features/trustee/test_budget_comparison_format.py | pending |
| T2 | 2,3,4 | integration | ja | platform-core/tests/features/trustee/test_budget_comparison_structure.py | pending |
| T3 | 5 | unit | ja | ui-nyla/src/pages/views/trustee/__tests__/TrusteeAnalyseView.test.tsx | pending |

## Links

- Workflow-Definition: `platform-core/modules/features/trustee/mainTrustee.py`
  430-461.
- Renderer-Pipeline: `platform-core/modules/serviceCenter/services/serviceGeneration/`.
- Verwandter Plan: `wiki/c-work/1-plan/2026-04-ai-reports-theming-and-pipeline.md`.
- Audit-Quelle: Subagent-Report 2026-04-29.

## Abschluss

- [ ] `wiki/b-reference/platform-core/features/trustee.md` Budget-Service-Sektion
      aktualisieren
- [ ] Dieses Dokument -> `z-archive/` verschoben