# Installationshandbuch

Diese Anleitung beschreibt den vorgesehenen Weg fuer die SaaS-Version in
`saas-app/`. Sie ist auf Webspace-Betrieb ohne Docker und ohne dauerhafte
Worker ausgelegt.

## Empfohlener Weg Auf Webspace

Wenn auf dem Hosting keine Shell- oder CLI-Ausfuehrung moeglich ist, nutze den
gefuehrten Installer im Public-Pfad:

- `https://deine-domain.tld/install/`

Der Installer kann:

- die `.env` speichern
- das SQL-Bundle erzeugen
- Migrationen direkt per PHP ausfuehren, wenn die zum Treiber passende PDO-Erweiterung verfuegbar ist
- nachtraegliche System-Updates automatisch einspielen
- den ersten Global-Admin direkt anlegen
- sich nach erfolgreicher Einrichtung sperren

Die CLI-Skripte unter `scripts/*.php` bleiben als Alternative fuer lokale
Vorbereitung oder Server mit Shell-Zugriff erhalten.

## Voraussetzungen

- PHP 8.2 oder neuer
- Composer fuer den spaeteren Laravel-Bootstrap
- MySQL oder MariaDB fuer das Zielsystem
- Webserver mit Document-Root auf `public/` des Zielprojekts
- Cron-Zugang
- optional: SMTP-Zugang fuer Mails
- optional: OIDC-Provider fuer SSO

## Installation Lokal

1. Repository klonen.
2. Mit `php scripts/check-prerequisites.php` die Voraussetzungen pruefen.
3. Mit `php scripts/prepare-saas-env.php` eine `.env` aus `.env.example` anlegen.
4. Datenbankzugang, URL, Mail und Tenancy-Werte in `saas-app/.env` eintragen.
5. Mit `php scripts/install-saas.php` das SQL-Bundle erzeugen.
6. Das SQL-Bundle manuell in MySQL/MariaDB importieren oder mit `php scripts/run-sql-migrations.php --connection=mysql --server=<server> --database=<db> --username=<user> --password=<pass>` direkt einspielen.
7. Einen ersten Mandanten anlegen.
8. Einen ersten Benutzer und eine Mitgliedszuordnung anlegen.
9. Spaeter Composer und das eigentliche Laravel-Bootstrap nachziehen.

## Migrationen Ausfuehren

Die aktuellen Dateien unter `saas-app/database/migrations/` sind SQL-Skizzen in
PHP-Dateien, keine Laravel-Migrationsklassen. Deshalb gibt es aktuell bewusst
kein `php artisan migrate`.

Stattdessen wird die SQL-Datei passend zum konfigurierten DB-Treiber ueber Skripte erzeugt:

- Installationsvorbereitung inklusive SQL-Bundle:
  `php scripts/install-saas.php`
- SQL direkt gegen MySQL/MariaDB ausfuehren:
  `php scripts/run-sql-migrations.php --connection=mysql --server=localhost --database=kaffeeliste_saas --username=root --password=<passwort>`

Die erzeugte SQL-Datei liegt anschliessend unter:

- `saas-app/database/migrations/generated/all-migrations.sql`

## Installationsskripte

Vorhandene Hilfsskripte:

- `scripts/check-prerequisites.php`
- `scripts/prepare-saas-env.php`
- `scripts/install-saas.php`
- `scripts/build-migration-bundle.php`
- `scripts/run-sql-migrations.php`

## Wichtige Umgebungswerte

Die wichtigsten Werte liegen in `saas-app/.env.example` und muessen fuer die
eigene Umgebung angepasst werden:

- `APP_URL`
- `DB_CONNECTION`
- `DB_HOST`, `DB_DATABASE`, `DB_USERNAME`, `DB_PASSWORD`
- `TENANCY_MODE`
- `TENANCY_CENTRAL_DOMAINS`
- `TENANCY_FALLBACK_TENANT`
- `OIDC_ENABLED`
- Mail-Zugangsdaten

## Webspace-Deployment

