# MOSAIC Starter-Kit

## Zweck

Das MOSAIC Starter-Kit ist ein Admin-Modul für neue MOSAIC-Projekte. Es richtet ein sofort lauffähiges Grundgerüst ein, damit ein Entwickler nach dem Anlegen eines Projekts direkt mit Login, Rollenverwaltung, Benutzertabelle, Menü und ersten Grid-Konfigurationen starten kann.

Das Modul liegt unter:

`_pgm/module/starter_kit/`

Wichtig: Das Starter-Kit ist ein Entwicklungs- und Admin-Werkzeug. Es gehört nicht auf einen Produktivserver und wird im FTP-Manager vom Transfer ausgeschlossen.

## Aufruf im Admin-Bereich

Der typische Ablauf ist:

1. MOSAIC entpacken und installieren.
2. In `_pgm/admin/admin.php` ein Projekt anlegen.
3. Das Projekt auswählen und in `db_edit.php` die Datenbankverbindung einrichten.
4. Im Generator-Auswahlfeld `starter_kit - Grundgerüst installieren` auswählen.
5. Die Hilfe-/Infoseite des Starter-Kits prüfen.
6. Über `Jetzt installieren` die Installation starten.

Wenn eine Datenbankverbindung neu angelegt wurde und das Starter-Kit verfügbar ist, kann direkt aus `db_edit.php` die Starter-Kit-Hilfe geöffnet werden. Die Installation erfolgt auch dort über dieselbe Hilfe-/Infoseite, damit der Ablauf einheitlich bleibt.

## Installationsvoraussetzungen

Das Starter-Kit benötigt:

- einen vorhandenen MOSAIC-Projektordner,
- eine gültige Datenbankverbindung für das ausgewählte Projekt,
- eine unterstützte Datenbankfamilie,
- Admin-Zugriff auf die MOSAIC-Administration.

Der Installer unterstützt derzeit:

- MySQL / MariaDB,
- PostgreSQL,
- SQLite.

Andere Datenbanktypen werden nicht durch das Starter-Kit installiert.

## Sicherheitsregeln

Das Starter-Kit arbeitet bewusst konservativ:

- Die Installation bricht ab, wenn `iss_users` bereits in der ausgewählten Datenbank vorhanden ist.
- Projektdateien werden niemals überschrieben.
- Wenn Ziel-Dateien bereits existieren, wird die Installation komplett abgebrochen.
- Wenn passende Menü-/Grid-Einträge bereits in `iss_apps` vorhanden sind, wird die Installation abgebrochen.
- Das Starter-Kit darf nicht per FTP-Manager auf Produktivserver übertragen werden.

Diese Regeln verhindern, dass eine bestehende Anwendung oder eine bestehende Sicherheitsstruktur versehentlich beschädigt wird.

## Angelegte Datenbanktabellen

Das Starter-Kit legt die folgenden Tabellen an, sofern sie benötigt werden:

| Tabelle | Zweck |
|---|---|
| `iss_users` | Benutzerverwaltung für Login und Benutzerpflege |
| `iss_apps` | Registrierung der MOSAIC-Applikationen |
| `iss_groups` | Rollenverwaltung |
| `iss_users_groups` | Zuordnung Benutzer zu Rollen |
| `iss_groups_apps` | Zuordnung Rollen zu Applikationen und Rechten |
| `iss_log` | Änderungsprotokoll / Logging |

Die Tabelle `iss_users` wird datenbankabhängig erzeugt. Für MySQL / MariaDB wird `utf8mb4` verwendet. Für PostgreSQL und SQLite werden passende Datentypen der jeweiligen Datenbankfamilie verwendet.

## Angelegte Rolle und Benutzer

Das Starter-Kit erzeugt:

- Rolle: `admin`
- Benutzer: `admin`
- Startpasswort: `creatorAdmin57`

Der Benutzer `admin` wird der Rolle `admin` zugeordnet. Die Rolle erhält für die Starter-Kit-Applikationen die Rechte:

- `V` Anzeigen,
- `A` Anlegen,
- `D` Drucken,
- `E` Ändern,
- `X` Löschen,
- `P` Sonder-/Programmaktionen.

Das Startpasswort ist nur für das Grundgerüst gedacht und sollte nach der ersten Anmeldung geändert werden.

## Angelegte Projektordner und Dateien

Die Templates aus `_pgm/module/starter_kit/templates/` werden in den Projektordner kopiert. Dabei werden Platzhalter wie `@PROJECT@`, `@DB@`, `@PROJECT_TITLE@` und `@DB_TYP@` ersetzt.

Erzeugte Ordner:

- `login`
- `menu`
- `data`
- `security`

### Login

Der Ordner `login` enthält:

