# MOSAIC KI-Entwicklerhandbuch

## Zweck

Dieses Dokument beschreibt MOSAIC so, dass eine KI daraus neue Module, Erweiterungen und Standardanwendungen ableiten kann, ohne zuerst den gesamten Kerncode lesen zu muessen.

Die Regeln hier sind als Arbeits-Spezifikation gedacht:

- kurz
- eindeutig
- copy/paste-faehig
- auf dem aktuellen Kernstand April 2026

Ergaenzend dazu gibt es eine reine Vorlagen-Datei:

- `MOSAIC_KI_Modulvorlagen.md`

Die oeffentliche und verbindliche Konfigurations-Spezifikation fuer externe Generatoren und KI-Systeme steht in:

- `MOSAIC_Config_Spezifikation.md`

## 1. Grundmodell

MOSAIC ist konfigurationsgetrieben.

Die fachliche Arbeit entsteht ueber:

- `*_grid.cfg`
- `*_form.cfg`
- `*_egrid.cfg`
- `*_report.cfg`
- `*_forum.cfg`
- `*_chart.cfg`
- `*_menu.cfg`
- optionale `*_function.php`

Die KI soll immer zuerst versuchen, ein Problem ueber Konfiguration und kleine Hook-Dateien zu loesen. Kerncode in `_pgm` wird nur angepasst, wenn ein Problem **frameworkweit** ist und nicht sauber projektlokal geloest werden kann.

## 2. Runner-Regel

Im Kern gilt verbindlich:

- `grid.php`
- `form.php`
- `show_egrid.php`

bilden die kanonischen CRUD-Einstiege. `show_egrid.php` delegiert intern an `egrid.php`.

Alle anderen fachlichen Runner verwenden konsequent `show_*`.

### Kanonische Runner

- `_pgm/show_menu.php`
- `_pgm/show_dashboard.php`
- `_pgm/show_calendar.php`
- `_pgm/show_connector.php`
- `_pgm/show_paypal.php`
- `_pgm/show_report.php`
- `_pgm/show_forum.php`
- `_pgm/show_chart.php`
- `_pgm/show_login.php`
- `_pgm/show_log.php`
- `_pgm/show_egrid.php`
- `_pgm/show_v_menu.php`

### Verbindliche Regel fuer KI-generierten Code

- Keine Alt-Wrapper erzeugen.
- Keine Verweise auf geloeschte Legacy-Namen erzeugen.
- eGrid-Konfigurationen direkt als `*_egrid.cfg` erzeugen; es gibt keinen eigenen eGrid-Builder im Kern.
- Bei neuen Menueeintraegen und Generatorlogik nur das aktuelle Runner-Schema verwenden.
- Bei Audit- oder Protokollansichten den Kernrunner `show_log.php` statt projektspezifischer Eigenloesungen bevorzugen.

### Geloeschte Legacy-Namen

Diese Namen duerfen fuer neue Arbeiten nicht mehr verwendet werden:

- `menu_show.php`
- `dashboard_show.php`
- `chart.php`
- `report.php`
- `login_show.php`
- `v_menu.php`

## 3. Dateinamen und Zuordnung

### CRUD-Module

Beispiel `kunde`:

- `kunde_grid.cfg`
- `kunde_form.cfg`
- `kunde_egrid.cfg`
- optional `kunde_grid_function.php`
- optional `kunde_form_function.php`
- optional `kunde_egrid_function.php`

### Weitere Modultypen

- `umsatz_report.cfg` -> `show_report.php`
- `main_forum.cfg` oder `*_forum.cfg` -> `show_forum.php`
- `analyse_chart.cfg` -> `show_chart.php`
- `main_menu.cfg` oder `*_menu.cfg` -> `show_menu.php`
- `navigation_v_menu.cfg` -> `show_v_menu.php`

### Hook-Regel

Wenn es zu einer `cfg`-Datei Logik gibt, lautet der Name immer:

- `xyz.cfg` -> `xyz_function.php`

Beispiele:

- `project_grid.cfg` -> `project_grid_function.php`
- `project_form.cfg` -> `project_form_function.php`
- `main_menu.cfg` -> `main_menu_function.php`
- `main_forum.cfg` -> `main_forum_function.php`

## 3a. Spezifikation fuer `show_forum.php`

Forum-Module laufen ueber:

- `show_forum.php`
- Konfigurationsdatei `*_forum.cfg`
- optional `*_forum_function.php`

Pflicht fuer die Konfiguration sind mindestens:

