# JG3 - UX e Flussi Utente

# 5. UX e Flussi Utente

---

## 5.1 Mappa delle aree dell'applicazione

```mermaid
graph TB
    LOGIN[Login\nKeycloak OIDC]

    LOGIN -->|OPERATOR| OP_AREA
    LOGIN -->|CLIENT| CL_AREA
    LOGIN -->|SUPER_ADMIN| SA_AREA

    subgraph "Area Operatore"
        OP_AREA[Templates List\n/templates]
        OP_AREA --> DESIGNER[Designer\n/designer/:id]
        OP_AREA --> SCHEMAS[Tipi Documento\n/schemas]
        DESIGNER --> CANVAS[Canvas Editor]
        DESIGNER --> PREVIEW[Anteprima PDF]
        DESIGNER --> PUBLISH[Pubblica]
    end

    subgraph "Area Cliente"
        CL_AREA[Dashboard Documenti\n/client/dashboard]
        CL_AREA --> CL_DOCS[Profili Stampa\n/client/documents/:type]
        CL_DOCS --> CL_PREVIEW[Anteprima Documento]
    end

    subgraph "Area Super Admin"
        SA_AREA[Gestione Tenant\n/admin/tenants]
        SA_AREA --> SA_TMPL[Template Cross-tenant]
        SA_AREA --> SA_ERP[Versioni ERP]
    end
```

---

## 5.2 Flusso Operatore — Creare un nuovo modello

```mermaid
flowchart LR
    START([Lista Modelli]) --> BTN[+ Nuovo Modello]
    BTN --> WIZARD{Schema\nesiste?}
    WIZARD -->|No| UPLOAD_XSD[Upload XSD\no auto-XSD da XML]
    WIZARD -->|Si| STEP2[Scegli XML\nper anteprima]
    UPLOAD_XSD --> STEP2
    STEP2 --> CREA[Crea Modello]
    CREA --> WORK[Progetta\nnel Canvas]
    WORK --> PREVIEW[Anteprima]
    PREVIEW -->|Modifica| WORK
    PREVIEW -->|OK| PUBLISH[Pubblica]
    PUBLISH --> DONE([Disponibile ai client])
```

---

## 5.3 Flusso Operatore — Import da MDL legacy

```mermaid
flowchart LR
    START([Lista Modelli]) --> IMPORT[Importa MDL]
    IMPORT --> MODE{Modalità}
    MODE -->|Auto| AUTO[Carica .mdl\nauto-detect XSD]
    MODE -->|Manuale| MAN[Carica .mdl\nseleziona schema]
    MODE -->|Bulk| BULK[Carica N file\nReport importazione]
    AUTO --> MATCH{XSD trovato?}
    MATCH -->|Si| CONVERT[MDL to JSON]
    MATCH -->|No| MAN
    MAN --> CONVERT
    CONVERT --> VERIFY[Verifica\nnel Designer]
    VERIFY -->|OK| SAVE2[Salva e Pubblica]
    VERIFY -->|Aggiusta| SAVE2
```

---

## 5.4 Flusso Cliente — Selezione profilo e anteprima

```mermaid
flowchart LR
    START([Dashboard]) --> DASH[Card per tipo documento]
    DASH --> SELECT[Seleziona tipo]
    SELECT --> PROFILES[Profili disponibili\ndefault - custom]
    PROFILES --> ACTIVATE{Cambia profilo?}
    ACTIVATE -->|Si| SET[Imposta profilo]
    ACTIVATE -->|No| PREVIEW2
    SET --> PREVIEW2[Anteprima dati reali]
    PREVIEW2 --> DONE2([Profilo confermato])
```

---

## 5.5 Struttura del Designer

```
┌──────────────────────────────────────────────────────────────────┐
│  TOP BAR:  [Nome modello]  [Modalità: Struttura/Dati]  [Salva]  [Preview]  [Pubblica]  │
├───────────────────────────────────────────────────────────────────│
│  TOOLBAR CONTESTUALE:                                             │
│  [+ Testo] [+ Campo] [+ Immagine] [+ Barcode] [+ Codice XSLT]   │
│  [Allinea sx] [Allinea centro] [Allinea dx]  [Distribuisci]     │
├────────────┬──────────────────────────────────┬───────────────────┤
│  DATA TREE │         CANVAS (A4/Letter)         │  PROPERTY PANEL  │
│            │                                    │                  │
│  ▼ TESTA   │  ┌── TESTA ────────────────────┐  │  Stile           │
│    CODE_DT │  │  ← Drag campi da tree       │  │  Posizione       │
│    NOME_CL │  └─────────────────────────────┘  │  Binding         │
│  ▼ CORPO   │                                    │  Parametri       │
│    IMPO_DA │  ┌── CORPO ────────────────────┐  │                  │
│    DESC_ART│  │  [ Tabella dati ]           │  │                  │
│            │  └─────────────────────────────┘  │                  │
│ [Cerca]    │                                    │                  │
│            │  ┌── PIEDE ────────────────────┐  │                  │
│  XML files │  │  Pag. [num]/[tot]           │  │                  │
│  xml1      │  └─────────────────────────────┘  │                  │
├────────────┴──────────────────────────────────┴───────────────────┤
│  STATUS BAR:  Zoom 100% | Mouse: X=45mm Y=23mm | Snap: ON        │
└──────────────────────────────────────────────────────────────────┘
```

