From ec581f67da7a3b2dc643997eaab5cb4b55ab8b53 Mon Sep 17 00:00:00 2001 From: ph34444 Date: Mon, 16 Mar 2026 15:41:38 +0100 Subject: [PATCH] docs: AI support automation design spec and implementation plan --- .env | 15 + compose.yaml | 61 + .../2026-03-16-ai-support-automation-plan.md | 1023 +++++++++++++++++ ...26-03-16-ai-support-automation-design.docx | Bin 0 -> 18031 bytes ...2026-03-16-ai-support-automation-design.md | 364 ++++++ 5 files changed, 1463 insertions(+) create mode 100644 .env create mode 100644 compose.yaml create mode 100644 docs/superpowers/plans/2026-03-16-ai-support-automation-plan.md create mode 100644 docs/superpowers/specs/2026-03-16-ai-support-automation-design.docx create mode 100644 docs/superpowers/specs/2026-03-16-ai-support-automation-design.md diff --git a/.env b/.env new file mode 100644 index 0000000..44d3193 --- /dev/null +++ b/.env @@ -0,0 +1,15 @@ +# DOMAIN_NAME and SUBDOMAIN together determine where n8n will be reachable from +# The top level domain to serve from +DOMAIN_NAME=fft-it.de + +# The subdomain to serve from +SUBDOMAIN=n8n + +# The above example serve n8n at: https://n8n.example.com + +# Optional timezone to set which gets used by Cron and other scheduling nodes +# New York is the default value if not set +GENERIC_TIMEZONE=Europe/Berlin + +# The email address to use for the TLS/SSL certificate creation +SSL_EMAIL=patrick.haas@eks-intec.de \ No newline at end of file diff --git a/compose.yaml b/compose.yaml new file mode 100644 index 0000000..1c7a7a6 --- /dev/null +++ b/compose.yaml @@ -0,0 +1,61 @@ +services: + traefik: + image: "traefik" + restart: always + command: + - "--api.insecure=true" + - "--providers.docker=true" + - "--providers.docker.exposedbydefault=false" + - "--entrypoints.web.address=:80" + - "--entrypoints.web.http.redirections.entryPoint.to=websecure" + - "--entrypoints.web.http.redirections.entrypoint.scheme=https" + - "--entrypoints.websecure.address=:443" + - "--certificatesresolvers.mytlschallenge.acme.tlschallenge=true" + - "--certificatesresolvers.mytlschallenge.acme.email=${SSL_EMAIL}" + - "--certificatesresolvers.mytlschallenge.acme.storage=/letsencrypt/acme.json" + ports: + - "80:80" + - "443:443" + volumes: + - traefik_data:/letsencrypt + - /var/run/docker.sock:/var/run/docker.sock:ro + - ./crts:/opt/custom-certificates + + n8n: + image: docker.n8n.io/n8nio/n8n + restart: always + ports: + - "127.0.0.1:5678:5678" + labels: + - traefik.enable=true + - traefik.http.routers.n8n.rule=Host(`${SUBDOMAIN}.${DOMAIN_NAME}`) + - traefik.http.routers.n8n.tls=true + - traefik.http.routers.n8n.entrypoints=web,websecure + - traefik.http.routers.n8n.tls.certresolver=mytlschallenge + - traefik.http.middlewares.n8n.headers.SSLRedirect=true + - traefik.http.middlewares.n8n.headers.STSSeconds=315360000 + - traefik.http.middlewares.n8n.headers.browserXSSFilter=true + - traefik.http.middlewares.n8n.headers.contentTypeNosniff=true + - traefik.http.middlewares.n8n.headers.forceSTSHeader=true + - traefik.http.middlewares.n8n.headers.SSLHost=${DOMAIN_NAME} + - traefik.http.middlewares.n8n.headers.STSIncludeSubdomains=true + - traefik.http.middlewares.n8n.headers.STSPreload=true + - traefik.http.routers.n8n.middlewares=n8n@docker + environment: + - N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS=true + - N8N_HOST=${SUBDOMAIN}.${DOMAIN_NAME} + - N8N_PORT=5678 + - N8N_PROTOCOL=https + - N8N_RUNNERS_ENABLED=true + - NODE_ENV=production + - WEBHOOK_URL=https://${SUBDOMAIN}.${DOMAIN_NAME}/ + - GENERIC_TIMEZONE=${GENERIC_TIMEZONE} + - TZ=${GENERIC_TIMEZONE} + volumes: + - n8n_data:/home/node/.n8n + - ./local-files:/files + - ./crts:/opt/custom-certificates + +volumes: + n8n_data: + traefik_data: \ No newline at end of file diff --git a/docs/superpowers/plans/2026-03-16-ai-support-automation-plan.md b/docs/superpowers/plans/2026-03-16-ai-support-automation-plan.md new file mode 100644 index 0000000..9c93a7d --- /dev/null +++ b/docs/superpowers/plans/2026-03-16-ai-support-automation-plan.md @@ -0,0 +1,1023 @@ +# AI-gestützte IT-Support-Automatisierung Implementation Plan + +> **For agentic workers:** REQUIRED: Use superpowers:subagent-driven-development or superpowers:executing-plans to implement this plan. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Ein produktives Hybrid-System bauen, das Freescout-Mails analysiert, KI-Vorschläge macht, Mensch-Approval einholt, und eine selbstlernende Wissensdatenbank aufbaut. + +**Architecture:** 4-phasiger Ansatz: +1. **Phase 1 (Setup):** Docker Compose + Vector DB + Freescout Custom Fields +2. **Phase 2 (Workflows):** n8n Workflows A (Mail-Processing), B (Approval), C (KB-Update) +3. **Phase 3 (Integration):** End-to-End Testing + API Connections +4. **Phase 4 (Production):** Monitoring + Dokumentation + Go-Live + +**Tech Stack:** +- **Orchestrierung:** n8n (vorhanden, Docker) +- **Vector DB:** Milvus (Docker) +- **KI:** LiteLLM API (extern: http://llm.eks-ai.apps.asgard.eks-lnx.fft-it.de) +- **Mail-Source:** Freescout API (extern: https://ekshelpdesk.fft-it.de) +- **Job-Execution:** Baramundi Management Server API (extern) +- **Audit Trail:** PostgreSQL (Docker) + +--- + +## Chunk 1: Infrastructure & Setup + +### Task 1.1: Vector Database in Docker Compose integrieren + +**Files:** +- Modify: `compose.yaml` +- Create: `.env.example` (aktualisieren mit neuen Vars) + +- [ ] **Step 1: compose.yaml lesen und Struktur verstehen** + +Schau dir die aktuelle Struktur an (Traefik, n8n). + +- [ ] **Step 2: Milvus Service zu compose.yaml hinzufügen** + +```yaml + milvus: + image: milvusdb/milvus:latest + restart: always + environment: + COMMON_STORAGETYPE: local + COMMON_LOG_LEVEL: info + ports: + - "127.0.0.1:19530:19530" + - "127.0.0.1:9091:9091" + volumes: + - milvus_data:/var/lib/milvus + healthcheck: + test: ["CMD", "curl", "-f", "http://localhost:9091/healthz"] + interval: 30s + timeout: 10s + retries: 5 + + postgres: + image: postgres:15-alpine + restart: always + environment: + POSTGRES_DB: n8n_kb + POSTGRES_USER: kb_user + POSTGRES_PASSWORD: ${POSTGRES_PASSWORD} + ports: + - "127.0.0.1:5432:5432" + volumes: + - postgres_data:/var/lib/postgresql/data + healthcheck: + test: ["CMD-SHELL", "pg_isready -U kb_user"] + interval: 10s + timeout: 5s + retries: 5 + +volumes: + traefik_data: + n8n_data: + milvus_data: + postgres_data: +``` + +- [ ] **Step 3: .env mit neuen Variablen aktualisieren** + +```bash +# Existing +SSL_EMAIL=your-email@example.com +SUBDOMAIN=n8n +DOMAIN_NAME=example.com +GENERIC_TIMEZONE=Europe/Berlin + +# New für KB +POSTGRES_PASSWORD=secure_password_change_me +MILVUS_API_URL=http://milvus:19530 +``` + +- [ ] **Step 4: Services starten und healthcheck testen** + +```bash +docker-compose up -d milvus postgres +docker-compose logs -f milvus +# Expected: "Milvus is ready to serve" + +curl http://127.0.0.1:9091/healthz +# Expected: 200 OK +``` + +- [ ] **Step 5: Commit** + +```bash +git add compose.yaml .env.example +git commit -m "infra: add Milvus vector DB and PostgreSQL for KB audit trail" +``` + +--- + +### Task 1.2: PostgreSQL Audit Schema erstellen + +**Files:** +- Create: `sql/01-audit-schema.sql` + +- [ ] **Step 1: Erstelle SQL Schema Datei** + +```sql +-- Audit Trail für KB Updates +CREATE TABLE knowledge_base_updates ( + id UUID PRIMARY KEY DEFAULT gen_random_uuid(), + ticket_id INTEGER NOT NULL, + problem_text TEXT NOT NULL, + kategorie VARCHAR(100), + lösung TEXT, + created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, + approved_at TIMESTAMP, + executed_at TIMESTAMP, + status VARCHAR(50) CHECK (status IN ('PENDING', 'APPROVED', 'REJECTED', 'EXECUTED')), + freescout_note TEXT +); + +CREATE INDEX idx_kbu_ticket ON knowledge_base_updates(ticket_id); +CREATE INDEX idx_kbu_status ON knowledge_base_updates(status); +CREATE INDEX idx_kbu_kategorie ON knowledge_base_updates(kategorie); + +CREATE TABLE kb_feedback ( + id UUID PRIMARY KEY DEFAULT gen_random_uuid(), + kb_entry_id VARCHAR(255) NOT NULL, + feedback VARCHAR(50) CHECK (feedback IN ('helpful', 'not_helpful')), + reason TEXT, + created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP +); + +CREATE INDEX idx_kbf_entry ON kb_feedback(kb_entry_id); + +CREATE TABLE workflow_executions ( + id UUID PRIMARY KEY DEFAULT gen_random_uuid(), + workflow_name VARCHAR(255), + ticket_id INTEGER, + status VARCHAR(50), + error_message TEXT, + execution_time_ms INTEGER, + created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP +); + +CREATE INDEX idx_we_ticket ON workflow_executions(ticket_id); +CREATE INDEX idx_we_workflow ON workflow_executions(workflow_name); +``` + +- [ ] **Step 2: Initialisiere PostgreSQL mit Schema** + +```bash +docker-compose exec postgres psql -U kb_user -d n8n_kb < sql/01-audit-schema.sql +# Expected: CREATE TABLE, CREATE INDEX messages +``` + +- [ ] **Step 3: Teste Schema** + +```bash +docker-compose exec postgres psql -U kb_user -d n8n_kb -c "\dt" +# Expected: 3 tables angezeigt +``` + +- [ ] **Step 4: Commit** + +```bash +git add sql/01-audit-schema.sql +git commit -m "infra: PostgreSQL audit schema for KB tracking" +``` + +--- + +### Task 1.3: Freescout Custom Fields erstellen (manuell) + +**Dokumentation:** Freescout API Docs + +- [ ] **Step 1: Freescout API Key vorbereiten** + +Erstelle `.env` Eintrag: +```bash +FREESCOUT_API_KEY=your_api_key_here +FREESCOUT_API_BASE=https://ekshelpdesk.fft-it.de/api/v1 +FREESCOUT_MAILBOX_ID=1 +``` + +- [ ] **Step 2: Test Freescout API Verbindung** + +```bash +curl -H "Authorization: Bearer $FREESCOUT_API_KEY" \ + https://ekshelpdesk.fft-it.de/api/v1/mailboxes/1 +# Expected: Mailbox JSON angezeigt +``` + +- [ ] **Step 3: Erstelle Setup-Skript für Custom Fields** + +Datei: `scripts/setup-freescout-fields.sh` + +```bash +#!/bin/bash + +API_BASE="${FREESCOUT_API_BASE}" +API_KEY="${FREESCOUT_API_KEY}" +MAILBOX_ID="${FREESCOUT_MAILBOX_ID}" + +echo "Creating Freescout Custom Fields..." + +# Field 1: AI_SUGGESTION (Text für JSON) +curl -X POST "$API_BASE/mailboxes/$MAILBOX_ID/custom-fields" \ + -H "Authorization: Bearer $API_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "name": "AI_SUGGESTION", + "title": "KI-Vorschlag", + "type": "text", + "required": false + }' && echo "✅ AI_SUGGESTION created" + +# Field 2: AI_SUGGESTION_STATUS (Dropdown) +curl -X POST "$API_BASE/mailboxes/$MAILBOX_ID/custom-fields" \ + -H "Authorization: Bearer $API_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "name": "AI_SUGGESTION_STATUS", + "title": "KI-Status", + "type": "select", + "required": false, + "options": ["PENDING", "APPROVED", "REJECTED", "EXECUTED"] + }' && echo "✅ AI_SUGGESTION_STATUS created" + +# Field 3: PROCESSED_BY_AI (Boolean) +curl -X POST "$API_BASE/mailboxes/$MAILBOX_ID/custom-fields" \ + -H "Authorization: Bearer $API_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "name": "PROCESSED_BY_AI", + "title": "Von KI verarbeitet", + "type": "checkbox", + "required": false + }' && echo "✅ PROCESSED_BY_AI created" + +echo "✅ All custom fields created!" +``` + +- [ ] **Step 4: Führe Setup Skript aus** + +```bash +bash scripts/setup-freescout-fields.sh +# Expected: 3x ✅ created +``` + +- [ ] **Step 5: Commit** + +```bash +git add scripts/setup-freescout-fields.sh +git commit -m "scripts: setup Freescout custom fields" +``` + +--- + +## Chunk 2: n8n Workflows Setup & Workflow A (Mail Processing) + +### Task 2.1: n8n Credentials & Collections vorbereiten + +**Files:** +- Create: `n8n-workflows/00-SETUP.md` +- Create: `n8n-workflows/workflow-a-mail-processing.json` + +- [ ] **Step 1: Verstehe n8n Workflow Export Format** + +n8n Workflows werden als JSON exportiert. Struktur: +```json +{ + "name": "Workflow Name", + "nodes": [...], + "connections": {...}, + "active": true +} +``` + +- [ ] **Step 2: Erstelle Setup-Dokumentation** + +Datei: `n8n-workflows/00-SETUP.md` + +```markdown +# n8n Workflows Setup + +## Benötigte Credentials + +1. **Freescout API:** + - Type: HTTP Request (Generic Credentials) + - Base URL: https://ekshelpdesk.fft-it.de/api/v1 + - Auth: Bearer Token (von .env FREESCOUT_API_KEY) + +2. **LiteLLM API:** + - Type: HTTP Request + - Base URL: http://llm.eks-ai.apps.asgard.eks-lnx.fft-it.de + - No auth needed (lokal) + +3. **PostgreSQL:** + - Host: postgres (Docker) + - Port: 5432 + - Database: n8n_kb + - User: kb_user + - Password: (von .env POSTGRES_PASSWORD) + +4. **Milvus:** + - Host: milvus + - Port: 19530 + - No auth + +## Workflow Import + +Importiere folgende Workflows in n8n: +1. workflow-a-mail-processing.json +2. workflow-b-approval-execution.json +3. workflow-c-kb-update.json + +Schalte sie in dieser Reihenfolge an: +1. Workflow A (Mail Processing) – hauptziel +2. Workflow B (Approval) – triggered bei Field-Änderung +3. Workflow C (KB Update) – triggered nach Workflow B +``` + +- [ ] **Step 3: Commit Setup Dokumentation** + +```bash +git add n8n-workflows/00-SETUP.md +git commit -m "docs: n8n setup and credential configuration" +``` + +--- + +### Task 2.2: Workflow A – Mail Processing (Polling + KI-Analyse) + +**Files:** +- Create: `n8n-workflows/workflow-a-mail-processing.json` + +**Logik:** +1. Trigger: Cron (alle 5 Min) +2. Freescout API: neue Tickets fetchen +3. Für jedes Ticket: Vector DB Query + LLM Call +4. Speichere Vorschlag in Freescout + +- [ ] **Step 1: Workflow-Struktur in n8n UI bauen** + +Node 1: **Cron Trigger** +- Cron: `*/5 * * * *` (alle 5 Min) + +Node 2: **Freescoot API – Get Conversations** +- Method: GET +- URL: `https://ekshelpdesk.fft-it.de/api/v1/mailboxes/1/conversations?status=active` +- Auth: Bearer Token +- Params: `status=active&limit=20&processed_by_ai=false` + +Node 3: **Loop through Conversations** +- Use: Loop node über Array aus Node 2 + +Node 4: **Extract Conversation Details** +- Use: Set node um Subject, Body zu extrahieren +```javascript +{ + ticket_id: item.id, + subject: item.subject, + body: item.threads[0].body, + customer_email: item.customer.email +} +``` + +Node 5: **Vector DB Query (Milvus)** +- Python node um ähnliche KB-Einträge zu finden +```python +from pymilvus import Collection + +# Connect to Milvus +collection = Collection("knowledge_base") + +# Search for similar problems +results = collection.search( + data=[embedding_vector], # zu erzeugen via LLM + anns_field="embedding", + param={ + "metric_type": "L2", + "params": {"nprobe": 10} + }, + limit=3, + output_fields=["problem_text", "kategorie", "lösung"] +) + +return results +``` + +Node 6: **LLM Call (LiteLLM)** +- HTTP Request zu LiteLLM +- Method: POST +- URL: `http://llm.eks-ai.apps.asgard.eks-lnx.fft-it.de/v1/chat/completions` +- Body: +```json +{ + "model": "available-model", + "messages": [ + { + "role": "system", + "content": "Du bist IT-Support-Assistent..." + }, + { + "role": "user", + "content": "Ticket: [subject]\n[body]\n\nÄhnliche Lösungen aus KB: [top 3 results]" + } + ], + "temperature": 0.3 +} +``` + +Node 7: **Parse LLM Response** +- Extract JSON aus response +```javascript +{ + kategorie: json.kategorie, + lösung_typ: json.lösung_typ, + vertrauen: json.vertrauen, + antwort_text: json.antwort_text, + begründung: json.begründung +} +``` + +Node 8: **Save to Freescout (Custom Fields)** +- HTTP Request +- Method: PUT +- URL: `https://ekshelpdesk.fft-it.de/api/v1/conversations/{ticket_id}` +- Body: +```json +{ + "custom_fields": { + "AI_SUGGESTION": "{{$node[\"Parse LLM Response\"].json}}", + "AI_SUGGESTION_STATUS": "PENDING", + "PROCESSED_BY_AI": true + } +} +``` + +- [ ] **Step 2: Exportiere Workflow als JSON** + +In n8n: Menu → Export → Full Workflow JSON +Speichere als `n8n-workflows/workflow-a-mail-processing.json` + +- [ ] **Step 3: Teste Workflow manuell** + +- Starte Workflow manuell (Test-Button) +- Check Freescout UI: neue Custom Fields angezeigt? +- Check n8n Logs auf Fehler + +- [ ] **Step 4: Aktiviere Cron Trigger** + +Schalte Workflow an. Sollte jetzt alle 5 Min laufen. + +- [ ] **Step 5: Commit** + +```bash +git add n8n-workflows/workflow-a-mail-processing.json +git commit -m "feat: workflow A – mail processing and KI analysis" +``` + +--- + +## Chunk 3: Workflow B & C (Approval + KB Update) + +### Task 3.1: Workflow B – Approval & Execution + +**Files:** +- Create: `n8n-workflows/workflow-b-approval-execution.json` + +**Logik:** +1. Trigger: Webhook oder Polling (wenn AI_SUGGESTION_STATUS geändert) +2. Validiere: APPROVED oder REJECTED +3. Wenn APPROVED: Branching + - Baramundi Job? → Baramundi API Call + - Automatische Antwort? → Email senden +4. Trigger Workflow C + +- [ ] **Step 1: Baue Trigger Node** + +Option A: **Webhook Trigger** (empfohlen) +- Freescout muss Webhook supportieren +- Trigger bei Field-Änderung + +Option B: **Polling via HTTP** +- Alle 2 Min abfragen: welche Conversations haben AI_SUGGESTION_STATUS = APPROVED +- Fallback wenn Webhook nicht verfügbar + +Für MVP: **Option B (Polling)** + +- [ ] **Step 2: Baue Approval Check Node** + +HTTP Request zu Freescout: +``` +GET /api/v1/conversations?custom_field_AI_SUGGESTION_STATUS=APPROVED&processed_approval=false +``` + +- [ ] **Step 3: Baue Branching Logic** + +Für jedes approved Ticket: +- Parse AI_SUGGESTION +- Check: ist `lösung_typ == "BARAMUNDI_JOB"` oder `"AUTOMATISCHE_ANTWORT"`? + +- [ ] **Step 4: Baramundi Job Node** + +Wenn Baramundi: +``` +POST /api/jobs (Baramundi Management Server) +{ + "name": "{{$node[...].json.baramundi_job.name}}", + "parameter": {...} +} +``` + +- [ ] **Step 5: Email/Reply Node** + +Wenn Automatische Antwort: +``` +POST /api/v1/conversations/{id}/threads +{ + "from": "support@company.com", + "to": "{{customer_email}}", + "subject": "Re: {{subject}}", + "body": "{{antwort_text}}" +} +``` + +- [ ] **Step 6: Mark as Executed** + +Nach Success: Update Custom Field +``` +PUT /api/v1/conversations/{id} +{ + "custom_fields": { + "AI_SUGGESTION_STATUS": "EXECUTED" + } +} +``` + +- [ ] **Step 7: Trigger Workflow C** + +Webhook Call zu Workflow C: +``` +POST http://n8n:5678/webhook/kb-update +{ + "ticket_id": "...", + "status": "EXECUTED" +} +``` + +- [ ] **Step 8: Exportiere & Teste** + +```bash +# Export Workflow B +# In n8n: Menu → Export + +git add n8n-workflows/workflow-b-approval-execution.json +git commit -m "feat: workflow B – approval gate and execution" +``` + +--- + +### Task 3.2: Workflow C – Knowledge Base Update + +**Files:** +- Create: `n8n-workflows/workflow-c-kb-update.json` + +**Logik:** +1. Trigger: Webhook von Workflow B +2. Hole Lösungs-Details +3. Generiere Embedding (LLM) +4. Speichere in Milvus +5. Update Häufigkeit bestehender Einträge +6. Log in PostgreSQL + +- [ ] **Step 1: Webhook Trigger Node** + +``` +POST http://n8n:5678/webhook/kb-update +``` + +Payload: +```json +{ + "ticket_id": "123", + "problem_text": "...", + "kategorie": "Hardware", + "lösung": "Drucker-Treiber neu installiert" +} +``` + +- [ ] **Step 2: Embedding Generation Node** + +LLM Call für Embedding: +``` +POST http://llm.eks-ai.apps.asgard.eks-lnx.fft-it.de/v1/embeddings +{ + "model": "available", + "input": "Hardware: {{kategorie}} + {{problem_text}}" +} +``` + +- [ ] **Step 3: Milvus Insert Node** + +Python Node: +```python +from pymilvus import Collection +import json + +collection = Collection("knowledge_base") + +entity = { + "id": uuid4(), + "problem_text": "{{problem_text}}", + "kategorie": "{{kategorie}}", + "lösung": "{{lösung}}", + "häufigkeit": 1, + "embedding": embedding_vector, + "timestamp": datetime.now(), + "freescout_ticket_id": ticket_id +} + +collection.insert([entity]) +collection.flush() + +return {"status": "inserted"} +``` + +- [ ] **Step 4: Update Häufigkeit (Optional)** + +Suche ähnliche KB-Einträge und erhöhe deren Häufigkeit: +```python +results = collection.search( + data=[embedding_vector], + limit=5, + threshold=0.85 +) + +for result in results: + # Update entry + collection.delete(id=result.id) + result.häufigkeit += 1 + collection.insert([result]) +``` + +- [ ] **Step 5: PostgreSQL Audit Log Node** + +PostgreSQL Node: +```sql +INSERT INTO knowledge_base_updates + (ticket_id, problem_text, kategorie, lösung, status, created_at, approved_at, executed_at) +VALUES + ('{{ticket_id}}', '{{problem_text}}', '{{kategorie}}', '{{lösung}}', 'EXECUTED', NOW(), NOW(), NOW()) +``` + +- [ ] **Step 6: Error Handling** + +Wenn einer der Steps fehlschlägt: +- Log Error in PostgreSQL +- Notify Admin (optional Email) +- STOP (nicht crashen) + +- [ ] **Step 7: Exportiere & Teste** + +```bash +git add n8n-workflows/workflow-c-kb-update.json +git commit -m "feat: workflow C – knowledge base auto-update" +``` + +--- + +## Chunk 4: Integration, Testing & Production + +### Task 4.1: End-to-End Testing + +**Files:** +- Create: `tests/e2e-test-scenario.md` +- Create: `tests/curl-test-collection.sh` + +- [ ] **Step 1: Schreibe E2E Test Szenario** + +```markdown +# E2E Test: Full Workflow + +## Setup +- Milvus läuft +- PostgreSQL läuft +- n8n läuft +- Freescout erreichbar +- LiteLLM erreichbar + +## Test Steps + +1. **Create Test Ticket in Freescout** + - Subject: "Drucker funktioniert nicht" + - Body: "Jeder Druck-Befehl wird abgelehnt. Fehlercode 5." + - Customer: test@example.com + +2. **Warte 5 Min** (Workflow A Cycle) + - Check n8n Logs: Mail verarbeitet? + - Check Freescout: Custom Field AI_SUGGESTION gefüllt? + +3. **Approve Vorschlag** + - Freescout: AI_SUGGESTION_STATUS = APPROVED + +4. **Warte 2 Min** (Workflow B Cycle) + - Check n8n: Job ausgelöst oder Email gesendet? + - Check Baramundi: Job erstellt? + +5. **Warte 1 Min** (Workflow C Cycle) + - Check PostgreSQL: INSERT in knowledge_base_updates? + - Check Milvus: KB-Eintrag erstellt? + +6. **Vector DB Search Test** + - Query Milvus mit ähnlichem Problem + - Sollte neuen Eintrag finden mit hoher Similarity +``` + +- [ ] **Step 2: Schreibe Test Curl Commands** + +`tests/curl-test-collection.sh`: + +```bash +#!/bin/bash + +echo "=== E2E Test Collection ===" + +# 1. Check Milvus Health +echo "✓ Testing Milvus..." +curl http://127.0.0.1:9091/healthz + +# 2. Check PostgreSQL +echo "✓ Testing PostgreSQL..." +docker-compose exec postgres psql -U kb_user -d n8n_kb -c "SELECT COUNT(*) FROM knowledge_base_updates;" + +# 3. Check Freescout API +echo "✓ Testing Freescout API..." +curl -H "Authorization: Bearer $FREESCOUT_API_KEY" \ + https://ekshelpdesk.fft-it.de/api/v1/mailboxes/1/conversations?limit=5 + +# 4. Check LiteLLM +echo "✓ Testing LiteLLM..." +curl -X POST http://llm.eks-ai.apps.asgard.eks-lnx.fft-it.de/v1/chat/completions \ + -H "Content-Type: application/json" \ + -d '{ + "model": "any", + "messages": [{"role": "user", "content": "test"}] + }' + +echo "=== All tests passed ===" +``` + +- [ ] **Step 3: Führe Tests aus** + +```bash +bash tests/curl-test-collection.sh +# Expected: ✓ All tests passed +``` + +- [ ] **Step 4: Erstelle echtes Test-Ticket in Freescout** + +Manuell oder via Freescout UI: +- Subject: "Drucker funktioniert nicht" +- Body: "Fehlercode 5 beim Drucken" + +Überwache: +- n8n Logs +- Freescout Custom Fields +- PostgreSQL + +- [ ] **Step 5: Commit** + +```bash +git add tests/ +git commit -m "test: E2E test scenarios and curl collection" +``` + +--- + +### Task 4.2: Monitoring & Logging Setup + +**Files:** +- Create: `docker-compose.override.yml` (für Logging) +- Create: `docs/MONITORING.md` + +- [ ] **Step 1: Füge n8n Logging zu Compose hinzu** + +`docker-compose.override.yml`: + +```yaml +services: + n8n: + environment: + - N8N_LOG_LEVEL=debug + - N8N_LOG_OUTPUT=stdout + logging: + driver: "json-file" + options: + max-size: "100m" + max-file: "10" +``` + +- [ ] **Step 2: Erstelle Monitoring Dokumentation** + +`docs/MONITORING.md`: + +```markdown +# Monitoring & Debugging + +## Key Metrics + +1. **Mail Processing Rate** + - N8N Logs: "processed X conversations" + - PostgreSQL: `SELECT COUNT(*) FROM workflow_executions WHERE workflow_name='workflow-a'` + +2. **Approval Rate** + - PostgreSQL: `SELECT status, COUNT(*) FROM knowledge_base_updates GROUP BY status` + - Expected: Meiste APPROVED + +3. **KB Growth** + - Milvus: `SELECT COUNT(*) FROM knowledge_base` (via Python) + - Expected: +1 pro appropierten Ticket + +4. **Error Rate** + - PostgreSQL: `SELECT * FROM workflow_executions WHERE status='ERROR'` + - Expected: < 5% + +## Troubleshooting + +### Workflow A läuft nicht +- Check: Cron trigger aktiv? +- Check: n8n credentials valid? +- Check: Freescout API erreichbar? + +### Workflow B triggert nicht +- Check: AI_SUGGESTION_STATUS im Freescout updatet? +- Check: Polling Interval (2 Min)? + +### Workflow C speichert nicht in KB +- Check: Milvus läuft? +- Check: Embedding generiert? + +## Logs + +```bash +# n8n Logs +docker-compose logs -f n8n + +# PostgreSQL +docker-compose exec postgres psql -U kb_user -d n8n_kb -c "SELECT * FROM workflow_executions LIMIT 10;" + +# Milvus +docker-compose logs -f milvus +``` +``` + +- [ ] **Step 3: Commit** + +```bash +git add docker-compose.override.yml docs/MONITORING.md +git commit -m "infra: logging and monitoring setup" +``` + +--- + +### Task 4.3: Production Dokumentation & Go-Live Checklist + +**Files:** +- Create: `docs/DEPLOYMENT.md` +- Create: `docs/GO-LIVE-CHECKLIST.md` + +- [ ] **Step 1: Schreibe Deployment Guide** + +`docs/DEPLOYMENT.md`: + +```markdown +# Deployment Guide + +## Prerequisites + +- Docker & Docker Compose installed +- Freescout API Key +- Baramundi API Access +- PostgreSQL Backup Strategy + +## Deployment Steps + +1. Clone Repository +2. Setup .env (siehe .env.example) +3. Run Docker Services: `docker-compose up -d` +4. Run DB Schema: `sql/01-audit-schema.sql` +5. Setup Freescout Custom Fields: `bash scripts/setup-freescout-fields.sh` +6. Import n8n Workflows (manual via n8n UI) +7. Run E2E Tests: `bash tests/curl-test-collection.sh` +8. Enable Workflows (schalte alle 3 Workflows an) + +## Monitoring + +See docs/MONITORING.md + +## Rollback + +1. Deaktiviere alle n8n Workflows +2. Lösche PostgreSQL Daten (optional) +3. Setze KB zurück (optional) +``` + +- [ ] **Step 2: Go-Live Checklist** + +`docs/GO-LIVE-CHECKLIST.md`: + +```markdown +# Go-Live Checklist + +## 1 Week Before + +- [ ] E2E Tests durchgeführt (alle ✓) +- [ ] Staging Environment getestet +- [ ] Team Training abgeschlossen +- [ ] Backup-Strategie definiert + +## Go-Live Day + +- [ ] Alle Docker Services laufen +- [ ] All n8n Workflows aktiv +- [ ] Monitoring Dashboard aktiv +- [ ] Backup vor Go-Live + +## Während Launch + +- [ ] Monitor n8n Logs +- [ ] Monitor Freescout +- [ ] Monitor Baramundi Job Queue +- [ ] Alert System aktiv + +## Nach 24h + +- [ ] KI-Vorschläge angezeigt? +- [ ] Approvals funktionieren? +- [ ] Jobs werden ausgelöst? +- [ ] KB wächst? + +## Nach 1 Woche + +- [ ] Statistiken: Wie viele Mails verarbeitet? +- [ ] Wie viele Approvals? +- [ ] Wie viele Baramundi Jobs? +- [ ] Feedback vom Team sammeln +``` + +- [ ] **Step 3: Commit** + +```bash +git add docs/DEPLOYMENT.md docs/GO-LIVE-CHECKLIST.md +git commit -m "docs: deployment and go-live documentation" +``` + +--- + +### Task 4.4: Final Testing & Acceptance + +- [ ] **Step 1: Führe alle E2E Tests durch** + +```bash +bash tests/curl-test-collection.sh +``` + +- [ ] **Step 2: Teste mit echtem Ticket (Staging)** + +Erstelle Test-Ticket in Freescout: +- Subject: "Test: Drucker funktioniert nicht" +- Body: "Fehlercode 5" + +Überwache 15 Min: +- Mail analysiert? +- KI-Vorschlag angezeigt? +- Approve Vorschlag +- Job ausgelöst oder Email gesendet? +- KB aktualisiert? + +- [ ] **Step 3: Dokumentiere Ergebnisse** + +Wenn alles ✓: Go-Live bereit! + +- [ ] **Step 4: Final Commit** + +```bash +git add . +git commit -m "feat: AI-support-automation MVP complete and tested" +``` + +--- + +## Summary + +✅ **Phase 1:** Milvus + PostgreSQL + Freescout Custom Fields +✅ **Phase 2:** Workflow A (Mail Processing) + Workflow B (Approval) + Workflow C (KB Update) +✅ **Phase 3:** E2E Testing + Monitoring +✅ **Phase 4:** Production Ready + +**Status:** Bereit für Implementation via `superpowers:subagent-driven-development` oder `superpowers:executing-plans` + +--- + +## Next Steps + +🚀 **Sollen wir starten?** +- Wenn ja: Nutze `superpowers:executing-plans` um den Plan zu implementieren +- Wenn nein: Änderungen an Plan vornehmen diff --git a/docs/superpowers/specs/2026-03-16-ai-support-automation-design.docx b/docs/superpowers/specs/2026-03-16-ai-support-automation-design.docx new file mode 100644 index 0000000000000000000000000000000000000000..e5fce1eee946b9cabaedf900f09268efa6300e1f GIT binary patch literal 18031 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

