163 lines
7.1 KiB
Markdown
163 lines
7.1 KiB
Markdown
<!-- status: plan -->
|
|
<!-- started: 2026-04-29 -->
|
|
<!-- component: gateway, frontend-nyla -->
|
|
|
|
# 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`:
|
|
|
|
```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
|
|
`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 |
|
|
|
|
## Links
|
|
|
|
- Workflow-Definition: `gateway/modules/features/trustee/mainTrustee.py`
|
|
430-461.
|
|
- Renderer-Pipeline: `gateway/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/gateway/features/trustee.md` Budget-Service-Sektion
|
|
aktualisieren
|
|
- [ ] Dieses Dokument -> `z-archive/` verschoben
|