# Schema Livelli AI — NIS2 Agile
> Versione 1.0 — 2026-03-09
> Documento di architettura per l'evoluzione dell'integrazione AI nella piattaforma

---

## Overview

La piattaforma NIS2 Agile prevede 5 livelli progressivi di assistenza AI, ciascuno con un perimetro di conoscenza, accesso ai dati e vincoli di privacy distinti.

```
L1  Guida Piattaforma      →  Dati: nessuno             →  Tutti
L2  Assistente Operativo   →  Dati: sessione corrente    →  Tutti
L3  Assistente Aziendale   →  Dati: org corrente         →  Org-scoped
L4  Analisi Cross-Org      →  Dati: org multiple         →  Consultant / Super Admin
L5  Feed Normativo AI      →  Dati: pubblici/ACN         →  Tutti
```

---

## L1 — Guida Piattaforma
**"Cosa fa questa funzione?"**

### Scopo
Spiegare le funzionalità del software NIS2 Agile: come usare ogni modulo, cosa significano i campi, come interpretare i risultati.

### Dati in ingresso al modello
- Pagina corrente (es. `risks.html`)
- Domanda dell'utente
- **Nessun dato aziendale** — il prompt non include mai dati dell'organizzazione

### Perimetro risposta AI
- Spiegare interfaccia, workflow, pulsanti, campi
- Spiegare la normativa NIS2 in termini generali
- Non può rispondere su dati specifici dell'organizzazione

### Implementazione attuale
→ `HelpSystem` in `help.js` — già implementato (modale contestuale per pagina)
→ **Evoluzione**: aggiungere chat testuale basata su Claude API con contesto solo documentazione piattaforma

### Privacy
✅ **Nessun rischio** — zero dati personali o aziendali nel prompt

---

## L2 — Assistente Operativo
**"Come faccio a...?"**

### Scopo
Guidare l'utente nell'esecuzione di operazioni specifiche: "come compilo l'assessment?", "come classifico questo rischio?", "cosa devo scrivere nel campo X?".

### Dati in ingresso al modello
- Pagina corrente + stato del form (campo attivo, errori)
- Domanda dell'utente
- **Solo dati minimi di contesto** (es. "stai compilando il campo 'impatto' di un rischio")
- **No PII, no dati sensibili** dell'organizzazione

### Perimetro risposta AI
- Istruzioni operative step-by-step
- Suggerimenti contestuali sul campo corrente
- Best practice NIS2 per il dato che si sta inserendo

### Implementazione
→ **Da costruire**: chat widget flottante attivabile per pagina
→ Prompt di sistema: documentazione operativa + pagina corrente
→ Modello suggerito: `claude-haiku-4-5` (economico, bassa latenza)

### Privacy
✅ **Rischio basso** — includere solo tipo di form/campo, mai i valori inseriti

---

## L3 — Assistente Aziendale
**"Come siamo messi noi?"**

### Scopo
Rispondere a domande sui dati reali dell'organizzazione corrente: "quali sono i nostri rischi critici?", "cosa manca per completare il gap assessment?", "quali policy non sono ancora approvate?".

### Dati in ingresso al modello
- Dati aggregati dell'organizzazione corrente (stesso multi-tenancy JWT)
- Gap assessment: punteggi per categoria
- Risk register: numero e livelli rischi, trattamenti
- Policy: stato approvazione
- Training: % completamento
- **Dati anonimizzati**: nomi persone → ruoli, fatturato → range, nome org → settore+dimensione

### Perimetro risposta AI
- Analisi dello stato di compliance specifico dell'org
- Priorità di intervento personalizzate
- Raccomandazioni basate sui gap reali
- Previsioni di rischio

### Implementazione attuale parziale
→ `AIService.php` — `analyzeGapAssessment()`, `suggestRisks()`, `generatePolicy()`, `classifyIncident()` già implementati
→ **Evoluzione**: aggiungere endpoint conversazionale `/api/ai/chat` con contesto org anonimizzato

### Anonimizzazione applicata (già in AIService.php)
```php
// Già implementato:
- employeeRange(): dipendenti → range (micro/piccola/media/grande)
- settore → codice ATECO, NON nome azienda
- NO nome organizzazione nel prompt
- NO fatturato esatto (solo range)
- NO nomi di persone
```

### Privacy
⚠️ **Attenzione moderata**
- Dati limitati all'org dell'utente autenticato (multi-tenancy garantito da `requireOrgAccess()`)
- Anonimizzazione obbligatoria prima dell'invio ad Anthropic
- Log AI interaction in `ai_interactions` table per audit
- **GDPR**: dati inviati a Anthropic USA → DPA Agreement necessario (verificare contratto)

---

## L4 — Analisi Cross-Organizzazione
**"Come si confrontano i miei clienti?"**

### Scopo
Permettere a consulenti, CISO multi-cliente e super_admin di analizzare pattern, benchmark e confronti **aggregati e anonimi** tra organizzazioni diverse.

**Esempi di query valide:**
- "Qual è il gap medio nel settore sanità tra i miei clienti?"
- "Quali rischi sono più frequenti nelle PMI del settore energia?"
- "Benchmark: come si posiziona questo cliente rispetto agli altri?"

