# MOSAIC Report Modul

## Uebersicht

Der Report-Baustein besteht aus:

- `_pgm/admin/create_show_report.php`
  Generator fuer `<name>_report.cfg` und `<name>_report_function.php`
  inklusive visuellem Spalten-, Filter- und Summary-Editor
- `<name>_report.cfg`
  Konfiguration fuer Datenquelle, Spalten, Filter, Kennzahlen und Exporte
- `<name>_report_function.php`
  Optionale Hook-Datei im MOSAIC-Stil
- `_pgm/show_report.php`
  Runner fuer HTML-, PDF-, XLS-, CSV- und JSON-Ausgabe

## Generator-Editor

`create_show_report.php` arbeitet jetzt primaer mit visuellen Buildern statt mit freien JSON-Textfeldern:

- `Spalten-Editor`
  fuer `field`, `label`, `type`, `align`, `format`, `visible`
- `Filter-Editor`
  fuer `alias`, `label`, `type`, `enabled`, `operators`, `default_operator`
- `Summary-Editor`
  fuer `label`, `type`, `field`, `format`
- `Feldvorschlaege`
  werden automatisch aus `sql` oder `base_table` geladen und koennen direkt in Spalten, Filter und Summary uebernommen werden
- `Basistabelle`
  wird im Tabellenmodus als echtes Dropdown aus der Projekt-DB geladen statt als Freitext
- `WHERE / ORDER BY-Helfer`
  erzeugt die Konfigurationswerte fuer `data.where` und `data.order_by` ohne Freitext als Hauptweg

Die JSON-Struktur wird weiterhin intern genauso erzeugt wie bisher, damit `show_report.php` und bestehende Hooks unveraendert bleiben.

Zusaetzlich zeigt der Generator pro Bereich eine JSON-Vorschau an, damit die erzeugte Konfiguration schnell geprueft werden kann.

## Dateinamen

Der Generator erzwingt das Suffix `_report.cfg`.

Beispiel:

- `umsatz_report.cfg`
- `umsatz_report_function.php`

## Grundaufbau der Config

```php
return [
    'app' => [
        'type' => 'report',
        'version' => 1,
        'title' => 'Umsatzreport',
    ],
    'description' => 'Monatlicher Umsatzbericht',
    'hooks_file' => 'umsatz_report_function.php',
    'data' => [
        'database' => 'default',
        'sql_mode' => 'custom',
        'sql' => 'SELECT id, name, amount, created_at FROM umsaetze',
        'base_table' => '',
        'base_alias' => 'rpt',
        'where' => '',
        'order_by' => '',
    ],
    'columns' => [
        ['field' => 'id', 'label' => 'ID', 'visible' => true, 'type' => 'number', 'align' => 'right'],
        ['field' => 'name', 'label' => 'Name', 'visible' => true, 'type' => 'text', 'align' => 'left'],
        ['field' => 'amount', 'label' => 'Betrag', 'visible' => true, 'type' => 'number', 'align' => 'right', 'format' => '99999.99'],
        ['field' => 'created_at', 'label' => 'Erstellt', 'visible' => true, 'type' => 'datetime', 'align' => 'left'],
    ],
    'filters' => [
        ['alias' => 'name', 'label' => 'Name', 'enabled' => true, 'type' => 'text', 'operators' => ['contains', '=', 'starts_with'], 'default_operator' => 'contains'],
        ['alias' => 'amount', 'label' => 'Betrag', 'enabled' => true, 'type' => 'number', 'operators' => ['=', '>', '>=', '<', '<=', 'between'], 'default_operator' => '>='],
    ],
    'summary' => [
        ['label' => 'Anzahl', 'type' => 'count', 'field' => '*'],
        ['label' => 'Summe Betrag', 'type' => 'sum', 'field' => 'amount', 'format' => '99999.99'],
    ],
    'ui' => [
        'headline' => 'Umsatzreport',
        'intro' => 'Filterbarer Bericht mit Exporten',
        'show_filter_bar' => true,
        'show_summary' => true,
        'striped_rows' => true,
        'empty_message' => 'Keine Daten gefunden.',
    ],
    'exports' => [
        'pdf' => true,
        'xls' => true,
        'csv' => true,
        'json' => true,
        'default_filename' => 'umsatzreport',
        'pdf_orientation' => 'L',
        'pdf_page_size' => 'A4',
    ],
];
```

## Datenquelle

Es gibt zwei Modi:

### `sql_mode = custom`

Der Report benutzt `data.sql` direkt als Basissql.

### `sql_mode = table`

Der Runner erzeugt intern:

```sql
SELECT * FROM <base_table> <base_alias>
```

und ergaenzt optional `where` und `order_by`.

## Filter

Filter werden auf die aeußere Query-Huelle `report_src` angewendet.
Deshalb sollten die benoetigten Spalten im SQL bereits als sichtbare Feldnamen bzw. Aliase vorhanden sein.

Unterstuetzte Operatoren:

- `contains`
- `starts_with`
- `ends_with`
- `=`
- `<>`
- `>`
- `>=`
- `<`
- `<=`
- `between`
- `in`
- `today`
- `this_month`
- `this_year`
- `empty`
- `not_empty`

## Exporte

`show_report.php` unterstuetzt:

- HTML: Standardansicht
- PDF: `?format=pdf`
- XLS: `?format=xls`
- CSV: `?format=csv`
- JSON: `?format=json`

## Hooks

Folgende Hooks werden unterstuetzt:

- `onApplicationInit(array &$context, array &$reportConfig)`
- `onCheckSecurity(array &$context, array &$reportConfig)`
- `onBeforeQuery(array &$context, array &$queryPayload, array &$reportConfig)`
- `onAfterQuery(array &$context, array &$rows, array &$reportConfig)`
- `onRow(array &$context, array &$row, array &$reportConfig)`
- `onBeforeSummary(array &$context, array &$summaryRows, array &$rows, array &$reportConfig)`
- `onBeforeRender(array &$context, array &$renderPayload, array &$reportConfig)`
- `onBeforeExport(array &$context, array &$exportPayload, array &$reportConfig)`
- `onAfterRender(array &$context, array &$renderPayload, array &$reportConfig)`

## Aufruf

Direkt:

```text
_pgm/show_report.php?project=<projekt>&modul=<name>&modul_path=<ordner>
```

Beispiel:

```text
_pgm/show_report.php?project=svsb&modul=umsatz&modul_path=reports
```

Dann erwartet MOSAIC die Konfiguration hier:

```text
svsb/reports/umsatz_report.cfg
```

## Integration

- `create_menu.php` erkennt `_report.cfg` und setzt den Runner auf `show_report.php`
- `show_menu.php` akzeptiert `show_report.php`
- `show_dashboard.php` erkennt `_report.cfg` und laedt Reports als Dashboard-Widget
- `admin.php` bietet einen eigenen Button `REPORT`

Das Modul folgt damit ebenfalls dem allgemeinen MOSAIC-Runnerkonzept:

- `grid/form/egrid` fuer generische CRUD-Faelle
- `show_*` fuer fachliche Anzeige- und Spezialrunner