- `project`
- `database`
- `module`
- `module_path`
- `bootstrap_file`
- `assets_relative_path`
- `storage_relative_path`
- `setup_sql_relative_path`
- `routing.default_view`
- `views`

Die `views`-Definition ordnet logische Forumsichten auf konkrete Skriptdateien im Modulordner ab.

Beispiel:

```php
'views' => [
    'start' => [
        'label' => 'Start',
        'script' => 'start.php',
    ],
    'topic' => [
        'label' => 'Thema',
        'script' => 'topic.php',
    ],
    'attachment' => [
        'label' => 'Anlage',
        'script' => 'attachment_download.php',
    ],
],
```

Regeln fuer KI:

- interne Links innerhalb eines Forum-Moduls immer ueber `show_forum.php` erzeugen
- Dateianlagen physisch nur ueber `storage_relative_path`
- Menues auf Forum-Boards ueber `show_forum.php` und `view=board`
- `bootstrap_file` darf eine projektspezifische Bibliothek wie `forum/forum_lib.php` laden

## 4. Grundregeln fuer neue Module

Wenn eine KI ein neues Standardmodul erzeugt, soll sie in dieser Reihenfolge denken:

1. Tabelle oder Sicht klaeren
2. `grid.cfg` anlegen
3. `form.cfg` anlegen
4. nur bei Bedarf Hook-Dateien anlegen
5. Menueeintrag setzen
6. Filters, Lookups, Session-Bindung und Delete-Schutz nachziehen

## 4a. Projekt-Security und Runner-Override

Die Projektkonfiguration in `mosaic_config.lic` ist fuer die Security verbindlich.

Aktueller Kernstand:

- `security.project_enabled = true`
  Dann werden Rollenrechte im Kern aktiviert, Login-Rollenlogik geladen und Runner gegen `iss_apps` / `iss_groups_apps` geprueft.
- `security.project_enabled = false`
  Dann gibt es keine Rollenauswahl, und die Rechtepruefung der Runner wird global uebersprungen.

Zusaetzlicher Runner-Override:

- In einer Runner-Konfiguration kann explizit `security => false` gesetzt werden.
- Das schaltet die Rechtepruefung fuer genau diesen Runner aus, auch wenn das Projekt insgesamt Security aktiviert hat.
- Dieser Override ist fuer gezielte oeffentliche oder technische Einstiegsseiten gedacht.

Regel fuer KI:

- Projektweite Security immer ueber `mosaic_config.lic` denken
- den Runner-Override nur bewusst und sparsam einsetzen
- keine eigene Parallel-Logik fuer Rechte neben dem Kern erfinden

## 4b. Audit-Logging von Datenaenderungen

Die Projektkonfiguration in `mosaic_config.lic` steuert auch das zentrale Audit-Logging:

- `logging.project_enabled = true`
  Dann protokolliert MOSAIC Insert, Update und Delete zentral in `iss_log`.
- `logging.project_enabled = false`
  Dann wird kein Audit-Log geschrieben.

Wichtige Regeln:

- Das Logging wird im Kern erzwungen und kann pro Runner nicht deaktiviert werden.
- BLOB-, Grafik- und Dateifelder werden nicht als Aenderungswerte in `iss_log` gespeichert.
- Fuer die Anzeige existiert der Kernrunner `_pgm/show_log.php`.
- Fuer die Tabellenerzeugung existiert die Admin-Seite `_pgm/admin/create_log.php`.

Regel fuer KI:

- bei projektoffenem Logging keine eigene Protokolltabelle parallel entwerfen
- stattdessen `iss_log` und `show_log.php` verwenden

## 5. Pfadkonzept

ISS-MOSAIC arbeitet mit einem dynamisch erkannten MOSAIC-Root. Der Ordner `_pgm` muss deshalb nicht zwingend unter `/iss` liegen. Entscheidend ist nur, dass `_pgm` und alle Projektordner unter demselben MOSAIC-Root liegen.

Zulaessige Strukturen sind zum Beispiel:

```text
WEB-Root/iss/_pgm
WEB-Root/iss/mo_user
WEB-Root/iss/demo
```

oder:

```text
WEB-Root/_pgm
WEB-Root/mo_user
WEB-Root/demo
```

Der Kern ermittelt daraus `APP_ROOT_PATH` und `APP_ROOT_URL`. Neue Kern- und Projektlogik darf deshalb keine festen Annahmen wie `/iss/_pgm`, `/iss/mo_user` oder `C:\xampp\htdocs\iss` enthalten.

