# 01 — Dizionario del master DVR TWISTER

Analisi esaustiva del file `-mat/07_DVR AGENZIE_TWISTER.xlsx` con l'obiettivo di avere una base dati completa per:
- dimensionare lo schema DB MySQL;
- dimensionare le ore di sviluppo nel preventivo;
- identificare le "combo uniche" richieste dal cliente e distinguerle da quelle già presenti;
- identificare tutti i dati di seed (lookup) da precaricare nel DB.

## Struttura del master — overview

Il master ha **13 fogli**. Sei sono "sezioni del DVR" (dati compilabili per-sede), quattro sono lookup/seed, uno è riferimento normativo (Legenda), uno contiene l'elenco reale delle sedi gestite da Twister.

| Foglio | Tipo | Righe×Cols | Merged | Cosa contiene |
|---|---|---|---|---|
| Copertina | Documento | 22×13 | 20 | Intestazione, sede, data, sommario revisioni |
| Dati | Documento | 80×14 | 25 | Anagrafica sede + descrizione immobile + planimetria |
| Pericoli | Documento | 108×7 | 26 | Checklist ~100 requisiti D.Lgs. 81/08 |
| Legenda | Riferimento | 47×12 | 36 | Matrice Probabilità × Gravità = Rischio |
| Valutazione | Documento | 64×8 | 49 | ~60 elementi di analisi con P, G, R=P×G, misure |
| Rischi | Documento | 86×3 | 74 | Tipologia rischi + piano emergenze + piano miglioramento |
| Incendio | Documento | 33×4 | 14 | Testo rischio incendio + elenco documentazione |
| Conclusione | Documento | 56×2 | 2 | Allegati (planimetria emergenza, luogo sicuro) |
| ListaF1 | Lookup | 232×8 | 0 | Catalogo combo/voci per foglio Pericoli |
| ListaF2 | Lookup | 148×5 | 0 | Catalogo combo/voci per foglio Valutazione |
| Lista F3 | Lookup | 51×6 | 0 | Zone sismiche + gradi rischio frane/alluvioni |
| Sismica | **Anagrafica reale** | 245×16 | 0 | **Elenco 240 sedi fisiche Alleanza gestite da Twister** |
| Categorie Protette | Lookup | 186×6 | 0 | Agenzie con lavoratori categorie protette |

> **Nota**: Il cliente parla di 800 file (600 xlsx + 200 docx). Il foglio Sismica ne elenca solo 240 con anagrafica: sono quelle in carico a Twister nel DVR. Le restanti (tipicamente Ispettorati Agenzia) probabilmente seguono template analogo ma non sono in questo master. **Chiedere al cliente** se l'elenco completo delle ~800 sedi esiste in un file master separato.

## Fogli-documento (dati per-sede) — dettaglio

### Copertina
Tre blocchi:
1. Testata fissa (titolo, riferimenti normativi) — **testo statico**, non va in DB.
2. `Sede:` nome agenzia + data emissione — **dipende da anagrafica**.
3. Tabella revisioni (Indice rev, Data, Descrizione, Preparato/Controllato/Approvato, Firma DL).

Campo | Tipo | Fonte
---|---|---
`nome_sede` | string | anagrafica
`data_emissione` | date | anagrafica/revisione
`revisioni[]` | array | non usato (scope escluso: niente versioning interno)

→ **Non serve tabella revisioni**. Se il cliente vuole mantenere la tabella "storico revisioni" nel PDF finale la generiamo solo con la revisione corrente (1 riga).

### Dati — Anagrafica
Il foglio ha una parte fissa di testo normativo (righe 1-18) e una parte dati per-sede:

