glpi-ai-knowledgebase/README.md

# KB Helpdesk – Editor & Google-Modus

Ein einziges Go-/Docker-Image für zwei Rollen auf derselben JSON-Wissensbasis:

1. **Editor-Modus** – vollständiger Einzel- und Masseneditor mit Backups.
2. **Google-Modus** – moderne, schreibgeschützte interne Helpdesk-Suche mit Artikel-Viewer.

Der Betriebsmodus wird ausschließlich über `APP_MODE` gewählt. Es ist kein zweiter Build und kein anderes Image nötig.

## Modi

### `APP_MODE=editor`

Der bekannte Administrationsmodus:

- Volltextsuche über ID, Titel, Text, Antwort, Keywords, Kategorien, Quelle und Pfad
- Filter für `auto_reply`, Sprache, Kommunikationsstil und Quelle
- Pagination für große Bestände mit 10.000+ Dateien
- Einzelbearbeitung als Formular
- vollständiger Raw-JSON-Editor
- Massenbearbeitung für Auswahl oder alle aktuellen Treffer
- Bulk-Setzen von `auto_reply`, `min_score`, `language`, `communication_style`, `source`, `source_uri`
- Keywords/Kategorien hinzufügen oder entfernen
- Suchen & Ersetzen in `title`, `text` und `answer`, optional per Regex
- Dry-Run/Vorschau vor Massenänderungen
- automatische Backups
- atomisches Schreiben per Temp-Datei + Rename
- Schutz vor extern veränderten Dateien

### `APP_MODE=google`

Reiner Helpdesk-/Viewer-Modus:

- große, reduzierte Suchoberfläche im Stil einer internen Suchmaschine
- Relevanzranking statt alphabetischer Trefferreihenfolge
- Gewichtung von ID/Fehlercode, Titel, Keywords, Kategorien, Problemtext und Antwort
- hervorgehobene Suchbegriffe
- Treffer-Auszüge aus Problem bzw. Lösung
- dynamische Schnellzugriffe aus den häufigsten Kategorien
- Pagination und URL-basierte Suchanfragen
- lesefreundlicher Artikel-Viewer
- Problem und Lösung visuell getrennt
- Antwort direkt in die Zwischenablage kopieren
- dauerhafter Link zu einem geöffneten Wissensartikel
- Quellenlink, sofern `source_uri` vorhanden ist
- responsive Oberfläche für Desktop, Tablet und Smartphone
- automatisches Neu-Einlesen des Dateiindex (standardmäßig alle 60 Sekunden)
- **keine Bearbeitungsoberfläche**
- **PUT-/Bulk-/Reload-Endpunkte werden serverseitig mit HTTP 403 gesperrt**

`viewer` und `search` werden zusätzlich als Alias für `google` akzeptiert. Für Deployments sollte aus Gründen der Eindeutigkeit `editor` oder `google` verwendet werden.

## Schnellstart

```bash
cp .env.example .env
docker compose up --build -d
```

Danach:

```text
http://localhost:8080
```

## Editor-Deployment

`.env`:

```dotenv
APP_MODE=editor
APP_TITLE=Knowledge Base Editor
APP_SUBTITLE=JSON · Massenbearbeitung · Docker

KB_DATA_PATH=../glpi-ai-agent-kb-microsoft-errorcodes-kompendium/knowledge
KB_DATA_MOUNT_MODE=rw
KB_BACKUP_PATH=./backups
KB_EDITOR_PORT=8080

BASIC_AUTH_USER=admin
BASIC_AUTH_PASSWORD=ein-langes-zufaelliges-passwort
```

Wichtig: Der Editor benötigt für das Knowledge-Verzeichnis `rw`.

## Google-/Helpdesk-Deployment

Dasselbe Image, nur andere ENV-Werte:

```dotenv
APP_MODE=google
APP_TITLE=IT Helpdesk Wissen
APP_SUBTITLE=Interne Lösungsdatenbank für Support und Service Desk
AUTO_RELOAD_INTERVAL=60s

KB_DATA_PATH=../glpi-ai-agent-kb-microsoft-errorcodes-kompendium/knowledge
KB_DATA_MOUNT_MODE=ro
KB_BACKUP_PATH=./backups
KB_EDITOR_PORT=8081

BASIC_AUTH_USER=helpdesk
BASIC_AUTH_PASSWORD=ein-langes-zufaelliges-passwort
```