Projektmodule liegen unter dem jeweiligen Projektordner, zum Beispiel:

- `<MOSAIC-Root>\cl\05_project`
- `<MOSAIC-Root>\cl\09_z_daten\01_formulare`

Der KI-Standard ist:

- modulbezogene Dateien liegen gemeinsam in einem Fachordner
- Unterebenen liegen in Unterordnern
- Namensschema soll im Projekt konsistent bleiben
- Pfad- und Dateiangaben im MOSAIC-Kern werden grundsaetzlich ueber `file_to_unix()` oder einen gleichnamigen guarded Bootstrap normalisiert
- fruehe Kern-/Admin-Dateien duerfen `file_to_unix()` lokal als Fallback bereitstellen, sollen dadurch aber nicht die komplette `iss_functions.php` vorzeitig laden
- URLs zu Kernrunnern werden aus `APP_ROOT_URL` plus `_pgm/<runner>.php` gebaut

Beispiel:

- `05_project\project_grid.cfg`
- `05_project\project_form.cfg`
- `05_project\project_form_function.php`
- `05_project\02_berichte\project_bericht_grid.cfg`
- `05_project\02_berichte\project_bericht_form.cfg`

## 6. Minimalregel fuer `primary_key`

`primary_key` soll in MOSAIC immer als Array gepflegt werden, auch bei einem einzelnen Feld.

Beispiel:

```php
'primary_key' => ['project_id'],
```

Nicht bevorzugt:

```php
'primary_key' => 'project_id',
```

## 7. Muster fuer `grid.cfg`

Ein Grid beschreibt:

- Titel
- SQL-Basisabfrage
- Primary Key
- Spalten
- Berechtigungen
- optionale Filter

### Minimales Muster

```php
<?php

return [
    'title' => 'Beispiel',
    'db_typ' => 'mysql',
    'sql' => 'SELECT `beispiel_id`, `bezeichnung`, `active` FROM `beispiel` ORDER BY `bezeichnung`',
    'primary_key' => ['beispiel_id'],
    'autoincrement' => true,
    'edit_link' => 'beispiel',
    'columns' => [
        'beispiel_id' => [
            'label' => 'ID',
            'type' => 'number',
            'sort' => true,
        ],
        'bezeichnung' => [
            'label' => 'Bezeichnung',
            'type' => 'text',
            'quicksearch' => true,
            'sort' => true,
        ],
        'active' => [
            'label' => 'Aktiv',
            'type' => 'checkbox',
            'sort' => true,
        ],
    ],
    'permissions' => [
        'edit' => true,
        'add' => true,
        'delete' => false,
        'copy' => false,
        'view' => true,
    ],
];
```

### Grid-Regeln fuer KI

- `edit_link` verweist auf das Modul ohne Suffix
- Suchspalten fuer Advanced Search duerfen unsichtbar sein
- Kontextfilter moeglichst schon in der SQL-Basisabfrage setzen
- Untergrids ohne Elternkontext sollen leer bleiben statt zu viel anzuzeigen

## 8. Muster fuer `form.cfg`

Ein Formular beschreibt:

- Zieltabelle
- Abfrage fuer den Bearbeitungskontext
- Primary Key
- Tabs
- Felder
- optional `transaction`

### Minimales Muster

```php
<?php

return [
    'title' => 'Beispiel',
    'table' => 'beispiel',
    'query' => 'SELECT `beispiel_id`, `bezeichnung`, `bemerkung`, `created`, `updated`, `created_by`, `updated_by`, `active` FROM `beispiel`',
    'primary_key' => ['beispiel_id'],
    'autoincrement' => true,
    'transaction' => false,
    'tabs' => [
        'TAB_1' => [
            'label' => 'Stammdaten',
            'fields' => [
                'beispiel_id' => [
                    'label' => 'ID',
                    'type' => 'integer',
                    'hidden_on_insert' => true,
                ],
                'bezeichnung' => [
                    'label' => 'Bezeichnung',
                    'type' => 'text',
                    'required' => true,
                    'input_length' => 100,
                ],
                'bemerkung' => [
                    'label' => 'Bemerkung',
                    'type' => 'text_multiline',
                    'input_length' => 65535,
                ],
                'active' => [
                    'label' => 'Aktiv',
                    'type' => 'checkbox',
                    'default_on_insert' => 1,
                ],
            ],
        ],
        'TAB_SYSTEM' => [
            'label' => 'System',
            'fields' => [
                'created' => [
                    'label' => 'Erstellt am',
                    'type' => 'datetime',
                    'hidden_on_insert' => true,
                    'readonly_on_insert' => true,
                    'readonly_on_update' => true,
                ],
                'updated' => [
                    'label' => 'Geaendert am',
                    'type' => 'datetime',
                    'hidden_on_insert' => true,
                    'readonly_on_insert' => true,
                    'readonly_on_update' => true,
                ],
                'created_by' => [
                    'label' => 'Erstellt von',
                    'type' => 'select',
                    'hidden_on_insert' => true,
                    'readonly_on_insert' => true,
                    'readonly_on_update' => true,
                ],
                'updated_by' => [
                    'label' => 'Geaendert von',
                    'type' => 'select',
                    'hidden_on_insert' => true,
                    'readonly_on_insert' => true,
                    'readonly_on_update' => true,
                ],
            ],
        ],
    ],
];
```

