first commit

2026-06-09 10:17:37 +02:00
commit a5b1de275d
16 changed files with 894 additions and 0 deletions
@@ -0,0 +1,156 @@
+# Blacklist - Installations- und Konfigurationshandbuch
+
+Schritt-für-Schritt-Anleitung zur Installation des Blacklist-Moduls im STARFACE Module Designer.
+
+---
+
+## Voraussetzungen
+
+- STARFACE 8.x, 9.x oder 10.x
+- Admin-Zugriff auf STARFACE
+- Kompilierte `BlacklistBlock.class` (siehe `./build-block.sh`)
+
+> Es ist **keine** zusätzliche Bibliothek nötig (anders als bei Mail2Fax kein JavaMail).
+> Es wird auch **kein** SSH-Zugriff zum Installieren von Libs benötigt.
+
+---
+
+## Teil 1: Modul-Erstellung im Module Designer
+
+### Schritt 1: Neues Modul erstellen
+
+STARFACE Admin → **Module → Module Designer → Neues Modul**
+
+- **Modul-Name**: `Blacklist`
+- **Beschreibung**: "Sperrt/behandelt eingehende Anrufe anhand einer Blacklist und anonyme Anrufe"
+- **Version**: `1.0.0`
+
+### Schritt 2: Class-Datei hochladen
+
+Tab **Ressourcen** → **Datei hochladen** → `BlacklistBlock.class`
+
+Optional (nur für die Aktion `ANNOUNCE`): eine Ansage-Audiodatei (WAV) hochladen.
+Der Dateiname wird später im Feld **Ansage-Datei** eingetragen.
+
+### Schritt 3: Funktion erstellen
+
+Tab **Funktionen** → neue Funktion `Blacklist` anlegen und den Block `BlacklistBlock`
+in den Ablauf ziehen.
+
+### Schritt 4: GUI-Elemente (Eingabefelder) anlegen
+
+Lege die Konfigurationsfelder an und verknüpfe sie mit den `@InputVar`-Feldern des Blocks:
+
+| Feldname | Typ | Label | Auswahlwerte |
+|----------|-----|-------|--------------|
+| `blacklistEntries` | STRING (mehrzeilig) | Blacklist-Einträge | |
+| `defaultAction` | STRING | Standard-Aktion | HANGUP, BUSY, REDIRECT, ANNOUNCE |
+| `defaultRedirectTarget` | STRING | Standard-Umleitungsziel | |
+| `announcementFile` | STRING | Ansage-Datei | |
+| `anonymousAction` | STRING | Aktion bei anonymen Anrufen | NONE, HANGUP, BUSY, REDIRECT, ANNOUNCE |
+| `anonymousRedirectTarget` | STRING | Umleitungsziel anonyme Anrufe | |
+| `countryCode` | STRING | Ländervorwahl | (Default 49) |
+| `prefixMatch` | BOOLEAN | Bereichssperre erlauben | (Default an) |
+
+> Die Auswahlwerte (`possibleValues`) sind bereits im Block hinterlegt und erscheinen
+> i.d.R. automatisch als Dropdown. Falls nicht, als normales Textfeld anlegen.
+
+### Schritt 5: GUI-Felder zuweisen
+
+Jedes GUI-Element mit dem gleichnamigen Block-Parameter verbinden. Alle `@InputVar`-Felder
+sollten verknüpft sein.
+
+### Schritt 6: Modul speichern
+
+Modul speichern.
+
+---
+
+## Teil 2: Modul als Anruf-Modul aktivieren
+
+Damit der Block bei eingehenden Anrufen läuft, muss das Modul als **Call-Processing-Modul**
+eingebunden werden.
+
+### Variante A: Für alle eingehenden Anrufe
+
+1. Module → **Modulkonfigurationen** → **[+] Neu**
+2. Modul `Blacklist` auswählen, Instanz benennen (z.B. "Blacklist - Zentrale")
+3. Felder ausfüllen (siehe Teil 3)
+4. Bei den Modul-Einstellungen den Typ **Call-Processing** wählen und die Aktivierung auf
+   **"bei allen eingehenden Anrufen"** setzen.
+5. Modul **aktivieren**.
+
+### Variante B: Pro Benutzer/Gruppe (Rufverteilung)
+
+Alternativ kann das Modul gezielt in die **Rufverteilung** eines Benutzers oder einer
+Gruppe eingehängt werden (Administration → Benutzer/Gruppe → Rufverteilung → Modul
+einfügen, **vor** der eigentlichen Zustellung). So gilt die Blacklist nur für diese
+Nummern.
+
+> **Wichtig:** Bei einem Treffer mit Aktion `HANGUP`/`BUSY`/`REDIRECT`/`ANNOUNCE` wird der
+> Anruf beendet bzw. umgeleitet und erreicht die nachgelagerte Zustellung nicht mehr.
+> Bei `ALLOW`/`NONE`/keinem Treffer läuft der Anruf normal weiter.
+
+---
+
+## Teil 3: Konfiguration (Beispiel)
+
+**Blacklist-Einträge:**
+```
+# Werbeanrufe-Bereiche komplett sperren
+0190;BUSY
+0900;BUSY
+# einzelner Störer: auflegen
+49301234567;HANGUP
+# Ausnahme: dieser eine Anschluss aus dem 089-Raum ist ok
+4989123456;ALLOW
+089;ANNOUNCE
+# nervige Nummer auf die Zentrale umleiten
+4972198765;REDIRECT;100
+```
+
+**Standard-Aktion (Blacklist):** `HANGUP`
+**Standard-Umleitungsziel:** `100`
+**Ansage-Datei:** `blacklist_ansage.wav` (zuvor als Ressource hochgeladen)
+
+**Aktion bei anonymen Anrufen:** `BUSY`
+*(oder `REDIRECT` mit Ziel, oder `NONE` zum Durchstellen)*
+
+**Ländervorwahl:** `49`
+**Bereichssperre erlauben:** ✓ an
+
+Mit dieser Konfiguration:
+- `0190…`/`0900…`/anonyme Anrufer hören Besetzt
+- `+49 30 1234567` wird aufgelegt
+- der gesamte `089…`-Bereich bekommt eine Ansage – **außer** `+49 89 123456` (Ausnahme oben)
+- `+49 721 98765` wird auf Nebenstelle 100 umgeleitet
+
+---
+
+## Logs und Fehlersuche
+
+**Log-Datei:**
+```
+/var/log/starface/starface.log
+```
+
+**Nützliche Meldungen:**
+```bash
+# alle Blacklist-Entscheidungen
+grep "Blacklist:" /var/log/starface/starface.log
+
+# Treffer
+grep "Blacklist-Treffer" /var/log/starface/starface.log
+
+# anonyme Anrufe
+grep "Blacklist: Anonymer Anruf" /var/log/starface/starface.log
+```
+
+**Häufige Punkte:**
+1. Block tut nichts / "kein Anruf-Kontext": Das Modul ist nicht als *Call-Processing* /
+   "bei allen eingehenden Anrufen" eingebunden.
+2. REDIRECT ohne Wirkung: Zielrufnummer/Nebenstelle prüfen, ggf. mit Amtskennziffer.
+3. ANNOUNCE ohne Ton: Audiodatei als Ressource hochgeladen und Dateiname im Feld korrekt?
+4. Nummer wird nicht erkannt: `countryCode` prüfen und im Log die normalisierte
+   `intl='…'`-Form mit dem Eintrag vergleichen.
+</content>