Für den Google-Modus wird `KB_DATA_MOUNT_MODE=ro` empfohlen. Damit existieren zwei Schutzschichten:

1. Die Go-Anwendung stellt keine schreibende Funktion bereit und blockiert die schreibenden API-Endpunkte.
2. Docker mountet die JSON-Dateien zusätzlich read-only.

Der Backup-Pfad wird im Google-Modus nicht benutzt; er bleibt nur Teil derselben Compose-Konfiguration.

## Ein Image, zwei Container

Als fertiges Beispiel liegt `docker-compose.dual.yml` bei. Es startet denselben Build gleichzeitig als Editor auf Port 8080 und als read-only Helpdesk-Suche auf Port 8081:

```bash
docker compose -f docker-compose.dual.yml up --build -d
```

Alternativ kann ein gebautes Image manuell zweimal gestartet werden:

```bash
docker build -t kb-helpdesk:local .
```

Editor:

```bash
docker run -d \
  --name kb-editor \
  -p 8080:8080 \
  -e APP_MODE=editor \
  -e APP_TITLE="KB Administration" \
  -v /srv/kb/knowledge:/data/knowledge:rw \
  -v /srv/kb/backups:/data/backups:rw \
  kb-helpdesk:local
```

Helpdesk-Suche:

```bash
docker run -d \
  --name kb-search \
  -p 8081:8080 \
  -e APP_MODE=google \
  -e APP_TITLE="IT Helpdesk Wissen" \
  -e APP_SUBTITLE="Interne Lösungsdatenbank" \
  -v /srv/kb/knowledge:/data/knowledge:ro \
  kb-helpdesk:local
```

Beide Container lesen damit denselben Bestand. Im Google-Modus wird der Dateiindex standardmäßig alle 60 Sekunden automatisch neu aufgebaut, sodass Änderungen aus dem Editor ohne Container-Neustart sichtbar werden. Mit `AUTO_RELOAD_INTERVAL=0` kann das deaktiviert werden. Der Editor besitzt zusätzlich einen manuellen Reload-Button.

## Konfiguration

| Variable | Standard | Bedeutung |
|---|---|---|
| `APP_MODE` | `editor` | `editor` oder `google`; zusätzlich Aliase `viewer`/`search` |
| `APP_TITLE` | modusabhängig | Name in Browser und Kopfzeile |
| `APP_SUBTITLE` | modusabhängig | Untertitel/Helpdesk-Beschreibung |
| `AUTO_RELOAD_INTERVAL` | Google: `60s`, Editor: aus | Dateiindex regelmäßig neu aufbauen; `0`/`off` deaktiviert |
| `DATA_DIR` | `./data/knowledge` | Wurzelverzeichnis der JSON-Dateien |
| `BACKUP_DIR` | `.kb-editor-backups` neben dem Datenordner | Backup-Ziel im Editor-Modus |
| `LISTEN_ADDR` | `:8080` | HTTP Listen-Adresse |
| `BASIC_AUTH_USER` | leer | Optionaler Basic-Auth-Benutzer |
| `BASIC_AUTH_PASSWORD` | leer | Optionales Basic-Auth-Passwort |
| `KB_DATA_PATH` | `./knowledge` | Hostpfad für Docker Compose |
| `KB_DATA_MOUNT_MODE` | `rw` | `rw` für Editor, empfohlen `ro` für Google-Modus |
| `KB_BACKUP_PATH` | `./backups` | Hostpfad für Backups |
| `KB_EDITOR_PORT` | `8080` | veröffentlichter Host-Port |

## Suche und Ranking im Google-Modus

Eine Suche muss alle eingegebenen Suchbegriffe im indexierten Dokument finden. Anschließend werden die Treffer gewichtet. Besonders hoch bewertet werden:

1. exakte ID-/Fehlercode-Treffer,
2. Titel,
3. Keywords,
4. Kategorien,
5. Problem-/Erkennungstext,
6. Antwort/Lösung,
7. Quelle.

Dadurch steht beispielsweise ein Artikel mit `0x80070005` direkt in ID/Titel vor einem Artikel, der denselben Code nur beiläufig im Lösungstext erwähnt.

Die Such-URL ist teilbar:

```text
/?q=0x80070005
```

Ein geöffneter Artikel erhält zusätzlich `doc=<interner-key>` und kann so intern direkt verlinkt werden.

## Tastatur