### Formular-Regeln fuer KI

- Bei Form-Feld-AJAX fuer laenger laufende Pruefungen optional `ajax_message` im `ajax`-Block setzen; der Runner zeigt immer einen Spinner und uebersetzt `ajax_message` automatisch per `deepl_translate()`.
- Auditfelder im Grid nur zeigen, wenn fachlich ausdruecklich gewollt
- Standardmaessig Auditfelder im Tab `System` readonly zeigen
- Eltern-`_ref`-Felder in Unterformularen vorbelegen und ausblenden
- Fuer genau eine Auswahl aus mehreren SQL- oder manuell gelieferten Optionen im Form oder eGrid den Typ `radio` verwenden; im klassischen Grid wird `radio` nicht eingesetzt.
- Pflichtfelder nur setzen, wenn fachlich klar
- abhängige Selects per AJAX/Hook nachladen, nicht per Freitext loesen

## 9. Wann Hook-Dateien noetig sind

Eine `*_function.php` ist sinnvoll, wenn eine KI mindestens eines dieser Themen braucht:

- Session-Bindung
- dynamische Lookups
- AJAX-Abhaengigkeiten
- Vorbelegung
- Validierung
- Delete-Schutz
- spezielle Link-/HTML-Ausgabe
- Dateiupload-Logik

### Typische Hook-Funktionen

- `onLoad`
- `onValidate`
- `onValidateSuccess`
- `onValidateFailure`
- `onBeforeInsert`
- `onAfterInsert`
- `onBeforeUpdate`
- `onAfterUpdate`
- `onBeforeDelete`
- `onAfterDelete`

### Hook-Regeln fuer KI

- Delete-Schutz serverseitig in `onBeforeDelete` absichern
- abhängige Daten nie nur ueber UI blocken
- Fehlermeldungen fachlich klar formulieren
- wenn im Projekt Standard: Meldungen ueber `deepl_translate(...)` fuehren
- DeepL-Cache-Regel beachten: zentrale MOSAIC-Standardtexte werden zuerst aus `_pgm/admin/_deepl_cache/<SPRACHE>/` gelesen; projektspezifische Texte werden danach aus `<projekt>/_deepl_cache/<SPRACHE>/` gelesen und neue Projektuebersetzungen werden dort geschrieben

## 10. Eltern-Kind-Ketten

Bei Untertabellen gilt:

- Basisgrid auf den Elternsatz filtern
- im Insert den Eltern-`_ref` aus dem Kontext vorbelegen
- Eltern-`_ref` nicht frei editierbar machen
- serverseitig die Zuordnung absichern

Beispielkette:

- Firma
- Projekt
- Projekt-Bericht
- Bericht-Formular
- Formular-Anlage

Wenn ein Untergrid ohne Elternkontext aufgerufen wird, soll es leer sein oder den Zugriff sauber blocken.

## 11. Menue-Regeln

Ein `*_menu.cfg` steuert die Navigation.

### Aktuelle Zusatzschalter

- `breadcrumb => true|false`
- `breadcrumb_clickable => true|false`

### Beispiel

```php
return [
    'title' => 'CL',
    'orientation' => 'horizontal',
    'breadcrumb' => true,
    'breadcrumb_clickable' => true,
    'items' => [
        // ...
    ],
];
```

### Menue-Regeln fuer KI

- `grid/form/egrid` direkt mit diesen Runnern eintragen
- fuer Spezialmodule nur kanonische `show_*`-Runner verwenden
- Menuepfade fachlich statt technisch benennen
- Breadcrumb nur aktivieren, wenn das Projekt ihn wirklich will