Campo | Tipo | Note
---|---|---
`sede_nome` | string | es. "CITTA' CENTRO - agenzia"
`sede_tipo` | enum | `agenzia` \| `ispettorato`
`indirizzo` | string |
`piano` | enum/string | **combo editabile**: Terra, Rialzato, 1..8, "2, 3", "3, 4"
`citta` | string | (città)
`provincia` | string(2) | (es. PD, KR) — da Sismica
`datore_lavoro` | string | "Dott. Davide Passero" (valore costante per Alleanza? da confermare)
`rspp` | string | "Ing. Antonino Abate" (costante?)
`descrizione_immobile` | text | testo lungo libero, es. "L'agenzia si trova al 6° piano…"
`planimetria_sede_img` | file | immagine allegata (attualmente embed nell'xlsx)

> La "descrizione immobile" è l'unico campo testo libero di lunghezza importante; in Pericoli/Valutazione i testi sono sempre compilati via combo.

### Pericoli (la parte più corposa)
Tabella con colonne fisse: `RIF | REQUISITO | VERIFICA E COMMENTO | U | P | NOTE` (A-F).
Le righe sono ~100, numerate come 1.1.1, 1.1.2, 1.2.5, … corrispondenti all'Allegato IV del D.Lgs. 81/08.

**Semantica colonne**:
- `A` (RIF) → codice punto, es. `1.4.1`. Fisso nel master, **seed**.
- `B` (REQUISITO) → testo della norma. Fisso nel master, **seed** (≈100 stringhe).
- `C` (VERIFICA E COMMENTO) → compilabile; alcune sono **combo**, alcune sono testo libero, alcune richiamate da anagrafica.
- `D` (U = Uffici) → stato: `S` | `X` | `X ` (condominiale) | `-` | `N` | vuoto. **Enum di 5-6 valori**.
- `E` (P = Pertinenze) → stesso enum di D.
- `F` (NOTE) → **combo a voci multiple** o testo libero. La maggior parte delle "combo uniche" richieste dal cliente sono qui.

**Enum stati D/E**: `S` (verificato) · `X` (da verificare) · `X ` (da verificare condominiale) · `-` (non pertinente) · `N` (non verificato).

### Pericoli — le combo richieste (dalle note cliente + ListaF1)
Elenco puntuale dei punti che hanno combo e/o richiedono accorpamento nel gestionale:

Punto | Col | Tipo | Note
---|---|---|---
1.1.1 | C | combo 2 voci | doc acquisita / attività in corso
1.1.2 | C | combo 2 voci | salute struttura ok / danni strutturali
1.1.7 | F | combo 2 voci | zona rifiuti / no locali deposito
1.3.1 | C | combo C/N | Conforme / Non Conforme / Non Applicabile
1.3.1.2 | F | combo 1 voce | ventilazione meccanizzata
1.3.1.5 | F | combo 4 voci | gestione piano interrato / cantine
1.3.2 | F | combo SI/NO + testo dettagli dislivelli
1.3.6 / 1.3.7 | F | combo varie | condominio vetrofanie, serramenti vano scala
1.4.1 | C | **richiamo auto piano** dall'anagrafica | cliente lo chiede esplicito
1.4.1 | F | **combo unica nuova** | 4 varianti: strisce antiscivolo × ascensore
1.4.3 / 1.4.4 | C,F | combo percorsi misti pedonale/veicolare
1.4.9 / 1.4.11 | C | combo presenza buche/ostacoli
1.5.1 | B | **cella unica** come da allegato (richiesta cliente)
1.5.6 | C | **combo unica nuova** | 5 varianti apertura porta/bussola
1.5.6 | F | **combo unica nuova** | 3 varianti meccanico/elettrico
1.5.7 | F | **combo unica nuova** | combina apertura + via di fuga + scala antincendio
1.5.10 | C | combo 3 voci cartellonistica
1.5.11 | C | combo 2 voci illuminazione emergenza
1.5.14.3 | C | combo conformità parapetti
1.6.1 | F | combo 2 voci nottolini bagni
1.6.10 | F | **combo unica nuova** | 2 varianti vetrofanie serramento condominio
1.6.11 / 1.6.12 | C,F | combo pareti trasparenti
1.7.1.2 / 1.7.2 | C,F | combo descrizione parapetti scale
1.7.2.1 e sottopunti | C | **combo NA/C/NC** | 4+ sottopunti
1.9.1.1 / 1.9.1.2 / 1.9.1.3 | F | combo aerazione/ventilazione
1.9.2.1 | F | **combo unica nuova** | 3 varianti riscaldamento/raffrescamento
1.9.2.3 | F | combo 3 voci termosifoni
1.9.2.4 / 1.9.2.5 | F | combo tende + persiane
1.10.3 / 1.10.5 | F | combo illuminazione parti comuni
1.13.1.1 | F | combo a.c.s. presente/non presente
1.13.1.2 | F | combo autoclave condominio/assente
1.13.2.2 | F | combo numero addetti (1..10+)
1.13.3.2 | F | **combo unica nuova** | 6 varianti numero bagni
2.2.1 | F | combo stampanti idonee/vicine a postazioni
4.1.1 / 4.1.3 / 4.2.2 | C | combo C/N

**Totale combo distinte nel foglio Pericoli**: ~35 combo + ~5 combo "uniche nuove" da comporre.

### Valutazione
Tabella con colonne: `A=Elementi di analisi | B=Figure esposte | C=Rischi | D=Misure di prevenzione | E=P | F=G | G=R | H=Misure di miglioramento`.

30 elementi di analisi ricorrenti (stabilità, altezza, pavimenti, vie circolazione, vie emergenza, porte, scale, microclima, illuminazione, servizi igienici, caduta dall'alto, polveri, impianti elettrici/termici/idrici/gas, apparecchiature informatiche, elettrodomestici, prese, illuminazione, postazione lavoro, lavori solitario, MMC, gestanti, appalti, spazi confinati, disabili, categorie protette, stress, mobbing, rumore, vibrazioni, CEM, radiazioni ottiche, esplosioni, radiazioni ionizzanti, chimico, amianto, FAV, radon, biologico, legionellosi, cancerogeno, stupefacenti, alcolici).

**Comportamento colonne** (dalle note cliente):
- `D` (misure prevenzione): editabile, combo con anteprima → bianco dopo selezione.
- `E` (P = Probabilità): scala 0-4 (valori `0/1/2/3/4`), parte gialla → bianca dopo input. Combo 0-1-2-3-4.
- `F` (G = Gravità): scala 1-4, combo 1-2-3-4.
- `G` (R = Rischio): **campo calcolato, non editabile**, `R = P × G`. Codifica colore dal risultato via Legenda (1=molto basso/verde, 2-3=basso, 4-6=medio, 8-9-12-16=alto).
- `H` (Misure miglioramento): **multi-select con flag** (3-6 voci pre-scritte selezionabili a piacere), il cliente chiede di tornare cella gialla → bianca dopo selezione; doppia/tripla combo da fondere in UNA combo con flag.

Esempi di combo H (da ListaF2):
- SERRAMENTI ESTERNI AREE CONDOMINIALI: 3 opzioni con score (0-1-0), (1-1-1), (2-2-4)
- AERAZIONE: 3 opzioni
- RISCALDAMENTO/RAFFRESCAMENTO: 5 opzioni
- ILLUMINAZIONE: 4 opzioni
- GAS RADON: 3 opzioni
- SEDUTE: 2 opzioni
- BARRIERE ARCHITETTONICHE: 3 opzioni
- CATEGORIE PROTETTE: 3 opzioni
- ecc.

> **Nota**: le triple come "(1-2-4)" rappresentano già P-G-R della variante; quando l'operatore seleziona la voce da H, P e G di quella riga potrebbero essere **auto-popolate** (da confermare col cliente ma è evidentemente l'intenzione).

### Rischi
Tre sezioni distinte nello stesso foglio:

**Tipologia rischio** (4-5 righe fisse):
- Rischio sismico: zona X (enum da Lista F3: 1, 1A, 1B, 2, 2A, 2B, 3, 3A, 3B, 3S, 4, 4A, 4B)
- Rischio idrogeologico: SI/NO + sotto-righe Frane (AA, P1-P4) e Alluvioni (P1-P4)
- Rischio ambientale: SI/NO + sotto-righe free-text (Benzinai, Attività industriali, Linea Ferroviaria, …)

**Piano gestione emergenze**: testo semi-libero (~4 paragrafi standard che il cliente ha chiesto di sistemare perché oggi "non si legge").

**Piano di miglioramento**: tabella `Attività | Responsabile | Date avvio/conclusione`. ~25 righe di azioni standard tutte con `Responsabile = "Operation di rete - Alleanza Assicurazioni"` (precompilato richiesto).

### Incendio
Testo statico + tabella `Elenco documentazione` (18+ righe):
- Certificati: idoneità statica, agibilità, abitabilità, licenze edilizie, insegne, SCIA prevenzione incendi…
- Dichiarazioni conformità DM 37/2008: elettrici, idrici, termici, aeraulici, allarme, insegne
- Verifiche impianti: messa a terra, scariche atmosferiche

Per ciascuna: colonna B = stato (es. "In corso di reperimento", "Impianto non presente", "Acquisito"…) — **combo libera con valori tipici**.

Righe 18-23 (multi-riga): sottotabelle dei sottotipi di impianto. Il cliente ha chiesto di non perderle nell'import.

### Conclusione
Tabella allegati: `ALL. 1 - PLANIMETRIA DI EMERGENZA`, `ALL. 2 - INDICAZIONE LUOGO SICURO ESTERNO`. Gli allegati sono caricabili in anagrafica e vanno referenziati qui.

## Lookup e seed data

### ListaF1 (232 righe) — combo Pericoli
Struttura "a blocchi": ogni blocco inizia con il codice punto (es. `1.4.1`) e poi elenca le varianti possibili per le varie colonne.
Tutti i valori combo del foglio Pericoli sono qui dentro. **Da portare in DB come tabella `lookup_combo_pericoli`** (vedi schema DB, task 2).

### ListaF2 (148 righe) — combo Valutazione
Stessa logica per il foglio Valutazione. Ogni voce ha il suo score P-G-R tra parentesi (es. "(1-1-1)").

### Lista F3 (51 righe) — zone rischio
- Righe 1-13: zone sismiche (13 valori)
- Righe 18-24: rischio frane (6 livelli: NO, AA, P1, P2, P3, P4)
- Righe 27-31: rischio alluvioni
- Righe 6-15: date piano miglioramento (esempio cronologia)

### Sismica (240 righe) — anagrafica sedi
Questo è il foglio più prezioso per il seed anagrafica. Ha 240 sedi con:

Colonna | Campo DB
---|---
A | tipo (AG / IA + stato riapertura)
B | `codice_agenzia`
C | `ispettorato_regionale`
D | `nome_agenzia`
E | `ispettorato_agenzia`
F | `localita`
G | `provincia` (sigla)
H | `indirizzo`
I | `mq`
J | `piano`
K | `impresa_sopralluogo` (7 valori: TWISTER, MASTER IMPIANTI, FRACARO, CARLIN, VIGORITO, GENEROSO, COIS)
L | `tecnico_twister` (nome)
M | `zona_sismica`
N | `rischio_frane`
O | `rischio_alluvioni`
P | `rischio_ambientale` (può essere multi-valore: "PORTO E FERROVIA", "FERROVIA, BENZINAIO")

Distribuzioni (240 sedi):
- **Tipo**: 146 AG (agenzie generali), 94 IA (ispettorati)
- **Zone sismiche**: 3=75, 4=66, 2=56, 2B=12, 1=12, 3A=7, 3B=4, 3S=3, 2A=1
- **Frane**: NO=208, P1=12, AA=5, P3=3, P2=3, P4=1
- **Alluvioni**: NO=184, P1=22, P2=14, P3=11, P4=1
- **Ambientale**: NO=162, FERROVIA=33, BENZINAIO=21, PORTO=2, FARMACEUTICA=1, CENTRALE IDROELETTRICA=1, + combinazioni

→ Il rischio ambientale è **multi-valore**; nel DB una tabella ponte `sede_rischio_ambientale(sede_id, tipo)`.

### Categorie Protette (186 righe)
Elenco agenzie con lavoratori categoria protetta:
- `gruppo_categoria_protetta` (es. "Inv. civile")
- `agenzia_riferimento`
- `percentuale_disabilita` (opzionale)

## Campi calcolati / derivati

1. `Valutazione.R = P × G` — ricalcolato in app, mai scritto a mano.
2. Classificazione rischio (Molto Basso, Basso, Medio, Alto) — derivata da R via Legenda.
3. `Pericoli.C` punto 1.4.1: "L'ufficio si trova al X° piano" — **auto-popolato** da `anagrafica.piano`.
4. Data revisione su copertina — derivata dalla revisione corrente.

## Regole visive celle (dalle note cliente)

Colore cella = semantica. Non è cosmetica, è funzionale.

Colore | Significato | UI del gestionale
---|---|---
Bianco | Campo compilato / testo libero | input normale
Giallo | Campo da modificare (valore di default presente ma modificabile) | highlight giallo, torna bianco dopo edit
Grigio | Combo con anteprima, non ancora selezionata | highlight grigio, torna bianco dopo selezione
Verde | Valore fisso/derivato/default applicativo | background verde, readonly
Viola | Combo obbligatoria per comporre la pagina | highlight viola bloccante

In termini di React/Svelte: uno `status` per campo (`empty|default|selected|derived|required_empty`) che mappa su classi CSS.

## Relazioni tra fogli

- Ogni sezione documento (Copertina/Dati/Pericoli/Valutazione/Rischi/Incendio/Conclusione) appartiene allo stesso **dvr** (per una sede e una data emissione).
- I fogli Lista F1/F2/F3 sono riferimenti delle combo — non cambiano per-sede.
- Il foglio Sismica è il "registry" delle sedi.
- Il foglio Categorie Protette si collega alle sedi via `agenzia_riferimento`.

## Implicazioni per lo schema DB (anticipate qui, formalizzate in task 2)

Entità principali:
- `agenzie` (anagrafica + campi Sismica + riferimenti DL/RSPP/tecnici)
- `agenzie_categorie_protette` (many-to-many con lavoratore)
- `agenzie_rischi_ambientali` (many-to-many con tipi di rischio)
- `dvr` (record per sede con stato compilazione; uno-a-uno con `agenzie` se no revisioning)
- `dvr_pericoli` (un record per punto normativo compilato per sede, con `rif`, `col_C`, `col_D`, `col_E`, `col_F`)
- `dvr_valutazione` (un record per elemento analisi: `elemento`, `P`, `G`, `H_selezioni[]` in JSON o tabella ponte)
- `dvr_rischi` (sismico, frane, alluvioni, piano emergenze testo, …)
- `dvr_incendio_doc` (documentazione tecnica stato/note)
- `dvr_piano_miglioramento` (azioni standard + date avvio/conclusione)
- `dvr_allegati` (file upload: planimetria, luogo sicuro, foto, …)
- `lookup_combo_pericoli` (seed 232 righe → struttura per-codice-punto)
- `lookup_combo_valutazione` (seed 148 righe)
- `lookup_requisiti` (seed ~100 righe dei testi normativi fissi)
- `lookup_zone_sismiche`, `lookup_gradi_frane`, `lookup_gradi_alluvioni`, `lookup_rischi_ambientali`
- `utenti`, `ruoli` (developer, super_admin, admin)

Totale tabelle previste: **~15-18**.

## Dati aperti / domande al cliente

1. **Elenco completo 800 sedi**: esiste un file master con tutte (non solo le 240 Twister)? Se no, da dove tiriamo l'anagrafica per le ~560 rimanenti?
2. **Datore di lavoro / RSPP**: è sempre lo stesso per tutte le sedi Alleanza, o cambia per ispettorato regionale? Se è sempre lo stesso → campo costante nell'app, non per-sede.
3. **Planimetria di emergenza / luogo sicuro esterno**: il cliente le fornirà in batch come PDF/immagine, oppure sono da estrarre dagli xlsx esistenti (sono embed)?
4. **Piano emergenze — testo**: il cliente ha chiesto di "sistemarlo perché non si legge". Ha un testo standard di riferimento che possiamo usare?
5. **Misure miglioramento Valutazione (col. H)**: selezionando una variante, P e G della riga si auto-popolano dai valori tra parentesi (es. `(2-2-4)`)? **Da confermare** ma è quasi certamente così.
6. **Multi-valore rischio ambientale**: confermare che un'agenzia può avere più rischi contemporaneamente (il foglio lo suggerisce).
7. **Soft-delete sedi**: obbligo conservazione dati, quanti anni? (5? 10? indefinito?)

## Confronto con quanto già consegnato dal precedente fornitore
Dalle note RTF, i difetti specifici della soluzione precedente sono principalmente:
- combo troppo granulari, da fondere (abbiamo identificato quali: 1.4.1, 1.5.6, 1.5.7, 1.6.10, 1.9.2.1, 1.13.3.2);
- colore celle non coerente con lo stato (nostro sistema `status` risolve);
- testi illeggibili in Incendio/Piano emergenze (l'import nostro, a mano, li ricostruisce);
- sezione Incendio non importata (nel precedente risultava vuota);
- riga "Indicazione luogo sicuro esterno" mancante (va aggiunta nella sezione Allegati/Conclusione);
- "Responsabile" piano miglioramento non precompilato.

Tutti questi sono **correzioni di design applicativo** o di mappatura import. Non sono problemi di perimetro che allarghino le ore.