# DeskHub-Plugins

Jedes Plugin liegt in einem eigenen Ordner `plugins/<slug>/`. Installation, Aktivierung und Entfernung erfolgen im Adminportal unter **Plugins**.
Dieser Ordner wird bei System-Updates nie überschrieben.

> **Sicherheit:** Plugins sind PHP-Code und laufen mit allen Rechten des Systems (auch Datenbankzugriff). Es gibt keine Sandbox.
> Nur Plugins aus vertrauenswürdiger Quelle installieren. Bei Problemen: Datei `plugins/.disabled` anlegen – dann wird kein Plugin geladen.
> nginx: PHP-Dateien unter `/plugins/` per `location ~ ^/plugins/.*\.php$ { deny all; }` sperren (die mitgelieferte `.htaccess` gilt nur für Apache).

## Aufbau

```
plugins/mein-plugin/
  plugin.json        Pflicht
  plugin.php         Startdatei (Standard), registriert Hooks/Menüs/API
  pages/*.php        Seiten (als Menüpunkt registriert)
  migrations/*.sql   Datenbank-Änderungen (beim Aktivieren einmalig). Dialekt: name.sqlite.sql / name.mysql.sql laufen nur auf der jeweiligen Datenbank, name.sql auf beiden
  assets/            js/css/Bilder
```

`plugin.json`:

```json
{
  "slug": "mein-plugin",
  "name": "Mein Plugin",
  "version": "1.0.0",
  "description": "Kurze Beschreibung",
  "author": "Name",
  "requires": "1.0.6",
  "permissions": ["hooks.tickets", "ui.menu"]
}
```

`permissions` nennt die Erweiterungspunkte, die das Plugin nutzt (`hooks.tickets`, `hooks.cron`, `ui.menu`, `ui.sidebar`, `api.endpoints`, `api.public`, `db.migrations`). Der Admin bestätigt sie bei der Aktivierung; nicht deklarierte Erweiterungspunkte werden abgelehnt. Das ist keine Sandbox. Die Hooks `cron.minute` (etwa jede Minute, für kurze Prüfabstände) und `cron.run` (höchstens alle 5 Minuten), beide mit der Berechtigung `hooks.cron`, werden ausgelöst vom echten Server-Cronjob (`cron/run_plugins.php`, wird unter Einstellungen → Cron-Jobs eingetragen) und vom eingebauten Hintergrund-Betrieb, nie doppelt. Der Filter `staff.page.top` (Berechtigung `ui.sidebar`) ergänzt einen Hinweis oben auf jeder Seite des Mitarbeiterbereichs (fertiges HTML; Kontext: `staff`, `activePage`). Vollständige Dokumentation inklusive Signieren: README.md im Hauptverzeichnis.

## Erweiterungspunkte

| Funktion | Zweck |
|---|---|
| `plugin_add_hook($hook, $fn)` | auf Ereignisse reagieren |
| `plugin_add_filter($hook, $fn)` | Inhalte/Werte ergänzen oder verändern |
| `plugin_register_menu($label, $seite, $recht = null)` | Menüpunkt → `pages/<seite>.php` (Variablen `$staff`, `$pdo`) |
| `plugin_register_api($name, $fn, $recht = null)` | Endpunkt `/api/staff/v1/plugin.php?p=<slug>&endpoint=<name>` |
| `plugin_setting($slug, $key)` / `plugin_set_setting(...)` | eigene Einstellungen |

Ereignisse (Hooks): `ticket.created`, `ticket.replied`, `ticket.status_changed`, `ticket.assigned` (Daten: `event`, `ticketId`, …),
`cron.run` (alle ~5 Minuten), `plugin.uninstall.<slug>` (beim Entfernen mit „Daten löschen“).
Filter: `ticket.view.sidebar` (HTML-Block in der Ticketansicht; Plugin ist für das Escapen von Ausgaben selbst verantwortlich).

## Fehlerverhalten

Wirft ein Plugin einen Fehler, wird er protokolliert und das Ticket/die Seite läuft normal weiter. Nach 3 Fehlern wird das Plugin automatisch
deaktiviert (Fehlertext im Adminportal sichtbar). Schwere Fehler (Fatal Error) deaktivieren das gerade ausgeführte Plugin beim nächsten Start.

Ein Beispiel liegt unter `docs/plugin-beispiel/`.