Runbook Chat Esterna

Obiettivo

Attivare la chat esterna in SafeOps in modo progressivo, tenant per tenant, senza toccare la chat ticket legacy.

Prerequisiti

• CHAT_INTEGRATION_ENABLED=True
• CHAT_SERVICE_BASE_URL configurato
• CHAT_WIDGET_BASE_URL configurato
• CHAT_HANDOFF_JWT_SECRET configurato
• CHAT_ENABLED_TENANTS valorizzato con i tenant da abilitare

Esempio:

CHAT_INTEGRATION_ENABLED=True
CHAT_ENABLED_TENANTS=tenant_safecondo,tenant_besant
CHAT_APP_ID=safeops-web
CHAT_SERVICE_BASE_URL=https://chat-service.example/api/v1
CHAT_WIDGET_BASE_URL=https://chat-widget.example
CHAT_HANDOFF_JWT_SECRET=<secret>
CHAT_HANDOFF_JWT_ALGORITHM=HS256
CHAT_HANDOFF_JWT_AUDIENCE=chat-service
CHAT_HANDOFF_JWT_ISSUER=safeops

Pilot consigliato iniziale solo su Besant:

CHAT_INTEGRATION_ENABLED=True
CHAT_ENABLED_TENANTS=tenant_besant
CHAT_APP_ID=safeops-web
CHAT_SERVICE_BASE_URL=<url-chat-service>
CHAT_WIDGET_BASE_URL=<url-chat-widget>
CHAT_HANDOFF_JWT_SECRET=<secret>
CHAT_HANDOFF_JWT_ALGORITHM=HS256
CHAT_HANDOFF_JWT_AUDIENCE=chat-service
CHAT_HANDOFF_JWT_ISSUER=safeops

Regola Multi-Tenant

Il token host viene emesso solo se il tenant effettivo e' risolto.

Identita' esterna sempre composta da: - tenant_id = effective_tenant_key() - app_id = safeops-web - external_user_id = current_user.id

Non esiste fallback a default.

Punti UI Attivi

La chat esterna e' montata oggi su: - Cliente - Ticket - Documento - Intervento - RAS - DVR

Note: - su Ticket convive con la chat legacy ticket - su RAS e DVR il mount e' nella pagina dynamic/compila - nelle viste piu' dense il pannello chat e' collassato di default

Attivazione Tenant

1. configurare CHAT_ENABLED_TENANTS
2. riavviare SafeOps
3. testare il tenant con un utente reale
4. verificare che l'handoff risponda 200
5. verificare che il widget apra la room corretta

Pilot Besant

Primo rollout consigliato: - abilitare solo tenant_besant - lasciare esclusi tenant_safecondo e altri tenant - fare collaudo completo su Besant prima di estendere l'allowlist

Checklist Besant: - Cliente: apertura widget - Ticket: apertura widget e convivenza con chat legacy - Documento: apertura widget dalla show - Intervento: apertura widget dal rapportino - RAS: apertura widget dal dynamic/compila - DVR: apertura widget dal dynamic/compila

Collaudo Minimo

Per ogni tenant abilitato controllare: - Cliente: apertura widget e room cliente corretta - Ticket: apertura widget senza rompere la chat legacy - Documento: apertura widget dalla show view - Intervento: apertura widget dal rapportino - RAS: apertura widget dal dynamic/compila - DVR: apertura widget dal dynamic/compila

Checklist Post-Attivazione

• handoff JWT ok
• exchange ok
• apertura widget ok
• room cliente deterministica
• isolamento tenant ok
• logout/login ok

Verifiche Funzionali

Controlli attesi: - tenant non risolto -> handoff rifiutato - tenant fuori allowlist -> handoff rifiutato - utente autenticato -> token host con claims coerenti - room key -> tenant/app/entity_type/entity_id

Test Backend

Comando:

cd /home/safeops/safeops && /root/.pyenv/versions/safeops/bin/python -m pytest -q tests/test_chat_integration.py

Atteso:

8 passed

Rollback

Rollback rapido: - mettere CHAT_INTEGRATION_ENABLED=False - oppure togliere il tenant da CHAT_ENABLED_TENANTS - riavviare SafeOps

Effetto: - il widget non si inizializza - l'endpoint handoff rifiuta la richiesta - la chat ticket legacy continua a funzionare

Cosa Non Toccare

• non rimuovere la chat ticket legacy
• non aggiungere persistenza messaggi in SafeOps
• non introdurre fallback tenant silenziosi
• non spostare logica chat nei moduli dominio

Escalation

Se il widget non si apre: 1. controllare feature flag 2. controllare tenant effettivo 3. controllare CHAT_SERVICE_BASE_URL e CHAT_WIDGET_BASE_URL 4. controllare che il microservizio chat accetti il JWT host