Legacy RAS JSON Import Strategy¶

Obiettivo¶

Importare checklist RAS legacy da JSON nel motore RAS dinamico attuale, mantenendo: - editabilita del documento da parte dell'amministratore - compatibilita con compila - conservazione degli allegati storici originali

Il perimetro stimato e di circa 50 casi della stessa famiglia JSON.

Decisione Architetturale¶

Non introdurre un motore separato solo per i legacy.

Scelta: - 1 template dynamic legacy-import dedicato a questa famiglia JSON - N documenti/istanze importate che usano quel template - 1 importer batch che legge i JSON e porta dati + immagini + allegati nel sistema corrente

Questo consente: - apertura in compila - modifica successiva del documento - ristampa/esportazione - governance coerente con il resto del progetto

Stato Attuale¶

Freeze operativo del ramo legacy RAS¶

Il ramo compila dei RAS legacy importati e' attualmente da considerare freeze.

Motivo: - e' stato riallineato per far combaciare correttamente: - struttura sezioni legacy importate - qid legacy - risposte salvate - draft runtime - il problema risolto era specifico dei documenti ras_json_v1 legacy importati, mentre i RAS nativi gia' funzionavano correttamente

Regola pratica: - non modificare il mapping legacy risposte/sezioni senza un bug reale riproducibile - non toccare il builder legacy solo per refactoring estetici o uniformita' col ramo nativo - ogni intervento futuro sul legacy deve partire da un caso documentato con: - doc_id - tenant - sezione/domanda coinvolta - differenza osservata tra dati salvati e render a video

In assenza di bug reale: - il ramo legacy RAS non va modificato

Regola Import V2¶

Il template legacy non va piu riusato in modo condiviso tra casi diversi.

Regola operativa: - 1 caso legacy = 1 legacy_model_id dedicato

Il comando CLI legacy_ras_json_import ora supporta questa modalita' direttamente: - se non passi --model-id - il sistema calcola un model_id dedicato e stabile a partire dal token identitario del caso (uid_unico o nome file)

Questo evita la sovrascrittura della struttura sezioni tra casi importati diversi.

Input Disponibili¶

Per ogni caso legacy sono presenti: - JSON completo di compilazione - cartella immagini legacy (folder_image) - PDF master e PDF schede - talvolta docx - zip storico Minnovi

Struttura JSON osservata¶

Il JSON contiene tipicamente: - testata documento: - nome_documento - descrizione - tecnico - tecnico_anagrafica - cliente - modello - id_univoco - data_creazione - data_chiusura - folder_image - dati_inseriti[]

Ogni elemento di dati_inseriti[] contiene: - id_scheda - nome_scheda - descrizione_scheda - padre - domande[] - fattori_rischio[] - total_domande - risposte_date

Domande standard¶

Ogni domanda standard contiene tipicamente: - id_domanda - testo_domanda - risposta - risultato - rischio - categoria_rischio - evidenza_riscontrata - misure_miglioramento - image[]

Fattori rischio¶

Ogni fattore rischio contiene: - id_fattore_rischio - nome_fattore_rischio - domande_rischio[]

Ogni domanda_rischio contiene: - id_domanda_rischio - testo_domanda_rischio - risposta - valore_rischio - note

Modello Target¶

Template unico¶

Creare un template dynamic dedicato, ad esempio: - RAS Legacy Import

Il template va costruito per accogliere la struttura completa della famiglia legacy: - schede principali - sottoschede - domande standard - fattori rischio

Documento importato¶

Per ogni JSON legacy importato creare: - un documento/istanza nel motore RAS corrente - una bozza/istanza completa con risposte gia valorizzate - allegati storici collegati

Mapping Dati¶

1. Gerarchia schede¶

Mapping: - dati_inseriti[].padre == null -> sezione root - dati_inseriti[].padre != null -> sezione child della sezione con id_scheda = padre

Label sezione: - preferire descrizione_scheda - fallback su nome_scheda