### Ruoli autorizzati
- `consultant` — solo le org di cui è membro (`user_organizations`)
- `super_admin` — tutte le org della piattaforma

### Dati in ingresso al modello
- **AGGREGATI**: medie, percentuali, distribuzioni — mai dati di singola org
- **ANONIMI**: organizzazioni identificate come "Org A", "Org B" — mai nome reale
- Settore e dimensione: consentiti (non identificativi singolarmente)
- **VIETATO**: nome org, P.IVA, referenti, incidenti specifici, dati PII

### Regola fondamentale
> **Un consulente NON deve mai poter ricostruire i dati di un'organizzazione specifica attraverso l'AI. Solo aggregati.**

### Implementazione
→ **Da costruire**: `AIService::crossOrgAnalysis()` con:
  - Query aggregata su DB (GROUP BY settore/dimensione)
  - Anonimizzazione labels prima del prompt
  - Filtro ruolo in `requireOrgAccess()` — verifica membership consultant
  - Endpoint: `POST /api/ai/cross-analysis` (solo `consultant`, `super_admin`)

### Privacy — CRITICO
🔴 **Alto rischio — implementare con cura**
- MAI passare org_id nel prompt
- MAI passare nomi, P.IVA, email nel prompt
- Aggregazione minima: almeno 3 organizzazioni per gruppo (k-anonymity)
- Audit log obbligatorio di ogni query cross-org (chi ha chiesto cosa, quando)
- **Consenso**: verificare se GDPR richiede consenso esplicito per analisi comparativa
- Il modello deve rispondere SOLO in forma aggregata — aggiungere istruzione nel system prompt:
  > "Non fornire mai dati riferibili a una singola organizzazione. Rispondi solo con statistiche aggregate."

---

## L5 — Feed Normativo AI
**"Cosa cambia con la nuova circolare ACN?"**

### Scopo
Aggiornamenti normativi automatici e analisi dell'impatto sulle organizzazioni: nuove circolari ACN, aggiornamenti DORA, modifiche D.Lgs. 138/2024, sentenze rilevanti.

### Dati in ingresso al modello
- Testo normativo (fonte pubblica: GU, ACN, EUR-Lex)
- Classificazione dell'organizzazione corrente (Essenziale/Importante/settore)
- **No dati interni** dell'organizzazione

### Perimetro risposta AI
- Riepilogo delle novità normative in linguaggio semplice
- Impatto specifico per tipo di soggetto NIS2 (Essenziale vs Importante)
- Scadenze e obblighi derivanti dall'aggiornamento
- Collegamento ai moduli della piattaforma da aggiornare

### Implementazione attuale
→ `NormativeController.php` — feed già implementato con ACK tracciato
→ **Evoluzione**: aggiungere `AIService::analyzeNormativeUpdate()` che:
  - Riceve il testo normativo
  - Genera riassunto + impatto per la classificazione dell'org
  - Suggerisce i controlli/policy da aggiornare

### Privacy
✅ **Nessun rischio significativo** — dati normativi pubblici + solo classificazione org (non identificativa)

---

## Matrice Riepilogativa

| Livello | Chi | Dati AI | Privacy | Stato |
|---------|-----|---------|---------|-------|
| **L1** Guida Piattaforma | Tutti | Nessuno | ✅ Safe | ✅ Implementato (help.js) |
| **L2** Assistente Operativo | Tutti | Contesto UI | ✅ Safe | 🔵 Da costruire |
| **L3** Assistente Aziendale | Utenti org | Dati org anonimizzati | ⚠️ Attenzione | ✅ Parziale (AIService) |
| **L4** Cross-Org Analysis | Consultant / Admin | Aggregati anonimi | 🔴 Alto | 🔵 Da costruire |
| **L5** Feed Normativo | Tutti | Testi pubblici | ✅ Safe | 🔵 Evoluzione normative |

---

## Principi Privacy Trasversali

1. **Data Minimization**: inviare ad Anthropic solo il minimo indispensabile
2. **Anonimizzazione sistematica**: nomi → ruoli, fatturati → range, org → settore+dim
3. **Audit trail**: ogni chiamata AI loggata in `ai_interactions` con timestamp, user, tipo
4. **Scope enforcement**: il layer PHP verifica sempre `requireOrgAccess()` prima di costruire il prompt
5. **No PII in prompt**: vietato nome persona, email, CF, P.IVA nel prompt
6. **K-anonymity per L4**: aggregare su minimo 3 org per evitare identificazione indiretta
7. **DPA Anthropic**: verificare Data Processing Agreement per trattamento dati EU

---

## Prossimi Sprint Suggeriti

| Priorità | Feature | Livello | Effort |
|----------|---------|---------|--------|
| Alta | Chat widget contestuale per pagina | L2 | 3 giorni |
| Alta | `POST /api/ai/chat` con contesto org | L3 | 2 giorni |
| Media | `analyzeNormativeUpdate()` per feed ACN | L5 | 1 giorno |
| Bassa | Cross-org benchmark per consultant | L4 | 5 giorni |

---

*Documento mantenuto da: Claude Code / Team NIS2 Agile*
*Aggiornare a ogni modifica architettura AI o normativa privacy*