# Flusso Completo di Utilizzo

## Flusso Operativo Completo

Questa guida descrive il flusso di lavoro completo, dall'ordine cliente alla generazione degli output amministrativi.

### Panoramica del Flusso Aziendale

```mermaid
flowchart LR
    A["1. ORDINE CLIENTE"] --> B["2. GENERAZIONE ODL\n(gestionale)"]
    B --> C["3. ESECUZIONE LAVORI\n+ timbrature"]
    C --> D["4. RAPPORTINI\n(compilazione operai)"]
    D --> E["5. SCANSIONE + OCR\n(estrazione AI)"]
    E --> F["6. REVISIONE\n(validazione operatore)"]
    F --> G["7. ELABORAZIONE\n(calcolo automatico)"]
    G --> H["8. OUTPUT EXCEL\n(A + B + C)"]
```

### Ciclo di Vita del Documento

```mermaid
stateDiagram-v2
    [*] --> InAttesa : Caricamento PDF
    InAttesa --> InElaborazione : Agente OCR (Azure AI)
    InElaborazione --> DaRevisionare : Estrazione completata
    DaRevisionare --> DaRevisionare : Salva Bozza
    DaRevisionare --> Confermato : Conferma operatore
    DaRevisionare --> Rifiutato : Rifiuto operatore
    Confermato --> Archiviato : Archiviazione
    Rifiutato --> [*]
    Archiviato --> [*]
```

### Logica Calcolo Ore

```mermaid
flowchart TD
    START["Timbratura giornaliera"] --> CHECK{"Totale ore ≤ 8h?"}
    CHECK -->|Sì| CASOA["CASO A"]
    CHECK -->|No| CASOB["CASO B"]
    CASOA --> A1["Ore viaggio = percorrenza"]
    A1 --> A2["Ore ordinarie = 8h − viaggio"]
    A2 --> A3["Straordinario = 0"]
    CASOB --> B1["Viaggio ordinario = parte entro 8h"]
    B1 --> B2["Ordinarie = 8h − viaggio ordinario"]
    B2 --> B3["Viaggio straord. = parte oltre 8h"]
    B3 --> B4["Straordinario = eccedenza − viaggio straord."]
```

---

### Fase 1: Preparazione – Configurazione Iniziale

Prima di iniziare il flusso operativo, assicurati che siano configurati:

1. **Operai e Badge** – Verifica che tutti gli operai attivi siano presenti nel sistema con il badge associato
2. **Commesse** – Controlla che le commesse padre e le sotto-commesse siano aggiornate
3. **Cantieri e Percorrenze** – Configura l'anagrafica cantieri con i **tempi di percorrenza** dalla sede
4. **Tariffe e Fasce** – Imposta i costi orari per dipendente e le fasce tariffarie contrattuali

---

### Fase 2: Ordine e Generazione ODL

**Chi**: Responsabile commessa

1. L'azienda riceve l'**ordine dal cliente**
2. L'operatore genera il **foglio di Lavorazione Interna (ODL)** nel gestionale
3. L'ODL include i materiali utilizzati (di magazzino o acquistati per il progetto)

---

### Fase 3: Esecuzione Lavori e Timbrature

**Chi**: Operai

- I **metalmeccanici** timbrano in azienda tramite il software interno e in cantiere (pausa pranzo, ecc.)
- Gli **edili** timbrano in cantiere tramite l'app mobile (con selezione del cantiere dal menu a tendina)

:::note[Notazione Timbrature]
I dati di timbratura possono presentare notazioni particolari: `6i00` (inserimento manuale), `12v07` (cantiere), `12:07` (timbratura automatica in azienda). Il sistema gestisce e normalizza questi formati.
:::

---

### Fase 4: Rapportini Giornalieri

**Chi**: Operai + Responsabile

- Ogni giorno i rapportini vengono **compilati dagli operai** e verificati dal responsabile
- Gli **impiegati** inseriscono le attività su una maschera dedicata nel sistema
- L'operatore ha la possibilità di **escludere le righe già inserite** durante la validazione

:::caution[Standard compilazione ODL]
Nella colonna "Operaio" del modulo ODL cartaceo, gli operai devono scrivere il proprio **codice risorsa** (matricola gestionale), non il nome e cognome. Questo consente al sistema OCR di identificare automaticamente l'operaio senza intervento manuale.
:::

---

### Fase 5: Scansione, Caricamento e OCR

**Chi**: Operatore amministrativo + Sistema AI

1. Raccogli gli **ODL cartacei** (PDF) compilati
2. Accedi a **Documenti > Carica Documenti**
3. Carica il PDF e assegna un titolo
4. Il sistema **Azure AI** estrae automaticamente i dati (OCR)
   - Durante l'estrazione, il flag **Fuori** viene impostato anche se nella descrizione della riga compaiono `VIAGGIO` o `FUORI SEDE`
5. Il documento passa allo stato **"Da revisionare"**

---

### Fase 6: Revisione e Validazione

**Chi**: Operatore amministrativo

1. Accedi a **Documenti > Lista Documenti**, filtra per **"Da revisionare"**
2. Apri la **Revisione** del documento
3. Verifica **intestazione**: cliente, commessa, descrizione
4. Controlla ogni **riga** della tabella lavorazioni:
   - Operaio corretto? (seleziona dal dropdown — ogni voce mostra **Cod. Risorsa — Nome**)
   - Ore lavorate corrette?
   - Flag **"Fuori"** corretto? (cruciale per il calcolo viaggio!)
5. Gestisci gli **alert** generati dal sistema (discrepanze ore, operai mancanti)
6. Se necessario, **dividi le ore** in sotto-commesse (Split)
7. Premi **"Salva Bozza"** per salvare le correzioni intermedie
8. Quando tutto è corretto, premi **"Conferma Dati"** (il documento verrà bloccato)

---

### Fase 7: Elaborazione Automatica

**Chi**: Sistema automatico

Dopo la conferma, il sistema calcola automaticamente:
- **Ore ordinarie** = MIN(ore timbrate, 8h) − ore viaggio entro 8h
- **Ore di viaggio** = tempo percorrenza andata + ritorno dal cantiere
- **Ore straordinarie** = (totale − 8h) − viaggio in eccedenza
- **Costi per fascia** = incrocio orario timbratura × tabella fasce tariffarie
- **Costo per risorsa** = ore × costo orario del dipendente

---

### Fase 8: Output Excel

**Chi**: Amministrazione / Direzione

Il sistema genera un **unico file Excel (.xlsx)** con tre fogli:

| Foglio | Contenuto |
|--------|-----------|
| **Output A** | Prospetto ore per dipendente/giorno (ordinarie, viaggio, straordinari) |
| **Output B** | Prospetto fasce tariffarie (ore e costi per fascia) |
| **Output C** | Prospetto costi per risorsa (cod_dipendente × costo) |

---

### Riepilogo Responsabilità

| Fase | Responsabile | Frequenza |
|------|-------------|-----------|
| Configurazione iniziale | Amministratore | Una tantum / Quando necessario |
| Generazione ODL | Responsabile commessa | Ad ogni ordine |
| Timbrature | Operai | Giornaliera |
| Rapportini | Operai + Responsabile | Giornaliera |
| Scansione + Upload | Operatore amministrativo | Settimanale |
| OCR | Sistema AI | Automatico |
| Revisione + Alert | Operatore amministrativo | Settimanale |
| Elaborazione ore | Sistema | Automatico |
| Output Excel | Amministrazione | Mensile / A richiesta |