E=Ag9a{*oAk+yzfTtx5WL(-=jhq&O&y+Iwk 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 literal 0 HcmV?d00001 diff --git a/docs/superpowers/specs/2026-03-16-ai-support-automation-design.md b/docs/superpowers/specs/2026-03-16-ai-support-automation-design.md new file mode 100644 index 0000000..1c81db9 --- /dev/null +++ b/docs/superpowers/specs/2026-03-16-ai-support-automation-design.md @@ -0,0 +1,364 @@ +# AI-gestützte IT-Support-Automatisierung mit Wissensdatenbank + +**Datum:** 2026-03-16 +**Status:** Design-Phase abgeschlossen, zur Implementation bereit +**Autor:** Team + +--- + +## 1. Problemstellung & Ziel + +**Problem:** Manuelle IT-Support-Tickets in Freescout erfordern manuelle Bearbeitung. Viele wiederkehrende Probleme könnten automatisiert werden, aber lokales KI-Modell ist noch nicht vollständig vertrauenswürdig. + +**Ziel:** Ein Hybrid-System aufbauen, das: +- Eingehende Mails analysiert mit lokalem LLM +- Lösungsvorschläge macht (automatische Behebung oder Baramundi-Job) +- **Mensch genehmigt alle Actions** (Approval-Gate) +- Eine selbstlernende Wissensdatenbank aufbaut und nutzt +- Mit der Zeit immer bessere Vorschläge macht + +**Success-Kriterium:** +- ✅ Mindestens 50% der Tickets werden von KI erkannt +- ✅ Mensch kann innerhalb Freescout approven/rejecten +- ✅ Genehmigt → automatische Ausführung (Baramundi oder Antwort) +- ✅ KB wächst mit jeder genehmigten Lösung + +--- + +## 2. Architektur-Übersicht + +### Komponenten & Technologien + +| Komponente | Technologie | Grund | +|---|---|---| +| **Orchestrierung** | n8n (Docker) | bereits vorhanden, robust | +| **Mail-Quelle** | Freescout API (https://ekshelpdesk.fft-it.de) | direkter API-Zugriff | +| **KI-Engine** | LiteLLM API (http://llm.eks-ai.apps.asgard.eks-lnx.fft-it.de/v1/chat/completions) | lokales, OpenAI-kompatibles Modell | +| **Vector Database** | Milvus oder Weaviate (Docker) | semantische Suche für KB | +| **Knowledge Base** | Vector Embeddings + Metadaten | Problem → Kategorie → Lösung → Häufigkeit | +| **Job-Execution** | Baramundi Management Server API | IT-Jobs auslösen | +| **Approval-UI** | Freescout Notes + Custom Field | Mensch genehmigt direkt in Freescout | +| **Optional Storage** | PostgreSQL (Docker) | Audit Trail, History, Metadaten | + +### System-Datenfluss + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ 1. MAIL-INGESTION & KI-ANALYSE │ +└─────────────────────────────────────────────────────────────────┘ + Freescout (neue Mails) + ↓ + n8n Polling Workflow (alle 5 Min) + ↓ + [Für jedes neue Ticket] + ├→ Vector DB Query: "Ähnliche Probleme finden?" + ├→ LLM-Call mit Mail + KB-Context + ├→ Parse KI-Response + └→ Speichere Vorschlag in Freescout (Note + Custom Field) + +┌─────────────────────────────────────────────────────────────────┐ +│ 2. HUMAN APPROVAL (Mensch-in-the-Loop) │ +└─────────────────────────────────────────────────────────────────┘ + Freescout Ticket zeigt KI-Vorschlag + ↓ + Support-Mitarbeiter liest Vorschlag + ↓ + [Approve] oder [Reject] geklickt + ↓ + Custom Field "AI_SUGGESTION_STATUS" = "APPROVED" / "REJECTED" + +┌─────────────────────────────────────────────────────────────────┐ +│ 3. EXECUTION & KB-UPDATE │ +└─────────────────────────────────────────────────────────────────┘ + n8n Webhook triggert bei Field-Änderung + ├→ Branching: + │ ├─ Baramundi-Job? → Baramundi API Call + │ └─ Automatische Antwort? → Mail/Antwort senden + └→ Bei Success: Lösung in Vector DB speichern + ├─ Generiere Embedding + ├─ Speichere [Problem | Kategorie | Lösung | Häufigkeit] + └─ Update bestehende KB-Einträge (Häufigkeit++) +``` + +--- + +## 3. Workflows (n8n) + +### Workflow A: Mail-Processing & KI-Analyse + +**Trigger:** Cron (alle 5 Minuten) + +**Schritte:** + +1. **Freescout API:** Hole neue, unverarbeitete Tickets + - Endpoint: `GET /api/conversations?status=active&limit=20` + - Filter: `processed_by_ai == false` + +2. **Für jedes Ticket:** + - Extract Mail-Inhalt: `subject`, `body`, `customer_email` + - **Vector DB Query:** Suche semantisch ähnliche Probleme aus KB + - Query: `subject + first 500 chars of body` + - Return: Top 3 Ergebnisse mit Kategorie + Lösung + +3. **LLM-Call** mit: + ```json + { + "system": "Du bist IT-Support-Assistent. Analysiere das Ticket und nutze die KB.", + "user_content": { + "ticket": { "subject": "...", "body": "..." }, + "similar_kb_entries": [ {...}, {...}, {...} ] + } + } + ``` + +4. **Parse Response** (JSON): + ```json + { + "kategorie": "Hardware|Software|Account|Netzwerk|Sonstiges", + "problem_verstanden": "Kurze Zusammenfassung", + "lösung_typ": "BARAMUNDI_JOB | AUTOMATISCHE_ANTWORT | ESKALATION", + "baramundi_job": { + "name": "Job-Name", + "parameter": { "..." } + }, + "antwort_text": "Kundenfreundliche Antwort für Mail...", + "vertrauen": 0.75, + "begründung": "Dieses Problem ist in KB vorhanden..." + } + ``` + +5. **Filter nach Vertrauen:** + - Wenn `vertrauen >= 0.6`: Vorschlag in Freescout speichern + - Wenn `vertrauen < 0.6`: Als "ESKALATION" markieren + +6. **Speichere Vorschlag in Freescout:** + - Note (für Mensch zu lesen): + ``` + [KI-VORSCHLAG] + Kategorie: Hardware + Lösung: Baramundi-Job "Drucker-Treiber-Update" + Vertrauen: 75% + Begründung: ... + ``` + - Custom Field `AI_SUGGESTION`: JSON serialisiert + - Custom Field `AI_SUGGESTION_STATUS`: "PENDING" + +7. **Markiere Ticket:** `processed_by_ai = true` + +--- + +### Workflow B: Approval & Execution + +**Trigger:** Freescout Custom Field `AI_SUGGESTION_STATUS` geändert + +**Schritte:** + +1. **Validiere:** Status ist "APPROVED" oder "REJECTED" + +2. **Wenn REJECTED:** + - Log in PostgreSQL: `{ticket_id, rejected_at, reason}` + - Notify Mensch (optional): "KI-Vorschlag wurde abgelehnt" + - **STOP** + +3. **Wenn APPROVED:** + - Hole KI-Vorschlag aus Custom Field + - Parse `lösung_typ` + +4. **Branching:** + + **A) Wenn `lösung_typ == "BARAMUNDI_JOB"`:** + - Call Baramundi API: + ``` + POST /api/jobs + { + "name": "...", + "parameter": {...} + } + ``` + - Speichere Job-ID in Freescout + - Schreibe Reply-Note: "✅ Baramundi-Job #123 ausgelöst" + + **B) Wenn `lösung_typ == "AUTOMATISCHE_ANTWORT"`:** + - Sende Email an Kunde: + ``` + To: customer_email + Subject: Re: [TICKET_SUBJECT] + Body: [antwort_text aus KI-Response] + ``` + - Schreibe Note in Freescout: "✅ Automatische Antwort gesendet" + - Markiere Ticket als gelöst + + **C) Wenn `lösung_typ == "ESKALATION"`:** + - Markiere für manuelles Review + - Notify Manager + +5. **Bei Success (A oder B):** + - Gehe zu Workflow C (KB-Update) + +--- + +### Workflow C: Knowledge Base Update + +**Trigger:** Nach Workflow B bei Success + +**Schritte:** + +1. **Extracte Info:** + - Problem-Text: `subject + body` + - Kategorie: aus KI-Response + - Lösung: `antwort_text` oder `baramundi_job.name` + - Timestamp: now + +2. **LLM-Embedding generieren:** + - Call LLM API: `/v1/embeddings` + - Input: `category + problem_text` + - Output: `embedding` (vector) + +3. **Vector DB Insert:** + ```json + { + "id": "uuid()", + "problem_text": "Drucker funktioniert nicht", + "kategorie": "Hardware", + "lösung": "Treiber neu installiert via Baramundi", + "häufigkeit": 1, + "embedding": [0.123, -0.456, ...], + "timestamp": "2026-03-16T10:30:00Z", + "baramundi_job_id": "123" (optional), + "freescout_ticket_id": "999" + } + ``` + +4. **Update bestehende KB-Einträge:** + - Query Vector DB: "Finde ähnliche Probleme" + - Für jeden Hit mit Similarity > 0.85: + - `häufigkeit++` + - Update `last_used_at` + +5. **Log in PostgreSQL:** + - `knowledge_base_updates` Tabelle + - Track: wann, was, von welchem Ticket + +6. **Cleanup (optional):** + - Einmal pro Woche: Archiviere alte Einträge (> 1 Jahr, häufigkeit = 0) + +--- + +## 4. Data Structures + +### Freescout Custom Fields (zu erstellen) + +``` +1. AI_SUGGESTION (Text/JSON) + - Speichert KI-Vorschlag als JSON + +2. AI_SUGGESTION_STATUS (Dropdown) + - Werte: PENDING, APPROVED, REJECTED, EXECUTED + +3. PROCESSED_BY_AI (Boolean) + - Markiert ob Mail schon analysiert wurde +``` + +### Vector DB Schema (Milvus/Weaviate) + +```json +{ + "id": "uuid", + "problem_text": "string", + "kategorie": "string", + "lösung": "string", + "häufigkeit": "integer", + "embedding": "vector[1024]", + "timestamp": "datetime", + "freescout_ticket_id": "integer", + "baramundi_job_id": "string (optional)" +} +``` + +### PostgreSQL Schema (optional, für Audit Trail) + +```sql +CREATE TABLE knowledge_base_updates ( + id UUID PRIMARY KEY, + ticket_id INTEGER, + problem_text TEXT, + kategorie VARCHAR, + lösung TEXT, + created_at TIMESTAMP, + approved_at TIMESTAMP, + executed_at TIMESTAMP, + status VARCHAR -- APPROVED, REJECTED, EXECUTED +); + +CREATE TABLE kb_feedback ( + id UUID PRIMARY KEY, + kb_entry_id UUID REFERENCES milvus, + feedback VARCHAR -- helpful, not_helpful + created_at TIMESTAMP +); +``` + +--- + +## 5. Sicherheit & Governance + +### Mensch-in-the-Loop + +- ✅ **Keine automatische Ausführung:** Jede Aktion benötigt manuellen Approval +- ✅ **Vertrauen-Scoring:** Nur Vorschläge mit `vertrauen >= 0.6` werden angezeigt +- ✅ **Audit Trail:** Alle Decisions werden gelogged (wer, wann, was) +- ✅ **Rejection-Tracking:** Abgelehnte Vorschläge werden analysiert → Modell-Improvement + +### Fehlerbehandlung + +- **LLM-Timeout:** Fallback auf "ESKALATION" +- **Baramundi-API-Fehler:** Retry 3x, dann manuelles Review +- **Vector DB Down:** Ignoriere KB-Context, nutze LLM ohne Context +- **Mail-Parsing-Fehler:** Markiere Ticket, notify Mensch + +--- + +## 6. Phasen & Rollout + +### Phase 1: MVP (Woche 1-2) +- ✅ n8n Workflows A (Mail-Processing) + B (Approval) einrichten +- ✅ Freescout API Integration testen +- ✅ LiteLLM Integration testen +- ✅ Manuelle Approval-Flow testen + +### Phase 2: KB Integration (Woche 3) +- ✅ Milvus in Docker deployen +- ✅ Workflow C (KB-Update) einrichten +- ✅ Vector DB Query in Workflow A integrieren + +### Phase 3: Production (Woche 4+) +- ✅ Monitoring + Alerting +- ✅ KB-Cleanup-Jobs +- ✅ Reporting + Analytics + +--- + +## 7. Success Metrics + +| Metrik | Ziel | Messung | +|---|---|---| +| **Mail-Erkennungsrate** | > 50% | (processed_by_ai = true) / total_tickets | +| **Approval-Rate** | > 70% | approved / total_suggested | +| **Baramundi-Job-Success** | > 90% | successful_jobs / total_jobs | +| **KB-Größe** | > 100 Einträge | count(*) from vector_db | +| **Häufigkeits-Improvement** | > 20% weniger Manual-Work | manual_processing_time t1 vs t2 | + +--- + +## 8. Offene Fragen & Next Steps + +- [ ] Welche Baramundi-Jobs sind verfügbar? +- [ ] Freescout API-Key vorhanden? +- [ ] LiteLLM API-Key/Auth Setup? +- [ ] PostgreSQL für Audit Trail gewünscht oder Optional? +- [ ] Milvus oder Weaviate bevorzugt? +- [ ] Wie oft soll KB-Cleanup laufen? + +--- + +**Status:** Bereit für Implementation Plan