- `index.php`
- `login.php`
- `login_function.php`
- `logout.php`
- `rollenauswahl.php`
- `logo.png`

Der Login enthält eine Rollenauswahl und nutzt ein neutrales Logo aus dem Starter-Kit.

### Menü

Der Ordner `menu` enthält:

- `app.php`
- `main_menu.cfg`

Das Hauptmenü enthält:

- Menügruppe `Data`
- Menüpunkt `users`
- Menügruppe `Security`
- Menüpunkte für Benutzer, Rollen, Benutzer-Rollen, Applikationen und Rollen-Applikationen

Alle Starter-Kit-Menüpunkte sind für die Rolle `admin` vorgesehen.

### Data

Der Ordner `data` enthält:

- `users_grid.cfg`

Diese Grid-Konfiguration zeigt die Tabelle `iss_users` als ersten Datenbereich.

### Security

Der Ordner `security` enthält die Pflege der zentralen Security-Tabellen:

- `iss_users_grid.cfg`
- `iss_users_form.cfg`
- `iss_users_form_function.php`
- `iss_groups_grid.cfg`
- `iss_groups_form.cfg`
- `iss_users_groups_grid.cfg`
- `iss_users_groups_form.cfg`
- `iss_apps_grid.cfg`
- `iss_groups_apps_grid.cfg`
- `iss_groups_apps_form.cfg`

Damit können Benutzer, Rollen, Rollen-Zuordnungen, Applikationen und Rollenrechte direkt im neuen Projekt gepflegt werden.

## Registrierung der Applikationen

Der Installer registriert die Starter-Kit-Applikationen in `iss_apps`. Die App-Namen folgen dem Schema:

`<projekt>|grid|<modul_path>|<modul>`

Beispiele:

- `<projekt>|grid|data|users`
- `<projekt>|grid|security|iss_users`
- `<projekt>|grid|security|iss_groups`
- `<projekt>|grid|security|iss_users_groups`
- `<projekt>|grid|security|iss_apps`
- `<projekt>|grid|security|iss_groups_apps`

Diese Einträge werden der Rolle `admin` über `iss_groups_apps` zugeordnet.

## Verhalten nach erfolgreicher Installation

Nach erfolgreicher Installation zeigt das Starter-Kit:

- den Installationsstatus,
- die angelegten Tabellen,
- die angelegten Dateien,
- die Login-Daten,
- einen Button `Projekt starten`.

Der Projektstart öffnet den erzeugten Login-Pfad:

`<projekt>/login/login.php`

## DeepL / Übersetzungen

Die Texte aus `admin.php`, `db_edit.php`, `db_create.php` und dem Starter-Kit werden über `deepl_translate()` übersetzt. Die zentralen Übersetzungen liegen im Admin-Cache:

`_pgm/admin/_deepl_cache/<SPRACHE>/`

Damit können die Übersetzungen später mitinstalliert werden, ohne dass jedes Projekt seine eigenen Kopien der MOSAIC-Standardtexte erzeugen muss.

## FTP-Manager

Das Starter-Kit wird im FTP-Manager bewusst ausgeschlossen. Folgende Pfade dürfen nicht auf den Produktivserver übertragen werden:

- `_pgm/module/starter_kit/`
- `_pgm/module/starter-kit/`

Der Ausschluss ist zentral in `should_exclude_transfer_file()` im FTP-Manager hinterlegt.

## Erweiterungspunkte

Das Starter-Kit kann später erweitert werden durch:

- zusätzliche Tabellen im Setup,
- weitere Grid-/Form-Konfigurationen,
- zusätzliche Rollen,
- weitere Menügruppen,
- projektspezifische Startseiten,
- optionale Beispielmodule.

Bei jeder Erweiterung muss die Grundregel erhalten bleiben: bestehende Datenbanken und Projektdateien dürfen nicht überschrieben werden.

## Prüfliste für Änderungen am Starter-Kit

Vor einer Freigabe sollte geprüft werden:

- Bricht der Installer ab, wenn `iss_users` bereits existiert?
- Werden keine vorhandenen Projektdateien überschrieben?
- Werden alle erzeugten Dateien korrekt in `login`, `menu`, `data` und `security` angelegt?
- Wird die Rolle `admin` angelegt?
- Wird der Benutzer `admin` angelegt und der Rolle zugeordnet?
- Sind alle Starter-Kit-Applikationen in `iss_apps` registriert?
- Sind die Rechte in `iss_groups_apps` gesetzt?
- Funktioniert der Login mit Rollenauswahl?
- Ist der Button `Projekt starten` nach der Installation sichtbar?
- Wird das Starter-Kit weiterhin vom FTP-Manager ausgeschlossen?
