# JG - GPEnext

GPEnext - Nuovo sistema di editor pdf propietario.

# JG1 - Panoramica

# GPE\_NEXT — Documentazione Completa di Prodotto

> **Versione:** v1-RC1 | **Data:** giugno 2026 | **Stato:** pronto per primo test cliente

---

## Indice rapido

<table id="bkmrk-%23-sezione-contenuto-"><thead><tr><th>\#</th><th>Sezione</th><th>Contenuto</th></tr></thead><tbody><tr><td>1</td><td>[Panoramica](#1-panoramica-di-prodotto)</td><td>Cos'è, perché esiste, utenti, valore, status</td></tr><tr><td>2</td><td>[Funzionalità Attuali](#2-funzionalit%C3%A0-attuali-v1-rc1)</td><td>Catalogo completo feature implementate</td></tr><tr><td>3</td><td>[Architettura Tecnica](#3-architettura-tecnica)</td><td>Stack, diagrammi di sistema, flussi dati, schema DB</td></tr><tr><td>4</td><td>[API Reference](https://gsdoc.genesyssoftware.eu/link/37581#bkmrk-4.-api-reference)</td><td>Documentazione api</td></tr><tr><td>5</td><td>[UX e Flussi Utente](https://gsdoc.genesyssoftware.eu/link/37582#bkmrk-5.-ux-e-flussi-utent)</td><td>Flussi utente</td></tr><tr><td>6</td><td>[Ecosistema SIGEA-Next](#6-ecosistema-a-sigea--sigea-next)</td><td>Posizionamento, integrazioni ERP, roadmap ecosistema</td></tr><tr><td>7</td><td>[Roadmap](#7-roadmap)</td><td>Feature pianificate v1→v2→future, EPIC in backlog</td></tr></tbody></table>

---

# 1. Panoramica di Prodotto

## Cos'è GPE\_NEXT

**GPE\_NEXT** è un editor web centralizzato di modelli di stampa per ERP. Consente a operatori tecnici e clienti finali di creare, personalizzare e gestire i template per tutti i documenti generati dall'ERP Genesys (ordini, fatture, DDT, estratti conto, buste paga, etichette, report, ecc.).

È il successore moderno del **GPE** (Genesys Print Editor), applicazione desktop proprietaria sviluppata in Java Swing che ha accompagnato l'ERP COBOL legacy per anni.

---

## 1.1 Perché è stato costruito — I problemi del GPE legacy

Il GPE desktop presentava **19 bug documentati** che ne rendevano l'uso quotidiano difficile per gli operatori:

<table id="bkmrk-categoria-bug-impatt"><thead><tr><th>Categoria</th><th>Bug</th><th>Impatto</th></tr></thead><tbody><tr><td>Compatibilità</td><td>Adobe Acrobat 64bit blocca l'avvio</td><td>Blocca l'uso ogni volta</td></tr><tr><td>Layout</td><td>Sezione testa si azzera dalla pagina 2</td><td>Stampe illeggibili</td></tr><tr><td>Tabelle</td><td>Impossibile inserire colonne se spazio ridotto</td><td>Workaround manuali obbligatori</td></tr><tr><td>Tabelle</td><td>Max 2-3 pagine con conteggio pagina Break corretto</td><td>Bug sistematico</td></tr><tr><td>Tabelle</td><td>Impossibile tabelle affiancate</td><td>Limita fortemente il layout</td></tr><tr><td>Tabelle</td><td>Non gestisce alto numero di colonne XML</td><td>Crash o workaround</td></tr><tr><td>Immagini</td><td>Loghi sgranati in stampa</td><td>Qualità professionale impossibile</td></tr><tr><td>Multi-cliente</td><td>Un modello per tutti: logo ridimensiona la testa</td><td>Impossibile per-tenant</td></tr><tr><td>Immagini</td><td>Resize server-side distrugge la risoluzione</td><td></td></tr><tr><td>Numerazione</td><td>Numerazione pagine non funzionante o sporca</td><td></td></tr></tbody></table>

**Problemi strutturali:**

- Applicazione desktop → non distribuibile via web, ogni operatore deve installarla localmente
- Nessuna gestione multi-tenant → impossibile personalizzazioni per cliente
- Formato output `.xslt-xfo` non documentato → dipendenza totale dal vendor
- Nessuna API → integrazione col nuovo ERP Angular+Spring Boot impossibile

---

## 1.2 Cosa fa GPE\_NEXT (in sintesi)

```
                    ┌─────────────────────────────────────┐
                    │           GPE_NEXT Web App           │
                    │                                      │
  Operatore ───────▶│  Designer Canvas (drag & drop)       │
  Cliente ─────────▶│  Template Management                  │───▶ PDF via REST API
  Admin ───────────▶│  Multi-Tenant Isolation              │         (ERP Angular + ERP COBOL bridge)
                    │  Preview Real-Time                    │
                    │  API REST pubblica                    │
                    └─────────────────────────────────────┘

```

### Flusso operativo (semplificato)

1. L'ERP genera un flusso **XML dati** (ordine, fattura, DDT…)
2. L'operatore carica l'XML in GPE\_NEXT e crea/modifica il **modello di stampa** con il designer visuale
3. Il modello viene **pubblicato** in GPE\_NEXT e diventa immediatamente disponibile via API REST
4. Quando l'ERP deve stampare: 
    - **ERP COBOL eSIGEA**: il bridge integrato nell'ERP chiama `POST /api/render` con l'XML dati → riceve il **PDF finale**
    - **Nuovo ERP Angular+Spring Boot**: chiama `POST /api/render` direttamente → riceve il **PDF finale**

---

## 1.3 Utenti del sistema

### OPERATOR (Operatore Genesys)

Staff tecnico Genesys che configura i modelli per i clienti.

- Accesso completo al designer canvas
- Può creare/modificare/pubblicare tutti i modelli
- Gestisce schemi XSD e file XML di test
- Può importare modelli legacy (`.mdl`)
- Vede il codice XSLT/XSL-FO generato

### CLIENT (Cliente finale)

Il cliente dell'ERP (es. azienda che usa SIGEA).

