inhaus-plugin-chat/README.md
Friederich Loheide 5f71c3e250 Nachrichten 1.1.0: Schnittstelle für die App, Verbindung prüfen
- /api/v1/chat: config, Gruppenchats, verlassen, bearbeiten, löschen, Reaktionen,
  „Gibt es Neues?“, „schreibt …“, GIFs, Echtzeit-Anmeldung und Anhänge mit Token
- Anhang-Adressen zeigen bei API-Aufrufen auf die API (Token statt Sitzung)
- Backend: „Echtzeit prüfen“ und „GIPHY prüfen“ melden sofort, ob die Zugangsdaten stimmen
- README: Schritt-für-Schritt-Einrichtung für pusher.com und GIPHY

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-09-27 20:10:35 +00:00

100 lines
5.7 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Nachrichten – Chat-Plugin für Inhaus
Direktnachrichten und Gruppenchats im Mitarbeiterportal.
- **Direktnachrichten** an alle Kolleginnen und Kollegen (Personensuche), **Gruppenchats** für alle mit dem Recht
„Gruppenchats anlegen“ (unter Rollen vergeben). Gruppen-Admins benennen um, fügen hinzu, entfernen, ernennen Admins.
- **Anhänge** (Bilder, PDFs, Office …; Einfügen aus der Zwischenablage, Ziehen & Ablegen), **GIFs**, **Emojis**,
**Reaktionen**, **Antworten** auf einzelne Nachrichten, **Bearbeiten** und **Löschen** eigener Nachrichten.
- **Ungelesen-Zähler** als Sprechblase neben der Glocke, „Neu“-Trenner, „gelesen“ unter eigenen Nachrichten,
„schreibt gerade …“. Stummschalten je Gespräch.
- **Benachrichtigung** (Glocke und Push, auch in der Inhaus-App) – je Gespräch einmal, bis es gelesen ist, und nicht,
während das Gespräch offen ist.
- Handy- und Desktop-Ansicht, Tastatur (Enter sendet, Umschalt+Enter neue Zeile, Esc bricht ab), Screenreader-Hinweise.
Voraussetzung: Inhaus **0.39.0** oder neuer.
## Installation
1. Neuestes Release herunterladen: `chat-<version>.zip` unter
https://git.loheide.cloud/friloo/inhaus-plugin-chat/releases
2. Backend → **Plugins** → hochladen → aktivieren. Updates erscheinen danach automatisch unter „Plugins“.
3. Unter **Rollen** das Recht **„Gruppenchats anlegen“** an die passenden Rollen vergeben (z. B. Teamleitungen).
4. Optional unter **Portal → Nachrichten**: GIPHY, Echtzeit, Größe von Anhängen; unter **Portal → Chat-GIFs** die
eigene GIF-Sammlung (Recht „Nachrichten einrichten“).
## Datenschutz
- Gespräche sehen nur ihre Mitglieder – **auch die Administration kann nicht mitlesen**. Anhänge liegen außerhalb des
öffentlichen Ordners und werden nur an Mitglieder ausgeliefert.
- **GIPHY** ist aus, bis ein Schlüssel eingetragen ist. Dann gehen Suchbegriffe an GIPHY und die Bilder werden von dort
geladen. Die eigene Sammlung bleibt im Haus.
- **Echtzeit**: Über den Dienst geht nur das Signal „es gibt Neues“ – keine Inhalte.
- Beim Entfernen des Plugins mit „Daten löschen“ verschwinden alle Nachrichten und Anhänge.
## Echtzeit (optional)
Ohne Einrichtung fragt der Chat alle 3 Sekunden (im Hintergrund seltener) nach Neuem – das läuft auf jedem Webspace.
Für sofortige Zustellung braucht es einen Pusher-kompatiblen Dienst. Über ihn geht nur das Signal „es gibt Neues“,
nie Nachrichteninhalte. Auf einem reinen Webspace (ohne dauerhaft laufende Prozesse) ist **pusher.com** der
einfachste Weg:
1. Kostenloses Konto unter <https://dashboard.pusher.com> anlegen („Channels“, Sandbox-Tarif:
200 000 Signale/Tag, 100 gleichzeitige Verbindungen – für die meisten Häuser genug).
2. „Create app“: Name z. B. „Inhaus“, Cluster **eu** (Server in der EU), Frontend „Vanilla JS“, Backend „Laravel“.
3. Unter „App Keys“ stehen `app_id`, `key`, `secret` und `cluster`.
4. Im Backend unter **Portal → Nachrichten → Echtzeit** einschalten, App-ID, Key, Secret und Cluster (`eu`)
eintragen, **Server leer lassen**, speichern.
5. Oben auf **„Echtzeit prüfen“** klicken – „Verbindung steht“ heißt: fertig.
Alternativ ein eigener Server mit **Laravel Reverb** oder **Soketi**: App-ID, Key, Secret, Server
(z. B. `ws.example.org`) und Port (443) eintragen. Der Server muss vom Browser bzw. der App (WebSocket) und
vom Portal (HTTP) aus erreichbar sein. Die Inhaus-App nutzt dieselbe Einrichtung automatisch.
## GIPHY (optional)
Die eigene GIF-Sammlung (Backend → Chat-GIFs) funktioniert ohne Einrichtung. Für die Suche bei GIPHY:
1. Unter <https://developers.giphy.com/dashboard/> anmelden, „Create an App“ → **API** (nicht SDK) wählen.
2. Den angezeigten API-Key im Backend unter **Portal → Nachrichten → GIFs** eintragen und speichern.
3. Oben auf **„GIPHY prüfen“** klicken.
Ein neuer Schlüssel ist ein Beta-Schlüssel (100 Abrufe pro Stunde); für mehr bei GIPHY ein „Production“-Upgrade
beantragen. Suchbegriffe gehen dabei an GIPHY, die GIFs lädt der Browser von dort.
## Schnittstelle für die App
Unter `/api/v1/chat/…` (Token nötig), dieselben Regeln wie im Portal:
| Methode | Pfad | Zweck |
|---|---|---|
| GET | `config` | eigene Person, `can_create_groups`, `giphy`, `realtime` (ohne Secret), `reactions`, `max_upload_mb` |
| GET | `conversations` | Gesprächsliste |
| POST | `direct {user_id}` / `groups {name, members[]}` | Direktnachricht öffnen / Gruppenchat anlegen (Recht nötig) |
| DELETE | `conversations/{id}` | Gespräch verlassen |
| GET | `conversations/{id}/messages?vor=` | 40 Nachrichten, ältere mit `vor` |
| POST | `conversations/{id}/messages {body, gif_url, reply_to, files[]}` | senden (JSON oder multipart) |
| POST | `conversations/{id}/read {message_id}` / `typing` | gelesen / „schreibt …“ |
| PUT / DELETE | `messages/{id}` | bearbeiten / löschen |
| POST | `messages/{id}/reaction {emoji}` | Reaktion umschalten |
| GET | `updates?seit=&offen=&nach=` | „Gibt es Neues?“ – wie im Portal |
| GET | `unread`, `gifs?q=` | ungelesene Nachrichten, GIF-Suche |
| POST | `realtime/auth {socket_id, channel_name}` | Anmeldung am privaten Echtzeit-Kanal |
| GET | `attachments/{id}` | Anhang (Adressen in den Antworten zeigen bei API-Aufrufen hierher) |
## Entwicklung
```bash
npm install
npm run build # dist/ – wird mit ins Repository eingecheckt
npm run package # baut und erzeugt chat-<version>.zip
```
Tests laufen in einer Inhaus-Installation, in der das Plugin unter `plugins/chat` liegt (Kopie oder Symlink):
```bash
vendor-dev/bin/phpunit plugins/chat/tests
```
Release: Version in `plugin.json` erhöhen, `npm run package`, Tag `vX.Y.Z` setzen und
`tea release create --tag vX.Y.Z --asset chat-X.Y.Z.zip`.