Codici: - generati deterministicamente da id_scheda + slug titolo

2. Domande standard¶

Ogni domanda legacy diventa una domanda dynamic con: - label = testo_domanda - valore principale = risposta - detail payload: - risultato - rischio - categoria_rischio - evidenza_riscontrata - misure_miglioramento - image

Schema consigliato: - type: select - choices ampie: - Si - No - In attesa - eventuali altre risposte legacy normalizzate

Detail fields consigliati: - risultato text/select - rischio text/select - categoria_rischio text - evidenza_riscontrata textarea - misure_miglioramento textarea - image file multiplo

Nota: - se risposta legacy e Si/no minuscolo o varianti, normalizzare in fase import - mantenere comunque il raw originario in meta.legacy

3. Fattori rischio¶

Non mescolarli alle domande standard.

Scelta consigliata: - per ogni scheda, creare una sottosezione dedicata Fattori di rischio - per ogni domanda_rischio creare una domanda dynamic separata

Valore principale: - risposta

Detail fields: - valore_rischio - note

Questo mantiene la semantica leggibile e modificabile nel nuovo sistema.

4. Immagini¶

Le immagini referenziate in image[] vanno risolte rispetto a: - folder_image

Strategia: - cercare il file per nome esatto nella cartella del caso - caricarlo su MinIO tenant-aware - salvare la chiave oggetto nel payload risposta della domanda

Fallback: - se il file non esiste, segnare warning import ma non bloccare l'import complessivo

5. Allegati storici¶

Per ogni documento importato allegare anche: - JSON originale - zip originale Minnovi - Libretto_Compilato.pdf - eventuale Libretto_Compilato.docx - PDF schede tematiche

Questi file non sono la fonte primaria del dato editabile, ma il fallback storico.

Metadati legacy da conservare¶

Nel documento o nel payload meta.legacy_import salvare almeno: - legacy_source = ras_json_v1 - legacy_id_univoco - legacy_json_filename - legacy_folder_image - legacy_tecnico_id - legacy_tecnico_anagrafica - legacy_cliente_id - legacy_modello_id - legacy_data_creazione - legacy_data_chiusura

Questo consente audit e debug.

Batch Import¶

Strategia¶

Non creare 50 template.

Creare: - 1 template dynamic legacy-import - 50 documenti/istanze importate

Flusso batch consigliato¶

scansione cartella input
per ogni JSON:
validazione base formato
risoluzione immagini
costruzione payload sections/questions/answers
creazione documento/istanza
salvataggio risposte
upload allegati storici
log risultato

Idempotenza¶

Usare come chiave naturale: - id_univoco

Modalita Operative Importer¶

L'importer CLI supporta ora due modalita esplicite.

1. `document_only`¶

E la modalita standard e consigliata finche la catena commerciale non e definita in modo stabile.

Cosa fa: - crea o aggiorna il template dynamic target - importa struttura schede/sottoschede/domande - importa risposte legacy - carica immagini su storage - allega JSON/PDF/ZIP storici - crea il documento dynamic e lo collega al cliente indicato

Cosa non fa: - non crea amministratori commerciali - non collega l'amministratore al cliente - non assegna reti commerciali o reti gestione - non modifica i link commerciali del cliente

Quando usarla: - fase pilota - casi legacy ancora da verificare - quando un altro flusso/progetto sta ancora chiudendo la catena commerciale - import di massa da validare prima del go-live definitivo

Comando tipo:

FLASK_APP=app flask legacy_ras_json_import \
  --case-dir /path/caso_001 \
  --model-id 90001 \
  --cliente-id 22372 \
  --import-mode document_only

2. `with_commercial_links`¶

E la modalita da usare solo quando la governance commerciale e stata chiusa e gli ID di riferimento sono noti.

Cosa fa in piu: - puo creare il link commerciale_amministratore_cliente se manca - puo aggiornare i commerciale_cliente_servizio_link gia esistenti con: - rete_commerciale_id - rete_gestione_id

