starface-chat-l-schen/README.md

# Starface Chat löschen

Kleines Bash-Script, das den kompletten UCC-Chatverlauf eines einzelnen
Starface-Users aus der internen Openfire-Chat-DB löscht. Nötig, weil Starface
in der App/Admin-UI selbst keine Möglichkeit bietet, den Chatverlauf eines
Users zu löschen — z.B. wenn ein Mitarbeiter das Unternehmen verlässt.

## Hintergrund

Starface nutzt für den UCC-Chat einen eingebetteten **Openfire-XMPP-Server**,
der dieselbe Postgres-Datenbank (`asterisk`) wie die restliche PBX verwendet.
Relevant sind zwei Tabellen (Openfire Monitoring-Plugin):

- `ofmessagearchive` — die eigentlichen Chat-Nachrichten (`fromjid`, `tojid`, `body`, `sentdate`, ...)
- `ofconversation` — Konversations-Header (Zeitraum, Nachrichtenanzahl je `conversationid`)

Es gibt **keine offizielle API** dafür — die Löschung passiert direkt per SQL
auf dem Starface-Server.

## Voraussetzungen

- SSH-Zugriff auf den Starface-Server (root oder ein User mit `sudo -u postgres`-Rechten)
- `psql` muss installiert sein (bei Starface Standard)
- Script liegt/läuft direkt **auf** dem Starface-Server (nicht remote per SQL-Tunnel)

## Nutzung

```bash
./delete_starface_chat.sh <user_id>
```

Beispiel — Mitarbeiter mit der Starface-Benutzer-ID `0022` verlässt das Unternehmen:

```bash
./delete_starface_chat.sh 0022
```

`<user_id>` ist die Starface-Benutzernummer/-ID wie sie intern als JID genutzt
wird (JID-Format `<user_id>@<starface-host>`) — einfach die Nummer/den
Login-Namen des Users angeben.

## Was das Script macht

1. Sucht alle Nachrichten in `ofmessagearchive`, bei denen der angegebene
   User Absender **oder** Empfänger ist (`fromjid`/`tojid LIKE '<user_id>@%'`).
2. **Erstellt zuerst ein Backup** — CSV-Dump aller betroffenen Nachrichten und
   Konversationen nach `/var/backups/starface_chat_backups/`, bevor irgendwas
   gelöscht wird.
3. Löscht die betroffenen Zeilen aus `ofmessagearchive`.
4. Löscht die zugehörigen `ofconversation`-Einträge — aber **nur**, wenn nach
   dem Löschen wirklich keine Nachricht mehr auf diese `conversationid`
   verweist (Konversations-Header bleibt sonst stehen).
5. Gibt am Ende die verbleibende Nachrichtenanzahl für den User aus (sollte `0` sein).

Alles läuft in **einer Transaktion** (`BEGIN` / `COMMIT`) — entweder alles
oder nichts.

## Wichtig: Archivierungs-Verzögerung (10-Minuten-Regel)

Openfire schreibt Chat-Nachrichten **nicht sofort** beim Senden in
`ofmessagearchive`. Eine Konversation wird erst archiviert, wenn Openfire sie
als **"idle"** einstuft — auf dieser Anlage ist das über
`conversation.idleTime` mit **10 Minuten** konfiguriert.

Praktisch heißt das: Wenn User A gerade eben mit User B geschrieben hat, steht
diese Nachricht in den ersten ~10 Minuten danach **noch nicht** in der DB.
Führt man das Script in diesem Zeitfenster aus, meldet es korrekt
`Gefundene Nachrichten: 0` — das ist **kein Fehler und kein Bug**, die
Nachricht ist einfach noch nicht archiviert. Erst wenn seit der letzten
Nachricht in einer Konversation ~10 Minuten nichts mehr passiert ist, landet
sie in `ofmessagearchive` und ist damit für das Script sichtbar/löschbar.

**Konsequenz für die Praxis:** Nach dem Löschen sollte man **mindestens
10-15 Minuten warten**, bevor man das Script erneut laufen lässt, um
sicherzugehen, dass wirklich auch die letzten Nachrichten vor der Löschung
archiviert wurden und mit erfasst werden. Bei einem austretenden Mitarbeiter
empfiehlt es sich, das Script frühestens 15 Minuten nach dessen letzter
Chat-Aktivität auszuführen (oder einfach am nächsten Tag), damit nichts mehr
"hinterher archiviert" wird und übrig bleibt.