- Ha la sua **dashboard** con i documenti disponibili
- Può selezionare il **profilo di stampa** da usare (tra quelli configurati dall'Operatore)
- Può visualizzare l'anteprima dei propri documenti
- **Non** può modificare struttura o template base

### SUPER\_ADMIN (Amministratore Genesys)

Gestione cross-tenant.

- Vede e gestisce tutti i tenant
- Imposta la versione ERP per ogni tenant
- Gestisce le migrazioni forzate di template

---

## 1.4 Valore per il cliente

<table id="bkmrk-prima-%28gpe-desktop%29-"><thead><tr><th>Prima (GPE Desktop)</th><th>Ora (GPE\_NEXT)</th></tr></thead><tbody><tr><td>Desktop Java, installa locale</td><td>Web app, qualsiasi browser</td></tr><tr><td>Un modello per tutti i clienti</td><td>Profili personalizzati per tenant</td></tr><tr><td>19 bug documentati che bloccano</td><td>Zero bug noti sulle funzionalità core</td></tr><tr><td>Nessuna API</td><td>REST API documentata (Swagger)</td></tr><tr><td>Immagini sgranate</td><td>Risoluzione originale preservata</td></tr><tr><td>Impossibile multi-tenant</td><td>Isolamento totale per-tenant</td></tr><tr><td>Nessuna anteprima affidabile</td><td>Preview real-time WYSIWYG</td></tr><tr><td>Dipendenza da Adobe Acrobat</td><td>Nessuna dipendenza</td></tr><tr><td>Solo COBOL legacy, output fisso su filesystem</td><td>REST API unificata: ERP COBOL bridge + nuovo ERP Angular</td></tr></tbody></table>

---

## 1.5 Status attuale (giugno 2026)

GPE\_NEXT è **pronto per il primo test con cliente reale**:

- ✅ **Tutti i 45 task P0** completati (100%)
- ✅ **Feature parity** completa con GPE legacy (v1)
- ✅ **Canvas UX** professionale (snap, guide, zoom, multi-select, undo/redo)
- ✅ **Integrazione Keycloak OIDC** funzionante
- ✅ **900+ test** automatici, 0 failure
- ✅ **Import legacy MDL** funzionante su tutti i modelli testati
- ✅ **Output ERP COBOL** validato su file reali (230+ XML)
- ✅ **Output PDF** via Gotenberg (Chromium) con layout WYSIWYG
- ✅ **Bridge ERP COBOL** operativo (eSIGEA chiama `POST /api/render`)
- 🔄 **Deploy OCI** in preparazione (EPIC A in corso)
- 🔄 **Admin Panel** in pianificazione (TASK-048)

---

## 1.6 Stack tecnologico (sintesi)

<table id="bkmrk-layer-tecnologia-fro"><thead><tr><th>Layer</th><th>Tecnologia</th></tr></thead><tbody><tr><td>Frontend</td><td>Angular 18+ (standalone), PrimeNG Aura, Angular CDK</td></tr><tr><td>Backend</td><td>Spring Boot 3.3, Java 21</td></tr><tr><td>PDF engine</td><td>Gotenberg 8+ (Chromium/Blink via Docker)</td></tr><tr><td>XSLT-FO</td><td>Apache FOP 2.10 (diagnostica/download)</td></tr><tr><td>Database</td><td>PostgreSQL 16, Flyway, JSONB</td></tr><tr><td>Auth</td><td>Keycloak OIDC (realm `gsauth`)</td></tr><tr><td>Infrastruttura</td><td>Docker, Nginx, OCI Linux</td></tr><tr><td>Preview browser</td><td>Paged.js (preview browser-side)</td></tr></tbody></table>

---

## 1.7 Posizionamento in a-SIGEA

GPE\_NEXT è il **Modulo 1** del progetto di evoluzione aziendale **a-SIGEA**:

```
a-SIGEA (futuro)
├── [M1] GPE_NEXT ✅ ← QUI SIAMO
├── [M2] Nuovo ERP Angular+Spring (in sviluppo)
├── [M3] Strato agentico AI
├── [M4] BI Generativa
├── [M5] Gestione Documentale e Knowledge Management
└── [M6] HAI (Humanized Augmented Intelligence) per Logistica

```

---

# 2. Funzionalità Attuali (v1-RC1)

> Tutte le funzionalità elencate sono **implementate e funzionanti** — non sono roadmap.

---

## 2.1 Designer Canvas

Il cuore di GPE\_NEXT è il **canvas di disegno visuale** a 3 pannelli:

```
┌─────────────┬──────────────────────────────┬─────────────┐
│  Data Tree  │        Canvas Pagina          │  Proprietà  │
│             │                               │             │
│ ▼ XML Tree  │  ┌─── TESTA ──────────────┐  │  Elemento   │
│  ├─ campo1  │  │  [logo]  [testo]        │  │  selezion.  │
│  ├─ campo2  │  └────────────────────────┘  │             │
│  └─ ...     │  ┌─── CORPO ──────────────┐  │  Stile      │
│             │  │  ┌──────────────────┐  │  │  Posizione  │
│ [Cerca...]  │  │  │    Tabella dati  │  │  │  Binding    │
│             │  │  └──────────────────┘  │  │             │
│             │  └────────────────────────┘  │  Parametri  │
│             │  ┌─── PIEDE ──────────────┐  │             │
│             │  │  [pag. X/Y]            │  └─────────────┘
│             │  └────────────────────────┘
└─────────────┴──────────────────────────────┘

```

### Sezioni della Pagina

<table id="bkmrk-sezione-descrizione-"><thead><tr><th>Sezione</th><th>Descrizione</th><th>ERP equivalente</th></tr></thead><tbody><tr><td>**Testa**</td><td>Intestazione ripetuta su ogni pagina</td><td>`region-before` XSL-FO</td></tr><tr><td>**Corpo**</td><td>Contenuto principale (tabelle dati)</td><td>`region-body`</td></tr><tr><td>**Piede**</td><td>Piè di pagina (numerazione, firme)</td><td>`region-after`</td></tr><tr><td>**Margine Sinistro**</td><td>Colonna laterale sinistra</td><td>`region-start`</td></tr><tr><td>**Margine Destro**</td><td>Colonna laterale destra</td><td>`region-end`</td></tr></tbody></table>

### Elementi del Canvas

<table id="bkmrk-elemento-descrizione"><thead><tr><th>Elemento</th><th>Descrizione</th><th>Binding</th></tr></thead><tbody><tr><td>**Static Field**</td><td>Testo statico o con segmenti misti</td><td>—</td></tr><tr><td>**Data Field**</td><td>Campo XML dell'ERP</td><td>XPath dal flusso dati</td></tr><tr><td>**Image/Logo**</td><td>Immagine o logo aziendale</td><td>Path filesystem + variabili `$IMGDIR`/`$PROCLIB`</td></tr><tr><td>**Barcode**</td><td>Codice a barre CODE\_128</td><td>Campo XML</td></tr><tr><td>**code-xslt-field**</td><td>Blocco XSLT raw (solo OPERATOR)</td><td>XSLT arbitrario</td></tr></tbody></table>

### Canvas UX — Strumenti di Disegno

<table id="bkmrk-funzionalit%C3%A0-shortcu"><thead><tr><th>Funzionalità</th><th>Shortcut</th><th>Note</th></tr></thead><tbody><tr><td>Snap to Grid</td><td>Toggle toolbar</td><td>Passo configurabile in mm</td></tr><tr><td>Smart Guides</td><td>Sempre attivo</td><td>Snap a bordi e centri elementi</td></tr><tr><td>Righelli mm</td><td>`R`</td><td>HiDPI, indicatore mouse in tempo reale</td></tr><tr><td>Multi-selezione</td><td>`Ctrl+Click`, lasso</td><td>Bounding box overlay</td></tr><tr><td>Allineamento</td><td>`Alt+L/C/R/T/M/B`</td><td>Align &amp; distribute</td></tr><tr><td>Sposta con tasto</td><td>`←↑→↓`</td><td>Nudge 1mm, `Shift`=10mm</td></tr><tr><td>Zoom</td><td>`Ctrl+scroll`, `Ctrl+0/1/2`</td><td>25–400%</td></tr><tr><td>Pan</td><td>`Spazio+drag`</td><td></td></tr><tr><td>Draw mode</td><td>Toggle toolbar</td><td>Disegna nuovo elemento</td></tr><tr><td>Guide draggabili</td><td>Dal righello</td><td>Snap per posizionamento</td></tr><tr><td>Copy/Paste</td><td>`Ctrl+C/V`</td><td>Tra sezioni e pagine</td></tr><tr><td>Duplicate</td><td>`Ctrl+D`</td><td></td></tr><tr><td>Z-order</td><td>Toolbar</td><td>Porta in primo piano / manda in fondo</td></tr><tr><td>Undo/Redo</td><td>`Ctrl+Z/Y`</td><td>Stack completo</td></tr><tr><td>Coordinate rapide</td><td>`Enter` su elemento</td><td>Input numerico mm</td></tr><tr><td>Shortcut help</td><td>`?` / `F1`</td><td>Overlay 5 categorie</td></tr><tr><td>Modalità PDF Fidelity</td><td>Auto</td><td>Chrome nascosto a riposo</td></tr></tbody></table>

### Modalità Vista Canvas

- **Struttura** — vede tutti i chrome (bordi, guide, badge)
- **Dati** — mostra i valori XML reali caricati
- **PDF Fidelity** — chrome nascosto, vista "come sarà il PDF"

---

## 2.2 Tabelle Dati

Le tabelle sono l'elemento più potente del sistema — coprono il 90% dei documenti ERP.

### Tipi di Riga

<table id="bkmrk-tipo-descrizione-xsl"><thead><tr><th>Tipo</th><th>Descrizione</th><th>XSLT generato</th></tr></thead><tbody><tr><td>**Header**</td><td>Intestazione colonna</td><td>Statica</td></tr><tr><td>**Data**</td><td>Riga dati dal flusso XML</td><td>`xsl:for-each`</td></tr><tr><td>**Total**</td><td>Riga aggregazione</td><td>`xsl:call-template`</td></tr><tr><td>**Group Break**</td><td>Salto gruppo / rottura</td><td>`xsl:for-each-group`</td></tr></tbody></table>

### Funzionalità Tabella

<table id="bkmrk-feature-dettaglio-ta"><thead><tr><th>Feature</th><th>Dettaglio</th></tr></thead><tbody><tr><td>Tabelle affiancate</td><td>Più tabelle nella stessa sezione (risolve bug GPE legacy)</td></tr><tr><td>Nested tables</td><td>Fino a 3 livelli di annidamento</td></tr><tr><td>Multi-row-type</td><td>Più tipi di riga nella stessa tabella</td></tr><tr><td>Merge celle</td><td>Colspan UI con merge/split visuale</td></tr><tr><td>Bordi per cella</td><td>Controllo lato per lato (top/right/bottom/left)</td></tr><tr><td>Zebra striping</td><td>Colorazione alternata righe</td></tr><tr><td>Header colorato</td><td>Background colore testa</td></tr><tr><td>Righe opzionali</td><td>`xsl:if` su riga intera</td></tr><tr><td>Page break</td><td>Controllo salto pagina (keep-together, minRowBefore)</td></tr><tr><td>Anchor Row</td><td>Gruppi logici che non si spezzano tra pagine</td></tr><tr><td>Sort Keys</td><td>Ordinamento dati (crescente/decrescente)</td></tr><tr><td>Group Break</td><td>Intestazione subtotale per ogni gruppo</td></tr><tr><td>Aggregate</td><td>sum/avg/count/min/max per colonna</td></tr><tr><td>RecOutMode</td><td>REC\_TO\_CELL (record → colonne)</td></tr><tr><td>Tabelle condizionali</td><td>`xsl:if` wrapper sulla tabella intera</td></tr><tr><td>Col-span dinamico</td><td>merge fino a N colonne</td></tr></tbody></table>

### Contenuto Misto nelle Celle

Ogni cella può contenere una sequenza di **segmenti misti**:

```
Cella: [ "Articolo: " | {CODART} | " - " | {DESART} ]
           testo       campo XML   testo   campo XML

```

### Funzioni e Macro sui Campi

<table id="bkmrk-funzione%2Fmacro-descr"><thead><tr><th>Funzione/Macro</th><th>Descrizione</th></tr></thead><tbody><tr><td>`LOWER()`</td><td>Converti in minuscolo</td></tr><tr><td>`RPAD()`</td><td>Padding destro</td></tr><tr><td>`TRIM()`</td><td>Rimuovi spazi</td></tr><tr><td>`SubstitutionList`</td><td>Mappa valori (es. `01→Aperto`, `02→Chiuso`)</td></tr><tr><td>`CURR_DATE`</td><td>Data corrente</td></tr><tr><td>`CURR_TIME`</td><td>Ora corrente</td></tr><tr><td>`PAGE_NUM`</td><td>Numero pagina corrente</td></tr><tr><td>`PAGE_TOT`</td><td>Totale pagine</td></tr><tr><td>Formati COBOL numerici</td><td>`N9_999v99s`, `sN9999p99`</td></tr><tr><td>Formati COBOL date</td><td>`DDpMMpYYYY`, `DDtMMtYYYY`, `YYYYtMMtDD`</td></tr><tr><td>XPath parametrici</td><td>`xsl:param` per espressioni dinamiche</td></tr></tbody></table>

---

## 2.3 Gestione Modelli (Template)

### Ciclo di vita del Modello

```
Bozza (Draft) ──[Pubblica]──▶ Versione Pubblicata
     ▲                              │
     │                              ▼
  [Modifica]              Distribuito ai Tenant

```

- **Bozza (Draft):** solo OPERATOR la vede, modificabile
- **Pubblicato:** accessibile ai client, immutabile (solo snapshot)
- **Versioning ERP:** ogni versione ha un `erpMinVersion` — il sistema seleziona automaticamente la versione compatibile con la versione ERP del tenant

### Profili Client

```
Template Base (Genesys) ──[clone]──▶ Profilo Tenant A
                         ──[clone]──▶ Profilo Tenant B

```

### Funzioni CRUD

- Crea nuovo modello (wizard 2 step)
- Clona modello esistente
- Importa da file `.mdl` legacy
- Import massivo (bulk) di file `.mdl`
- Modifica in designer, salva bozza, pubblica versione
- Attiva profilo per tenant
- Storico versioni, anteprima versione storica, ripristino versione
- Elimina (con conferma)
- Lista con filtri e ricerca

### Multi-Pagina (Multi-PageModel)

Un documento può avere **più modelli pagina** (pagina 1 diversa dalle successive, intestazioni diverse per cliente):

```
Documento: ┌─ PageModel 1 (estr_cont) ─ ogni cliente
           └─ PageModel 2 (estr_cont_este) ─ ogni cliente esteso

```

Navigazione tra pagine con tab-bar nel designer. Ogni pagina ha i propri margini, sezioni e contenuti.

---

## 2.4 Gestione Schema / Tipo Documento

### Flusso XML → Schema → Modello

```
ERP genera XML ──▶ Upload XML in GPE_NEXT
                        │
                        ▼
               Conversione automatica XML→XSD
                        │
                        ▼
               Schema (Tipo Documento) creato
                        │
                        ▼
               Modello di stampa associato allo Schema

```

### Funzionalità Schema

- Upload XML → conversione automatica XSD (inferenza tipi COBOL)
- Import XSD manuale
- Carica file XML multipli per lo stesso schema
- Parser XSD → albero visuale dei campi nel designer
- Associazione file XML al modello (per anteprima con dati reali)
- Validazione: impossibile caricare XML senza XSD
- Validazione: impossibile creare modello senza schema associato
- Supporto XPath relativi e assoluti
- Gestione Schema Ditta: XPath per `CODE_DITT` (logo per-azienda)
- Auto-detect XPath ditta dal tree, con auto-detect su import MDL

### Import Legacy MDL

GPE\_NEXT importa i file `.mdl` del vecchio GPE con **fedeltà completa**:

<table id="bkmrk-elemento-mdl-support"><thead><tr><th>Elemento MDL</th><th>Supporto</th><th>Note</th></tr></thead><tbody><tr><td>`page-model`</td><td>✅</td><td>Mapping completo</td></tr><tr><td>`table`</td><td>✅</td><td>Incluse condizioni</td></tr><tr><td>`table-row` (H/D/T/GB)</td><td>✅</td><td>Tutti i tipi</td></tr><tr><td>`table-column`</td><td>✅</td><td>Larghezze mm</td></tr><tr><td>`text-block`</td><td>✅</td><td>Testo statico e misto</td></tr><tr><td>`data-field`</td><td>✅</td><td>XPath binding</td></tr><tr><td>`image`</td><td>✅</td><td>Path con variabili</td></tr><tr><td>`code-xslt-field`</td><td>✅</td><td>Preservato byte-per-byte</td></tr><tr><td>`barcode`</td><td>✅</td><td>CODE\_128</td></tr><tr><td>Multi-page</td><td>✅</td><td></td></tr><tr><td>Condizioni `xsl:if`</td><td>✅</td><td>Su elementi, righe, tabelle</td></tr><tr><td>SubstitutionList</td><td>✅</td><td></td></tr><tr><td>FuncCall</td><td>✅</td><td>LOWER, RPAD, TRIM</td></tr><tr><td>Macro date/ora</td><td>✅</td><td></td></tr><tr><td>XPath parametrici</td><td>✅</td><td></td></tr><tr><td>Regioni LEFT/RIGHT</td><td>✅</td><td></td></tr><tr><td>Tabelle affiancate</td><td>✅</td><td></td></tr><tr><td>RecOutMode</td><td>✅</td><td>REC\_TO\_CELL</td></tr></tbody></table>

---

## 2.5 Preview e Anteprima

- Preview real-time con dati XML reali nel pannello destro
- Rendering via **Paged.js** (browser-side, instant) e **Gotenberg** (PDF reale)
- Auto-generate all'apertura del pannello
- Mostra TUTTE le pagine del documento, numerazione `X/Y` corretta
- **Stampa al Volo (EPO):** override temporaneo di valori XML direttamente dall'anteprima (`contenteditable` su iframe, non persistente)

---

## 2.6 Output e Integrazione ERP

### PDF via REST API (entrambi gli ERP)

```
ERP (Angular o COBOL bridge) ──[POST /api/render]──▶ GPE_NEXT Backend
              XML dati                                      │
                                                            ▼
                                                  Carica template attivo
                                                            │
                                                            ▼
                                                  Genera HTML+CSS via XSLT
                                                            │
                                                            ▼
                                                  Gotenberg (Chromium)
                                                            │
                                                            ▼
                                                  PDF ◀────────────────

```

**API Render:**

- `POST /api/render` — body: XML ERP → response: PDF binario
- Risoluzione automatica tenant dal JWT
- Risoluzione automatica template attivo per tipo documento
- Supporto versioning ERP (usa la versione template compatibile)
- Iniezione logo per-ditta automatica

### Integrazione ERP COBOL eSIGEA (bridge REST API)

L'ERP COBOL integra con GPE\_NEXT tramite un **bridge integrato nel motore ERP**, che chiama la stessa `POST /api/render` usata dal nuovo ERP Angular. Non è necessaria nessuna operazione manuale di deposit file.

**Come funziona:**

- Il bridge nell'ERP COBOL chiama `POST /api/render` con l'XML dati e le credenziali JWT
- GPE\_NEXT risolve automaticamente il tenant, il template attivo e la versione ERP compatibile
- La risposta è un PDF binario pronto all'uso

### Esportazione XSLT-FO (funzionalità secondaria)

GPE\_NEXT conserva la capacità di generare e scaricare il file `.xslt-xfo` tramite il pulsante "Scarica XSLT-FO" — utile per ispezione, diagnostica o clienti non ancora migrati al bridge. **Non è il metodo primario di integrazione COBOL.**

Caratteristiche tecniche del file generato:

- Encoding ISO-8859-1, namespace `gs-gpe:`, output autocontenuto
- Post-processing per compatibilità `libGSSPM.dll` (7 trasformazioni)
- Path variabili `$IMGDIR`/`$PROCLIB` preservate come testo letterale

### Print API Pubblica (in sviluppo)

Epic **PAPI** pianificato (PAPI-001→012):

- `POST /api/print/{documentType}` — stampa per tipo documento
- Swagger UI navigabile + documentazione OpenAPI 3.0

---

## 2.7 Multi-Tenant

- Ogni **tenant** (cliente Genesys) ha i propri dati completamente isolati
- `tenant_id` estratto dal JWT Keycloak (claim `groups`) — MAI da query param
- Provisioning automatico al primo login
- Solo `SUPER_ADMIN` ha vista cross-tenant (endpoint `/api/admin/**`)
- Wizard migrazione 3-step per upgrade forzato versione ERP
- Logica `findBestPublishedVersion` automatica

---

## 2.8 Sicurezza e Autenticazione

<table id="bkmrk-feature-dettaglio-id"><thead><tr><th>Feature</th><th>Dettaglio</th></tr></thead><tbody><tr><td>Identity Provider</td><td>Keycloak OIDC (`gsauth.genesyssoftware.eu`)</td></tr><tr><td>Token</td><td>JWT access token + refresh token</td></tr><tr><td>Tenant</td><td>Derivato da claim `groups` Keycloak</td></tr><tr><td>Ruoli</td><td>`SUPER_ADMIN`, `OPERATOR`, `CLIENT`</td></tr><tr><td>Multi-tenant isolation</td><td>Tutti gli endpoint filtrano per `tenant_id`</td></tr><tr><td>Rate limiting</td><td>`/api/auth/login` protetto</td></tr><tr><td>XPath whitelist</td><td>Solo XPath sicuri in engine XSLT</td></tr><tr><td>MDC logging</td><td>Pseudonimizzato (no dati personali nei log)</td></tr><tr><td>Error sanitization</td><td>Nessun dettaglio interno esposto nelle risposte</td></tr></tbody></table>

---

## 2.9 Monitoraggio e Logging

- **Structured logging** JSON (profilo prod) / testo colorato (profilo dev)
- **MDC** con `tenant_id`, `request_id`, `user_id` (pseudonimizzati)
- **Performance logs** su operazioni critiche (generazione PDF, render XSLT)
- **Sentry** self-hosted (configurato, deployment in pianificazione)
- **Actuator** Spring Boot (health check, metrics)

---

# 3. Architettura Tecnica

---

## 3.1 Vista d'insieme del sistema

```mermaid
graph TB
    subgraph "Client Layer"
        B[Browser\nAngular 18+\nPaged.js]
        ERP_ANG[ERP Angular\nnuovo]
        ERP_COBOL[ERP COBOL eSIGEA\nbridge integrato]
    end

    subgraph "GPE_NEXT Platform"
        NGINX[Nginx\nReverse Proxy]
        FE[Frontend\nAngular SPA]
        BE[Backend\nSpring Boot 3.3]
        DB[(PostgreSQL 16\nFlyway migrations\nJSONB)]
        GTB[Gotenberg 8\nChromium PDF]
        FOP[Apache FOP 2.10\nXSL-FO only]
    end

    subgraph "Identity & Security"
        KC[Keycloak OIDC\ngsauth.genesyssoftware.eu]
    end

    subgraph "XSLT-FO — funzione secondaria"
        XSLOUT[Download .xslt-xfo\nper ispezione/diagnostica]
    end

    B --> NGINX
    ERP_ANG -->|POST /api/render\nXML → PDF| NGINX
    ERP_COBOL -->|POST /api/render\nXML → PDF\nbridge nell'ERP| NGINX
    NGINX --> FE
    NGINX --> BE
    BE --> DB
    BE --> GTB
    BE -->|FOP path solo| FOP
    BE -.->|publish .xslt-xfo\nfunzionalità secondaria| XSLOUT
    B --> KC
    BE --> KC

```

---

## 3.2 Stack tecnico dettagliato

### Frontend

```
Angular 18+ (standalone components)
├── PrimeNG (Aura dark preset)
├── Angular CDK Drag & Drop
├── Paged.js (preview browser-side)
├── Lucide Icons (tree-shaken)
├── AutoAnimate (motion)
├── CodeMirror 6 (editor XSLT)
└── Chart.js [pianificato v2]

```

Pattern architetturali: standalone components, Signals per state locale, `inject()`, `ChangeDetectionStrategy.OnPush`, template syntax `@if`/`@for`/`@switch`, SCSS con CSS custom properties.

### Backend

```
Spring Boot 3.3 (Java 21)
├── Spring Security + Keycloak JWT
├── Spring Data JPA (PostgreSQL)
├── Flyway migrations (V1→V30+)
├── RestClient (Spring 6) per Gotenberg
├── Saxon-HE (XSLT 2.0 processor)
├── Apache FOP 2.10 (XSL-FO diagnostica)
├── PDFBox (manipolazione PDF)
├── Springdoc OpenAPI [pianificato PAPI]
└── Logback JSON (structured logging)

```

Struttura package:

```
controller/ → service/ → repository/ → model/
                │
                ├── dto/        (API contracts)
                ├── html/       (HTML template engine → Gotenberg)
                ├── xslfo/      (XSL-FO engine → download/diagnostica)
                └── xml/        (XML→XSD conversion, XSD parser)

```

### Database

```sql
-- Schema principale (PostgreSQL 16)
tenants           -- Multi-tenant root
  └─ users        -- Utenti per tenant
  └─ schemas      -- Tipi documento (XSD + XML files)
  └─ templates    -- Modelli di stampa (JSONB content)
     └─ template_base_versions  -- Versioning draft/publish
  └─ tenant_active_profiles     -- Profilo attivo per tipo doc
  └─ images        -- Loghi e immagini
  └─ refresh_tokens

```

Ogni tabella (tranne `tenants`) ha `tenant_id NOT NULL` con indice. Template content in JSONB. UUID come PK ovunque.

---

## 3.3 Flusso dati — Generazione PDF (stesso percorso per entrambi gli ERP)

```mermaid
sequenceDiagram
    participant ERP as ERP (Angular o COBOL bridge)
    participant BE as Backend Spring Boot
    participant XSLT as Saxon XSLT 2.0
    participant GTB as Gotenberg (Chromium)
    participant DB as PostgreSQL

    ERP->>BE: POST /api/render\nAuthorization: Bearer JWT\nBody: XML dati ERP

    BE->>BE: Estrai tenant_id dal JWT\n(claim groups)
    BE->>DB: Trova template attivo\nper (tenant_id, document_type, erp_version)
    DB-->>BE: Template JSON (JSONB)

    BE->>XSLT: Trasforma template JSON\nin HTML+CSS XSLT template
    XSLT-->>BE: HTML XSLT template

    BE->>XSLT: Applica XSLT template\nsull'XML dati ERP
    XSLT-->>BE: HTML paginato

    BE->>GTB: POST /forms/chromium/convert/html\nBody: HTML + CSS
    GTB-->>BE: PDF binario

    BE-->>ERP: PDF binario\nContent-Type: application/pdf

```

---

## 3.4 Flusso dati — Integrazione ERP COBOL (bridge REST API)

Il bridge integrato nell'ERP COBOL chiama GPE\_NEXT esattamente come fa il nuovo ERP Angular.

```mermaid
sequenceDiagram
    participant ERP_C as ERP COBOL eSIGEA
    participant BRG as Bridge ERP COBOL
    participant BE as Backend Spring Boot
    participant XSLT as Saxon XSLT 2.0
    participant GTB as Gotenberg (Chromium)
    participant DB as PostgreSQL

    ERP_C->>BRG: Richiesta stampa documento + XML dati
    BRG->>BE: POST /api/render\nAuthorization: Bearer JWT\nBody: XML dati ERP
    BE->>BE: Estrai tenant_id dal JWT
    BE->>DB: Trova template attivo
    DB-->>BE: Template JSON (JSONB)
    BE->>XSLT: Genera HTML+CSS dal template
    XSLT-->>BE: HTML paginato
    BE->>GTB: Converti HTML → PDF
    GTB-->>BE: PDF binario
    BE-->>BRG: PDF binario
    BRG-->>ERP_C: PDF pronto

```

## 3.4.1 Esportazione XSLT-FO (funzionalità secondaria)

L'operatore può scaricare il file `.xslt-xfo` per ispezione, diagnostica o clienti non migrati al bridge.

```mermaid
sequenceDiagram
    participant OP as Operatore
    participant FE as Frontend Angular
    participant BE as Backend Spring Boot
    participant GEN as XslFoGeneratorService
    participant POST as XslFoErpPostprocessor

    OP->>FE: Click "Scarica XSLT-FO"
    FE->>BE: POST /api/templates/{id}/publish-xslfo
    BE->>GEN: generate(templateJson)
    GEN-->>BE: XSLT-FO (namespace gs-gpe:,\nISO-8859-1, autocontenuto)
    BE->>POST: apply ERP postprocessing\n(7 trasformazioni compatibilità)
    POST-->>BE: XSLT-FO finale
    BE->>BE: Valida well-formedness XML
    BE-->>FE: 200 OK + bytes file\n+ header X-Published-Path
    FE-->>OP: Download file .xslt-xfo

```

---

## 3.5 Architettura Multi-Tenant

```mermaid
graph LR
    JWT[JWT Token\nclaim groups:\n/client/TENANT_A]

    subgraph "Request Pipeline"
        F1[TenantContextFilter] --> F2[JwtAuthenticationFilter]
        F2 --> F3[Controller]
        F3 --> F4[Service]
        F4 --> F5[Repository]
    end

    JWT --> F1
    F1 -->|tenant_id estratto\ne messo in ThreadLocal| F4
    F5 -->|findByIdAndTenantId\nMAI findById| DB[(PostgreSQL)]

```

**Regola assoluta:** ogni query al DB deve includere `tenant_id`. Unica eccezione: endpoint `/api/admin/**` con `@PreAuthorize("hasRole('SUPER_ADMIN')")`.

---

## 3.6 Engine XSLT-FO — Struttura interna

```
XslFoGeneratorService.generate(GpeTemplateDto)
├── writeXslHeader()           → dichiarazione, namespace, encoding
├── writeParams()              → xsl:param per campi ERP
├── writeUtilityTemplates()    → template riutilizzabili inline
├── writeSimplePageMaster()    → layout pagina (margini, regioni)
│   └── [per ogni PageModel]
├── writePageSequenceMaster()  → alternanza pagine (first/rest/last)
└── writePageSequence()        → contenuto
    ├── writeStaticContent()   → TESTA + PIEDE (region-before/after)
    └── writeFlowContent()     → CORPO (region-body)
        └── [per ogni tabella] → writeTable()

```

**Post-processor ERP (7 trasformazioni per `libGSSPM.dll`):**

1. Aggiunge `xsl:template match="/"` wrapper
2. Rimuove `border-collapse` da `fo:table`
3. Fix attributi `fo:table-column`
4. Fix `fo:table-body` attributi extra
5. Rimuove wrapper `fo:block` da `fo:static-content`
6. Sostituisce variabili `$IMGDIR`/`$PROCLIB` con testo letterale
7. Fix namespace `gs-gpe:style-list`

---

## 3.7 Engine HTML (per Gotenberg) — Struttura interna

```
HtmlTemplateService
├── generateXsltTemplate(template)   → produce XSLT template (HTML)
│   ├── buildPageCss()              → CSS Paged Media (@page, @media print)
│   ├── HtmlPageLayoutRenderer
│   │   ├── renderHeader()
│   │   ├── renderBody()
│   │   └── renderFooter()
│   └── buildGlobalCss()            → .page-layout, .row-anchor-group
├── HtmlTableRenderer
│   ├── renderMergedDataRows()      → xsl:for-each + anchor groups
│   ├── renderHeaderRows()
│   └── renderTotalRows()
└── HtmlFieldRenderer

PdfGenerationService
├── Pass 1: render HTML → conta pagine (PDFBox)
├── Pass 2: inject page-total nelle <span> pre-riempite
└── Pass 3: chiamata Gotenberg → PDF finale

```

---

## 3.8 Performance Budget (Frontend)

<table id="bkmrk-asset-limite-js-prim"><thead><tr><th>Asset</th><th>Limite</th></tr></thead><tbody><tr><td>JS primo route</td><td>&lt; 180kb gzip</td></tr><tr><td>CSS totale</td><td>&lt; 45kb gzip</td></tr><tr><td>Font Inter variable</td><td>&lt; 100kb woff2</td></tr><tr><td>Font JetBrains Mono</td><td>&lt; 50kb woff2</td></tr><tr><td>Icone Lucide</td><td>&lt; 15kb gzip</td></tr></tbody></table>

---

## 3.9 Deployment (OCI Linux)

```mermaid
graph TB
    subgraph OCI_SERVER["OCI Linux Server"]
        subgraph DOCKER["Docker Compose"]
            NGINX2[nginx 80/443]
            FE2[frontend Angular + nginx]
            BE2[backend Spring Boot]
            DB2[(PostgreSQL 16)]
            GTB2[Gotenberg 3000]
        end
        XSLOUT[XSLT-FO download path]
    end

    INTERNET[Internet] --> NGINX2
    NGINX2 --> FE2
    NGINX2 --> BE2
    BE2 --> DB2
    BE2 --> GTB2
    BE2 -.-> XSLOUT

```

**Environment variables critiche:**

```
JWT_SECRET=...
DB_PASSWORD=...
GOTENBERG_URL=http://gotenberg:3000
XSLFO_OUTPUT_PATH=/gsnr/gpe-next/data/xslfo
KEYCLOAK_ISSUER_URI=https://gsauth.genesyssoftware.eu/realms/gsauth
SPRING_PROFILES_ACTIVE=production

```

---

## 3.10 Database Schema — Entità principali

```mermaid
erDiagram
    tenants ||--o{ users : "ha"
    tenants ||--o{ schemas : "possiede"
    tenants ||--o{ templates : "possiede"
    tenants ||--o{ images : "possiede"
    tenants ||--o{ tenant_active_profiles : "ha"

    schemas ||--o{ schema_xml_files : "ha"
    schemas ||--o{ templates : "riferimento"

    templates ||--o{ template_base_versions : "versioni"
    templates ||--o{ tenant_active_profiles : "profilo attivo"

    tenants {
        UUID id PK
        string slug UK
        string company_name
        UUID company_logo_image_id FK
        string keycloak_group_path UK
        string erp_version
        TIMESTAMPTZ created_at
    }

    schemas {
        UUID id PK
        UUID tenant_id FK
        string name
        string document_type
        string document_label
        string erp_min_version
        text xsd_content
        string ditta_code_xpath
        boolean force_migration
        TIMESTAMPTZ updated_at
    }

    templates {
        UUID id PK
        UUID tenant_id FK
        UUID base_schema_id FK
        string name
        string profile_name
        boolean is_base_template
        UUID xml_file_id FK
        JSONB content
        JSONB draft_content
        TIMESTAMPTZ created_at
        TIMESTAMPTZ updated_at
    }

    images {
        UUID id PK
        UUID tenant_id FK
        string filename
        string display_name
        string content_type
        bytea data
    }

```

---

# 6. Ecosistema a-SIGEA / SIGEA-Next

---

## 6.1 Il contesto: 40 anni di ERP COBOL

Genesys Software S.r.l. ha sviluppato in quattro decenni un ecosistema ERP proprietario completo — **eSIGEA** / **SIGEAdb** — che gestisce l'intero ciclo aziendale:

```
eSIGEA / SIGEAdb (COBOL legacy)
├── Magazzino · Logistica (picking, packing, spedizioni)
├── Acquisti · Ciclo Passivo (fatture fornitori, pagamenti)
├── Amministrazione · Contabilità · Finanza
├── Produzione · Commerciale
└── Ciclo Attivo (offerte, ordini, fatture clienti, DDT)

```

**Caratteristiche AS-IS:**

- Thin client (interfaccia testuale o UI leggera)
- Database proprietario (rimane tale — **non viene migrato**)
- Comunicazione via API/TCP tra thin client e backend COBOL
- Stampe documenti via GPE (editor desktop proprietario) + XSLT-FO + libGSSPM.dll

---

## 6.2 Il progetto a-SIGEA

Il progetto **a-SIGEA** (agentic-SIGEA) è il piano strategico di modernizzazione dell'intero ecosistema, finanziato dal bando **STEP - Regione Puglia** e con il supporto scientifico del **Politecnico di Bari (DMMM)**.

**Due direttive di ricerca:**

1. Evoluzione agentica della piattaforma SIGEA — architettura microservizi + AI
2. HAI per la Logistica — Humanized Augmented Intelligence, AR + AI per operatori logistici

### Transition AS-IS → TO-BE

```mermaid
graph LR
    subgraph "AS-IS (oggi)"
        TC1[Thin Client legacy]
        ERP1[eSIGEA COBOL monolite]
        DB1[(Database proprietario eSIGEA\n— invariato)]
        GPE1[GPE Desktop stampe]
    end

    subgraph "TO-BE (a-SIGEA target)"
        TC2[Angular SPA nuovo ERP]
        MS[Microservizi Spring Boot]
        DB_NEW[(PostgreSQL\nnuovi servizi\nGPE_NEXT + nuovo ERP)]
        AI_LAYER[Strato Agentico AI]
        DOCS[Gestione Documentale\n+ Knowledge Management]
        BI[BI Generativa]
        HAI2[HAI Interface AR + smart glasses]
        GPE2[GPE_NEXT ✅ stampe web]
    end

    TC1 -.->|evolve| TC2
    ERP1 -.->|coesiste e usa bridge API| GPE2
    GPE1 -.->|sostituito da| GPE2

```

> **Nota:** il database proprietario di eSIGEA **non migra** a PostgreSQL. PostgreSQL è il database di GPE\_NEXT e del nuovo ERP Angular — sistemi nuovi che si affiancano all'ERP COBOL esistente, non lo sostituiscono in blocco.

---

## 6.3 Posizionamento di GPE\_NEXT

```mermaid
graph TB
    subgraph "a-SIGEA — Mappa Moduli"
        M1[GPE_NEXT\nEditor Stampe Web\n✅ PRONTO]
        M2[Nuovo ERP\nAngular + Spring Boot\n🔄 In sviluppo]
        M3[Strato Agentico\nMicroservizi AI\n📋 Pianificato]
        M4[BI Generativa\nReportistica NL\n📋 Pianificato]
        M5[Gestione Documentale\nKnowledge Management\n📋 Pianificato]
        M6[HAI Logistica\nAR + Smart Glasses\n🔬 Ricerca]
    end

    M1 ---|integra con| M2
    M2 ---|usa| M3
    M3 ---|alimenta| M4
    M3 ---|gestisce| M5
    M3 ---|potenzia| M6
    M1 ---|output documenti per| M4

```

**GPE\_NEXT oggi:**

- Modulo 1 completato di a-SIGEA
- Risolve un pain point immediato e misurabile (stampe)
- Genera valore per i clienti correnti senza aspettare altri moduli
- Pone le basi architetturali (multi-tenant, REST API, JWT Keycloak) riutilizzabili dai moduli successivi

---

## 6.4 Come GPE\_NEXT connette i due mondi ERP

Entrambi gli ERP ottengono i PDF attraverso la **stessa API REST** di GPE\_NEXT. La differenza è solo nel chiamante.

```mermaid
graph TB
    subgraph "ERP COBOL eSIGEA (legacy)"
        ERP_C[eSIGEA COBOL\ngenera XML dati]
        BRIDGE[Bridge integrato\nnell'ERP COBOL]
        PDF_C[PDF output per utente]
    end

    subgraph "GPE_NEXT"
        GPN_API[POST /api/render\nREST API]
        HTML_GEN[HtmlTemplateService\n+ Saxon XSLT 2.0]
        GOTENBERG[Gotenberg\nChromium PDF]
        DB[(PostgreSQL\ntenant + template)]
    end

    subgraph "Nuovo ERP Angular"
        ERP_A[Nuovo ERP Angular\ngenera XML dati]
        PDF_A[PDF output WYSIWYG]
    end

    ERP_C --> BRIDGE
    BRIDGE -->|POST /api/render\nBearer JWT + XML| GPN_API
    ERP_A -->|POST /api/render\nBearer JWT + XML| GPN_API
    GPN_API --> DB
    GPN_API --> HTML_GEN --> GOTENBERG
    GOTENBERG -->|PDF| BRIDGE --> PDF_C
    GOTENBERG -->|PDF| PDF_A

```

> **XSLT-FO:** GPE\_NEXT conserva la funzionalità di generare file `.xslt-xfo` scaricabili — strumento di ispezione/diagnostica, non il flusso stampa attivo.

---

## 6.5 GPE\_NEXT come foundation per i moduli futuri

### Integrazione con Modulo 2 (Nuovo ERP) — operativa

GPE\_NEXT è **già integrato** con il nuovo ERP Angular:

- `POST /api/render` — lo stesso endpoint usato dal bridge COBOL
- JWT multi-tenant compatibile con Keycloak (stesso realm `gsauth`)
- Template versioning con selezione automatica per versione ERP
- Wizard migrazione template per upgrade versione ERP

Questa è l'unica integrazione diretta e confermata tra GPE\_NEXT e gli altri moduli a-SIGEA.

### Relazione con M3, M4, M5, M6 — nessuna integrazione pianificata

GPE\_NEXT è un **modulo verticale specifico** (stampe): risolve un problema preciso e lo fa bene. Non è una piattaforma trasversale.

- **M3 Strato Agentico**: si collegherà direttamente al DB dell'ERP — non passerà per GPE\_NEXT
- **M4 BI Generativa**: lavora con dati strutturati dal DB — i PDF non sono input utili alla BI
- **M5 Gestione Documentale**: se e quando esisterà, potrà archiviare i PDF generati da GPE\_NEXT, ma è una relazione indiretta e non pianificata
- **M6 HAI Logistica**: GPE\_NEXT genera i documenti logistici (DDT, etichette) che gli operatori usano — ma l'interfaccia AR/smart glasses è un progetto separato senza integrazione diretta con GPE\_NEXT

GPE\_NEXT porta valore **autonomamente**, indipendentemente dall'evoluzione degli altri moduli.

---

## 6.6 Integrazioni esterne identificate

<table id="bkmrk-sistema-tipo-integra"><thead><tr><th>Sistema</th><th>Tipo integrazione</th><th>Status</th></tr></thead><tbody><tr><td>ERP COBOL (eSIGEA)</td><td>Bridge nell'ERP chiama `POST /api/render`</td><td>✅ Operativo</td></tr><tr><td>Nuovo ERP Angular (M2)</td><td>REST API `POST /api/render` — stessa API del COBOL</td><td>✅ Operativo</td></tr><tr><td>Keycloak OIDC</td><td>Auth SSO (realm `gsauth`)</td><td>✅ Operativo</td></tr><tr><td>Gotenberg (Chromium)</td><td>PDF generation interna</td><td>✅ Operativo</td></tr><tr><td>Viewer XML in-browser (BRG)</td><td>XSL bridge per aprire XML ERP nel browser</td><td>📋 Pianificato</td></tr><tr><td>Altri moduli a-SIGEA (M3/M4/M5/M6)</td><td>Nessuna integrazione pianificata</td><td>—</td></tr></tbody></table>

---

## 6.7 Integrazioni ERP — dettaglio

### Bridge eSIGEA → GPE\_NEXT (operativo)

Il bridge integrato nell'ERP COBOL consente a eSIGEA di chiamare GPE\_NEXT tramite la sua REST API. Quando eSIGEA deve stampare:

1. eSIGEA genera l'XML dati del documento
2. Il bridge chiama `POST /api/render` con il JWT di autenticazione e l'XML come body
3. GPE\_NEXT risolve il tenant, il template attivo e la versione ERP compatibile
4. GPE\_NEXT genera HTML → Gotenberg → restituisce il PDF al bridge
5. eSIGEA consegna il PDF all'utente

### Viewer XML in-browser (BRG — pianificato)

Un XSL "ponte" separato (`gpenext-bridge.xsl`, epic BRG-001→005) è pianificato per permettere di aprire qualsiasi XML ERP direttamente nel browser come visualizzazione PDF, senza passare dall'applicazione desktop. Questo epic è **distinto e separato** dal bridge operativo — è uno strumento UI per operatori, non un'integrazione di backend.

---

## 6.8 Timeline evolutiva

```mermaid
gantt
    title a-SIGEA — Timeline evolutiva (stima)
    dateFormat  YYYY-MM
    axisFormat  %m/%Y

    section GPE_NEXT (M1)
    Sviluppo core              :done, 2026-03, 2026-05
    Feature parity + UX        :done, 2026-04, 2026-06
    Primo test cliente          :active, 2026-06, 2026-07
    Deploy produzione           :2026-07, 2026-08
    v2 features (grafici, etc.) :2026-08, 2026-12

    section Nuovo ERP (M2)
    Sviluppo in corso           :active, 2025-01, 2027-06
    Integrazione GPE_NEXT       :2026-06, 2026-10
    Beta clienti                :2027-01, 2027-06

    section Strato AI (M3)
    Ricerca industriale (RI)    :2026-07, 2027-01
    Sviluppo microservizi       :2027-01, 2028-06

    section BI Generativa (M4)
    Sviluppo                    :2027-06, 2028-12

    section HAI Logistica (M6)
    Ricerca (TRL5→TRL8)         :2026-07, 2028-12

```

---

## 6.9 Valore strategico del progetto

### Per Genesys Software

- **Differenziazione competitiva:** unico ERP COBOL italiano con modulo web di design stampe
- **Fidelizzazione clienti:** migliore UX → maggiore soddisfazione → minor churn
- **Scalabilità:** architettura web multi-tenant → nuovi clienti senza installazioni locali
- **Foundation tecnologica:** pattern architetturali riusabili per tutti i moduli a-SIGEA

### Per i clienti dell'ERP

- **Autonomia:** possono personalizzare i propri modelli senza dipendere da Genesys
- **Velocità:** nuovo modello in ore invece che giorni
- **Qualità:** output PDF professionale con preview WYSIWYG
- **Continuità:** compatibilità totale con il vecchio COBOL durante la transizione

### Nel contesto di a-SIGEA

GPE\_NEXT è il **Modulo 1 completato** di a-SIGEA: risolve un problema reale e immediato (le stampe ERP) e consegna valore ai clienti oggi, prima ancora che gli altri moduli esistano. Il suo ruolo nel piano a-SIGEA è questo — non è un layer trasversale, è un pezzo autonomo che funziona da solo e si integra concretamente solo con il nuovo ERP (M2).

---

# 7. Roadmap

---

## Legenda

<table id="bkmrk-simbolo-significato-"><thead><tr><th>Simbolo</th><th>Significato</th></tr></thead><tbody><tr><td>✅</td><td>Completato</td></tr><tr><td>🔄</td><td>In corso</td></tr><tr><td>📋</td><td>Pianificato (backlog)</td></tr><tr><td>🔮</td><td>Futuro (v2+)</td></tr><tr><td>🔴</td><td>Bloccante / Alta priorità</td></tr></tbody></table>

---

## 7.1 v1 — Release corrente (giugno 2026)

### Funzionalità completate ✅

**Foundation:**

- Design system SCSS + PrimeNG Aura dark
- Backend Spring Boot + PostgreSQL + Flyway
- JWT Auth + Keycloak OIDC multi-tenant
- Multi-tenant isolation (tenant da JWT groups)

**Core Engine:**

- XML → XSD conversion engine (230+ XML ERP testati)
- XSD Parser + Data Field Tree API
- Template JSON model (dual-side TS+Java)
- Template CRUD REST API
- XSLT-FO Generator Engine (piena compatibilità COBOL, per download/diagnostica)
- PDF Engine via Gotenberg (Chromium, WYSIWYG)
- 7 postprocessing fixes per `libGSSPM.dll`

**Designer Canvas:**

- Canvas 3-pannelli (data tree, canvas, property panel)
- Multi-sezione (Testa, Corpo, Piede, Left, Right)
- Elementi: Static, Data, Image, Barcode, code-xslt-field
- Snap to grid, Smart guides, Righelli mm
- Multi-select, Align &amp; Distribute
- Arrow key nudge, Draw mode, Guide draggabili
- Zoom/Pan (25–400%), Position overlay
- Copy/Paste/Duplicate, Z-order
- Undo/Redo stack completo
- Shortcut help overlay (F1)
- Keyboard accessibility WCAG 2.2 AA
- Canvas PDF-Fidelity mode
- Onboarding tour guidato (7 step)

**Tabelle:**

- 4 tipi riga (Header/Data/Total/Group Break)
- Tabelle affiancate, nested (3 livelli)
- Merge celle (colspan), bordi per cella
- Zebra striping, zebra per modulo
- Page break, anchor row, keep-together
- Sort keys, aggregate, group break
- SubstitutionList, FuncCall, Macro
- RecOutMode REC\_TO\_CELL
- Righe opzionali, condizioni tabella
- Cell content editor (segmenti misti)

**Multi-pagina:**

- Multi-PageModel (layout diversi per pagina)
- Navigazione tab-bar tra pagine
- XSL-FO multi-page-sequence
- Preview multi-pagina

**Output e Integrazione:**

- Live preview (Paged.js + Gotenberg)
- Viewer codice XSLT/XSL-FO (CodeMirror)
- REST API render `POST /api/render` per ERP (usata da nuovo ERP Angular + bridge ERP COBOL)
- Integrazione ERP COBOL eSIGEA via bridge REST API (bridge operativo in eSIGEA)
- Esportazione XSLT-FO (download file `.xslt-xfo` — funzionalità secondaria/diagnostica)
- Template versioning (draft/publish, storico versioni, ripristino)
- ERP version management + wizard migrazione
- Client dashboard + profili
- MDL legacy import (singolo + bulk)
- Stampa al volo (Ephemeral Print Override)

**Retrocompatibilità XSL-FO ERP:**

- Fix parametri XPath (`rawSelect` as-is) — TASK-149 ✅
- Fix `$IMGDIR`/`$PROCLIB` come testo letterale — TASK-156 ✅
- Fallback path immagini `src-alt-N` — TASK-150 ✅
- Fix `align` dual-output (ERP `fo:external-graphic` vs FOP `fo:block`) — TASK-157 ✅

**Sicurezza:**

- Rate limiting login, XPath whitelist
- MDC pseudonimizzato, error sanitization
- Structured logging JSON

---

## 7.2 v1.1 — Q3 2026 (in pianificazione)

### Priorità alta 🔴

<table id="bkmrk-feature-epic-id-note"><thead><tr><th>Feature</th><th>Epic ID</th><th>Note</th></tr></thead><tbody><tr><td>Admin Panel (Utenti/Tenant)</td><td>TASK-048</td><td>Gestione tenant da UI</td></tr><tr><td>Client Personalization avanzata</td><td>TASK-032</td><td>Personalizzazioni per-tenant</td></tr><tr><td>Print API pubblica + Swagger</td><td>PAPI-001→012</td><td>API documentata per nuovo ERP</td></tr><tr><td>Viewer XML in-browser (BRG)</td><td>BRG-001→005</td><td>Apri XML ERP direttamente nel browser</td></tr><tr><td>Elementi liberi nel Body</td><td>TASK-124</td><td>Free-position nel body</td></tr></tbody></table>

### Priorità media

<table id="bkmrk-feature-epic-id-note-1"><thead><tr><th>Feature</th><th>Epic ID</th><th>Note</th></tr></thead><tbody><tr><td>Sentry self-hosted OCI</td><td>MANUAL-005</td><td>Error tracking</td></tr><tr><td>Bulk Format Tabella</td><td>TASK-089</td><td>Formattazione massiva</td></tr><tr><td>Stile Condizionato per Cella</td><td>TASK-093</td><td>CSS condizionale celle</td></tr><tr><td>Gestione Logo Per-Tenant</td><td>TASK-151</td><td>Gallery logo per ditta</td></tr><tr><td>Custom Fields Ditta</td><td>DCF-001→003</td><td>Equivalente custom\_tag.xml</td></tr><tr><td>Import MDL: Warning elementi</td><td>BULK-006/007</td><td>Visibilità parsing warning</td></tr><tr><td>Virtual Scrolling Data Tree</td><td>TASK-039</td><td>Performance tree grandi</td></tr></tbody></table>

---

## 7.3 v2 — Q4 2026 / Q1 2027

### Wizard Grafico (Charts)

```mermaid
graph LR
    XML[Dati XML ERP] --> AGG[ChartDataAggregatorService\nsum/avg/count per XPath]
    AGG --> CHART_WIZ[Wizard 4 step\ntipo · dati · stile · preview]
    CHART_WIZ --> CANVAS_EL[ChartCanvasElement\nChart.js preview]
    CHART_WIZ --> SVG_BE[SVG renderer Backend\nApache Batik]
    SVG_BE --> PDF_CHART[Grafico nel PDF]

```

Bar chart, Line chart, Pie chart da dati XML aggregati via XPath — output SVG nel PDF.

### Funzionalità aggiuntive v2

<table id="bkmrk-feature-id-note-ante"><thead><tr><th>Feature</th><th>ID</th><th>Note</th></tr></thead><tbody><tr><td>Anteprima massiva PDF (ZIP)</td><td>PDF-001→005</td><td>Batch preview tutti i modelli</td></tr><tr><td>Macro PAGE\_NUM\_INC / PAGE\_TOT\_INC</td><td>TASK-080</td><td>Numerazione avanzata</td></tr><tr><td>Mini-Outline Template Navigator</td><td>TASK-082</td><td>Navigazione struttura</td></tr><tr><td>Dark/Light Theme Toggle</td><td>TASK-046</td><td>Per designer</td></tr><tr><td>Advanced Template Search &amp; Filter</td><td>TASK-045</td><td>Ricerca avanzata</td></tr><tr><td>CI/CD GitHub Actions</td><td>DEPLOY-019</td><td>Pipeline automatica</td></tr></tbody></table>

---

## 7.4 v3 — 2027 (visione)

### Integrazione Strato Agentico

```mermaid
graph TB
    USER([Operatore]) --> AI[AI Agent\nstrato agentico a-SIGEA]
    AI -->|Crea modello fattura| GPN_API[GPE_NEXT API]
    GPN_API -->|Analizza XSD| SCHEMA_ANALYSIS[Schema Analysis]
    SCHEMA_ANALYSIS -->|Proposta layout| AI
    AI -->|Crea template| GPN_API
    GPN_API -->|Template generato| PREVIEW[Preview automatica]
    PREVIEW --> USER
    USER -->|Approva| PUBLISH[Pubblica]

```

- Template generation via AI: AI analizza XSD e propone layout automatico
- Natural language configuration: "sposta il logo in alto a destra"
- Smart field mapping: AI suggerisce binding XPath contestuale

### Integrazione BI Generativa e HAI Logistica

- GPE\_NEXT espone metadati semantici dei documenti → BI Generativa aggrega e analizza
- Template stampa documenti logistici (DDT, etichette) → stampa da smart glasses AR

---

## 7.5 KPI

<table id="bkmrk-kpi-target-v1-target"><thead><tr><th>KPI</th><th>Target v1</th><th>Target v2</th></tr></thead><tbody><tr><td>Template importati da legacy MDL</td><td>100% fedeltà</td><td>—</td></tr><tr><td>Tempo creazione modello vs GPE</td><td>-60%</td><td>-80%</td></tr><tr><td>Bug segnalati in produzione</td><td>&lt; 5 critici</td><td>0</td></tr><tr><td>Tempo risposta API render</td><td>&lt; 2s</td><td>&lt; 1s</td></tr><tr><td>Clienti su piattaforma</td><td>3-5 pilota</td><td>20+</td></tr><tr><td>Tipi documento supportati</td><td>230+</td><td>300+</td></tr><tr><td>Test automatici passing</td><td>900+</td><td>1200+</td></tr></tbody></table>

---

*Documento generato: giugno 2026 — versione consolidata da 8 file di documentazione*

# JG2 - API Reference

# 4. API Reference

> **Base URL:** `https://{host}/api`**Auth:** Bearer JWT (Keycloak OIDC) — header `Authorization: Bearer <token>`**Tenant:** estratto automaticamente dal claim `groups` del JWT

---

## 4.1 Autenticazione

### Flusso OIDC (produzione)

```mermaid
sequenceDiagram
    participant U as Browser
    participant KC as Keycloak gsauth
    participant BE as GPE_NEXT Backend

    U->>KC: Redirect login
    KC-->>U: Access Token (JWT)
    U->>BE: Request + Authorization: Bearer JWT
    BE->>KC: Valida token (JWKS)
    BE-->>U: Response (tenant isolato)

```

**Realm:** `gsauth` | **Client:** `gpenext`

Token claims usati:

- `sub` → user ID
- `groups` → `/client/{keycloak_group_path}` → tenant
- `realm_access.roles` → `SUPER_ADMIN`, `OPERATOR`, `CLIENT`

---

## 4.2 Endpoint — Schemas (Tipi Documento)

### `GET /schemas`

Lista tutti gli schemi del tenant corrente. **Ruoli:** OPERATOR, SUPER\_ADMIN

**Response 200:**

```json
[
  {
    "id": "uuid",
    "name": "EFATT121_1P",
    "documentType": "EFATT121_1P",
    "documentLabel": "Fattura",
    "erpMinVersion": "6.9.0.0",
    "forceMigration": false,
    "hasDittaXpath": true,
    "xmlFilesCount": 3
  }
]

```

### `POST /schemas`

Crea schema vuoto. **Ruoli:** OPERATOR

### `POST /schemas/{id}/xsd`

Upload file XSD. `multipart/form-data`: `xsdFile`, `displayName`

### `POST /schemas/{id}/xml-files`

Upload file XML di test. `multipart/form-data`: `xmlFile`, `displayName`

### `GET /schemas/{id}/fields`

Albero dei campi XSD per il data tree nel designer.

**Response 200:**

```json
{
  "root": "RFAMEZ2D",
  "fields": [
    {
      "name": "TESTA",
      "type": "complex",
      "xpath": "/RFAMEZ2D/TESTA",
      "children": [
        { "name": "CODE_DITT", "type": "string", "xpath": "/RFAMEZ2D/TESTA/CODE_DITT" }
      ]
    }
  ]
}

```

### `PUT /schemas/{id}/ditta-xpath`

Aggiorna XPath per il codice ditta. **Ruoli:** OPERATOR

```json
{ "dittaCodeXPath": "./TESTA/CODE_DITT" }

```

---

## 4.3 Endpoint — Templates (Modelli)

### `GET /templates`

Lista modelli del tenant. Params: `schemaId`, `isBase`

### `POST /templates`

Crea nuovo modello. **Ruoli:** OPERATOR

```json
{
  "name": "Fattura Personalizzata",
  "profileName": "custom",
  "schemaId": "uuid",
  "xmlFileId": "uuid",
  "orientation": "portrait",
  "pageFormat": "A4"
}

```

### `GET /templates/{id}`

Dettaglio completo template (include contenuto JSON JSONB).

### `PUT /templates/{id}`

Salva il modello (bozza). **Ruoli:** OPERATOR

### `DELETE /templates/{id}`

Elimina modello. **Ruoli:** OPERATOR

### `POST /templates/{id}/clone`

Clona modello (crea profilo cliente).

```json
{
  "profileName": "profilo-cliente-xyz",
  "targetTenantId": "uuid"
}

```

### `PUT /templates/{id}/activate`

Attiva un profilo come default per il tipo documento del tenant. **Ruoli:** OPERATOR, SUPER\_ADMIN

### `POST /templates/{id}/publish`

Pubblica il template (crea versione pubblicata). **Ruoli:** OPERATOR

**Response 200:**

```json
{
  "versionId": "uuid",
  "publishedAt": "2026-06-19T10:00:00Z",
  "erpMinVersion": "6.9.0.0"
}

```

### `GET /templates/{id}/versions`

Storico versioni pubblicate del template.

### `PATCH /templates/{id}/restore/{versionId}`

Ripristina una versione storica come contenuto corrente.

### `POST /templates/{id}/publish-xslfo`

Genera e scarica il file `.xslt-xfo` (funzionalità secondaria).

**Query params:** `writeToDisk` (boolean, default: false)

**Response 200:**

```
Content-Type: application/xml; charset=ISO-8859-1
Content-Disposition: attachment; filename="EFATT121_1P_xfo.xsl"
X-Published-Path: /gsnr/gpe-next/data/xslfo/tenant-uuid/EFATT121_1P_xfo.xsl

```

### `GET /templates/{id}/xslfo-source`

Visualizza il codice XSLT-FO generato senza scaricare. **Ruoli:** OPERATOR

### `POST /templates/{id}/preview`

Genera anteprima PDF del template.

```json
{ "xmlFileId": "uuid", "overrides": {} }

```

### `POST /templates/bulk-import`

Import massivo file `.mdl` legacy. `multipart/form-data`: `files[]`

### `POST /templates/import-mdl`

Import singolo file `.mdl`. `multipart/form-data`: `mdlFile`, `schemaId`, `mode` (auto|manual)

---

## 4.4 Endpoint — Render (Integrazione ERP)

### `POST /render`

**Endpoint principale per ERP.** Riceve XML dati ERP, restituisce PDF. Usato sia dal nuovo ERP Angular che dal bridge ERP COBOL eSIGEA.

**Ruoli:** OPERATOR, CLIENT, SUPER\_ADMIN (tipicamente chiamato da ERP con service account)

**Request:**

```
Content-Type: application/xml
Authorization: Bearer <JWT>

<?xml version="1.0" encoding="UTF-8"?>
<EFATT121>
  <estr_cont>...dati fattura...</estr_cont>
</EFATT121>

```

**Query params:**

- `documentType` (string) — tipo documento (es. `EFATT121_1P`)
- `erpVersion` (string, opzionale) — versione ERP per selezione template
- `profileName` (string, opzionale) — profilo specifico

**Response 200:** PDF binario **Response 404:** nessun template attivo per il tipo documento **Response 422:** XML malformato o non valido contro XSD

### `GET /render/version-info`

Info versione template che verrebbe usato per un dato documento.

---

## 4.5 Endpoint — Client Dashboard

### `GET /client/dashboard`

Dashboard con tutti i documenti disponibili per il tenant. **Ruoli:** CLIENT, OPERATOR

### `GET /client/documents/{documentType}/profiles`

Lista profili disponibili per un tipo documento. **Ruoli:** CLIENT

---

## 4.6 Endpoint — Me / Tenant Info

### `GET /me/tenant`

Info sul tenant e utente corrente.

**Response 200:**

```json
{
  "tenantId": "uuid",
  "tenantSlug": "azienda-xyz",
  "companyName": "Azienda XYZ S.r.l.",
  "role": "OPERATOR",
  "erpVersion": "6.9.0.0"
}

```

---

## 4.7 Endpoint — Immagini

### `POST /images`

Upload immagine/logo. `multipart/form-data`: `image`, `displayName`

### `GET /images/{id}/content`

Scarica il contenuto binario dell'immagine.

---

## 4.8 Endpoint — Admin (SUPER\_ADMIN only)

### `GET /admin/tenants` — Lista tutti i tenant

### `PUT /admin/tenants/{id}/erp-version` — Imposta versione ERP per un tenant

### `GET /admin/templates` — Lista tutti i template cross-tenant

---

## 4.9 Codici di errore

<table id="bkmrk-codice-situazione-40"><thead><tr><th>Codice</th><th>Situazione</th></tr></thead><tbody><tr><td>`400`</td><td>Richiesta malformata</td></tr><tr><td>`401`</td><td>Token JWT mancante o scaduto</td></tr><tr><td>`403`</td><td>Ruolo insufficiente o tentativo cross-tenant</td></tr><tr><td>`404`</td><td>Risorsa non trovata (o non appartiene al tenant)</td></tr><tr><td>`409`</td><td>Conflitto (es. nome duplicato)</td></tr><tr><td>`422`</td><td>XML non valido contro XSD</td></tr><tr><td>`500`</td><td>Errore interno (log su Sentry)</td></tr></tbody></table>

**Formato errore:**

```json
{
  "status": 404,
  "error": "Not Found",
  "message": "Template not found",
  "timestamp": "2026-06-19T10:00:00Z"
}

```

---

## 4.10 Esempi curl

```bash
# Render PDF da XML ERP (nuovo ERP o bridge COBOL)
curl -X POST https://gpenext.host/api/render \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/xml" \
  -d @fattura.xml \
  --query "documentType=EFATT121_1P" \
  -o output.pdf

# Scaricare XSLT-FO (funzionalità secondaria)
curl -X POST https://gpenext.host/api/templates/{id}/publish-xslfo \
  -H "Authorization: Bearer $TOKEN" \
  -o EFATT121_1P_xfo.xsl

```

---

# 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à

<table id="bkmrk-selezione-pannello-m"><thead><tr><th>Selezione</th><th>Pannello mostrato</th></tr></thead><tbody><tr><td>Nessuno</td><td>Hint d'uso</td></tr><tr><td>Elemento (testo/campo/immagine)</td><td>Stile, posizione, binding, condizione</td></tr><tr><td>Tabella</td><td>Configurazione tabella, stile, colonne</td></tr><tr><td>Riga tabella</td><td>Tipo, visibilità, condizione, anchor</td></tr><tr><td>Cella tabella</td><td>Contenuto segmenti, stile cella, colspan</td></tr><tr><td>Multi-selezione</td><td>Allinea, distribuisci, dimensioni</td></tr><tr><td>Sezione (testa/corpo/piede)</td><td>Altezza, margini</td></tr></tbody></table>

---

## 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

<table id="bkmrk-shortcut-azione-ctrl"><thead><tr><th>Shortcut</th><th>Azione</th></tr></thead><tbody><tr><td>`Ctrl+Z`</td><td>Undo</td></tr><tr><td>`Ctrl+Y` / `Ctrl+Shift+Z`</td><td>Redo</td></tr><tr><td>`Ctrl+S`</td><td>Salva bozza</td></tr><tr><td>`Ctrl+C/V`</td><td>Copia / Incolla</td></tr><tr><td>`Ctrl+Shift+V`</td><td>Incolla in posizione</td></tr><tr><td>`Ctrl+D`</td><td>Duplica</td></tr><tr><td>`Delete` / `Backspace`</td><td>Elimina elementi selezionati</td></tr><tr><td>`←↑→↓`</td><td>Sposta 1mm</td></tr><tr><td>`Shift+←↑→↓`</td><td>Sposta 10mm</td></tr><tr><td>`Enter`</td><td>Coordinate input rapido (mm)</td></tr></tbody></table>

### Zoom e Pan

<table id="bkmrk-shortcut-azione-ctrl-1"><thead><tr><th>Shortcut</th><th>Azione</th></tr></thead><tbody><tr><td>`Ctrl+scroll`</td><td>Zoom in/out centrato sul cursore</td></tr><tr><td>`Ctrl+0`</td><td>Zoom 100%</td></tr><tr><td>`Ctrl+1`</td><td>Zoom to Fit</td></tr><tr><td>`Ctrl+2`</td><td>Zoom to Selection</td></tr><tr><td>`Spazio+drag`</td><td>Pan libero</td></tr></tbody></table>

### Allineamento (multi-selezione)

<table id="bkmrk-shortcut-azione-alt%2B"><thead><tr><th>Shortcut</th><th>Azione</th></tr></thead><tbody><tr><td>`Alt+L/C/R`</td><td>Allinea sinistra / centro / destra</td></tr><tr><td>`Alt+T/M/B`</td><td>Allinea alto / centro / basso</td></tr><tr><td>`Alt+H/V`</td><td>Distribuisci orizzontalmente / verticalmente</td></tr></tbody></table>

### Altro

<table id="bkmrk-shortcut-azione-%3F-%2F-"><thead><tr><th>Shortcut</th><th>Azione</th></tr></thead><tbody><tr><td>`?` / `F1`</td><td>Apri overlay aiuto scorciatoie</td></tr><tr><td>`R`</td><td>Toggle righelli</td></tr><tr><td>`G`</td><td>Toggle griglia</td></tr><tr><td>`Esc`</td><td>Deseleziona / chiudi dialog</td></tr></tbody></table>

---

## 5.10 Accessibilità

GPE\_NEXT segue le linee guida **WCAG 2.2 AA**:

- Navigazione keyboard completa, alternative keyboard per Drag &amp; Drop
- `aria-*` su tutti i componenti interattivi
- Contrasto colori AA su tutti i temi
- `cdkTrapFocus` nei dialog, `role="status"` su banner informativi

---