Limiti intenzionali: - non inventa servizi commerciali se il cliente non ne ha - non crea automaticamente rete commerciale o rete gestione - non prova a dedurre da solo l'amministratore corretto

Quando usarla: - solo dopo validazione del perimetro commerciale - solo con parametri espliciti - solo quando il cliente target e gia stato verificato

Comando tipo:

FLASK_APP=app flask legacy_ras_json_import \
  --case-dir /path/caso_001 \
  --model-id 90001 \
  --cliente-id 22372 \
  --import-mode with_commercial_links \
  --amministratore-id <ID_AMMINISTRATORE> \
  --rete-commerciale-id <ID_RETE_COMMERCIALE> \
  --rete-gestione-id <ID_RETE_GESTIONE>

Regola Batch Consigliata¶

Per il batch dei circa 50 casi la regola prudente e:

importare prima tutti i casi in document_only
verificare correttezza di:
cliente target
struttura importata
immagini
documento editabile
solo dopo, se serve, applicare gli agganci commerciali in un secondo passaggio

Questo evita di mischiare due problemi diversi: - migrazione documentale legacy - riallineamento commerciale/amministratore/reti

Dato Pilota Gia Validato¶

Caso validato: - file: doc_RAS_GARAGE NUOVA DARSENA_RAS_20250415_02ed3a3c.json - cliente target: #22372 Garage Nuova Darsena - documento creato: #380 - immagini caricate: 97 - immagini mancanti: 2

Le due immagini mancanti erano: - webcam_image_1744802266333.jpg - webcam_image_1744802678204.jpg

Il pilota ha confermato: - il mapping JSON -> RAS dinamico e corretto - il cliente/documento si collegano bene - la parte commerciale va trattata separatamente, non implicitamente durante il primo import

Decisione Operativa Attuale¶

Finche la catena: - rete commerciale - rete tecnica - amministratore - tecnici - documenti - RAS

non e consolidata, il batch legacy va eseguito in document_only.

Regola: - se id_univoco e gia importato, non reimportare automaticamente - opzionale --force-update solo per rerun controllati

Validazioni Import¶

Bloccare import solo per errori gravi: - JSON non parseabile - dati_inseriti assente o non lista - assenza totale di struttura importabile

Gestire come warning: - immagine mancante - scheda senza domande - risposte non normalizzabili - allegato storico mancante

Normalizzazioni consigliate¶

Risposte¶

Normalizzare varianti: - si, Si, SI -> Si - no, No, NO -> No - stringhe vuote -> ""

HTML/text¶

Campi come evidenza_riscontrata possono contenere HTML.

Scelta consigliata: - conservare il testo originale - opzionalmente sanitizzare HTML minimo

Rischio¶

rischio e valore_rischio vanno mantenuti come stringhe nel primo import.

Non forzare subito tassonomie se non sono stabili.

UI / Uso Post Import¶

Dopo l'import l'amministratore deve poter: - aprire il documento nel runtime attuale - vedere le schede migrate - vedere risposte e immagini - correggere testo e dettagli - aggiornare il documento - ristampare o riesportare

Cosa non fare¶

non creare un viewer legacy separato come percorso principale
non usare i PDF come fonte dati primaria
non tentare una migrazione cieca immagine -> domanda se il filename non combacia
non generare un template per ogni singolo caso

Piano di esecuzione consigliato¶

creare template RAS Legacy Import
costruire importer su 1 JSON pilota
verificare in UI:
struttura schede
risposte
immagini
editabilita
eseguire import su 3 casi campione
correggere mapping
lanciare batch sui restanti ~50 casi

Conclusione¶

La famiglia JSON osservata e abbastanza coerente per un import strutturato nel RAS dinamico.

La soluzione corretta e: - un unico template dynamic dedicato alla famiglia legacy - un importer batch - documenti importati editabili - allegati storici mantenuti come fallback