AI RAS Quality Control Plan - 2026-07-10¶

Obiettivo¶

Usare l'AI locale SafeOps per controllare un RAS prima della finalizzazione o consegna, senza modificare automaticamente dati, immagini, checklist, categorie o documenti.

Perimetro iniziale:

tenant produzione: tenant_safecondo, tenant_besant;
utenti pilota: Emma per RAS/documentale, Jeme solo formazione;
modello AI locale Ollama;
storage MinIO come sorgente file;
DB SafeOps come sorgente verita' per tenant, cliente, documento, risposte, gallery e audit.

Cosa Si Puo' Controllare¶

Testo¶

errori ortografici evidenti;
frasi incomplete o troppo generiche;
contraddizioni tra risposta, nota e stato della domanda;
risposte mancanti su sezioni obbligatorie;
linguaggio non tecnico o non professionale;
incongruenze tra conclusione e dettaglio.

Concetto¶

risposta positiva con note che descrivono una criticita';
risposta negativa senza misura correttiva;
rischio indicato ma senza evidenza;
non conformita' citata ma non collegata a scheda NC;
documento checklist citato ma non presente tra i documenti autorizzati;
categoria RAS incoerente con il contenuto.

Foto¶

Nella prima fase il controllo deve essere metadata-first:

foto mancanti dove la domanda le richiede;
numero foto superiore ai limiti della domanda/gallery;
foto local:* non sincronizzate;
foto senza didascalia o contesto;
immagine non apribile da MinIO;
duplicati evidenti per stessa domanda;
mapping ambiguo tra foto e domanda.

Il controllo visuale reale, cioe' "la foto mostra davvero quello che dice la risposta", richiede un modello vision o una pipeline OCR/immagine dedicata. Va abilitato solo dopo test su dati pilota, per evitare falsi positivi in produzione.

Modalita' Operativa Sicura¶

Il controllo AI deve produrre solo un report:

ok;
warning;
errore_bloccante;
motivazione;
azione consigliata;
riferimenti a documento, domanda, sezione, foto o allegato.

Non deve:

correggere testi automaticamente;
sostituire foto;
spostare immagini;
cambiare categorie;
finalizzare o bloccare definitivamente un RAS senza conferma umana;
leggere documenti/clienti non autorizzati per l'utente.

Primo Flusso Consigliato¶

L'utente apre un RAS autorizzato.
Clicca Controllo qualita' AI.
Backend verifica tenant, utente, cliente e documento con lo stesso perimetro documentale gia' usato dall'AI retrieval.
Backend estrae solo struttura RAS, risposte, note, riferimenti gallery e metadati MinIO.
AI genera report testuale.
Report salvato come audit o mostrato in preview.
L'utente decide se correggere manualmente.

Livelli Di Severita'¶

Livello	Uso
`info`	suggerimento migliorativo non necessario
`warning`	possibile incoerenza da verificare
`errore_bloccante`	problema che dovrebbe fermare finalizzazione o consegna

Esempi di errore bloccante:

immagine local:* ancora presente;
foto richiesta ma assente;
documento non apribile da MinIO;
domanda obbligatoria senza risposta;
mapping immagine ambiguo su sezione critica;
utente non autorizzato al documento.

Decisione Tecnica¶

Partire con un servizio backend dedicato, separato dal semplice chat gateway:

ai_retrieval: ricerca documenti autorizzati;
futuro ai_ras_quality: controllo qualita' RAS autorizzato;
nessuna chiamata diretta del modello al DB;
nessun accesso diretto del modello a MinIO;
payload costruito dal backend e ridotto ai soli dati necessari.

Prossimo Step¶

Implementare una prima API read-only:

input: documento_id;
controlli: tenant, utente, documento autorizzato;
output: report JSON con problemi testuali/strutturali metadata-first;
niente analisi vision nella prima versione;
niente scrittura DB nella prima versione, salvo eventuale audit se richiesto.

Implementazione Fase 1 - 2026-07-10¶

Creato il primo servizio read-only:

servizio: app/services/ai_ras_quality.py;
endpoint: POST /api/ai/ras-quality;
input accettato: documento_id o document_id;
accesso consentito solo se AI abilitata per tenant e utente;
il documento viene risolto tramite perimetro documentale autorizzato;
se il documento non e' autorizzato o non e' RAS, non viene analizzato.

Controlli implementati:

documento RAS riconosciuto da payload ras_master, document_kind, service_code, legacy_service_code, source_table;
presenza risposte RAS;
risposte negative/critiche con dettaglio troppo debole;
risposte positive con note critiche;
testi molto brevi;
gallery item senza key;
riferimenti local:*;
foto senza didascalia;
foto duplicate;
chiavi immagine non presenti in stored_files.

Output:

status: ok, warning, errore_bloccante;
summary;
issues;
scope: ras_quality_metadata_text_only.

Verifiche:

test gateway AI passati: 10;
compilazione sintattica di gateway e servizio RAS quality eseguita.

Integrazione Incarichi Tecnici - 2026-07-10¶

Aggancio operativo:

aggiunto pulsante Controllo AI nella colonna RAS degli incarichi tecnici;
il pulsante compare solo per incarichi da richiesta RAS con documento compila esistente e risposte/bozze presenti;
il pulsante non compare per RAS gia' completati, consegnati o chiusi;
il pulsante rispetta configurazione AI per tenant e utente;
la lista incarichi chiama POST /api/ai/ras-quality e mostra il report in modale.

Il controllo resta read-only:

nessuna modifica a risposte;
nessuna finalizzazione;
nessuna scrittura su MinIO;
nessun blocco automatico della chiusura.

Verifiche:

compilazione sintattica di app/modules/commerciale/models.py;
test gateway AI passati: 10.