## 12. Suchfilter

Fuer anspruchsvollere Grids soll die KI an Advanced Search denken.

Typisches Muster:

- sichtbare Fachspalten
- zusaetzliche unsichtbare Suchspalten
- `filters`-Block mit sprechenden Labels

Wenn Lookups ueber Ref-Felder laufen, ist haeufig eine eigene Suchspalte mit ausgeschriebenem Namen sinnvoll.

## 13. Datei- und Bildlogik

Datei- oder Uploadfelder brauchen meist Hook-Logik.

Regeln:

- Dateipfade projektlokal halten
- Vorschau- oder Download-Sonderlogik moeglichst modulbezogen loesen
- Kern nur dann aendern, wenn das Verhalten wirklich global sein soll

## 14. MySQL-Engine und Transaktionen

Bei MySQL/MariaDB soll ein Projekt konsistent nur mit **einer** Engine arbeiten:

- entweder `MyISAM`
- oder `InnoDB`

### Form-Regel

Im `*_form.cfg` darf oben stehen:

```php
'transaction' => true,
```

### Wirkung

- fehlt der Eintrag, gilt `false`
- `transaction = true` greift fuer `mysql`, `pgsql` und `oracle`
- unter `mysql` nur bei Engine `InnoDB`
- bei `MyISAM` passiert bewusst nichts Transaktionales

### KI-Regel

- Wenn fachlich Rollback wichtig ist, echte DB-Transaktionen bewusst einplanen
- unter `mysql` nur mit `InnoDB` arbeiten
- `transaction => true` ist fuer `pgsql` und `oracle` zulaessig
- Keine Rollback-Garantie fuer Dateioperationen behaupten

## 15. Sicherheits- und Session-Regeln

Viele Projektmodule sind sessiongebunden.

Typische Muster:

- `firma_ref` aus Session festziehen
- `mitarbeiter_ref` aus Session vorbelegen
- Fremdfirmenzugriff blocken
- Untertabellen nur im erlaubten Kontext anzeigen

Die KI soll solche Bindungen **nicht** nur optisch, sondern auch serverseitig absichern.

## 16. Was die KI standardmaessig liefern soll

Wenn die Aufgabe ein neues CRUD-Modul beschreibt, soll die KI im Normalfall liefern:

1. SQL-Schema oder Tabellenerweiterung
2. `*_grid.cfg`
3. `*_form.cfg`
4. optionale `*_function.php`
5. Menueerweiterung
6. kurze Verifikation

Wenn Untertabellen beteiligt sind, zusaetzlich:

1. Elternfilter im Grid
2. Vorbelegung der Eltern-Refs
3. Delete-Schutz bei Abhaengigkeiten

## 17. Was die KI vermeiden soll

- alte Wrappernamen
- globale Kernanpassung fuer rein projektlokale Anforderungen
- ungesicherte Delete-Operationen
- freie Bearbeitung von Eltern-Refs in Unterformularen
- Mischbetrieb von `MyISAM` und `InnoDB` in fachlichen Transaktionsketten
- Annahmen, die im Projekt schon anders konfiguriert sind

## 18. Arbeitsmodus fuer KI

Empfohlene Reihenfolge:

1. vorhandenes Modul lesen
2. bestehendes Namensschema uebernehmen
3. nur die kleinste notwendige Erweiterung bauen
4. bei Unterstrukturen konsequent Elternkontext absichern
5. danach Syntax und Kernlogik pruefen

## 19. Kurzreferenz

### Wenn die KI ein Grid bauen soll

- `*_grid.cfg`
- Runner `grid.php`
- `primary_key` als Array
- `edit_link` auf Modulnamen

### Wenn die KI ein Formular bauen soll

- `*_form.cfg`
- Runner `form.php`
- optional `transaction`
- Auditfelder in `System`

### Wenn die KI ein Menue bauen soll

- `*_menu.cfg`
- Runner `show_menu.php`
- optional `breadcrumb`
- optional `breadcrumb_clickable`

### Wenn die KI eine Spezialansicht bauen soll

- passende `show_*`-Logik
- keine Legacy-Runner

## 20. Merksatz

MOSAIC ist am schnellsten, wenn die KI:

- zuerst Konfiguration denkt
- dann kleine Hook-Dateien ergaenzt
- und den Kern nur fuer echte Rahmenregeln aendert

Dann bleiben Projekte schnell, konsistent und wartbar.
