# Reporting – Entwicklerdokumentation **Zielgruppe:** Entwicklung und technische Weiterentwicklung ## 1. Zweck und Systemüberblick Das Portalum-Berichtswesen kapselt die Auswahl, Parametrierung und Ausgabe der List-&-Label-Berichte in der ReportEngine. Die zentrale Oberfläche ist `Frontends/Portalum/Reporting/LuLReporting.frm`. Sie verbindet: - die Berichtsauswahl über Berichtstyp und Berichtsdefinition, - berichtsspezifische Parameter und Filter, - Layout-, Sortierungs- und Druckerauswahl, - Vorschau, Papierdruck, PDF und zusätzlichen CSV-Export, - Favoriten als wiederverwendbare Ausgabekonfiguration, - Druckaufträge/Print Jobs als automatisierbare Folge mehrerer Favoriten, - den Info-Tab mit der technischen RTF-Dokumentation je Berichtsnummer. Der eigentliche List-&-Label-Auftrag wird in `frmLuLControl` als Job verwaltet. Fehlerstatus, Start/Ende, erfolgreiche Datensätze und CSV-Zeilen werden dort zentral geführt. Die Oberfläche lädt zunächst die Konfiguration und Felddefinitionen, übergibt anschließend die Nutzdaten und beendet danach den List-&-Label-Auftrag kontrolliert. Wichtige Einstiegspunkte: - Parameterhilfe: `Frontends/Portalum/Reporting/LuLReporting.frm:3675` - Favorit anlegen: `Frontends/Portalum/Reporting/LuLReporting.frm:3866` - Favorit laden/speichern: `Frontends/Portalum/Reporting/LuLReporting.frm:4210` und `Frontends/Portalum/Reporting/LuLReporting.frm:4284` - Druckaufträge ausführen: `Frontends/Portalum/Reporting/LuLReporting.frm:4386` - zentrale Datenübergabe: `Frontends/Portalum/Reporting/LuLReporting.frm:4472` - direkter PDF-Export: `Frontends/Portalum/Reporting/LuLReporting.frm:6516` - CSV-Ziel auflösen: `Frontends/Portalum/Reporting/LuLReporting.frm:7848` ## 2. Bedienoberfläche ### 2.1 Parameter-Tab Der Parameter-Tab besitzt jetzt flächendeckend aussagekräftige Hinweise. Alle `sevText`-Komponenten verwenden Balloon-Info mit Titel und Info-Icon. `sevCheck` unterstützt keine sev-Balloon-Eigenschaften und verwendet deshalb den ausführlichen Standard-Tooltip `ToolTipText`. Abgedeckt sind: - Start- und Enddatum einschließlich Hinweis auf dynamische Datumsregeln, - optionaler Uhrzeitbereich, - vier berichtsspezifische Optionen, - vier berichtsspezifische Text-/Zahlenparameter, - Ausgabe nicht verwendeter Filter, - Ausgabe definierter Fußzeilen, - zusätzlicher CSV-Export, - CSV-Zielordner und dynamischer Dateiname, - Berichtstitel, Kurzbeschreibung und Anzahl verfügbarer Layoutvarianten. Die Hinweise erläutern außerdem, dass Datum, Zeit, Zusatzparameter und CSV-Einstellungen in Favoriten und Druckaufträgen weiterverwendet werden. Beim CSV-Dateinamen werden die Platzhalter `%DV`, `%D1` und `%D2` erklärt; beim Überfahren wird zusätzlich der aktuell aufgelöste Dateiname angezeigt. ### 2.2 Filter-Tab Die Bedienung dynamischer und manueller Filter ist optisch getrennt: - Dokument mit kleinem Zahnrad: dynamischer Wert aus aktuellem Bediener, Arbeitsplatz, Sitzung oder Tagesabschluss. - Dokument mit drei horizontalen Linien: manuelle Parameterauswahl; der Klick führt denselben Pfad wie `vsFilter_CellButtonClick` aus. Die Gestaltung basiert auf dem bereits vorhandenen Dokument-/Filter-Symbol der `imgTV`-ImageList. Dunkelgrau `#212121` und Portalum-Grün `#9CBD52` wurden direkt aus dieser Referenz übernommen. Die Quelldateien `Frontends/Portalum/Reporting/Images/FilterDynamic.ico` und `Frontends/Portalum/Reporting/Images/FilterSelect.ico` sind echte transparente 16×16-/8-Bit-ICO-Dateien mit klassischer 1-Bit-AND-Maske. Beide ICOs sind in `LuLReporting.frx` eingebettet und unter `FILTERDYNAMIC` und `FILTERSELECT` in `imgTV` hinterlegt. Grid und Kontextmenü verwenden dieselben Ressourcen (`Frontends/Portalum/Reporting/LuLReporting.frm:5571`, `Frontends/Portalum/Reporting/LuLReporting.frm:8784`). ## 3. PDF-Export – wesentliche Verbesserungen Der PDF-Export wurde erheblich verbessert und ist jetzt nicht mehr nur ein manueller Einzelweg, sondern sauber in Favoriten und Druckaufträge/Print Jobs eingebunden. ### 3.1 Zielprüfung Bei ausdrücklich angegebener PDF-Ausgabe werden Zielordner und Dateiname vor dem Start geprüft. Ein fehlendes oder nicht erreichbares PDF-Ziel führt zu einem eindeutigen Abbruch. Es erfolgt insbesondere kein unbemerkter Fallback auf den Windows-Standarddrucker. Die Prüfung liegt sowohl im interaktiven PDF-Weg als auch im Direktdruckweg (`Frontends/Portalum/Reporting/LuLReporting.frm:6516`, `Frontends/Portalum/Reporting/LuLDirectPrint.frm:153`). ### 3.2 Kontrollierter List-&-Label-Auftrag Relevante List-&-Label-Rückgabewerte werden zentral über `RegisterLlResult` ausgewertet. Dazu gehören unter anderem Druckerzuordnung, Start, Seiten, Felder, Feldabschluss und Auftragsende. Der Job besitzt einen eindeutigen Fehlerstatus und einen zentralen Aufräumpfad (`Frontends/Portalum/Reporting/LuLControl.frm:141`, `Frontends/Portalum/Reporting/LuLControl.frm:159`, `Frontends/Portalum/Reporting/LuLControl.frm:182`). Zusätzlich gilt: - Benutzerabbruch und technischer Fehler werden unterschieden. - `LlPrintEnd` wird kontrolliert und nicht mehrfach ausgeführt. - Berichte ohne übergebene Datensätze erzeugen keine leere PDF-Datei. - Nur erfolgreich abgeschlossene PDF-Ausgaben erhöhen die PDF-Zähler, beispielsweise bei Rechnungen (`Frontends/Portalum/Reporting/LuLAusgabe.cls:690`). - Print Jobs können PDF still ohne Auswahldialog erzeugen und erhalten den PDF-Zielordner aus dem Auftrag. ### 3.3 Favoriten und Print Jobs Ein Favorit speichert den Ausgabekanal über `cpFavDrucker`; für PDF wird der Wert `PDF` hinterlegt. Beim Print Job wird zunächst der komplette Favorit mit Layout, Sortierung, Parametern, Filtern und Exportoptionen geladen. Anschließend wird entweder der Drucker des Favoriten beziehungsweise Auftrags verwendet oder eine PDF-Datei erzeugt. Der PDF-Dateiname eines Druckauftrags wird eindeutig aus Favoritenname, Datum und Bediener-/Computerkennung aufgebaut. Der PDF-Zielordner stammt aus `cpPJFolderPDF` des Druckauftrags (`Frontends/Portalum/Reporting/LuLReporting.frm:4386`). ## 4. CSV-Export – wesentliche Verbesserungen Auch der zusätzliche CSV-Export wurde erheblich verbessert und funktioniert sauber mit manuellen Ausgaben, Favoriten und Druckaufträgen/Print Jobs. ### 4.1 Konfiguration und Platzhalter Der CSV-Export kann zusätzlich zu Vorschau, Druck oder PDF aktiviert werden. Gespeichert werden: - Aktivierung über `cpFavAdvCSVuse`, - Zielordner über `cpFavAdvCSVFolder`, - Dateinamensmuster über `cpFavAdvCSVDynFile`. Unterstützte Platzhalter: - `%DV`: Berichtsbezeichnung, - `%D1`: Startdatum, - `%D2`: Enddatum. Die frühere falsche Verwendung des Startdatums für `%D2` wurde korrigiert. Der Name wird erst beim konkreten Ausführen aufgelöst. Dadurch funktionieren dynamische Datumswerte auch nach dem Laden eines Favoriten oder beim Start eines Druckauftrags. ### 4.2 Persistenz in Favoriten `FavoritAdd`, `FavoritLoad`, `FavoritStore` und `MoveToFavorit` übertragen CSV-Aktivierung, Ordner und Dateinamensmuster zusammen mit Datum, Uhrzeit, Zusatzparametern, Layout, Sortierung, Drucker und Filtern. Ein Print Job lädt somit nicht nur den Bericht, sondern die vollständige CSV-Konfiguration des zugeordneten Favoriten (`Frontends/Portalum/Reporting/LuLReporting.frm:3866`, `Frontends/Portalum/Reporting/LuLReporting.frm:4210`, `Frontends/Portalum/Reporting/LuLReporting.frm:4284`). ### 4.3 Dateiverarbeitung und Fehler `ReadExportFileName` setzt den vollständigen Namen zusammen, behandelt vorhandene Dateien kontrolliert und meldet Fehler über den zentralen Jobstatus. `WriteCSVLine` verwendet `FreeFile`, unterscheidet Header und Datenzeilen und leitet Öffnungs- oder Schreibfehler an `FailJob` weiter (`Frontends/Portalum/Reporting/LuLReporting.frm:7848`, `Frontends/Portalum/Reporting/LuLControl.frm:195`). CSV wird in der zentralen Datenübergabe vorbereitet. Damit greift derselbe Exportweg auch dann, wenn ein Favorit über einen Print Job als Papierdruck oder PDF gestartet wird (`Frontends/Portalum/Reporting/LuLReporting.frm:4472`). ## 5. Favoriten und Druckaufträge Favoriten bilden die wiederverwendbare Konfiguration eines Berichts. Persistiert werden insbesondere: - Berichtstyp, Layout und Sortierung, - Drucker beziehungsweise PDF, - feste oder dynamische Datumswerte, - Uhrzeitbereich, - berichtsspezifische Checkboxen und Textparameter, - aktive Filter einschließlich dynamischer Filter, - Anzeige nicht verwendeter Filter, - CSV-Aktivierung, CSV-Ordner und Dateinamensmuster. Druckaufträge referenzieren einen oder mehrere Favoriten. `PrintAuftraege` lädt jeden Favoriten über `MoveToFavorit`, kann den Drucker aus Favorit, Arbeitsplatz, Standarddrucker oder expliziter Vorgabe beziehen und unterstützt PDF als eigenen Ausgabeweg. Die optional gespeicherte CSV-Konfiguration läuft dabei über denselben zentralen Datenjob mit. Damit sind PDF und CSV jetzt konsistent in den wiederverwendbaren und automatisierten Ausgabepfaden enthalten und nicht mehr auf eine manuelle Sitzung beschränkt. ## 6. Fehlerbehandlung und Stabilität Folgende Bereiche wurden abgesichert: - zentrale List-&-Label-Fehlerauswertung mit Schritt, Fehlernummer und Beschreibung, - kontrollierter Jobabschluss und eindeutiger Benutzerabbruch, - Erkennung von Ausgaben ohne Datensätze, - keine Druckerauswahl bei automatischen Ausgaben, - kein Papierausdruck bei ungültigem PDF-Ziel, - kontrollierte CSV-Öffnungs-, Lösch- und Schreibfehler, - sichtbare RTF-Ladefehler und atomisches Speichern mit Sicherungsdatei, - Sammlung und Markierung aller fehlenden Pflichtfilter, - harte Fehler bei nicht lesbaren Layoutdateien, weiche Warnungen bei alten Metadaten, - Zähler nur für tatsächlich abgeschlossene Druck- und PDF-Ausgaben. ## 7. Berichtsspezifische Korrekturen - Bericht 6004: Query-/Nullzugriffe, Feldname und Veranstaltungsindex korrigiert. - Bericht 3530: falscher Routerfall korrigiert und Bestelllisten-Datenübergabe implementiert. - Bericht 6001: doppelte Parameterfälle zusammengeführt. - Bericht 9503 (Küchenbon): bis zur fachlichen Festlegung bewusst gesperrt. - Bericht 9505 (Bewirtungsbeleg): bis zur fachlichen Festlegung bewusst gesperrt. - Bon-Zahlungsarten: Fortschrittsberechnung verwendet die tatsächliche Anzahl gültiger Zahlungsarten. ## 8. Info-Dateien und zukünftige Berichte Für alle derzeit bekannten Berichte wurden 83 einheitlich aufgebaute RTF-Info-Dateien erzeugt. Der Generator liegt unter `Tools/ReportingInfo/Build-ReportingInfo.ps1`. Inhaltliche Definitionen und Prüfwerkzeuge befinden sich ebenfalls unter `Tools/ReportingInfo`. Verbindliche Zeichensatzregel: Die Definitionsskripte werden wegen Windows PowerShell 5 mit UTF-8-BOM gespeichert. Der Generator erzeugt dagegen bewusst ASCII-RTF mit `\ansicpg1252`. Zeichen aus Windows-1252 werden als `\'hh` geschrieben; andere Unicode-Zeichen, beispielsweise der Pfeil, als `\uN?`. `\ansicpg65001` und rohe UTF-8-Bytes sind für das VB6-`richtx32.ocx` nicht zulässig. Nach jeder Generierung ist `powershell.exe -NoProfile -ExecutionPolicy Bypass -File Tools\ReportingInfo\Test-ReportingInfoRtf.ps1` auszuführen. Der Prüfer lädt sämtliche Dateien über einen Windows-RichTextBox-Parser und erkennt falsche Header, rohe Nicht-ASCII-Bytes sowie typische Mojibake-Zeichen. Für einen neuen Bericht ist künftig erforderlich: 1. eindeutigen Berichtstyp und Routerfall ergänzen, 2. Parameter in `INITParamter` definieren, 3. Filter mit Pflichtstatus und Editierbarkeit registrieren, 4. Datenübergabe und No-Data-Verhalten prüfen, 5. Layout-/Metadaten bereitstellen, 6. Info-Definition ergänzen, RTFs neu erzeugen und `Test-ReportingInfoRtf.ps1` ausführen, 7. Favorit und Print Job mit PDF sowie optionalem CSV testen. ## 9. Setup und Auslieferung Die Reporting-Info-Dateien werden bereits rekursiv über `Reporting/Info/*` in Setup und Update übernommen. Für die neuen Info-Dateien war keine zusätzliche Inno-Setup-Regel erforderlich (`C:/Source/Setup6/Setup_Files.iss:246`, `C:/Source/Setup6/Update_Files.iss:182`). Die Filter-Icons sind in `LuLReporting.frx` eingebettet und benötigen ebenfalls keine externe Setup-Datei. ## 10. Validierung Erfolgreich durchgeführt: - statische Prüfung der geänderten Fehler- und Ausgabepfade, - Vollständigkeits- und Zeichensatzprüfung: 83 von 83 Info-RTFs erfolgreich über `Test-ReportingInfoRtf.ps1` geladen, - VB6-Build `ReportEngine.vbp`, zuletzt `ReportEngine.dll` mit 1.593.344 Byte, - VB6-Build des SalesEngine-gekoppelten `TestDemoREE.vbp`, `TestDemoREE.exe` mit 471.040 Byte, - Prüfung der eingebetteten transparenten 16×16-Icons, - Prüfung der Tooltip-Abdeckung aller sichtbaren Parametergruppen. Nicht automatisch ausgelöst wurden reale Papierdrucke, Kundendatenänderungen oder physische End-to-End-Ausgaben. Diese Prüfungen bleiben Bestandteil des fachlichen Abnahmetests. ## 11. Bewusst offene Fachthemen - 9503 Küchenbon: Positionsquelle und gewünschte Struktur fachlich festlegen. - 9505 Bewirtungsbeleg: Datenquelle, Pflichtobjekt und Standardlayout festlegen. - Neue Berichte müssen weiterhin einzeln auf fachliche Filterwirkung, Layoutfelder sowie kundenspezifische Drucker- und Dateirechte geprüft werden. ## 12. Anwenderdokumentation Das vollständige, offline-fähige HTML-Anwenderhandbuch liegt unter `Tools/ReportingInfo/Anwenderdokumentation/Reporting-Anwenderhandbuch.html`. Die zugehörigen Screenshots werden relativ aus dem Unterordner `assets` geladen. Das Handbuch beschreibt die fachliche Bedienung von Berichtsauswahl, Parametern, dynamischen und manuellen Filtern, Layout, Sortierung, Drucker, Info-Tab, Vorschau, Druck, PDF, CSV, Favoriten und Druckaufträgen. Zusätzlich enthält es konkrete Praxisabläufe, Fehlermeldungen, Supportangaben und Abnahmechecklisten. Validiert wurden HTML-Struktur, interne Sprungziele, lokale Bildverweise, Alternativtexte und das Drucklayout. Ein lokaler Edge-Drucktest erzeugte 23 Seiten ohne leere Seite.