# Piano AI per EasyForma

Stato: deciso il 15/09/2026. Principio: l'AI entra solo dove oggi l'ente fa lavoro manuale, lungo o soggetto a
errori; ogni proposta dell'AI è mostrata in anteprima e confermata dall'utente, mai applicata in silenzio.
Tutto ciò che è deterministico (codice fiscale, calcoli di ore, regole del Vademecum) resta codice normale:
l'AI si occupa di leggere testo disordinato e di scrivere testo per umani.

## 1. Dove l'ente perde tempo oggi

| Lavoro manuale                                                                                                   | Durata tipica      | Automazione                                                                                  |
| ---------------------------------------------------------------------------------------------------------------- | ------------------ | -------------------------------------------------------------------------------------------- |
| Ricopiare i discenti da email, PDF, Excel dell'agenzia in un CSV con le colonne giuste                           | 20–40 min per aula | **Import intelligente**: incolla qualsiasi elenco, l'AI lo trasforma in righe partecipante   |
| Ricavare data di nascita, sesso e comune di nascita per l'anagrafica Forma.Temp                                  | 2 min per discente | **Codice fiscale → anagrafica** (deterministico, nessuna AI)                                 |
| Creare a mano 10–20 lezioni con date e orari                                                                     | 10–15 min per aula | **Calendario da una frase**: "5 lezioni di 4 ore, martedì e giovedì dalle 9, dal 1° ottobre" |
| Controllare a fine lezione chi non ha raggiunto le ore, chi si è disconnesso, e scrivere la nota per il registro | 10 min per lezione | **Relazione di lezione**: anomalie calcolate + nota in italiano pronta per Forma.Temp        |
| Capire un errore restituito da FTWEB (`koMessages` criptici)                                                     | imprevedibile      | **Spiegazione dell'errore** in italiano con l'azione da fare                                 |
| Rispondere ai discenti su come si entra in aula                                                                  | continuo           | Testo di invito già chiaro (fatto); FAQ pubbliche (fatto)                                    |

Rimandati (valore più basso o dipendenze): trascrizione e riassunto delle registrazioni (richiede audio e consenso),
assistente chat sulla documentazione, controllo di conformità pre-consolidamento (arriva con l'integrazione FTWEB).

## 2. Architettura

```
app/Services/Ai/
├── AiClient.php               interfaccia: extract(schema, prompt, input) → array; write(prompt, input) → string
├── AnthropicAiClient.php      Messages API via Http (config ai.php), tool-use per output strutturato, retry 2
├── FakeAiClient.php           risposte deterministiche per dev/test (parser euristico + testi fissi)
├── AiServiceProvider.php      binding per driver (env AI_DRIVER=fake|anthropic)
├── AiUsage.php                log costo/token per company (tabella ai_usages)
└── Features/
    ├── ParticipantListParser.php   testo libero → righe {first_name,last_name,fiscal_code,email,phone,role}
    ├── SchedulePlanner.php         frase → lista di lezioni {title, scheduled_at, duration_minutes}
    ├── MeetingReportWriter.php     anomalie (deterministiche) + nota in italiano
    └── FormatempErrorExplainer.php koMessages → spiegazione + azione suggerita
app/Support/FiscalCode.php     parsing e validazione del codice fiscale (checksum, data, sesso, codice catastale)
```

Modelli: `claude-sonnet-5` per estrazione e scrittura, `claude-haiku-4-5-20251001` per la spiegazione errori.
Chiavi in `.env` (`ANTHROPIC_API_KEY`), mai per cliente. Ogni chiamata registra token e costo stimato in
`ai_usages` (company_id, feature, model, input_tokens, output_tokens, cost_cents) per monitorare i margini.
Limite per company: `ai.monthly_budget_cents` (default 500) oltre il quale le funzioni AI rispondono con un
messaggio chiaro invece di chiamare il modello.

Dati inviati al modello: solo il testo incollato dall'utente o i dati della lezione già in nostro possesso.
Niente credenziali, niente password Forma.Temp, niente registrazioni. Informativa aggiunta alla privacy policy.

## 3. Funzioni della prima consegna

1. **Import intelligente** — `POST /classrooms/{id}/participants/ai-parse` con `text` (max 20.000 caratteri):
   risposta JSON `{rows: [...], warnings: [...]}`; anteprima in una tabella modificabile; conferma con l'endpoint
   di import già esistente. Il parser fake gestisce righe "Cognome Nome CF email" separate da virgole/tab/spazi.
2. **Codice fiscale → anagrafica** — su creazione/import partecipante: valida il checksum, ricava `birth_date`,
   `gender`, `birth_place_code` (nuove colonne nullable su `participants`), segnala CF non validi come warning.
3. **Calendario da una frase** — `POST /classrooms/{id}/meetings/ai-plan` con `prompt`: propone lezioni entro i
   limiti dell'aula (ore massime, intervallo date); anteprima; conferma con `POST /classrooms/{id}/meetings/bulk`.
   Il planner fake interpreta "N lezioni di H ore, <giorni settimana> dalle HH, dal <data>".
4. **Relazione di lezione** — al termine della lezione (evento meeting ended) un job calcola le anomalie:
   partecipanti sotto il 100% e sotto il 75% delle ore, disconnessioni > 15 minuti, ingressi in ritardo > 10 minuti,
   docente assente; l'AI scrive la nota (≤ 600 caratteri) salvata in `meetings.ai_report` (json: anomalies, note,
   generated_at). Card "Relazione" sulla pagina lezione con "Rigenera" e copia negli appunti.
5. **Spiegazione errori Forma.Temp** — quando un `FormatempSync` fallisce, `FormatempErrorExplainer` produce
   `formatemp_syncs.explanation`; mostrata accanto all'errore.

## 4. Criteri di accettazione (spec `specs/ai-assistente.md`)

Vedi la spec: sei criteri verificabili con `AI_DRIVER=fake`, più test unitari con `Http::fake` sul client Anthropic.

## 5. Vetrina

Sezione "L'assistente che fa il lavoro noioso" sulla landing (dopo "Come funziona"), quattro righe requisito →
soluzione con lo stesso dispositivo grafico della sezione Conformità, una FAQ ("I dati dei discenti finiscono in
un modello AI?") e una riga nella tabella comparativa dei prezzi ("Assistente AI: incluso in tutti i pacchetti,
fino a N operazioni al mese"). Copy in `docs/marketing-copy.md` §6b.