## Wichtig: Lokaler Client-Cache (Windows-App)

Dieses Script löscht **nur die serverseitige Kopie** in der Postgres-DB. Der
STARFACE-Windows-Client (WinApp) hält den Chatverlauf zusätzlich **lokal
gecacht**, pro Kontakt als eigene Datei, im Profil des angemeldeten
Windows-Users:

```
%APPDATA%\STARFACE GmbH\WinApp\ChatHistory\<kontakt_id>@<starface-host>.dat
```

Beispiel: der Verlauf mit Kontakt `0001` liegt als `0001@172.0.2.6.dat`.

**Auch nach erfolgreichem DB-Löschen bleibt der Chat in der App sichtbar**,
solange diese `.dat`-Datei nicht ebenfalls entfernt wird — der Client liest
beim Start aus dem lokalen Cache, nicht (nur) vom Server.

Um einen Verlauf wirklich vollständig verschwinden zu lassen:

1. STARFACE-Client **komplett schließen** (nicht nur minimieren — die Datei
   ist sonst durch den Prozess gesperrt)
2. Passende `.dat`-Datei löschen, z.B.:
   ```
   del "%APPDATA%\STARFACE GmbH\WinApp\ChatHistory\0001@172.0.2.6.dat"
   ```
   (Alternativ den kompletten `ChatHistory`-Ordner leeren, um **alle**
   Verläufe auf diesem Rechner zu entfernen.)
3. Client neu starten — der Verlauf mit diesem Kontakt ist weg.

**Wichtig:** Das betrifft nur den **einen** Windows-Rechner/das eine Profil,
auf dem gelöscht wurde. Hat der Gesprächspartner (z.B. `0005`) den gleichen
Chat auf seinem eigenen Rechner offen, bleibt dieser dort unberührt — dafür
müsste auf **jedem** beteiligten Rechner die jeweilige `.dat`-Datei separat
gelöscht werden. Ein reines Neuinstallieren des Clients auf **demselben**
Rechner reicht **nicht** aus, da der `ChatHistory`-Ordner im
Windows-Benutzerprofil liegt und von einer Deinstallation normalerweise nicht
angerührt wird. Auf einem **komplett neuen/anderen** Rechner (frisches
Windows-Profil) existiert dagegen keine alte `.dat`-Datei — dort taucht der
Verlauf dann gar nicht erst auf, weil er nirgends zentral auf dem Server
dupliziert liegt.

**Empfohlene Reihenfolge beim Austritt eines Mitarbeiters:**

1. `./delete_starface_chat.sh <user_id>` auf dem Server ausführen (nach der
   10-Minuten-Wartezeit, s.o.)
2. Auf jedem Windows-Rechner, auf dem mit diesem User gechattet wurde, Client
   schließen und die passende `.dat`-Datei im `ChatHistory`-Ordner löschen

## Wichtige Einschränkung: gemeinsame Konversation

Openfire speichert eine Konversation zwischen zwei Usern als **eine
gemeinsame** Nachrichten-Historie — es gibt **keine getrennten Kopien** pro
Teilnehmer (kein "Postfach pro User").

Das heißt konkret: Löscht man z.B. User `0022`, der einen Chat mit User `0005`
hatte, verschwindet dieser Chat **für beide Seiten** — nicht nur bei `0022`.
Andere Chats von `0005` mit anderen Kollegen (ohne `0022`) bleiben davon
unberührt.

Es gibt technisch keinen Weg, "nur die Hälfte" eines Chats zu löschen, ohne
die Nachrichten zu duplizieren oder zu anonymisieren (Body/Name ersetzen statt
Zeile zu löschen) — das macht dieses Script bewusst nicht, da vollständige
Löschung (z.B. aus DSGVO-Gründen beim Austritt eines Mitarbeiters) hier das
Ziel war.

## Sicherheit

- Backup **vor** jeder Löschung, automatisch, ungefragt.
- Input-Validierung: `user_id` darf nur `A-Za-z0-9._-` enthalten (keine SQL-Injection über das Argument).
- `set -euo pipefail` — Script bricht bei jedem Fehler sofort ab.
- Bei `0` gefundenen Nachrichten: Script beendet sich ohne jede Aktion.

## Wiederherstellung aus dem Backup

Die CSV-Backups liegen unter `/var/backups/starface_chat_backups/` und lassen
sich bei Bedarf mit `\copy ... FROM ... WITH CSV HEADER` wieder in die
jeweilige Tabelle zurückspielen.