1. Den Inhalt von `saas-app/` auf den Zielserver hochladen.
2. Das Document-Root auf `public/` zeigen lassen.
3. Schreibrechte fuer `saas-app/`, `.env`, `.installer.lock` und `database/migrations/generated/` sicherstellen.
4. Sicherstellen, dass `open_basedir` nicht nur auf `public/` eingeschraenkt ist. PHP muss mindestens auf den kompletten Ordner `saas-app/` zugreifen duerfen, obwohl der Document-Root auf `public/` zeigt.
5. Den Installer unter `/install/` aufrufen und die Einrichtung durchfuehren.
6. Danach den Global-Admin unter `/admin/login` anmelden.
7. In der zentralen Verwaltung unter `/admin/tenants` die ersten Tenants inklusive Lizenzplan anlegen.
8. Nach erfolgreicher Einrichtung den Installer sperren.
9. Die Anwendung einmal per Browser aufrufen und die Grundseiten pruefen.

## MySQL Und MariaDB

Der aktuelle Installer ist jetzt auf MySQL/MariaDB ausgelegt:

- Standardwert `DB_CONNECTION=mysql`
- Standardport `3306`
- direkte PHP-Migration ueber `pdo_mysql`
- SQL-Bundle im MySQL/MariaDB-Dialekt

Wenn `pdo_mysql` auf dem Hosting nicht geladen ist, kann das SQL-Bundle weiter
manuell im Datenbank-Tool des Hosters importiert werden.

## Cron- und Batch-Betrieb

Die Zielarchitektur nutzt Cron statt dauerhafter Worker.

Typische Aufgaben:

- Queue-Jobs verarbeiten
- Import-Jobs abarbeiten
- Export-Jobs erzeugen
- Benachrichtigungen versenden
- Aufraeum- und Statusjobs ausfuehren

Empfehlung: pro Aufgabe einen klar benannten Cron-Eintrag anlegen und die
Ausgabe in Logdateien schreiben.

## Zentrale Verwaltung

Nach der Installation stehen diese Web-Einstiege bereit:

- `/admin/login` fuer den Global-Admin
- `/admin/` fuer die zentrale Verwaltungsuebersicht
- `/admin/tenants` fuer die Tenant-Verwaltung
- `/admin/updates` fuer System-Updates und Datenbankerweiterungen

## Lizenzplaene

Die SaaS-Anwendung arbeitet jetzt mit Lizenzplaenen pro Mandant. Darueber kann
gesteuert werden, welche Zusatzfunktionen im jeweiligen Tenant verfuegbar sind.

- `Starter`: Basisfunktionen fuer Mitglieder, Buchungen, Einzahlungen und Inhalte
- `Team`: zusaetzlich Mandanten-Einstellungen, PDF-Drucklisten, Papierlisten-Erfassung und Basis-Exporte
- `Business`: vorbereitet fuer SSO, Importe, Exporte, Benachrichtigungen und Auswertungen
- `Enterprise`: erweitert um White-Labeling, Sonderfunktionen und priorisierte Updates

Mandanten-Einstellungen und Exportfunktionen muessen daher nicht fuer jede
Lizenz freigeschaltet sein.

## Update-Prozess

Schemaaenderungen und spaetere Datenanpassungen laufen ueber versionierte
PHP-Update-Dateien unter `saas-app/updates/`.

Der bevorzugte Weg auf Webspace ist:

1. Als Global-Admin anmelden.
2. `/admin/updates` aufrufen.
3. Ausstehende Updates per Klick ausfuehren.

Alternativ steht lokal oder auf Servern mit Shell-Zugriff weiter zur Verfuegung:

- `php scripts/run-updates.php`

## Betriebscheck

Nach dem Setup sollten diese Punkte funktionieren:

- Login oder SSO-Startseite
- Dashboard pro Mandant
- Mitgliederliste
- Buchungen und Kontostand
- Hinweise und Content
- Import- und Export-Status

Wenn einer dieser Bereiche fehlt, liegt meist entweder ein Tenancy-Fehler, ein
DB-Problem oder eine unvollstaendige Deployment-Konfiguration vor.