### Property Panel — Modalità

| Selezione | Pannello mostrato |
|-----------|------------------|
| Nessuno | Hint d'uso |
| Elemento (testo/campo/immagine) | Stile, posizione, binding, condizione |
| Tabella | Configurazione tabella, stile, colonne |
| Riga tabella | Tipo, visibilità, condizione, anchor |
| Cella tabella | Contenuto segmenti, stile cella, colspan |
| Multi-selezione | Allinea, distribuisci, dimensioni |
| Sezione (testa/corpo/piede) | Altezza, margini |

---

## 5.6 Flusso Pubblicazione

```mermaid
flowchart LR
    DESIGNER_DONE([Modello pronto nel Designer])
    DESIGNER_DONE --> PUBLISH_BTN[Click Pubblica]
    PUBLISH_BTN --> DIALOG[Dialog Pubblica Versione]
    DIALOG --> ERP_VERSION[Imposta erpMinVersion opzionale]
    ERP_VERSION --> FORCE_MIG[Force Migration? opzionale]
    FORCE_MIG --> CONFIRM[Conferma]

    CONFIRM --> PUB_JSON[Pubblica snapshot nel DB\nmodello disponibile via API]
    PUB_JSON --> NOTIFY_TENANTS[Notifica tenant:\nNuova versione disponibile]

    subgraph "ERP COBOL eSIGEA"
        BRIDGE[Bridge nell'ERP COBOL\nPOST /api/render] --> PDF_COBOL[PDF output]
    end

    subgraph "Nuovo ERP Angular"
        NOTIFY_TENANTS --> API_CALL[POST /api/render con XML dati]
        API_CALL --> PDF_OUT[PDF output]
    end

    PUB_JSON -.-> BRIDGE
```

> **XSLT-FO:** il pulsante "Scarica XSLT-FO" (`POST /api/templates/{id}/publish-xslfo`) è disponibile come strumento secondario per ispezione o diagnostica — non è il flusso di integrazione COBOL attivo.

---

## 5.7 Flusso ERP Versioning

```mermaid
flowchart TD
    ADMIN([SUPER_ADMIN imposta versione ERP per un tenant])
    ADMIN --> SET_VER[PUT /admin/tenants/uuid/erp-version 6.9.0.0]
    SET_VER --> CHECK[Sistema verifica:\nc'è versione template compatibile?]
    CHECK -->|Sì, match esatto| USE[Usa template v6.9]
    CHECK -->|No, usa best match| BEST[Usa ultima versione ≤ 6.9]
    CHECK -->|Force migration pending| BANNER[Mostra banner/overlay nel frontend cliente]
    BANNER --> WIZARD_MIG[Wizard migrazione 3 step per Operatore]
    WIZARD_MIG --> UPGRADE[Profilo aggiornato al nuovo template]
    UPGRADE --> USE
```

---

## 5.8 Onboarding nuovo Operatore

Al primo accesso, tour guidato automatico in 7 step interattivi (skippabile):

1. Cos'è GPE_NEXT
2. Come creare un tipo documento
3. Usare il Designer
4. Aggiungere tabelle
5. Anteprima PDF
6. Pubblicare
7. Done — pronto per lavorare

---

## 5.9 Scorciatoie da tastiera

### Canvas
| Shortcut | Azione |
|----------|--------|
| `Ctrl+Z` | Undo |
| `Ctrl+Y` / `Ctrl+Shift+Z` | Redo |
| `Ctrl+S` | Salva bozza |
| `Ctrl+C/V` | Copia / Incolla |
| `Ctrl+Shift+V` | Incolla in posizione |
| `Ctrl+D` | Duplica |
| `Delete` / `Backspace` | Elimina elementi selezionati |
| `←↑→↓` | Sposta 1mm |
| `Shift+←↑→↓` | Sposta 10mm |
| `Enter` | Coordinate input rapido (mm) |

### Zoom e Pan
| Shortcut | Azione |
|----------|--------|
| `Ctrl+scroll` | Zoom in/out centrato sul cursore |
| `Ctrl+0` | Zoom 100% |
| `Ctrl+1` | Zoom to Fit |
| `Ctrl+2` | Zoom to Selection |
| `Spazio+drag` | Pan libero |

### Allineamento (multi-selezione)
| Shortcut | Azione |
|----------|--------|
| `Alt+L/C/R` | Allinea sinistra / centro / destra |
| `Alt+T/M/B` | Allinea alto / centro / basso |
| `Alt+H/V` | Distribuisci orizzontalmente / verticalmente |

### Altro
| Shortcut | Azione |
|----------|--------|
| `?` / `F1` | Apri overlay aiuto scorciatoie |
| `R` | Toggle righelli |
| `G` | Toggle griglia |
| `Esc` | Deseleziona / chiudi dialog |

---

## 5.10 Accessibilità

GPE_NEXT segue le linee guida **WCAG 2.2 AA**:
- Navigazione keyboard completa, alternative keyboard per Drag & Drop
- `aria-*` su tutti i componenti interattivi
- Contrasto colori AA su tutti i temi
- `cdkTrapFocus` nei dialog, `role="status"` su banner informativi

---