Im Google-Modus fokussiert `/` von überall die Suche.

Im Editor gelten zusätzlich die bereits vorhandenen Tastaturfunktionen, unter anderem `Ctrl+S`/`Cmd+S` zum Speichern.

## JSON-Verhalten

Die Anwendung arbeitet direkt mit `.json`-Dateien. Für Suche und Navigation liegt ein Index im RAM. Unbekannte zusätzliche JSON-Felder bleiben beim Bearbeiten erhalten.

Das bekannte Schema kann beispielsweise enthalten:

```json
{
  "id": "KB-MSERR-...",
  "title": "...",
  "text": "...",
  "answer": "...",
  "auto_reply": true,
  "min_score": 0.78,
  "categories": ["Windows"],
  "keywords": ["0x80070005"],
  "source": "Microsoft Learn",
  "source_uri": "https://learn.microsoft.com/...",
  "language": "de-DE",
  "communication_style": "formal"
}
```

## Backups im Editor-Modus

Bei einem normalen Speichern entsteht ein Zeitstempelverzeichnis, zum Beispiel:

```text
backups/
└── 20260728-153012.123456789/
    └── KB-MSERR-ACT-00001.json
```

Bei einer Massenänderung werden alle Originaldateien desselben Vorgangs gemeinsam gesichert. Die relative Unterverzeichnisstruktur bleibt erhalten.

Backups werden nicht automatisch gelöscht.

## Externe Dateiänderungen

Der Editor erkennt beim Speichern, wenn die betreffende Datei seit dem Indexieren außerhalb der Anwendung verändert wurde. In diesem Fall wird das Überschreiben verweigert.

Der Index wird beim Prozessstart aufgebaut. Im Google-Modus wird er standardmäßig alle 60 Sekunden erneut aus den Dateien aufgebaut. Das Intervall lässt sich mit `AUTO_RELOAD_INTERVAL` ändern (`30s`, `2m` usw.); Werte unter fünf Sekunden werden abgelehnt. Im Editor erfolgt kein automatischer Reload, damit laufende Bearbeitungen nicht überraschend überlagert werden; dort steht **„Neu einlesen“** zur Verfügung.

## API

Lesend in beiden Modi:

- `GET /api/health`
- `GET /api/config`
- `GET /api/items?q=...&page=1&page_size=60`
- `GET /api/search?q=...&page=1&page_size=20`
- `GET /api/facets?limit=10`
- `GET /api/items/{key}`

Nur im Editor-Modus:

- `PUT /api/items/{key}`
- `POST /api/bulk`
- `POST /api/reload`

Im Google-Modus antworten diese drei Endpunkte mit HTTP `403 Forbidden`.

## Sicherheit

Für interne Remote-Nutzung sollte mindestens Basic Auth aktiviert und die Anwendung hinter einem Reverse Proxy mit TLS veröffentlicht werden.

Das Compose-Setup:

- startet das Container-Root-Filesystem read-only,
- entfernt Linux-Capabilities,
- setzt `no-new-privileges`,
- verwendet `/tmp` als kleines tmpfs,
- kann den Knowledge-Mount im Google-Modus zusätzlich read-only einbinden.

Die Oberfläche hat keine externen CDN-/JavaScript-Abhängigkeiten.

## Ohne Docker

Voraussetzung: Go 1.23 oder neuer.

Editor:

```bash
APP_MODE=editor go run ./cmd/server -data /pfad/zum/knowledge
```

Google-Modus:

```bash
APP_MODE=google \
APP_TITLE="IT Helpdesk Wissen" \
APP_SUBTITLE="Interne Wissenssuche" \
go run ./cmd/server -data /pfad/zum/knowledge
```

Tests/Build:

```bash
go test ./...
go vet ./...
go build -o kb-helpdesk ./cmd/server
```

## Projektstruktur

```text
.
├── cmd/server/
│   ├── app.go
│   ├── main.go
│   ├── web/              # Editor-Oberfläche
│   │   ├── index.html
│   │   ├── app.js
│   │   └── style.css
│   └── viewer/           # Google-/Helpdesk-Oberfläche
│       ├── index.html
│       ├── app.js
│       └── style.css
├── internal/store/
│   ├── store.go
│   └── store_test.go
├── knowledge/
├── backups/
├── Dockerfile
├── docker-compose.yml
├── docker-compose.dual.yml
├── .env.example
├── Makefile
└── go.mod
```