Analisi Unificata dell'Architettura Sistec HMI

Progetti analizzati: Sistec.5315 (LAG) — HMI Pressopiegatrice / Cella di Produzione
+ Sistec.5309 (FAEL) — HMI Cella di Produzione
Data: Luglio 2026
Scopo: Analisi trasversale dell'architettura Sistec HMI, identificazione degli antipattern comuni, e proposta di un'architettura modulare unificata applicabile a qualsiasi commessa

Premessa

Le codebase 5315_LAG e 5309_FAEL condividono lo stesso software di base HMI per celle di produzione Sistec. Ogni commessa (LAG, FAEL, future) presenta un layout impianto diverso con macchinari differenti, ma il fulcro applicativo — interfaccia PLC, gestione produzione, robot KUKA, presse, tracciamento job — è comune.

Decisione Strategica

Le commesse esistenti (LAG, FAEL) non vengono refattorizzate. L'architettura target descritta in questo documento è il blueprint per la prossima commessa, da sviluppare ex-novo seguendo i principi di stack verticali, NuGet, DI, Layout Engine e Avalonia.

1. Architettura Corrente: Monolite Condiviso

1.1 Progetti Fondazione (identici in entrambi)

flowchart TB
    subgraph Foundation["LIBRERIE FONDAZIONE (identiche)"]
        Core["Sistec.Core (netstandard2.1)
Modelli · Interfacce · Enum · Utils
215-219 file"]
        Controls["Sistec.Controls (net8.0-windows)
Bottoni, LED, Motori, Valvole
Controlli generici WinForms"]
        UI["Sistec.UI (net8.0-windows)
Layout pagine, dialoghi base
44 file"]
        OpcUa["Sistec.Opc.Ua (netstandard2.1)
Wrapper OPC UA Foundation SDK
19 file"]
    end

    subgraph LAG_Only["SOLO 5315 LAG"]
        Safan["Sistec.Safan (netstandard2.1)
Client TCP pressa Safan
Test NUnit + Simulator"]
        Sinumerik["Sistec.Sinumerik (netstandard2.1)
Adattatore CNC Siemens ONE
LagNx1525 + Simulazione"]
    end

    subgraph FAEL_Only["SOLO 5309 FAEL"]
        KukaClient["Kuka.Client (netstandard2.1)
Client TCP KRC robot
11 file"]
        EsaClient["Esa.Client (netstandard2.1)
Client Modbus pressa ESA
6 file"]
        EasyModbus["EasyModbus (netstandard2.1)
Stack Modbus TCP puro"]
        Bus["Sistec.Bus (net8.0-windows)
Zebus messaging pub/sub"]
    end

    Foundation --> LAG_Only
    Foundation --> FAEL_Only

1.2 Il God Project: Sistec.HMI/Common / Sistec.5315/Common

flowchart LR
    subgraph Common["⚠️ PROGETTO COMUNE (God Project)"]
        CL["Logic/
Business logic"]
        CC["Controls/
User controls applicativi"]
        CDB["DB/
Repository implementazioni"]
        CDTO["DTO/
Data Transfer Objects"]
        CDUT["DUT/
Data Unit Type (OPC UA)"]
        CModel["Model/
Modelli dominio applicativi"]
        CCells["Cells/
Viste cella"]
        CDialogs["Dialogs/
Finestre dialogo"]
        CLayout["Layout/
Pagine layout"]
        CFrmHMI["FrmHMI/
LogicFactory, LogicCollection"]
    end

    Common -->|LAG| LAG_Refs["Sistec.Controls, Core, OpcUa,
Safan, Sinumerik"]
    Common -->|FAEL| FAEL_Refs["Kuka.Client, Bus, Controls,
Core, OpcUa"]

Metriche comuni:

1.3 Le God Class

flowchart LR
    subgraph LAG["5315 LAG"]
        MF["MainForm
19 partial file
Orchestrazione centrale:
PLC, KUKA, Safan,
Sinumerik, Watchdog,
Job, pagine, popup"]
    end
    subgraph FAEL["5309 FAEL"]
        FH["FrmHMI (AB)
24 partial file, ~5.156 righe
Orchestrazione centrale:
PLC, KUKA, Modbus,
ESA, DB, Watchdog,
Produzione, Manutenzione"]
        FHC["FrmHMI (C)
17 partial file, ~2.499 righe
Stesso pattern,
copia ridotta"]
    end

    LAG -->|Stesso anti-pattern| FAEL

In entrambi i casi: il costruttore del Form principale inizializza manualmente TUTTO (OPC UA, tag PLC, logics, watchdog, eventi) senza DI container.

1.4 Stack Frammentato: KUKA Robot

Il robot KUKA è l'esempio perfetto di bassa coesione in entrambe le codebase:

flowchart TB
    subgraph Legend["Legenda"]
        LAG_STYLE["LAG: in Sistec.Core/Interfaces + Sistec.5315/Common/Logic"]
        FAEL_STYLE["FAEL: in Kuka.Client separato + Sistec.HMI/Common/Logic"]
    end

    subgraph Scattered["KUKA — FRAMMENTATO"]
        Interfaces["Interfacce
LAG: Sistec.Core/Interfaces/IRobotLogic
FAEL: (mancante, uso diretto)"]
        Client["Client TCP KRC
LAG: assente (mescolato)
FAEL: Kuka.Client ✅"]
        Logic["Logica Robot
LAG: Common/Logic/RobotLogicKuka
FAEL: Common/Logic (misto)"]
        U1["UI Controls
LAG: Sistec.Controls/Robots +
Common/Controls/RobotCommands"]
        U2["FAEL: AB/Robots/ +
AB/FrmHMI/FrmHMI.Robot.cs"]
        Config["Config
LAG: HMI/Config/Kuka.ini
FAEL: AB/Config/ + Common"]
    end

    Interfaces --> Logic
    Client --> Logic
    Logic --> U1
    Logic --> U2
    Logic --> Config

Per capire KUKA servono 5 progetti diversi in entrambe le codebase.

1.5 Anti-Pattern Trasversali

1.6 Sistec.Opc.Ua — Valutazione Libreria OPC UA

La libreria Sistec.Opc.Ua è il wrapper attorno all'OPC Foundation SDK (v1.5.376.244) usato da entrambe le commesse per tutta la comunicazione col PLC. È condivisa (stesso codice base) ma ha divergenze tra LAG e FAEL.

Giudizio sintetico: Stabile in funzionamento nominale, fragile in scenari di recovery, riavvio e carico.

Problemi Critici

Problemi Alti

Differenze LAG vs FAEL

Conclusione: FAEL ha ricevuto bugfix sostanziali che LAG non ha. La versione FAEL è la baseline consigliata per il nuovo Sistec.Stack.PLC.

Impatto sull'Architettura Target

Attenzione — principio chiave: Sistec.Library.OpcUa è una libreria orizzontale, NON una libreria verticale del solo PLC. Può essere usata da PIÙ stack (PLC, Sinumerik, e potenzialmente robot KUKA se via OPC UA). Non va duplicata. Lo stesso vale per Sistec.Library.Modbus e Sistec.Library.Tcp.

Nell'architettura a stack verticali (§2), Sistec.Opc.Ua si decompone in:

Regola: Se un domani KUKA dovesse supportare OPC UA, Sistec.Stack.Kuka.Client dipenderà da Sistec.Library.OpcUa — senza duplicare nulla.

La logica di connessione, certificati, riconnessione va mantenuta ma con:

• IDisposable pattern standard
• CancellationToken canonicamente usato (non Task.Delay(Infinite))
• SemaphoreSlim o ConcurrentQueue per _pendingSubscriptions
• Eventi con weak reference o unsubscribe esplicito
• ReconnectionPolicy configurabile via IOptions<T>

2. Architettura Proposta: Stack Verticali Unificati

2.1 Principi Guida

2.2 Struttura a Stack Verticali

Ogni dispositivo/dominio diventa uno stack verticale con 5 layer:

flowchart TB
    subgraph Legend["LEGENDA RELAZIONI"]
        DEP_DOTTED["● - - -> Dipende da libreria
orizzontale (condivisa)"]
        DEP_SOLID["● ──→ Dipende da layer interno
dello stesso stack"]
    end

    subgraph Stack["Sistec..Stack (es. Sistec.Stack.Kuka)"]
        direction TB
        UI["Sistec..Stack.UI
UserControls, Pages
WinForms view layer"]
        SVC["Sistec..Stack.Services
Orchestrators, Use Cases
Logica applicativa"]
        DRV["Sistec..Stack.Driver
ITagProvider, TagValue<T>
Astrazione device → dominio"]
        CLI["Sistec..Stack.Client
Logica client DEVICE-SPECIFICA
(usa libreria orizzontale
per il protocollo)"]
        SIM["Sistec..Stack.Simulator
Server mock / device finto
Test e sviluppo offline"]
    end

    subgraph Horizontal["LIBRERIE ORIZZONTALI
(condivise, MAI duplicate)"]
        TcpLib["Sistec.Library.Tcp
Socket pool, reconnect,
message framing"]
        ModbusLib["Sistec.Library.Modbus
Client/Server Modbus TCP"]
        OpcUaLib["Sistec.Library.OpcUa
UAClient, Session,
MonitoredItem"]
    end

    UI --> SVC
    SVC --> DRV
    DRV --> CLI
    SIM --> CLI
    CLI -.-o TcpLib
    CLI -.-o ModbusLib
    CLI -.-o OpcUaLib

    style Horizontal fill:#e0f7fa,stroke:#006064,stroke-dasharray: 5 5

NB: Il layer Client di ogni stack NON reimplementa il protocollo — usa le librerie orizzontali Sistec.Library.Tcp, Sistec.Library.Modbus, Sistec.Library.OpcUa. Queste sono un'istanza unica, condivisa tra tutti gli stack che ne hanno bisogno (es. Sistec.Library.OpcUa è usata da PLC e Sinumerik, e opzionalmente da KUKA).

Sistec.Library.Redis è la libreria trasversale per stato condiviso veloce — usata da tutti gli stack che necessitano hot data (sessioni, allarmi, pallet, contatori, metriche). Opzionale: se Redis non è configurato, i servizi degradano graceful su MySQL (§19.13).

2.3 Mappa degli Stack

flowchart TB
    subgraph Fondazione["FONDAZIONE"]
        Core["Sistec.Core
Modelli dominio, Interfacce pure
Enum, Eccezioni, Eventi
netstandard2.1"]
        Controls["Sistec.Controls
Controlli WinForms generici
Led, Button, Container, Motors, Valves
Nessuna logica di dominio"]
        SistecUI["Sistec.UI
Layout pagine, menu,
alarm banner, user management"]
    end

    subgraph Comunicazione["LIBRERIE ORIZZONTALI (condivise, MAI duplicate per stack)"]
        TcpLib["Sistec.Library.Tcp
Socket pool, reconnect
message framing
(usata da KUKA, Safan)"]
        OpcUaLib["Sistec.Library.OpcUa
UAClient, Session,
MonitoredItem
(usata da PLC, Sinumerik,
opzionalmente KUKA)"]
        ModbusLib["Sistec.Library.Modbus
EasyModbus puro
Client/Server Modbus TCP
(usata da ESA)"]
        BusLib["Sistec.Library.Bus
Zebus pub/sub o HTTP+Redis
Comunicazione inter-pannello"]
        RedisLib["Sistec.Library.Redis
Hot data layer trasversale
Sessioni, Allarmi, Pallet,
Traduzioni, Metriche
(opzionale)"]
    end

    subgraph Macchine["STACK VERTICALI — MACCHINE"]
        Kuka["Sistec.Stack.Kuka
Robot KUKA KRC
Client · Driver · Services · UI · Simulator"]
        Safan["Sistec.Stack.Safan
Pressa Safan (TCP)
Client · Driver · Services · UI · Simulator"]
        Esa["Sistec.Stack.Esa
Pressa ESA (Modbus)
Client · Driver · Services · UI · Simulator"]
        PlcInt["Sistec.Stack.PLC
Interfaccia PLC (OPC UA)
Client · Driver · Services · UI · Simulator"]
        Sinumerik["Sistec.Stack.Sinumerik
CNC Siemens ONE
Client · Driver · Services · UI · Simulator"]
    end

    subgraph Applicazione["STACK VERTICALI — APPLICAZIONE"]
        Production["Sistec.Stack.Production
Orchestrazione produzione
Services + UI"]
        JobMgmt["Sistec.Stack.JobManagement
Job lifecycle, tracking
Services + UI"]
        Maintenance["Sistec.Stack.Maintenance
Manutenzione, safety
Services + UI"]
        Alarms["Sistec.Stack.Alarms
Alarm journal, notifiche
Services + UI"]
    end

    subgraph Persistence["PERSISTENZA (multi-progetto)"]
        PersAbst["Sistec.Infra.Persistence
Interfacce repository,
Unit of Work contract"]
        PersDapper["Sistec.Infra.Persistence.Dapper
Implementazione Dapper"]
        PersMySql["Sistec.Infra.Persistence.MySql
MySqlConnector"]
        PersSqlSrv["Sistec.Infra.Persistence.SqlServer
Microsoft.Data.SqlClient"]
        PersUoW["Sistec.Infra.Persistence.UnitOfWork
Transaction scope"]
    end

    subgraph Config["CONFIGURAZIONE"]
        ConfigLib["Sistec.Configuration
Options pattern, INI/XML reader
IOptions<T>"]
    end

    subgraph CodeGen["CODE GENERATION"]
        DUTGen["Sistec.Infra.CodeGen
dotnet tool
CODESYS → POCO + OPC UA + TagConstants"]
    end

    Production -->|usa| Kuka
    Production -->|usa| Safan
    Production -->|usa| Esa
    Production -->|usa| PlcInt
    Production -->|usa| Sinumerik
    Production -->|usa| JobMgmt

    Kuka -.->|TCP| TcpLib
    Kuka -.->|opzionale OPC UA| OpcUaLib
    Safan -.->|TCP| TcpLib
    Esa -.->|Modbus| ModbusLib
    PlcInt -.->|OPC UA| OpcUaLib
    Sinumerik -.->|OPC UA| OpcUaLib

    Kuka --> Core
    Safan --> Core
    Esa --> Core
    PlcInt --> Core
    Sinumerik --> Core

    PersAbst --> Core
    PersDapper --> PersAbst
    PersMySql --> PersDapper
    PersSqlSrv --> PersDapper
    PersUoW --> PersDapper

    ConfigLib --> Core
    DUTGen --> PlcInt

    classDef foundation fill:#e1f5e1,stroke:#2e7d32
    classDef comm fill:#fce4ec,stroke:#c62828
    classDef machine fill:#e8f5e9,stroke:#2e7d32
    classDef app fill:#fff8e1,stroke:#f57f17
    classDef data fill:#f3e5f5,stroke:#7b1fa2
    classDef infra fill:#e0f7fa,stroke:#006064

    class Core,Controls,SistecUI foundation
    class TcpLib,OpcUaLib,ModbusLib,BusLib comm
    class Kuka,Safan,Esa,PlcInt,Sinumerik machine
    class Production,JobMgmt,Maintenance,Alarms app
    class PersAbst,PersDapper,PersMySql,PersSqlSrv,PersUoW data
    class ConfigLib,DUTGen infra

2.4 Librerie Orizzontali: Principio di Non Duplicazione

Le librerie orizzontali (Sistec.Library.Tcp, Sistec.Library.Modbus, Sistec.Library.OpcUa) sono un'unica istanza condivisa tra tutti gli stack. Non vanno mai replicate:

flowchart LR
    subgraph Orizzontali["LIBRERIE ORIZZONTALI — UNA SOLA COPIA"]
        Tcp["Sistec.Library.Tcp"]
        Opc["Sistec.Library.OpcUa"]
        Mod["Sistec.Library.Modbus"]
    end

    subgraph Stacks["STACK CHE LE USANO"]
        Kuka_Client["Sistec.Stack.Kuka.Client
KrcClient, KrcConnectionPool"]
        Safan_Client["Sistec.Stack.Safan.Client
SafanClient"]
        Plc_Client["Sistec.Stack.PLC.Client
OpcUaClientCollection"]
        Sinu_Client["Sistec.Stack.Sinumerik.Client
CNC OPC UA wrapper"]
        Esa_Client["Sistec.Stack.Esa.Client
EsaModbusClient"]
    end

    Tcp ---> Kuka_Client
    Tcp ---> Safan_Client
    Opc ---> Plc_Client
    Opc ---> Sinu_Client
    Opc -..->|opzionale| Kuka_Client
    Mod ---> Esa_Client

    style Orizzontali fill:#e0f7fa,stroke:#006064,stroke-dasharray: 5 5

Cosa contengono le librerie orizzontali:

Cosa contengono i Client verticali (esempi):

Regola pratica: se un pezzo di codice parla il protocollo (TCP framing, OPC UA session, Modbus PDU) → sta nella libreria orizzontale. Se parla con un dispositivo specifico (comando KUKA, registro ESA, nodo CNC) → sta nel Client verticale.

2.5 Stack KUKA — Dettaglio (Esempio Completo)

2.6 Stack Safan (LAG) — Dettaglio

2.7 Stack ESA (FAEL) — Dettaglio

2.8 Stack PLC — Dettaglio

2.9 Stack Sinumerik (LAG) — Dettaglio

2.10 Stack Produzione / Job Management — Dettaglio

2.11 Grafo Dipendenze (Unificato)

flowchart LR
    subgraph HMI_Apps["APPLICAZIONI HMI (Thin Shells)"]
        LAG_HMI["Sistec.5315.HMI
Composition Root +
pagine specifiche LAG"]
        FAEL_AB["Sistec.5309.HMI.AB
Composition Root +
pagine specifiche AB"]
        FAEL_C["Sistec.5309.HMI.C
Composition Root +
pagine specifiche C"]
        BS["Sistec.5309.HMI.BS
Composition Root +
pagine specifiche BS"]
    end

    subgraph Shell["SISTEC.HMI.SHELL (shared)"]
        CR["Program.cs + FrmHMI thin
DI Container + IOptions"]
    end

    subgraph Prod_Stacks["STACK APPLICATIVI"]
        Prod["Sistec.Stack.Production"]
        Job["Sistec.Stack.JobManagement"]
        Maint["Sistec.Stack.Maintenance"]
        Alarm["Sistec.Stack.Alarms"]
    end

    subgraph Machine_Stacks["STACK MACCHINA"]
        Kuka["Sistec.Stack.Kuka"]
        Safan["Sistec.Stack.Safan"]
        Esa["Sistec.Stack.Esa"]
        Plc["Sistec.Stack.PLC"]
        Sinu["Sistec.Stack.Sinumerik"]
    end

    subgraph Libraries["LIBRERIE FONDAZIONE"]
        Core["Sistec.Core"]
        Controls["Sistec.Controls"]
        SUI["Sistec.UI"]
        OPC["Sistec.Library.OpcUa"]
        Modbus["Sistec.Library.Modbus"]
        Bus["Sistec.Library.Bus
(Zebus o HTTP+Redis)"]
        RLib["Sistec.Library.Redis
(Data Layer Trasversale)"]
    end

    subgraph Infra["INFRASTRUTTURA"]
        Config["Sistec.Configuration"]
        Pers["Sistec.Infra.Persistence*"]
        CodeGen["Sistec.Infra.CodeGen"]
    end

    LAG_HMI --> Shell
    FAEL_AB --> Shell
    FAEL_C --> Shell
    BS --> Shell

    Shell --> Prod_Stacks
    Shell --> Alarm
    Shell --> Controls
    Shell --> SUI

    Prod_Stacks --> Machine_Stacks
    Prod_Stacks --> Job
    Maint --> Plc

    Kuka --> OPC
    Kuka --> Core
    Safan --> Core
    Esa --> Modbus
    Esa --> Core
    Plc --> OPC
    Plc --> Core
    Sinu --> OPC
    Sinu --> Core

    Machine_Stacks --> Config
    Prod_Stacks --> Pers
    Job --> Pers

    Controls --> Core
    SUI --> Controls
    SUI --> Core

    Bus --> Core

    classDef app fill:#e3f2fd,stroke:#1565c0
    classDef shell fill:#e3f2fd,stroke:#1565c0,stroke-width:3px
    classDef prod fill:#fff8e1,stroke:#f57f17
    classDef machine fill:#e8f5e9,stroke:#2e7d32
    classDef foundation fill:#e1f5e1,stroke:#2e7d32
    classDef infra fill:#f3e5f5,stroke:#7b1fa2

    class LAG_HMI,FAEL_AB,FAEL_C,BS app
    class Shell shell
    class Prod,Job,Maint,Alarm prod
    class Kuka,Safan,Esa,Plc,Sinu machine
    class Core,Controls,SUI,OPC,Modbus,Bus foundation
    class Config,Pers,CodeGen infra

2.12 Code Generation per DUT

I file DUT (tag mapping OPC UA) sono attualmente scritti a mano in entrambe le codebase con commenti //order matters: use the same order used in the codesys structure — estremamente fragili e fonte di bug.

Soluzione: Code generation da definizioni CODESYS:

flowchart LR
    INPUT["CODESYS .txt / .xml"] --> GEN["Sistec.Infra.CodeGen
(dotnet tool)"]
    GEN --> POCO["Sistec.Stack.PLC.DTO (generated/)
← POCO puri (senza EncodeableBase)"]
    GEN --> OPCENC["Sistec.Stack.PLC.OPCUA (generated/)
← Encodeable version"]
    GEN --> TAGS["Sistec.Stack.PLC.Tags (generated/)
← TagConstants.Main.ProductionValid"]
    GEN --> BIND["Sistec.Stack.PLC.Binding (generated/)
← Bind() tipizzato"]

Vantaggi:

• Elimina errori di ordinamento campi
• Elimina codice duplicato (AB vs C in FAEL)
• Aggiungere nuovo DUT = aggiungere definizione CODESYS + rigenerare
• Tag type-safe (non più "Main_ProductionValid" ma TagConstants.Main.ProductionValid)
• POCO puri separati da EncodeableBase — rompe il technology lock-in OPC UA

2.13 Gestione Varianti HMI (Problema Aperto)

FAEL presenta 3 varianti (AB, C, BS) con ~45-55% di codice duplicato. LAG ha una singola variante.

Problema identificato ma non risolto nel presente documento: La strategia per unificare le varianti HMI (feature flags, configurazione, o mantenimento di progetti separati snelli) va discussa separatamente, in quanto:

• Dipende dalle effettive differenze di layout e macchinari
• Impatta il piano di refactoring complessivo
• Richiede validazione con il team di sviluppo

Raccomandazione preliminare: Iniziare comunque con la creazione degli stack verticali (Fase 1-2). La gestione varianti può essere affrontata in Fase 3 quando gli stack saranno stabili e le differenze tra varianti saranno più visibili.

2.14 Pattern di Composizione: DI Container

// Program.cs — Composition Root unificato
public static void Main()
{
    var builder = Host.CreateApplicationBuilder(args);

    // Configurazione
    builder.Services.Configure<PlcOptions>(builder.Configuration.GetSection("Plc"));
    builder.Services.Configure<KukaOptions>(builder.Configuration.GetSection("Kuka"));
    builder.Services.Configure<SafanOptions>(builder.Configuration.GetSection("Safan"));
    builder.Services.Configure<EsaOptions>(builder.Configuration.GetSection("Esa"));

    // Stack macchina (attivazione condizionale per variante)
    builder.Services.AddKukaStack();
    builder.Services.AddSafanStack();    // LAG
    // builder.Services.AddEsaStack();   // FAEL (alternativo a Safan)
    builder.Services.AddPlcStack();
    builder.Services.AddSinumerikStack(); // LAG

    // Stack applicativi
    builder.Services.AddProductionStack();
    builder.Services.AddJobManagementStack();
    builder.Services.AddMaintenanceStack();
    builder.Services.AddAlarmsStack();

    // UI
    builder.Services.AddSingleton<FrmHMI>();

    var host = builder.Build();
    var form = host.Services.GetRequiredService<FrmHMI>();
    Application.Run(form);
}

// Metodo extension per stack KUKA
public static IServiceCollection AddKukaStack(this IServiceCollection services)
{
    services.AddSingleton<IKrcClient, KrcClient>();
    services.AddSingleton<IKukaTagProvider, KukaTagProvider>();
    services.AddSingleton<IKukaRobotLogic, KukaRobotLogic>();
    services.AddSingleton<IRobotFollowService, RobotFollowService>();
    return services;
}

2.15 Strategia di Test Unificata

Standard: NUnit 4.3.2 (già presente in LAG per Safan su net10.0) come framework unico per tutti i test automatici. coverlet.collector per code coverage. Ogni stack ha il suo progetto di test.

2.16 Design Pattern Applicati

L'architettura target adotta esplicitamente i seguenti pattern creazionali e strutturali nei layer indicati:

Dove nascono:

• Factory Method — nel Driver layer ogni stack ha un TagFactory che produce TagValue<T> tipizzati dal DTO CODESYS. Anche nel Layout Engine: ControlFactory (sez. 8.4) istanzia controlli UI da nome dichiarato in layout.json.
• Facade — è il pattern strutturale dominante in ogni Sistec.*.Stack.Services. Il Client sa solo di byte/stream, il Driver sa di tag/mapping, il Services orchesta e presenta una superficie di dominio pulita.
• Proxy — il Simulator di ogni stack (Sistec.*.Stack.Simulator) è un Proxy dell'implementazione reale. La DI sceglie quale registrare: services.AddSingleton<KrcClient> (produzione) vs services.AddSingleton<IKrcClient, SimulatorKrcClient> (test).
• Mediator — lo stack Sistec.Stack.Production (sez. 2.9) è di fatto un Mediator tra tutti gli stack macchina, senza che KUKA conosca Safan o viceversa.

2.17 Perché IoC e DI sono Essenziali

L'architettura corrente (LAG e FAEL) non usa DI container. Il risultato è sotto gli occhi di tutti: costruttori da centinaia di righe, God Class, service locator sparsi, e l'impossibilità di testare un singolo layer senza istanziare mezzo sistema.

IoC e DI non sono una moda .NET. Sono un principio ingegneristico trasversale — la Dependency Inversion Principle (DIP) è uno dei 5 SOLID — adottato da ogni ecosistema mainstream:

Tutti i framework moderni di ogni linguaggio si aspettano DI. I template dotnet new generano già Program.cs con builder.Services. Le librerie .NET di terze parti (Serilog, EF Core, MediatR, FluentValidation) offrono extension methods su IServiceCollection. L'unico posto dove non si usa DI è il codice legacy Sistec — e questo isolamento è la causa diretta di molti anti-pattern elencati in §1.5.

Cosa risolve DI, concretamente, per Sistec:

Esempio concreto — oggi vs domani:

// OGGI — LAG MainForm.cs
public MainForm()
{
    _safanClient = new SafanClient("Safan_0");                    // dipende da TcpClient
    _safanLogic = new SafanPressBrakeLogic(_safanClient).Use(...); // dipende da SafanClient
    _plcLogic = new PlcLogic(GVL_HMI);                            // dipende da OpcUaClient
    _cellLogic = new CellLogic(_plcLogic, _punchingLogic,          // dipende da tutto
        _safanLogic, _robotLogic);
    // 278 righe di new, configurazioni, event wiring
}

// DOMANI — Composition Root
builder.Services.AddSafanStack();  // 4 righe registrano Client+Driver+Services
builder.Services.AddPlcStack();
builder.Services.AddProductionStack();

public class FrmHMI(                         // costruttore vuoto,
    CellLogic cellLogic,                     // DI risolve tutto
    SafanPressBrakeLogic safanLogic, ...);

public class SafanPressBrakeLogic(           // anche Services è testabile:
    ISafanClient client,                     // può ricevere un SafanSimulator
    IOptions<SafanOptions> options);         // o il SafanClient reale

Non usare DI oggi significa ignorare un principio adottato trasversalmente da Java (2004), .NET (2016), TypeScript (2016), Go (2018), Python (2018), Rust (2020). Non esiste un progetto enterprise in alcun linguaggio moderno che gestisca dipendenze con new a mano. Anche Avalonia, il framework HMI target, si integra nativamente con IServiceCollection.

In sintesi: IoC e DI sono il collante architetturale di tutta la proposta. Senza DI, gli stack verticali sarebbero ancora legati da new espliciti — perderemmo testabilità, sostituibilità e la capacità di attivare/disattivare stack per commessa. Con DI, ogni stack è un pacchetto NuGet che si auto-registra, e il Composition Root è l'unico posto dove si decide cosa usare.

3. Roadmap Greenfield: Costruire per la Nuova Commessa

L'architettura target descritta nelle sezioni successive non si applica alle commesse LAG e FAEL esistenti, che rimangono in manutenzione correttiva con WinForms legacy. Viene invece costruita ex-novo per la prossima commessa, partendo da zero con le fondazioni condivise e aggiungendo via via gli stack macchina necessari.

Principi

┌─────────────────────────────────────────────────────┐
│              NUOVA COMMESSA (GREENFIELD)              │
│                                                       │
│  Fase 1 ─── Fondazioni (interfacce + infrastruttura) │
│  Fase 2 ─── Stack macchina necessari alla commessa    │
│  Fase 3 ─── Applicativi + UI                          │
│  Fase 4 ─── Deploy + collaudo                         │
│                                                       │
│  Esistenti (LAG, FAEL) restano invariati              │
└─────────────────────────────────────────────────────┘

Fase 1: Fondazioni Condivise (4-5 settimane)

Tutto ciò che serve a qualsiasi commessa — indipendente dalla macchina specifica.

Sistec.Infra.*                     ← NuGet packages
├── Sistec.Infra.Persistence          Interfacce + Dapper + MySql + SqlServer
├── Sistec.Infra.Configuration        Options pattern (sostituisce Configuration statica)
├── Sistec.Infra.Authentication       BCrypt + badge RFID + Employee/Role management
├── Sistec.Infra.Logging              ILogger<T> strutturato, output JSON
└── Sistec.Infra.CodeGen              dotnet tool → DUT da CODESYS → POCO + TagConstants

Sistec.Platform.*                   ← NuGet packages
├── Sistec.Platform.Controls          Controlli base (Button, Led, Numeric, Valve, Motor)
├── Sistec.Platform.OpcUa             Wrapper OPC UA Foundation SDK
├── Sistec.Platform.Modbus            Stack Modbus TCP/RTU
└── Sistec.Platform.Cloud             MQTT connector opzionale

Fase 2: Stack Macchina della Commessa (2-3 settimane per stack)

Solo gli stack necessari alla commessa in corso. Ogni stack è un pacchetto NuGet indipendente.

Sistec.Stack.Kuka.*                 ← Se la commessa ha KUKA
├── Client    → TCP/IP KRC
├── Driver    → Comandi robot
├── Services  → Logica robot
├── UI        → Pagine Avalonia
└── Simulator → Test

Sistec.Stack.Safan.*                ← Se la commessa ha pressa Safan
├── Client    → TCP/IP Winsock
├── Driver    → Comandi pressa
├── Services  → Logica pressa
├── UI        → Pagine Avalonia
└── Simulator → Test

... stesso pattern per ESA, Sinumerik, PLC, Bus ...

Fase 3: Applicativi + UI (3-4 settimane)

Sistec.Stack.Production             ← Orchestrazione cella
Sistec.Stack.JobManagement          ← Cicli di vita job
Sistec.Stack.Maintenance            ← Manutenzione predittiva (ONNX)
Sistec.Stack.Alarms                 ← Alarm journal
Sistec.RecipeEngine                 ← Workflow configurabile JSON
Sistec.PalletStateMachine           ← Macchina a stati pallet

Sistec.HMI.Shell                    ← Composition Root Avalonia
├── LayoutEngine                    ← layout.json → UI
└── EmployeeStatsPage               ← Statistiche produzione per dipendente

Fase 4: Deploy + Collaudo (1-2 settimane)

Ansible playbook                    ← Setup PC industriale
├── roles/common                    ← Hostname, utenti, firewall
├── roles/mysql                     ← MySQL + seed DB
├── roles/hmi_app                   ← Deploy HMI + servizio Windows
└── roles/codesys                   ← WSL2 + Docker + container CODESYS

Test ricevimento                    ← Collaudo in fabbrica
├── smoke test su ogni stack
├── test layout.json
└── test statistiche operatore

Riepilogo Tempi

Le commesse successive riutilizzano Fase 1 + gli stack già esistenti, riducendo i tempi a 6-10 settimane (solo Fase 2-4).

4. Confronto: Situazione Attuale vs Architettura Proposta

5. Vantaggi dell'Architettura Unificata

6. Anti-Pattern e Soluzioni (Riepilogo Trasversale)

flowchart LR
    subgraph PROBLEMI["ANTI-PATTERN TRASVERSALI"]
        AP1["① God Project
Common (LAG + FAEL)"]
        AP2["② God Class
MainForm / FrmHMI"]
        AP3["③ Service Locator
Configuration + LogicCollection"]
        AP4["④ No DI Container
new + .Use()"]
        AP5["⑤ Accoppiamento
a classi concrete"]
        AP6["⑥ Stack frammentato
KUKA in 5 progetti"]
        AP7["⑦ Technology Lock-In
DUT → EncodeableBase"]
        AP8["⑧ Magic Strings
Tag name hardcoded"]
        AP9["⑨ DB Access Sparso
No Unit of Work"]
        AP10["⑩ Lava Flow / Dead Code
Contracts\**, commenti"]
        AP11["⑪ SafeInvoke
WinForms nei layer bassi"]
        AP12["⑫ Duplicazione Varianti
AB vs C vs BS (FAEL)"]
        AP13["⑬ Fire-and-Forget
Forget() + Task.Run ovunque"]
        AP14["⑭ Hub Dipendenze
Common → 6 progetti"]
        AP15["⑮ Version Drift
Sistec.Core → LAG vs FAEL"]
        AP16["⑯ Missing IDisposable
TcpClient, KrcClient, ..."]
        AP17["⑰ Blocking in Async
.Result + spin-wait"]
        AP18["⑱ Duplicazione Test
13× FakeOpcUa identici"]
    end

    subgraph SOLUZIONI["SOLUZIONI"]
        S1["Stack verticali
Smantellare Common"]
        S2["DI Container +
FrmHMI thin orchestrator"]
        S3["IOptions<T>
+ DI"]
        S4["Microsoft.Extensions
DependencyInjection"]
        S5["Dipendere da
interfacce"]
        S6["Sistec.Stack.Kuka
modulo unico verticale"]
        S7["Code Generation DUT
POCO + EncodeableBase separati"]
        S8["TagConstants generati
type-safe"]
        S9["Sistec.Infra.Persistence
con Unit of Work"]
        S10["Eliminare dead code
pulizia sistematica"]
        S11["ISyncContext astratto
no Control.SafeInvoke"]
        S12["Feature flags /
discussione aperta"]
        S13["await esplicito +
error tracking"]
        S14["Estrarre interfacce
di Common in un progetto API"]
        S15["Baseline unico
partire da FAEL + cherry-pick"]
        S16["IDisposable + using
su tutte le classi I/O"]
        S17["Task.Wait() vietato
await in tutto il path async"]
        S18["Test共享 library
FakeOpcUa → NuGet test helper"]
    end

    AP1 --> S1
    AP2 --> S2
    AP3 --> S3
    AP4 --> S4
    AP5 --> S5
    AP6 --> S6
    AP7 --> S7
    AP8 --> S8
    AP9 --> S9
    AP10 --> S10
    AP11 --> S11
    AP12 --> S12
    AP13 --> S13
    AP14 --> S14
    AP15 --> S15
    AP16 --> S16
    AP17 --> S17
    AP18 --> S18

    style PROBLEMI fill:#ffebee,stroke:#c62828
    style SOLUZIONI fill:#e8f5e9,stroke:#2e7d32

6.1 Dettaglio Anti-Pattern Aggiuntivi (dall'Analisi Approfondita)

6.2 Gestione Utenti Inadeguata

L'analisi della gestione utenti rivela un sistema funzionante ma insufficiente per gli standard moderni e per le richieste dei clienti.

Situazione Attuale

La user management è identica in entrambe le codebase e si basa su:

Problemi Identificati

1. Niente utenti reali, solo ruoli — Il sistema ha 4 livelli (Operator, Maintenance, Expert, Sistec) ma nessun legame tra un dipendente reale e la sua produzione. Non esiste una tabella employees o operators. L'Account memorizza solo un livello e una password, non un nome dipendente, badge, turno, o matricola.

2. Password in chiaro — UserPassword memorizzata in plaintext su MySQL. Confronto in chiaro: txtuserPassword.Text != selectedUser.UserPassword. Hardcoded Sistec password "747832" nel codice sorgente (Globals_Standard.cs:213).

3. SQL injection — frmUserManagement.cs costruisce query con interpolazione diretta: $"INSERT INTO accounts ... VALUES ('{txtuserPassword.Text}')". Operazioni CRUD attualmente commentate (non funzionanti).

4. Nessuna produzione per utente — Impossibile rispondere a domande come "quanti pezzi ha prodotto Mario Rossi oggi?", "qual è il tempo medio per cambio utensile di questo operatore?", "quanti scarti ha prodotto il turno notturno?".

5. Auto-login backdoor — File loginSistec.ls bypassa completamente l'autenticazione.

6. Login dialog rudimentale — Nessun supporto per badge RFID, nessun login con tessere, nessun PIN rapido (solo password testuale).

7. Nessun audit trail — Non c'è traccia di chi ha fatto cosa (chi ha modificato un parametro, chi ha forzato un reset, chi ha cambiato la configurazione).

8. Nessun principal .NET — Thread.CurrentPrincipal mai impostato, niente ClaimsPrincipal, niente autorizzazione dichiarativa [Authorize].

Proposta: Sistema a Utenti Reali per Dipendente

flowchart LR
    subgraph NOW["OGGI — Solo Ruoli"]
        A1["accounts table
ID | UserLevel | Password | Name_it"]
        A2["Login: scegli ruolo
da ComboBox"]
        A3["Produzione: anonima
nessun legame operatore"]
    end

    subgraph FUTURE["DOMANI — Utenti Reali"]
        B1["employees table
BadgeId | Nome | Turno | Role"]
        B2["Login: badge RFID
o selezione dipendente"]
        B3["Produzione: tracciata
per operatore"]
        B4["Statistiche: pezzi/h,
scarti, tempi morti"]
    end

    NOW -->|Refactoring| FUTURE

Il sistema proposto:

• Tabella employees con: BadgeId (PK), FirstName, LastName, Shift (Mattina/Pomeriggio/Notte), Role (FK → roles), PinCode (hashato), IsActive
• Tabella roles con permessi granulari: CanEditParameters, CanResetMachine, CanAccessReports, CanManageUsers, ecc.
• Login via badge RFID (lettore USB seriale) o PIN rapido (4-6 cifre) o selezione da lista
• Log produzione con OperatorId FK su ogni Job, ProductionEvent, ScrapEvent, AlarmAck, ParameterChange
• Statistiche in pagina dedicata: pezzi/ora per operatore, scarti %, tempi ciclo medi, confronto turni
• Password hashate con BCrypt/Argon2, niente plaintext
• Parametri in appsettings.json: "AutoLogin": false, "RFIDReader": "COM3", "PinMinLength": 4

Questa modifica è indipendente dagli stack macchina — può essere realizzata in parallelo alle fasi 0-1 e non blocca la migrazione a stack verticali.

7. Rischi e Mitigazioni

8. Il Gap: Layout Engine Configurabile

L'architettura a stack verticali risolve la frammentazione del codice macchina, ma non basta per consegnare un nuovo impianto senza scrivere codice. Il problema aperto è il layout HMI: la disposizione delle pagine, la posizione dei controlli, i collegamenti tra schermate cambiano per ogni commessa e attualmente richiedono pagine WinForms scritte a mano.

8.1 Obiettivo

Nuova commessa = cartella con:
├── manifest.json          ← Quali stack attivare, versione firmware
├── layout.json            ← Struttura pagine, zone, navigazione
├── config/                ← Parametri macchina (Kuka.ini, PLC.json, Safan.json)
├── tags/                  ← DUT generati da CODESYS
├── resources/             ← Immagini, icone, traduzioni
└── (nessun file .cs nuovo)

8.2 Architettura del Layout Engine

flowchart TB
    subgraph Manifest["MANIFEST COMMESSA"]
        MJ["manifest.json
Versione, Variante,
Stack attivi, Riferimenti"]
    end

    subgraph LayoutDef["DEFINIZIONE LAYOUT"]
        LJ["layout.json
Albero pagine, zone,
posizioni, binding tag"]
        LT["layouts/
Template page (opzionali)
WinForms designer export"]
    end

    subgraph Engine["SISTEC.LAYOUT.ENGINE"]
        LP["LayoutParser
Legge JSON → albero pagine"]
        LB["LayoutBuilder
Costruisce UserControl
da definizioni"]
        LBind["LayoutBinder
Collega controlli a tag PLC
via ITagProvider"]
        LNav["LayoutNavigation
Menu, breadcrumb,
pulsantiere"]
    end

    subgraph Rendering["RENDERING"]
        RZ["ZoneRenderer
Contenitore zona →
disposizione controlli"]
        RC["ControlFactory
Nome controllo →
istanza UserControl dallo stack"]
        RD["DialogFactory
Dialoghi (manutenzione,
job, popup)"]
    end

    subgraph Stacks["STACK VERTICALI"]
        Kuka["Sistec.Stack.Kuka.UI"]
        Safan["Sistec.Stack.Safan.UI"]
        Esa["Sistec.Stack.Esa.UI"]
        Plc["Sistec.Stack.PLC.UI"]
        Sinumerik["Sistec.Stack.Sinumerik.UI"]
        Prod["Sistec.Stack.Production.UI"]
        Maint["Sistec.Stack.Maintenance.UI"]
        Jobs["Sistec.Stack.JobManagement.UI"]
    end

    Manifest --> Engine
    LayoutDef --> Engine
    Engine --> Rendering
    Rendering -->|ControlFactory cerca| Stacks

8.3 Formato layout.json (Proposta)

{
  "$schema": "https://sistec.it/schemas/layout-v1.json",
  "version": "1.0",
  "plant": "LAG-5315",
  "variant": "LAG",

  "screens": [
    {
      "id": "home",
      "title": "Home",
      "type": "grid",
      "rows": 2, "cols": 3,
      "cells": [
        { "row": 0, "col": 0, "rowSpan": 2,
          "control": "Kuka.Views.ucKukaInfo",
          "binding": { "robot": "Kuka_0" }
        },
        { "row": 0, "col": 1,
          "control": "Safan.Views.SafanStatusView",
          "binding": { "press": "Safan_0" }
        },
        { "row": 0, "col": 2,
          "control": "PLC.Views.PlcStatusControl",
          "binding": { "plc": "PLC_0" }
        },
        { "row": 1, "col": 1,
          "control": "JobManagement.Views.JobSummary",
          "binding": {}
        },
        { "row": 1, "col": 2,
          "control": "Alarms.Views.AlarmBanner",
          "binding": { "limit": 5 }
        }
      ]
    },
    {
      "id": "production",
      "title": "Produzione",
      "type": "tabbed",
      "tabs": [
        { "title": "Job",   "control": "Production.Views.JobView" },
        { "title": "CutPlan", "control": "Production.Views.CutPlanView" },
        { "title": "Pannelli", "control": "Production.Views.PanelTrackingView" }
      ]
    },
    {
      "id": "maintenance",
      "title": "Manutenzione",
      "type": "page",
      "control": "Maintenance.Views.MaintenanceView",
      "binding": {}
    }
  ],

  "navigation": {
    "type": "sidebar",
    "items": [
      { "label": "Home",         "icon": "home.png",      "screen": "home" },
      { "label": "Produzione",   "icon": "production.png","screen": "production" },
      { "label": "Manutenzione", "icon": "wrench.png",    "screen": "maintenance" }
    ]
  },

  "dialogs": [
    {
      "id": "job-create",
      "control": "JobManagement.Views.CreateJobDialog",
      "size": { "width": 800, "height": 600 }
    },
    {
      "id": "alarm-history",
      "control": "Alarms.Views.AlarmHistoryDialog",
      "size": { "width": 1024, "height": 768 }
    }
  ]
}

8.4 ControlFactory: Come i controlli UI arrivano a runtime

Pattern: Factory Method — la creazione del controllo è delegata a una factory registrata da ogni stack, senza che il Layout Engine conosca il tipo concreto.

Ogni stack verticale registra i propri controlli in un dizionario globale al momento della registrazione nel DI container:

// In Sistec.Stack.Kuka.UI/ModuleRegistration.cs
public static void RegisterControls(ControlRegistry registry)
{
    registry.Register("Kuka.Views.ucKukaInfo",     () => new ucKukaInfo());
    registry.Register("Kuka.Views.KukaOverride",    () => new KukaOverrideControl());
    registry.Register("Kuka.Views.RobotDropOffset", () => new RobotDropOffsetView());
}

// In Sistec.Stack.PLC.UI/ModuleRegistration.cs
public static void RegisterControls(ControlRegistry registry)
{
    registry.Register("PLC.Views.PlcStatusControl", () => new PlcStatusControl());
    registry.Register("PLC.Views.WatchdogIndicator",() => new WatchdogIndicator());
}

Il ControlFactory nel LayoutEngine cerca il nome dal JSON, istanzia il controllo e applica i binding:

public class ControlFactory
{
    private readonly Dictionary<string, Func<UserControl>> _registry = new();

    public UserControl Create(string controlName, Dictionary<string, object> binding)
    {
        if (!_registry.TryGetValue(controlName, out var factory))
            throw new UnknownControlException(controlName);

        var control = factory();
        ApplyBinding(control, binding); // setta proprietà via reflection / ITagProvider
        return control;
    }
}

8.5 Ciclo di Vita di una Nuova Commessa

flowchart LR
    A["Cliente ordina
impianto"] --> B["Ingegnere compila
manifest.json layout.json config/"]

    B --> C["Sistec.Infra.CodeGen
genera DUT da CODESYS"]

    C --> D["Collaudo: si lancia
l'HMI con la cartella
della commessa"]

    D --> E["L'HMI:
1. Legge manifest.json
2. Attiva gli stack necessari
3. Carica layout.json
4. Carica risorse
5. Avvia"]

    E --> F{"Tutto OK?"}
    F -->|Sì| G["Consegnato.
Zero righe di codice scritte."]
    F -->|No| H["Si modifica solo
layout.json o config/
mai codice C#"]
    H --> D

8.6 Quando Serve Ancora Codice

8.7 Impatto sulla Roadmap

Il Layout Engine è una Fase 6 che si aggiunge dopo la Fase 5:

gantt
    title Roadmap con Layout Engine
    dateFormat  YYYY-MM-DD
    axisFormat  %d/%m

    section Fase 6 — Layout Engine (3-4 settimane)
    Progettare formato layout.json + schema JSON         :f6a, 2026-09-01, 3d
    Implementare LayoutParser                            :f6b, after f6a, 3d
    Implementare ControlFactory + ControlRegistry         :f6c, after f6b, 4d
    Implementare LayoutBuilder + ZoneRenderer             :f6d, after f6c, 4d
    Implementare LayoutNavigation (menu, breadcrumb)      :f6e, after f6d, 3d
    Integrare con manifest.json + startup sequence        :f6f, after f6e, 3d
    Creare validatore schema JSON per layout              :f6g, after f6f, 2d
    Strumento designer (anteprima layout)                 :f6h, optional, 5d

Importante: Il Layout Engine ha senso SOLO dopo che gli stack verticali esistono. Senza stack verticali, i controlli UI sono sparsi in 5 progetti e il ControlFactory non saprebbe dove cercarli. Le fasi 0-5 sono prerequisito obbligatorio.

8.8 Translation Strategy: Cloud-First, Chiavi Parlanti

Problema attuale

Nelle codebase legacy (LAG/FAEL), le chiavi di traduzione sono accoppiate ai nomi dei controlli WinForms:

uc2_ThicknessCheck_grpCalibrations  →  "Calibrations"
uc2_Sistec_grpAutoOverRide          →  "Auto Override"
btnCancel                           →  "Cancel"
Cancel                              →  "Cancel"  (chiave diversa, stessa parola)
#Cancel                             →  "Cancel"  (ancora diversa)

Stessa parola "Cancel" appare con 3 chiavi diverse a seconda del contesto. Ogni impianto ha una copia locale della tabella translations nel suo MySQL — manutenzione N volte, rischio divergenza.

Soluzione

Quando l'impianto è connesso a Internet, la tabella delle traduzioni è online e unica per tutti gli impianti. Le chiavi sono parlanti e seguono la convenzione {dominio}.{entità}.{proprietà}.

Regole fondamentali:

1. Stessa parola = stessa chiave — ui.btn.cancel ovunque, non 10 chiavi diverse
2. Prefisso impianto per override specifici — plant5315.robot.customAlarmMessage
3. Nessun accoppiamento con componenti UI — la chiave descrive il significato, non il controllo
4. Fallback offline — cache locale delle chiavi più usate (UI base, allarmi critici)

Schema tabella translations centralizzata:

Gerarchia chiavi proposta:

ui.               ← Controlli generici (btn, dialog, menu)
robot.            ← Robot KUKA, stato, comandi
press.            ← Pressa, allarmi, parametri
production.       ← Job, ricette, tracking
maintenance.      ← Manutenzione, diagnostica
alarm.            ← Allarmi generici
plant{ID}.        ← Override specifici impianto

Esempio codice — confronto legacy vs greenfield:

// PRIMA (legacy): 10 chiavi diverse per "Cancel"
btnCancel.Text = t.GetOrDefault("btnCancel", "#Cancel");
btn2.Text = t.GetOrDefault("Cancel", "#Cancel");
btn1.Text = t.GetOrDefault("btnCancel", "#Cancel");

// DOPO (greenfield): chiave unica parlante
btnCancel.Text = t.Get("ui.btn.cancel");

// PRIMA (legacy): chiave accoppiata al componente
grpCalibrations.Text = t.GetOrDefault("uc2_ThicknessCheck_grpCalibrations", "#Calibrations");

// DOPO (greenfield): chiave basata sul significato
grpCalibrations.Text = t.Get("press.calibrations.title");

Deployment e sincronizzazione:

Con Redis attivo, una traduzione corretta è visibile su tutti i pannelli in tempo reale via Pub/Sub, senza attendere il sync periodico. Il TTL garantisce refresh forzato periodico contro il DB cloud.

Vantaggi:

• Manutenzione 1× invece di N — una traduzione corretta su tutti gli impianti
• Consistenza — stesso testo = stessa chiave in ogni pagina, ogni impianto
• Aggiornamenti instantanei — correggere un refuso = un UPDATE, non N deploy
• Plant-specific — override con prefisso plant{ID} per esigenze locali senza inquinare le chiavi condivise
• Offline resilience — cache locale garantisce operabilità anche senza rete

9. Logica di Dominio Configurabile: Recipe Engine e Pallet State Machine

Stesso problema del layout, ma sulla logica applicativa: ricette, pallet, flussi di produzione sono attualmente hardcoded in CellLogic/ProductionOrchestrator con if/else su variante impianto. LAG ha una logica, FAEL un'altra. La soluzione è identica: estrarre la logica in dati configurabili.

9.1 Recipe Engine: Esecuzione Workflow da JSON

Oggi: BendingProgramService, CutPlanService, PressRobotTeamService contengono sequenze hardcoded con if/else su CellType.AB vs CellType.C.

// OGGI — logica hardcoded in CellLogic
public async Task ExecuteProductionStep(StepType step)
{
    if (_cellType == CellType.LAG)
    {
        await _kuka.LoadPanel("vacuum_a");
        await _safan.Bend("P123", 90);
        await _kuka.Unload("pallet_1");
    }
    else if (_cellType == CellType.FAEL)
    {
        await _kuka.LoadPanel("gripper_b");
        await _esa.Press("PROG_456");
        await _kuka.Unload("pallet_2");
        await _conveyor.Advance(); // FAEL ha un nastro in più
    }
}

Proposta: Recipe = workflow configurabile in JSON, eseguito da un RecipeEngine generico che non conosce la variante impianto.

{
  "recipeId": "BEND_PANEL_LAG_001",
  "displayName": "Piegatura pannello standard LAG",
  "plantVariant": "LAG",
  "steps": [
    {
      "id": "load_panel",
      "machine": "Kuka_0",
      "action": "LOAD_PANEL",
      "params": { "gripper": "vacuum_a", "pickFrom": "infeed" },
      "timeout": 30,
      "retry": 2
    },
    {
      "id": "bend",
      "machine": "Safan_0",
      "action": "BEND",
      "params": { "program": "P123", "angle": 90, "speed": "fast" },
      "timeout": 60,
      "dependsOn": ["load_panel"]
    },
    {
      "id": "unload",
      "machine": "Kuka_0",
      "action": "UNLOAD",
      "params": { "destination": "pallet_1", "orientation": "stacked" },
      "dependsOn": ["bend"]
    }
  ],
  "rules": {
    "retryOnError": true,
    "maxRetries": 3,
    "requireApproval": false,
    "abortOnFailure": true,
    "logEachStep": true
  }
}

Il RecipeEngine esegue la sequenza senza sapere cosa fa ogni macchina — chiama i metodi sullo stack appropriato via interfacce:

// Sistec.Stack.RecipeEngine — generico, zero if/else su variante
public class RecipeEngine : IRecipeEngine
{
    private readonly IMachineRegistry _machines;
    private readonly ILogger<RecipeEngine> _logger;

    public async Task<RecipeResult> ExecuteAsync(Recipe recipe, CancellationToken ct)
    {
        var context = new RecipeContext(recipe);
        foreach (var step in recipe.Steps.OrderBy(s => s.Order))
        {
            await WaitForDependencies(step, context, ct);
            var machine = _machines.Resolve(step.Machine); // interfaccia IMachineAction
            var result = await machine.ExecuteActionAsync(step.Action, step.Params, ct);
            context.SetStepResult(step.Id, result);
            if (!result.Success && recipe.Rules.AbortOnFailure)
                return RecipeResult.Failed(step, result.Error);
        }
        return RecipeResult.Completed(context);
    }
}

Ogni stack macchina registra le azioni che sa eseguire:

// In Sistec.Stack.Kuka.Services
public class KukaRobotActionProvider : IMachineActionProvider
{
    public string MachineName => "Kuka_0";
    public Dictionary<string, Func<StepParams, Task<ActionResult>>> Actions => new()
    {
        ["LOAD_PANEL"] = async p => { await _robot.LoadPanel(p.Get<string>("gripper")); return ActionResult.Ok(); },
        ["UNLOAD"]     = async p => { await _robot.Unload(p.Get<string>("destination")); return ActionResult.Ok(); },
    };
}

Ricette diverse per impianto

📁 Sistec.5315.LAG/
   ├── config/
   │   └── recipes/
   │       ├── bend_panel_lag.json      ← LAG: Kuka + Safan
   │       └── punch_program.json       ← LAG: con Sinumerik

📁 Sistec.5309.FAEL.AB/
   ├── config/
   │   └── recipes/
   │       ├── bend_panel_fael.json     ← FAEL: Kuka + Esa + conveyor
   │       └── cut_plan.json            ← FAEL: senza Sinumerik

Stesso RecipeEngine, stessi stack macchina, ricette diverse in JSON. Zero codice toccato.

9.2 Pallet State Machine: Macchina a Stati Configurabile

Oggi: PalletLogic in FAEL (100 righe) vs assente in LAG (o implementato diversamente in ProductionOrchestrator). If/else su numero pallet, tipi, stati, transizioni.

Proposta: macchina a stati finita configurabile in JSON, ogni impianto definisce stati, transizioni, vincoli.

{
  "palletConfig": {
    "count": 9,
    "types": [
      { "id": "standard", "label": "Standard", "capacity": 50, "maxWeight": 500 },
      { "id": "oversize", "label": "Oversize",  "capacity": 10, "maxWeight": 1000 }
    ],
    "layout": "3x3",
    "initialState": "EMPTY"
  },
  "states": [
    { "id": "EMPTY",         "label": "Vuoto" },
    { "id": "LOADING",       "label": "In carico" },
    { "id": "FULL",          "label": "Pieno" },
    { "id": "QUALITY_CHECK", "label": "Controllo qualità" },
    { "id": "SHIPPED",       "label": "Spedito" },
    { "id": "REWORK",        "label": "Da rilavorare" }
  ],
  "transitions": [
    { "from": "EMPTY",         "to": "LOADING",       "trigger": "panel_placed" },
    { "from": "LOADING",       "to": "FULL",          "trigger": "capacity_reached" },
    { "from": "LOADING",       "to": "LOADING",       "trigger": "panel_placed" },
    { "from": "FULL",          "to": "QUALITY_CHECK", "trigger": "request_qc" },
    { "from": "FULL",          "to": "REWORK",        "trigger": "qc_failed" },
    { "from": "QUALITY_CHECK", "to": "SHIPPED",       "trigger": "qc_passed" },
    { "from": "QUALITY_CHECK", "to": "REWORK",        "trigger": "qc_failed" },
    { "from": "REWORK",        "to": "LOADING",       "trigger": "rework_done" },
    { "from": "SHIPPED",       "to": "EMPTY",         "trigger": "pallet_cleared" }
  ],
  "rules": {
    "maxPalletsPerType": { "standard": 6, "oversize": 3 },
    "requireQcForType": ["oversize"],
    "autoAdvanceOnFull": true,
    "notifyOnStateChange": ["FULL", "QUALITY_CHECK"]
  }
}

// Sistec.Stack.PalletTracking — generico, zero if/else
public class PalletStateMachine
{
    private readonly PalletConfig _config;
    private readonly Dictionary<string, Pallet> _pallets = new();

    public bool TryTransition(string palletId, string trigger, out string error)
    {
        var pallet = _pallets[palletId];
        var transition = FindValidTransition(pallet.State, trigger);
        if (transition == null)
        {
            error = $"Transition '{trigger}' not allowed from state '{pallet.State}'";
            return false;
        }
        pallet.State = transition.To;
        OnStateChanged?.Invoke(pallet);
        error = null;
        return true;
    }
}

Con Redis opzionale, lo stato pallet è persistito in un Hash Redis: sistec:{plant}:pallet:{id} con campi state, type, partCount, currentJob. Se l'HMI riavvia, lo stato recupera da Redis invece di ripartire da EMPTY. TTL 24h per cleanup automatico pallet non usati. Il DB MySQL resta source of truth definitiva.

Differenze per impianto in configurazione

Tutto in JSON. Zero if/else su CellType.

9.3 Nuovi Stack

Seguono lo stesso pattern: Client? → Driver? → Services → UI → Simulator. Services è il cuore (RecipeEngine, PalletStateMachine). UI fornisce viste di监控/controllo. Simulator permette test offline.

9.4 Ciclo di Vita: Nuova Variante di Impianto

1. Cliente ordina impianto con 4 pallet, controllo qualità obbligatorio
2. Ingegnere copia template cartella commessa
3. Modifica:
   - config/pallets/config.json: count: 4, requireQcForType: ["standard", "oversize"]
   - config/recipes/*.json: sequenze specifiche
4. Collauda con RecipeEngineSimulator + PalletSimulator
5. Consegna. Zero codice.

9.5 Impatto sulla Roadmap

Fase 3 (aggiornata): Stack applicativi (3 settimane)
  ├── Sistec.Stack.Production
  ├── Sistec.Stack.RecipeEngine  ← NUOVO
  ├── Sistec.Stack.PalletTracking ← NUOVO
  └── Sistec.Stack.JobManagement, Maintenance, Alarms

9.6 Predictive Maintenance: ML al Posto del Timer

La manutenzione attuale è time-based ("cambia olio ogni 1000 ore", "sostituisci cinghia ogni 6 mesi") — non riflette l'usura reale. Un macchinario fermo 3 mesi si ritrova una manutenzione schedulata inutilmente, mentre uno stressato può rompersi prima del previsto.

La proposta: predictive maintenance basata su modello ML on-device, dove ogni stack macchina pubblica features operative (cicli, torque, temperature, vibrazioni) e il Maintenance.Stack le consuma per stimare la Remaining Useful Life (RUL) di ogni componente.

Architettura

flowchart LR
    subgraph Stacks["STACK MACCHINA → TELEMETRY"]
        Kuka["Sistec.Stack.Kuka
pubblica: cicli gripper,
torque giunti, ore moto
via IMachineTelemetryProvider"]
        Safan["Sistec.Stack.Safan
pubblica: numero pieghe,
forza cilindri, errori"]
        Plc["Sistec.Stack.PLC
pubblica: ore macchina,
temperature motori, vibrazioni"]
    end

    subgraph Maint["Sistec.Stack.Maintenance (migliorato)"]
        Collect["TelemetryCollector
raccoglie features
da ogni stack via provider"]
        Feat["FeatureTransformer
aggrega (avg, max, sum)
per finestra temporale"]
        ML["OnnxRuntimeEngine
carica modello .onnx
→ RUL per componente"]
        Sched["PredictiveScheduler
RUL < threshold →
crea task manutenzione
con priorità"]
        Alert["AlertService
notifica operatore
giallo/rosso"]
    end

    subgraph Config["CONFIGURAZIONE"]
        Models["models/*.onnx
modello addestrato
per macchinario-specifico"]
        Thresholds["thresholds.json
soglie RUL per
ogni componente
{warning, critical}"]
        SchedCfg["schedules.json
manutenzione time-based
di fallback"]
    end

    Kuka -->|IMachineTelemetryProvider| Collect
    Safan -->|IMachineTelemetryProvider| Collect
    Plc -->|IMachineTelemetryProvider| Collect
    Collect --> Feat --> ML
    Config --> ML
    Config --> Sched
    ML --> Sched
    Sched --> Alert

    Maint -.->|telemetria aggregata| Cloud["Sistec.Stack.Cloud
opzionale: invia features
a cloud per ri-addestramento"]

Configurazione

{
  "components": [
    {
      "id": "kuka_joint_1",
      "displayName": "Giunto KUKA 1",
      "machine": "Kuka_0",
      "modelFile": "models/kuka_joint_rul.onnx",
      "features": [
        { "source": "Kuka_0", "tag": "Joint1.Torque",       "aggregate": "avg_last_hour" },
        { "source": "Kuka_0", "tag": "Joint1.Temperature",  "aggregate": "max_last_hour" },
        { "source": "Kuka_0", "tag": "Joint1.Cycles",       "aggregate": "sum_since_last_maint" }
      ],
      "thresholds": {
        "warning":  { "rul": 100, "level": "yellow" },
        "critical": { "rul": 20,  "level": "red" }
      },
      "fallbackSchedule": { "everyHours": 2000 }
    },
    {
      "id": "safan_cylinder",
      "displayName": "Cilindro pressa Safan",
      "machine": "Safan_0",
      "modelFile": "models/safan_cylinder_rul.onnx",
      "features": [
        { "source": "Safan_0", "tag": "Cylinder.Force",  "aggregate": "avg" },
        { "source": "Safan_0", "tag": "Cylinder.Cycles", "aggregate": "sum" }
      ],
      "thresholds": {
        "warning":  { "rul": 500,  "level": "yellow" },
        "critical": { "rul": 100,  "level": "red" }
      }
    }
  ]
}

Provider di Telemetria

Ogni stack macchina espone un'interfaccia che il Maintenance.Stack consuma:

// Sistec.Core.Interfaces — contratto condiviso
public interface IMachineTelemetryProvider
{
    string MachineId { get; }
    Task<Dictionary<string, double>> CollectFeaturesAsync(
        IEnumerable<string> tagNames, TimeSpan window, CancellationToken ct);
}

// Sistec.Stack.Kuka.Services — implementazione
public class KukaTelemetryProvider : IMachineTelemetryProvider
{
    public string MachineId => "Kuka_0";
    public async Task<Dictionary<string, double>> CollectFeaturesAsync(
        IEnumerable<string> tagNames, TimeSpan window, CancellationToken ct)
    {
        // Legge dai tag OPC UA / KRC, calcola medie, massimi, somme
        return new Dictionary<string, double>
        {
            ["Joint1.Torque"] = await _kukaClient.ReadAverageAsync("Joint1.Torque", window),
            ["Joint1.Temperature"] = await _kukaClient.ReadMaxAsync("Joint1.Temp", window),
            ["Joint1.Cycles"] = await _cycleCounter.GetSinceLastMaintenanceAsync(),
        };
    }
}

Ciclo di vita del modello ML

1. Addestramento (cloud o PC dev)
   ├── Raccogliere dati storici: features + timestamp rottura/sostituzione
   ├── Addestrare modello (scikit-learn, PyTorch, LightGBM)
   └── Esportare in ONNX → modello.onnx

2. Deploy
   ├── Il file .onnx va in config/models/ della commessa
   └── OnnxRuntimeEngine lo carica all'avvio

3. Inferenza (sull'HMI, ogni ora)
   ├── TelemetryCollector raccoglie features da tutti gli stack
   ├── FeatureTransformer normalizza
   ├── OnnxRuntimeEngine esegui → RUL per ogni componente
   └── PredictiveScheduler: RUL < soglia → crea task manutenzione

4. Miglioramento continuo
   ├── Le features + l'esito effettivo della manutenzione
   │   (rotto/sostituito/sano) tornano indietro via Cloud.Stack
   └── Modello ri-addestrato periodicamente con nuovi dati

Soglie e notifiche

Vantaggi

Impatto sull'architettura

• Sistec.Stack.Maintenance si arricchisce: aggiunge PredictiveEngine, OnnxRuntimeEngine, TelemetryCollector. Resta un pacchetto NuGet sempre presente.
• Ogni stack macchina (Kuka, Safan, PLC, ...) deve implementare IMachineTelemetryProvider — zero cambiamenti alla logica esistente, si aggiunge solo un provider.
• I file .onnx sono dati di configurazione, non codice. Vanno in config/models/ della commessa.
• ONNX Runtime è una dipendenza NuGet del Maintenance.Stack. Funziona su Windows e Linux (Avalonia).

9.6.1 Digital Twin — Replica 3D Real-Time dello Stato Macchina

Il Digital Twin è il trend #1 dell'HMI industriale 2026: una replica 3D real-time della macchina che mostra stato, movimenti e anomalie in tempo reale. Non è un render decorativo — è uno strumento operativo che riduce i tempi di diagnostica del 40-60%.

Cosa Mostra

Vista Digital Twin nell'HMI:
┌─────────────────────────────────────────────┐
│  [3D Viewport — KUKA Robot + Pressa]         │
│                                              │
│    ╔══╗                                      │
│    ║K1║───🤖 KUKA KR210                      │
│    ║  ║    ● Online | Programma: P123        │
│    ║  ║    🔴 Joint 3 overload (allarme)     │
│    ║S ║                                      │
│    ║a ║───🏭 Pressa Safan                     │
│    ║f ║    ● Running | Ciclo: 38/120         │
│    ║a ║                                      │
│    ║n║───📦 Pallet 1: EMPTY                  │
│    ╚══╝    Pallet 2: FULL (QC pending)       │
│                                              │
│  [Stati] 🟢 Running  ⚠️ Warning  🔴 Fault     │
└─────────────────────────────────────────────┘

Livelli di Fedeltà

Target: Livello 1 (minimo) + Livello 2 (obiettivo) per prima commessa greenfield.

Integrazione con Predictive Maintenance

Il Digital Twin non è solo estetico — è il cruscotto visivo della predictive maintenance (§9.6):

// Maintenance.Stack → DigitalTwinService
public class DigitalTwinService
{
    // Colora componenti in base alla RUL predetta
    public RulColor GetComponentColor(string componentId)
    {
        var rul = _predictiveEngine.GetRul(componentId);
        return rul switch
        {
            > 500  => RulColor.Green,   // Normale
            > 100  => RulColor.Yellow,  // Attenzione
            > 20   => RulColor.Orange,  // Pianificare manutenzione
            _      => RulColor.Red      // Sostituire immediatamente
        };
    }
}

Architettura

flowchart LR
    subgraph Stacks["STACK MACCHINA"]
        Kuka["Sistec.Stack.Kuka
→ posizione giunti, stato"]
        Safan["Sistec.Stack.Safan
→ corsa cilindro, forza"]
        Plc["Sistec.Stack.PLC
→ sensori, allarmi"]
    end

    subgraph DT["Sistec.Stack.DigitalTwin (NUOVO)"]
        DT_State["StateCollector
Aggrega stato da tutti gli stack"]
        DT_3D["SceneRenderer
SkiaSharp 3D / Avalonia 3D
→ viewport interattivo"]
        DT_Anim["AnimationEngine
Movimenti basati su dati reali"]
    end

    subgraph UI["UI Avalonia"]
        DT_View["DigitalTwinView
Control registrato in ControlRegistry
layout.json: fullscreen o card"]
    end

    Kuka --> DT_State
    Safan --> DT_State
    Plc --> DT_State
    DT_State --> DT_3D
    DT_3D --> DT_Anim
    DT_Anim --> DT_View

    style DT fill:#e3f2fd

Dettaglio Stack

layout.json

{
  "id": "digital-twin",
  "title": "Digital Twin",
  "type": "page",
  "control": "DigitalTwin.Views.DigitalTwinView",
  "binding": {
    "machines": ["Kuka_0", "Safan_0", "PLC_0"],
    "refreshMs": 200,
    "camera": { "initialZoom": 1.0, "allowRotate": true }
  }
}

Impatto sulla Roadmap

Fase 3 (nuova): Stack applicativi (4-5 settimane)
  ├── Sistec.Stack.Production
  ├── Sistec.Stack.RecipeEngine
  ├── Sistec.Stack.PalletTracking
  ├── Sistec.Stack.Maintenance (predictive ML)
  ├── Sistec.Stack.DigitalTwin (Livello 1-2)  ← NUOVO
  └── Sistec.Stack.JobManagement, Alarms

Il Digital Twin è un differenziatore competitivo — nessun competitor Sistec (PMI italiana) lo offre. Per la prima commessa greenfield, il Livello 1 (schematico 2.5D) è sufficiente per dimostrare il concept.

Fase 3 (aggiornata): Stack applicativi (3-4 settimane)
  ├── Sistec.Stack.Production
  ├── Sistec.Stack.RecipeEngine
  ├── Sistec.Stack.PalletTracking
  ├── Sistec.Stack.Maintenance (predictive ML + Digital Twin)  ← MIGLIORATO
  └── Sistec.Stack.JobManagement, Alarms

9.7 Logging Strutturato con DI, non Statico

Il logger statico Utilities.Logger è esattamente lo stesso anti-pattern di Configuration.PlcConfig[...] — service locator globale, impossibile da mockare, sostituire o configurare per contesto.

Oggi: statico + plain text

// ANTI-PATTERN: service locator statico
Utilities.Logger?.Debug($"{log.Context}: {log.Message}");
// → plain text file, zero struttura, zero ricercabilità
// → impossibile testare (mockare un campo statico è un incubo)
// → thread safety? affidato a Serilog internamente, ma zero controllo

// Tre astrazioni diverse per la stessa cosa:
Utilities.Logger?.Debug("...");          // Serilog diretto
ISistecLogger<LogItem>.Log("...");       // custom wrapper
Globals_Standard.Log("...");             // delegazione UI

Domani: ILogger via DI + JSON strutturato

// Nel Composition Root (Program.cs)
builder.Host.UseSerilog((ctx, cfg) =>
    cfg.ReadFrom.Configuration(ctx.Configuration)
       .Enrich.WithMachineName()
       .Enrich.WithProperty("Application", "Sistec.5315.LAG")
       .WriteTo.Console()
       .WriteTo.File(
            path: "Logs/sistec-.json",
            rollingInterval: RollingInterval.Day,
            formatter: new Serilog.Formatting.Json.JsonFormatter())  // JSON!
       .WriteTo.Debug());

// In ogni classe: costruttore, non statico
public class KukaRobotLogic : IKukaRobotLogic
{
    private readonly ILogger<KukaRobotLogic> _logger;

    public KukaRobotLogic(..., ILogger<KukaRobotLogic> logger)
    {
        _logger = logger; // ← iniettato dal container DI
    }

    public async Task LoadPanelAsync(string gripper)
    {
        _logger.LogInformation("Loading panel with {Gripper}", gripper);
        //                     ^ named placeholder, non $"..."!
    }
}

Output JSON:

{
  "@t": "2026-07-02T14:30:00.123Z",
  "@l": "Information",
  "@mt": "Loading panel with {Gripper}",
  "Gripper": "vacuum_a",
  "MachineName": "SPV-LAG-01",
  "Application": "Sistec.5315.LAG"
}

Vantaggi del JSON strutturato:

• Ricercabile: jq 'select(.Gripper == "vacuum_a")' o Elastic/Kibana
• Filtrável per campo: tutti i log del KUKA, tutte le temperature > 80°C
• Aggregabile tra impianti: stesso formato per LAG e FAEL, stesso Elastic index
• Alerting automatico: {Gripper} = "vacuum_a" && {Temperature} > 80 → Slack/PagerDuty

Cosa cambia in pratica

Impatto sulla roadmap

Non serve uno stack separato. Si risolve in Fase 0b (Fondazione):

Fase 0b (aggiornata): Fondazione (3-4 settimane)
  ├── DI Container + Configuration
  ├── Sostituire Utilities.Logger con ILogger<T> via DI
  ├── Eliminare ISistecLogger<LogItem> e Globals_Standard.Log()
  ├── Migrare log4net (Sistec.Bus) a Serilog
  ├── Convertire Debug.Print() in ILogger.LogTrace()
  ├── Configurare output JSON + rolling file
  ├── Persistence multi-progetto
  └── CodeGen prototipo

La migrazione non è blocante: si può fare gradualmente. Un nuovo stack (es. Kuka.Stack) nasce già con ILogger<T> via DI. I vecchi file continuano a usare lo statico finché non vengono refactorati.

10. Modello di Distribuzione: NuGet Packages

Ogni stack verticale diventa un pacchetto NuGet pubblicato su un feed interno (NuGet.Server / GitHub Packages / Azure Artifacts). La commessa diventa un progetto CSProj minimale che referenzia solo i pacchetti necessari.

10.1 Pacchetti Proposti

I pacchetti si dividono in due categorie: sempre presenti (platform) e per commessa (macchinario).

flowchart TB
    subgraph Always["✅ SEMPRE PRESENTI (Platform)"]
        Core["Sistec.Core
netstandard2.1"]
        Controls["Sistec.Controls
net8.0-windows"]
        SistecUI["Sistec.UI
net8.0-windows"]
        LayoutEngine["Sistec.LayoutEngine
net8.0-windows"]
        ConfigLib["Sistec.Configuration
netstandard2.1"]
        Persistence["Sistec.Infra.Persistence*
netstandard2.1"]

        Plc["Sistec.Stack.PLC
net8.0-windows"]
        Alarms["Sistec.Stack.Alarms
net8.0-windows"]
        Maintenance["Sistec.Stack.Maintenance
net8.0-windows"]
        JobMgmt["Sistec.Stack.JobManagement
net8.0-windows"]
        Production["Sistec.Stack.Production
net8.0-windows"]
    end

    subgraph Optional["🔧 PER COMMESSA (Machine)"]
        Kuka["Sistec.Stack.Kuka"]
        Fanuc["Sistec.Stack.Fanuc
(futuro)"]
        OtherRobots["⋯ altro robot"]

        Safan["Sistec.Stack.Safan"]
        Gade["Sistec.Stack.Gade
(futuro)"]
        Esa["Sistec.Stack.Esa"]
        OtherPress["⋯ altra pressa"]

        Sinumerik["Sistec.Stack.Sinumerik"]
        OpcUaLib["Sistec.Library.OpcUa"]
        ModbusLib["Sistec.Library.Modbus"]
        BusLib["Sistec.Library.Bus"]
    end

    classDef always fill:#e1f5e1,stroke:#2e7d32
    classDef optional fill:#fff8e1,stroke:#f57f17

    class Core,Controls,SistecUI,LayoutEngine,ConfigLib,Persistence always
    class Plc,Alarms,Maintenance,JobMgmt,Production always
    class Kuka,Fanuc,OtherRobots,Safan,Gade,Esa,OtherPress,Sinumerik,OpcUaLib,ModbusLib,BusLib optional

10.2 Progetto Commessa: Prima e Dopo

Oggi (LAG)

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <OutputType>WinExe</OutputType>
    <TargetFramework>net8.0-windows</TargetFramework>
  </PropertyGroup>
  <ItemGroup>
    <!-- 7 riferimenti a progetto, non pacchetti -->
    <ProjectReference Include="..\Sistec.Core\Sistec.Core.csproj" />
    <ProjectReference Include="..\Sistec.Controls\Sistec.Controls.csproj" />
    <ProjectReference Include="..\Sistec.UI\Sistec.UI.csproj" />
    <ProjectReference Include="..\Sistec.Opc.Ua\Sistec.Opc.Ua.csproj" />
    <ProjectReference Include="..\Sistec.Safan\Source\Sistec.Safan.csproj" />
    <ProjectReference Include="..\Sistec.Sinumerik\Sistec.Sinumerik.csproj" />
    <ProjectReference Include="..\..\Common\Sistec.Common.csproj" />
  </ItemGroup>
</Project>

Domani — Template dotnet new sistec-hmi

<!-- Template base: sempre gli stessi, ogni commessa li ha -->
<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <OutputType>WinExe</OutputType>
    <TargetFramework>net8.0-windows</TargetFramework>
    <AssemblyName>Sistec.$(Commessa)</AssemblyName>
  </PropertyGroup>
  <ItemGroup>
    <!-- Platform — sempre presenti -->
    <PackageReference Include="Sistec.Core" Version="4.3.*" />
    <PackageReference Include="Sistec.Controls" Version="4.3.*" />
    <PackageReference Include="Sistec.UI" Version="4.3.*" />
    <PackageReference Include="Sistec.LayoutEngine" Version="1.0.*" />
    <PackageReference Include="Sistec.Configuration" Version="1.0.*" />
    <PackageReference Include="Sistec.Infra.Persistence" Version="1.0.*" />
    <PackageReference Include="Sistec.Stack.PLC" Version="2.1.*" />
    <PackageReference Include="Sistec.Stack.Alarms" Version="2.1.*" />
    <PackageReference Include="Sistec.Stack.Maintenance" Version="2.1.*" />
    <PackageReference Include="Sistec.Stack.JobManagement" Version="2.1.*" />
    <PackageReference Include="Sistec.Stack.Production" Version="2.1.*" />
    <!-- 🔧 Qui l'ingegnere aggiunge i pacchetti macchinario -->
  </ItemGroup>
</Project>

Domani — Commessa LAG (con macchinari)

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <OutputType>WinExe</OutputType>
    <TargetFramework>net8.0-windows</TargetFramework>
    <AssemblyName>Sistec.5315.LAG</AssemblyName>
  </PropertyGroup>
  <ItemGroup>
    <!-- Platform (sempre, dal template) -->
    <PackageReference Include="Sistec.Core" Version="4.3.*" />
    <PackageReference Include="Sistec.Controls" Version="4.3.*" />
    <PackageReference Include="Sistec.UI" Version="4.3.*" />
    <PackageReference Include="Sistec.LayoutEngine" Version="1.0.*" />
    <PackageReference Include="Sistec.Configuration" Version="1.0.*" />
    <PackageReference Include="Sistec.Infra.Persistence" Version="1.0.*" />
    <PackageReference Include="Sistec.Stack.PLC" Version="2.1.*" />
    <PackageReference Include="Sistec.Stack.Alarms" Version="2.1.*" />
    <PackageReference Include="Sistec.Stack.Maintenance" Version="2.1.*" />
    <PackageReference Include="Sistec.Stack.JobManagement" Version="2.1.*" />
    <PackageReference Include="Sistec.Stack.Production" Version="2.1.*" />

    <!-- Machine (aggiunti per LAG) -->
    <PackageReference Include="Sistec.Stack.Kuka" Version="2.1.*" />
    <PackageReference Include="Sistec.Stack.Safan" Version="2.1.*" />
    <PackageReference Include="Sistec.Stack.Sinumerik" Version="2.1.*" />
    <PackageReference Include="Sistec.Library.OpcUa" Version="2.1.*" />
  </ItemGroup>

  <ItemGroup>
    <!-- Soli file di configurazione e risorse -->
    <Content Include="manifest.json" CopyToOutputDirectory="Always" />
    <Content Include="layout.json" CopyToOutputDirectory="Always" />
    <Content Include="config\**\*.json" CopyToOutputDirectory="Always" />
    <Content Include="resources\**\*" CopyToOutputDirectory="Always" />
  </ItemGroup>
</Project>

Domani — Commessa FAEL C (senza pressa, senza CNC)

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <OutputType>WinExe</OutputType>
    <TargetFramework>net8.0-windows</TargetFramework>
    <AssemblyName>Sistec.5309.C</AssemblyName>
  </PropertyGroup>
  <ItemGroup>
    <!-- Platform (sempre, dal template) -->
    <!-- ... identico al template ... -->

    <!-- Machine (aggiunti per FAEL C) -->
    <PackageReference Include="Sistec.Stack.Kuka" Version="2.1.*" />
    <PackageReference Include="Sistec.Library.OpcUa" Version="2.1.*" />
    <!-- Nota: senza Safan.Stack, senza Esa.Stack, senza Sinumerik.Stack -->
    <!-- Non serve Modbus.Library (nessuna pressa) -->
  </ItemGroup>
</Project>

10.3 Consistenza Versioning

Tutti i pacchetti di uno stack verticale condividono la stessa versione (es. Sistec.Stack.Kuka.Client 2.1.0, Sistec.Stack.Kuka.Driver 2.1.0, Sistec.Stack.Kuka.Services 2.1.0, ecc.). Questo garantisce che i layer siano compatibili.

<!-- Directory.Build.props nel repo dello stack -->
<Project>
  <PropertyGroup>
    <VersionPrefix>2.1.0</VersionPrefix>
    <VersionSuffix>$(VersionSuffix)</VersionSuffix>
    <Authors>Sistec AM</Authors>
    <PackageProjectUrl>https://sistec.it</PackageProjectUrl>
    <RepositoryType>git</RepositoryType>
    <ContinuousIntegrationBuild>true</ContinuousIntegrationBuild>
  </PropertyGroup>
</Project>

10.4 Ciclo di Vita Commessa con NuGet

flowchart LR
    A["📋 Contratto
commessa"] --> B["🏗️ Ingegnere
crea progetto da template
`dotnet new sistec-hmi`"]

    B --> C["Il template include già
tutti i pacchetti platform
(PLC, Alarms, JobMgmt,
Production, Maintenance)"]

    C --> D["📦 Aggiunge solo
pacchetti macchinario
`dotnet add package Sistec.Stack.Kuka`"]

    D --> E["⚙️ Compila manifest.json
layout.json config/"]

    E --> F["🧪 Collaudo
`dotnet run`"]

    F -->|OK| G["📦 Pubblica
`dotnet publish`
→ EXE + DLL + JSON"]

    F -->|Ko| H["Corregge solo
JSON/INI/immagini"]
    H --> E

    subgraph CI["CI/CD Pipeline"]
        I["Repo Fondazione
→ build → test →
publish NuGet (platform)"]
        J["Repo Stack Macchina
→ build → test →
publish NuGet (machine)"]
    end

    I -.->|NuGet platform| C
    J -.->|NuGet machine| D

10.5 Impatto su Sviluppo e Consegna

| Ruolo | Oggi | Domani | |---|---|---|---| | Sviluppatore di stack (es. Kuka) | Scrive codice frammentato in 5 progetti, impact analysis su tutto | Scrive codice dentro un unico repo stack, test NUnit, publish NuGet | | Ingegnere di commessa | Fork di soluzione, copia file, modifica codice C#, rischi regressione | dotnet new sistec-hmi (ha già tutto il platform), aggiunge 2-3 pacchetti macchina, scrive JSON | | Messa in servizio | Build da sorgente, dipende dal dev che ha scritto quella commessa | dotnet publish con pacchetti già testati, rollback = cambiare versione NuGet | | Bug fixing | Apri soluzione commessa, cerca in 5 progetti, fix, rebuild tutto | Fix nel repo dello stack, nuova versione NuGet, commessa aggiorna versione | | Nuovo macchinario | Scrittura codice sparsa, difficile da standardizzare | Nuovo repo stack verticale, primo pacchetto NuGet, poi configurabile | | Allineamento versioni | Ogni commessa ha versioni diverse degli stessi file | Platform versionato centralmente, tutte le commesse sulla stessa base |

10.6 Strategia di Adozione

Non serve convertire tutto in una volta. Si procede per fasi, partendo da ciò che è sempre uguale:

Fase 1: Platform NuGet (sempre presenti)
  ├── Estrarre in repo separati: Sistec.Core, Sistec.Controls, Sistec.UI
  ├── Estrarre: Sistec.Stack.PLC, Sistec.Stack.Alarms, Sistec.Stack.Maintenance
  ├── Estrarre: Sistec.Stack.JobManagement, Sistec.Stack.Production
  ├── CI/CD per ognuno: build → test NUnit → publish NuGet
  ├── Template `dotnet new sistec-hmi` con TUTTI questi pacchetti già inclusi
  └── LAG e FAEL iniziano a referenziarli via NuGet

Fase 2: Machine NuGet (per commessa)
  ├── Sistec.Stack.Kuka come pilota
  ├── Estrarre dal monolite in repo separato
  ├── LAG e FAEL aggiungono solo Kuka.Stack → primo stack condiviso
  ├── Poi Safan.Stack, Esa.Stack, Sinumerik.Stack...
  └── Nuovi macchinari (Fanuc, Gade, ...) nascono già come NuGet

Fase 3: Smantellamento Common
  ├── Tutti gli stack sono NuGet
  ├── Common non contiene più nulla di vivo
  ├── Eliminare progetto Common
  └── Correggere namespace

Fase 4: Layout Engine
  ├── Sistec.LayoutEngine come NuGet platform
  ├── layout.json sostituisce le pagine WinForms custom
  └── Nuova commessa = solo JSON + immagini

Vantaggio chiave: già dalla Fase 1 tutte le commesse condividono la stessa base platform via NuGet. Non si aspetta la fine del refactoring per vedere benefici.

10.7 Il Problema del Diverging Branches (LAG milestons/4.5 vs FAEL mileston/v3.25)

Oggi il versioning è di fatto assente: lo stesso Sistec.Core esiste in due branch divergenti e incompatibili. È il sintomo più evidente dell'assenza di un modello di distribuzione.

flowchart LR
    subgraph Oggi["OGGI — branch divergenti"]
        direction TB
        LAG["LAG: milestons/4.5
Core versione 4.5.*"]
        FAEL["FAEL: mileston/v3.25
Core versione 3.25.*"]
        LAG -.->|API incompatibili| FAEL
    end

    subgraph Domani["DOMANI — NuGet unificato"]
        direction TB
        FEED["Feed NuGet Sistec
Una sola Sistec.Core nuget"]
        LAGv2["LAG: PackageReference
Sistec.Core 5.0.0"]
        FAELv2["FAEL: PackageReference
Sistec.Core 5.0.0"]
    end

    Oggi -->|"Passaggio obbligato: riconciliazione"| Domani

Il modello NuGet risolve il problema a regime (una volta pubblicato, non si può più divergere), ma richiede un passaggio intermedio di riconciliazione dei due branch.

Passaggio Obbligato: Riconciliazione dei Branch

Prima di pubblicare qualsiasi pacchetto NuGet, i due branch devono essere riconciliati in un unico main. Non esistono scorciatoie.

Raccomandazione: Combinare le opzioni — standardizzare su LAG (più recente, già con NUnit su net10.0, architettura più pulita) e usare una finestra di compatibilità dove FAEL wrappa le differenze minori con adapter temporanei.

Cosa Cambia con NuGet

Impatto sulla Roadmap

La riconciliazione dei branch è un prerequisito della Fase 1. Senza, non si può pubblicare nulla su NuGet:

Fase 0: Riconciliazione (2-4 settimane) ← NUOVA
  ├── Analizzare diff tra milestons/4.5 (LAG) e mileston/v3.25 (FAEL)
  ├── Scegliere base comune (raccomandato: LAG, più recente)
  ├── Creare adapter temporanei per API divergenti in FAEL
  ├── Verificare che entrambe le commesse compilino sulla stessa base
  └── Git: unificare in unico main/master

Fase 1: Platform NuGet (dopo riconciliazione)
  ├── Ora ha senso: si parte da un'unica base condivisa
  └── Template `dotnet new sistec-hmi` usa la base riconciliata

In sintesi: sì, il modello NuGet risolve il problema del versioning divergente a regime. Ma prima va fatto un lavoro di riconciliazione tra i due branch, altrimenti si pubblicherebbe su NuGet una delle due versioni (e l'altra diventerebbe inutilizzabile). La buona notizia: LAG è più recente (v4.5 vs v3.25) e il divario è colmabile con adapter temporanei.

11. Modernizzazione UI: Avalonia e Cross-Platform

WinForms è una tecnologia di 22 anni (.NET Framework 1.0, 2003). Anche WPF ha 18 anni. L'architettura a stack verticali proposta separa già la UI (Sistec.<Nome>.Stack.UI), per cui il passo successivo naturale è sostituire WinForms con un framework moderno — senza dover riscrivere i layer Client, Driver e Services.

11.1 Perché non WinForms

11.2 Opzioni Modern UI

Raccomandazione: Avalonia UI — è il framework .NET cross-platform più maturo per applicazioni desktop industriali:

• XAML moderno con binding dichiarativo, compiled bindings
• DPI scaling automatico
• Touch/gesture nativo
• Theming completo (Fluent, Material, custom)
• SVG e font icon nativi
• Funziona su Linux embedded (ARM) — tipico dei pannelli industriali
• Nessuna dipendenza da Windows-specific API

11.3 Impatto sull'Architettura a Stack

La separazione UI (layer Stack.UI WinForms) già prevista nell'architettura a stack verticali rende la migrazione incrementale e isolata:

flowchart LR
    subgraph Oggi["OGGI — WinForms"]
        UI_WF["Sistec.Stack.Kuka.UI
(UserControl WinForms)"]
        SVC["Sistec.Stack.Kuka.Services
(logica pura)"]
        DRV["Sistec.Stack.Kuka.Driver
(tag provider)"]
        CLI["Sistec.Stack.Kuka.Client
(TCP KRC)"]
    end

    subgraph Transizione["TRANSIZIONE — side-by-side"]
        UI_WF2["Sistec.Stack.Kuka.UI.WinForms
(vecchio, legacy)"]
        UI_AV["Sistec.Stack.Kuka.UI.Avalonia
(nuovo, moderno)"]
        SVC2["Sistec.Stack.Kuka.Services
(identico, nessuna modifica)"]
    end

    subgraph Domani["DOMANI — Avalonia"]
        UI_AV2["Sistec.Stack.Kuka.UI
(solo Avalonia, WinForms rimosso)"]
        SVC3["Sistec.Stack.Kuka.Services
(identico)"]
    end

    Oggi --> Transizione
    Transizione --> Domani

Punti chiave:

1. I layer sottostanti (Client, Driver, Services) NON cambiano — sono già puri .NET, senza dipendenze UI
2. Ogni stack può migrare individualmente — non serve un big-bang
3. Side-by-side possibile — durante la transizione, uno stack può avere UI WinForms e un altro UI Avalonia
4. Il LayoutEngine (sezione 8) diventa ancora più potente — i controlli registrati nel ControlRegistry vengono da Avalonia invece che da WinForms

11.4 Cosa Cambia per Ogni Stack

// OGGI — WinForms
public class ucKukaInfo : UserControl
{
    private Label _statusLabel;
    public ucKukaInfo()
    {
        _statusLabel = new Label { Location = new Point(10, 10) };
        Controls.Add(_statusLabel);
    }
    public void UpdateStatus(string status)
    {
        if (InvokeRequired) { Invoke(() => _statusLabel.Text = status); return; }
        _statusLabel.Text = status;
    }
}

// DOMANI — Avalonia
public class KukaInfoView : UserControl
{
    // Binding dichiarativo, niente code-behind
    // Niente InvokeRequired (Avalonia gestisce il thread)
}

<!-- DOMANI — Avalonia XAML -->
<UserControl xmlns="https://github.com/avaloniaui"
             xmlns:vm="clr-namespace:Sistec.Stack.Kuka.ViewModels">
    <StackPanel>
        <TextBlock Text="{Binding RobotName}" FontSize="18" />
        <TextBlock Text="{Binding Status}" 
                   Foreground="{Binding StatusColor}" />
        <Button Command="{Binding StartProgramCommand}"
                Content="Avvia Programma" />
    </StackPanel>
</UserControl>

11.5 Strategia di Migrazione UI

Fase 0: Setup (1 settimana)
  ├── Aggiungere Avalonia al solution (progetti esistenti non toccati)
  ├── Creare Sistec.Core.UI.Abstraction — interfacce UI neutre
  │     (es. IViewProvider, IDialogService, INavigationService)
  └── Template progetto Avalonia + WinForms side-by-side

Fase 1: Kuka.Stack.UI pilota (2-3 settimane)
  ├── Riscrivere ucKukaInfo, KukaOverride in Avalonia
  ├── ViewModel per ogni view (logica UI, non di dominio)
  ├── Testare side-by-side con WinForms
  └── Rilasciare Sistec.Stack.Kuka.UI.Avalonia come pacchetto NuGet

Fase 2: Altri stack (2-3 settimane per stack)
  ├── Safan.Stack.UI → Avalonia
  ├── PLC.Stack.UI → Avalonia
  ├── Sinumerik.Stack.UI → Avalonia
  └── Production.Stack.UI → Avalonia

Fase 3: LayoutEngine su Avalonia (1-2 settimane)
  ├── ControlRegistry ora emette controlli Avalonia
  ├── layout.json funziona identico (cambia solo il renderer)
  └── layout.json può includere binding Avalonia-style

Fase 4: Rimozione WinForms (1 settimana)
  ├── Verificare che tutti gli stack siano migrati
  ├── Eliminare i progetti Stack.UI.WinForms
  ├── Eliminare Sistec.Controls (sostituito da controlli Avalonia nativi)
  └── Eliminare dipendenza da System.Windows.Forms

11.6 Rischi e Mitigazioni

11.7 Roadmap UI — Impatto sulla Timeline

gantt
    title Roadmap Modernizzazione UI
    dateFormat  YYYY-MM-DD
    axisFormat  %d/%m

    section Fase UI 0 — Setup
    Setup Avalonia + side-by-side template        :u0a, 2026-10-01, 5d
    Interfacce UI astratte                         :u0b, after u0a, 3d

    section Fase UI 1 — Pilota Kuka
    Kuka.Stack.UI in Avalonia                      :u1a, after u0b, 10d
    ViewModel layer + test                         :u1b, after u1a, 5d
    Rilascio NuGet Kuka.Stack.UI.Avalonia          :u1c, after u1b, 2d

    section Fase UI 2 — Migrazione stack
    Safan.Stack.UI → Avalonia                      :u2a, after u1c, 10d
    PLC.Stack.UI → Avalonia                        :u2b, after u2a, 10d
    Production.Stack.UI → Avalonia                 :u2c, after u2b, 10d
    Alarms + Maintenance + Job UI → Avalonia       :u2d, after u2c, 10d

    section Fase UI 3 — Layout Engine
    LayoutEngine su Avalonia                       :u3a, after u2d, 7d
    layout.json con binding Avalonia               :u3b, after u3a, 5d

    section Fase UI 4 — Cleanup
    Rimuovere WinForms e Sistec.Controls           :u4a, after u3b, 5d

11.8 WebAssembly (WASM): HMI nel Browser

Avalonia UI può compilare il target WebAssembly (WASM), consentendo all'HMI di girare in un browser senza installazione. Questo abilita scenari che l'EXE nativo non copre.

Scenario d'Uso

flowchart LR
    subgraph Native["EXE NATIVO (Pannello Industriale)"]
        EXE["Sistec.HMI.exe
Avalonia su Windows/Linux
→ Controllo macchine"]
    end

    subgraph Browser["WEBASSEMBLY (Browser)"]
        WASM1["PC Ufficio Tecnico
sistec-hmi.local:5000
→ Monitoraggio + parametri"]
        WASM2["Tablet Capoturno
→ Stato produzione"]
        WASM3["TV Reparto
→ KPI fullscreen"]
    end

    EXE -->|REST API localhost| WASM1
    EXE -->|REST API localhost| WASM2
    EXE -->|REST API localhost| WASM3

Vincolo Architetturale

La versione WASM è read-only e non sostituisce l'EXE nativo:

EXE nativo:
  ├── Controlla macchine (KUKA, PLC, pressa)
  ├── Scrive tag OPC UA
  ├── Esegue produzione
  └── Gestisce aggiornamenti automatici

WASM browser:
  ├── Legge stato da API REST
  ├── Mostra KPI, trend, allarmi
  ├── Modifica parametri non critici (con autorizzazione)
  └── Mai comandi diretti alle macchine

Implementazione

<!-- Sistec.HMI.Shell — target multiplo -->
<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFrameworks>net10.0-windows;net10.0-browserwasm</TargetFrameworks>
  </PropertyGroup>
</Project>

La compilazione WASM produce file statici (.wasm, .js, .html) servibili da Nginx o dalla REST API dell'HMI nativo su localhost:5000/wasm/.

Vantaggi

Rischi

Roadmap

Fase UI 5 — WebAssembly (2-3 settimane, dopo Fase UI 3)
  ├── Configurare target net10.0-browserwasm
  ├── Estrarre API REST comune (riusa §19.2)
  ├── Adattare UI per schermo touch browser (da §21.6)
  ├── Deploy WASM come file statici serviti dall'HMI nativo
  └── Test su tablet + TV reparto

12. Gestione Utenti e Tracciamento Produzione

L'attuale sistema utenti è rudimentale: solo 4 livelli gerarchici (Operator < Maintenance < Expert < Sistec) memorizzati in una tabella accounts con password in chiaro, nessun legame con dipendenti reali, nessuna statistica di produzione per operatore. Per i clienti moderni serve un sistema che tracci chi produce cosa e permetta report di produttività per dipendente.

12.1 Architettura Proposta

flowchart LR
    subgraph AUTH["Autenticazione"]
        RFID["Badge RFID
Lettore USB seriale"]
        PIN["PIN rapido
4-6 cifre"]
        SEL["Selezione da lista
touch screen"]
    end

    subgraph DB["Database"]
        EMP["employees
BadgeId | Nome | Turno | RoleId | PinHash"]
        ROL["roles
Permission flags"]
        LOG["production_log
OperatorId | JobId | Timestamp | EventType"]
    end

    subgraph UI["UI"]
        LOGIN["LoginPage
Pick operatore + PIN"]
        DASH["DashboardStat
Pezzi/h, scarti %, tempi ciclo"]
        ADMIN["AdminPage
Gestione dipendenti e ruoli"]
    end

    AUTH --> LOGIN
    LOGIN --> EMP
    ROL -->|"CanEditParameters"| UI
    EMP -->|"FK"| LOG
    LOG --> DASH

12.2 Modello Dati

-- Ruoli con permessi granulari (bit flags)
CREATE TABLE roles (
    Id          INT PRIMARY KEY AUTO_INCREMENT,
    Name        VARCHAR(50) NOT NULL,          -- "Supervisore", "Operatore", "Manutenzione"
    Permissions BIGINT NOT NULL DEFAULT 0,     -- Bitmask: 1=CanEditParams, 2=CanReset, 4=CanManageUsers, ...
    IsActive    BOOLEAN NOT NULL DEFAULT TRUE
);

-- Dipendenti reali
CREATE TABLE employees (
    BadgeId     INT PRIMARY KEY AUTO_INCREMENT, -- 4-6 cifre, leggibile su badge RFID
    FirstName   VARCHAR(50) NOT NULL,
    LastName    VARCHAR(50) NOT NULL,
    Shift       TINYINT NOT NULL DEFAULT 1,     -- 1=Mattina, 2=Pomeriggio, 3=Notte
    RoleId      INT NOT NULL,
    PinHash     VARCHAR(256) NOT NULL,           -- BCrypt/Argon2 hash
    PinSalt     VARCHAR(128) NOT NULL,
    IsActive    BOOLEAN NOT NULL DEFAULT TRUE,
    CreatedAt   DATETIME NOT NULL DEFAULT NOW(),
    LastLogin   DATETIME NULL,
    FOREIGN KEY (RoleId) REFERENCES roles(Id)
);

-- Log produzione (esempi)
CREATE TABLE production_log (
    Id          BIGINT PRIMARY KEY AUTO_INCREMENT,
    OperatorId  INT NOT NULL,
    JobId       INT NULL,
    EventType   VARCHAR(50) NOT NULL,           -- "JobStarted", "JobCompleted", "Scrap", "ParamChange", "AlarmAck"
    Timestamp   DATETIME NOT NULL DEFAULT NOW(),
    Details     JSON NULL,                      -- Dettagli evento (es. {parameter: "pressure", old: 10, new: 12})
    FOREIGN KEY (OperatorId) REFERENCES employees(BadgeId)
);

12.3 Modello C#

[Flags]
public enum Permission : long
{
    None            = 0,
    ViewProduction  = 1 << 0,
    EditParameters  = 1 << 1,
    ResetMachine    = 1 << 2,
    ManageJobs      = 1 << 3,
    ManageUsers     = 1 << 4,
    ViewReports     = 1 << 5,
    Admin           = 1 << 6,
    All             = ~0L
}

public record Role(int Id, string Name, Permission Permissions, bool IsActive);

public record Employee(
    int BadgeId,
    string FirstName,
    string LastName,
    Shift Shift,
    Role Role,
    bool IsActive,
    DateTime? LastLogin
);

public enum Shift { Morning = 1, Afternoon = 2, Night = 3 }

12.4 Servizi

Con Redis opzionale, la sessione operatore vive in sistec:{plant}:session:{badge} con TTL 30min e heartbeat estensibile. L'operatore che badgea su AB è riconosciuto anche su C — senza rilogin. RedisSessionStore pubblica su Pub/Sub i cambi di stato (login/logout) per aggiornare in tempo reale la lista operatori attivi su tutti i pannelli. Auto-logout centralizzato: se Redis scade la sessione, tutti i pannelli vedono l'operatore sloggato contemporaneamente. | IProductionAnalyticsService | Statistiche per operatore | GetPiecesPerHourAsync(operatorId, range), GetScrapRateAsync(operatorId, range), GetShiftComparisonAsync(range) | | IAuditService | Log eventi operatore | LogEventAsync(operatorId, eventType, details), GetEventsAsync(filters) |

12.5 PIN e Sicurezza

• PIN 4-6 cifre (non password lunghe) — pensato per uso industriale con guanti, touch screen, badge RFID
• Hashing: BCrypt (costo 10) o Argon2id — niente plaintext
• Niente auto-login backdoor: il file loginSistec.ls viene eliminato
• Account Sistec integrato: creato come un normale Employee con ruolo Admin nel seed del database — stessa sicurezza degli altri utenti
• Configurabile via appsettings.json:

  {
    "Authentication": {
      "Provider": "Pin",          // "Pin" | "Rfid" | "Both"
      "RfidReaderPort": "COM3",
      "RfidReaderBaudRate": 9600,
      "PinMinLength": 4,
      "PinMaxLength": 6,
      "BcryptCostFactor": 10,
      "AutoLogoutMinutes": 30,
      "BruteForceLockout": { "MaxAttempts": 5, "LockoutMinutes": 15 }
    }
  }
  

12.6 Statistiche Produzione per Operatore

La dashboard EmployeeStatsPage mostra:

12.7 Integrazione con CI/CD

La gestione utenti è indipendente dagli stack macchina — può essere sviluppata e versionata come pacchetto Sistec.Infra.Authentication NuGet, consumato da tutti gli stack UI.

Sistec.Infra.Authentication          ← NuGet
├── IAuthenticationService.cs        ← Interfaccia
├── IEmployeeRepository.cs
├── IRoleRepository.cs
├── IProductionAnalyticsService.cs
├── Models/
│   ├── Employee.cs
│   ├── Role.cs
│   └── Permission.cs
├── Services/
│   ├── AuthenticationService.cs     ← BCrypt verify + session
│   ├── ProductionAnalyticsService.cs
│   └── AuditService.cs
└── Data/
    ├── EmployeeRepository.cs        ← Dapper
    └── RoleRepository.cs

12.8 Roadmap

Fase A: Foundation (1 settimana)
    Modello dati + migration DB
    Repository + servizi DI
    Password hashing con BCrypt
Fase B: Login UI (1-2 settimane)
    LoginPage Avalonia (PIN + badge)
    Session management + auto-logout
    Role-based authorization nei view-model
Fase C: Admin (1 settimana)
    CRUD dipendenti + ruoli
    Reset PIN
Fase D: Statistiche (2-3 settimane)
    ProductionAnalyticsService
    EmployeeStatsPage + grafici
    Esportazione CSV/PDF

12.9 Vantaggi per il Cliente

13. Microservizi: Perché No

Con stack verticali, NuGet e Avalonia la domanda sorge spontanea. La risposta è: per un HMI industriale, i microservizi risolverebbero problemi che non hai, creandone di nuovi.

13.1 Cosa Comprano i Microservizi (e perché non servono)

13.2 Cosa Costano i Microservizi (e perché pesa)

13.3 Confronto: Modular Monolith vs Microservices

flowchart TB
    subgraph ModularMonolith["✅ MODULAR MONOLITH (proposto)"]
        MM_PROC["1 processo
Sistec.HMI.exe"]
        MM_KUKA["Sistec.Stack.Kuka
(DLL in-process)"]
        MM_SAFAN["Sistec.Stack.Safan
(DLL in-process)"]
        MM_PLC["Sistec.Stack.PLC
(DLL in-process)"]
        MM_PRODUCTION["Sistec.Stack.Production
(DLL in-process)"]
        MM_LAYOUT["LayoutEngine + Avalonia UI"]

        MM_KUKA -.->|chiamate dirette, interfacce| MM_PRODUCTION
        MM_SAFAN -.->|stesso processo| MM_PRODUCTION
        MM_PLC -.->|stessa memoria| MM_KUKA
    end

    subgraph Microservices["❌ MICROSERVIZI"]
        MS_KUKA["Kuka.Service
(processo separato)"]
        MS_SAFAN["Safan.Service
(processo separato)"]
        MS_PLC["Plc.Service
(processo separato)"]
        MS_PRODUCTION["Production.Service
(processo separato)"]
        MS_HMI["HMI (Avalonia)
(processo separato)"]
        MS_BROKER["Message Broker
(RabbitMQ/gRPC)"]

        MS_KUKA -.->|REST/gRPC| MS_BROKER
        MS_SAFAN -.->|REST/gRPC| MS_BROKER
        MS_PLC -.->|REST/gRPC| MS_BROKER
        MS_PRODUCTION -.->|REST/gRPC| MS_BROKER
        MS_HMI -.->|REST/gRPC| MS_BROKER
    end

    subgraph Comparison["CONFRONTO"]
        C1["Monolith: 1 EXE, 1 cartella, doppio click"]
        C2["Microservizi: 5+ servizi, container, docker-compose, orchestrazione"]
        C3["Monolith: chiamate dirette, zero serializzazione, zero latenza"]
        C4["Microservizi: gRPC/JSON, serializzazione, latenza di rete"]
        C5["Monolith: crash = riavvio. Microservizi: crash parziale = stato incoerente"]
    end

13.4 La Via Giusta: Modular Monolith + NuGet

L'architettura proposta in questo documento è un Modular Monolith:

Un unico EXE, composto da pacchetti NuGet, con confini netti tra stack.

La regola pratica: se non hai un team di 5+ persone per servizio e traffico da gestire, i microservizi sono over-engineering. Il Modular Monolith ti dà il 90% dei benefici di isolamento con il 10% della complessità.

13.5 Quando Riconsiderare

Microservizi avrebbero senso solo se tra 3-5 anni:

1. Central Control Room: l'HMI non è più su un pannello locale, ma c'è un server centrale che gestisce 20 celle di produzione contemporaneamente
2. Multi-tenant: lo stesso software serve 10 impianti diversi da un unico server
3. Team >15 sviluppatori: servono team indipendenti che deployano in autonomia su un cluster

Fino ad allora, Modular Monolith + NuGet + Avalonia è la scelta giusta.

13.6 Eccezione: Cloud Connector per Industry 4.0

Un discorso diverso vale per la raccolta dati verso cloud — che ha senso ed è ortogonale all'architettura principale.

Non è un microservizio, è uno stack verticale come gli altri

flowchart LR
    subgraph HMI["HMI (1 processo, Modular Monolith)"]
        Kuka["Sistec.Stack.Kuka"]
        Safan["Sistec.Stack.Safan"]
        PLC["Sistec.Stack.PLC"]
        Prod["Sistec.Stack.Production"]
        Alarms["Sistec.Stack.Alarms"]
        Jobs["Sistec.Stack.JobManagement"]

        subgraph Cloud["Sistec.Stack.Cloud (NUOVO)"]
            Collector["CloudDataCollector
Si sottoscrive a eventi
degli altri stack"]
            MQTT["MqttPublisher
Invia a broker MQTT
o HTTP API"]
            Buffer["OfflineBuffer
Coda locale se cloud
non disponibile"]
        end
    end

    Cloud -->|MQTT / HTTPS| CloudBroker["Cloud Broker
(Azure / AWS / on-prem)"]
    CloudBroker --> Dashboard["Dashboard centrale
KPI, OEE, trend"]
    CloudBroker --> Analytics["Analytics / ML"]
    CloudBroker --> ERP["ERP / MES"]

    Kuka -.->|eventi| Cloud
    Safan -.->|eventi| Cloud
    PLC -.->|eventi| Cloud
    Prod -.->|eventi| Cloud
    Alarms -.->|eventi| Cloud
    Jobs -.->|eventi| Cloud

Perché questo NON rompe l'architettura

• È uno stack verticale come tutti gli altri — stesso pattern (Client? → Driver? → Services → UI? → Simulator)
• È opzionale — non incluso nel template base, si aggiunge via dotnet add package Sistec.Stack.Cloud
• È non invasivo — non tocca gli altri stack, si aggancia ai loro eventi
• È testabile con un CloudSimulator (broker MQTT finto) come qualsiasi altro stack

Esempio

// Sistec.Stack.Cloud/CloudDataCollector.cs
public class CloudDataCollector : ICloudDataCollector
{
    private readonly MqttPublisher _mqtt;
    private readonly OfflineBuffer _buffer;

    public CloudDataCollector(
        IAlarmService alarms,       // da Sistec.Stack.Alarms
        IJobTracker jobs,           // da Sistec.Stack.JobManagement
        IProductionTracker prod,    // da Sistec.Stack.Production
        MqttPublisher mqtt,
        IOptions<CloudOptions> options)
    {
        alarms.OnAlarmRaised += (alarm) =>
            PublishAsync("alarms/raised", alarm);
        jobs.OnJobCompleted += (job) =>
            PublishAsync("jobs/completed", job);
        prod.OnPartProduced += (part) =>
            PublishAsync("production/part", part);
    }

    private async Task PublishAsync(string topic, object data)
    {
        if (_mqtt.IsConnected)
            await _mqtt.PublishAsync(topic, data);
        else
            await _buffer.EnqueueAsync(topic, data); // salva in SQLite locale
    }
}

Quando ha senso

Standard IIoT: Sparkplug B v3.1

Il Cloud.Stack pubblica eventi in formato MQTT Sparkplug B v3.1 (febbraio 2026), lo standard Eclipse Foundation per IIoT. Sparkplug B definisce:

Vantaggi rispetto a MQTT "piano":

Pattern Ibrido: OPC UA al Edge, Sparkplug B Northbound

Lo standard de facto 2026 per l'architettura IIoT è il modello ibrido:

flowchart LR
    subgraph Edge["RETE MACCHINE (Edge)"]
        PLC["PLC
OPC UA Server"]
        HMI["HMI
OPC UA Client
(real-time control)"]
        PLC -->|OPC UA Client/Server| HMI
    end

    subgraph Bridge["BRIDGE"]
        SM["Sistec.Stack.Cloud
OPC UA PubSub Reader
→ Sparkplug B Edge Node"]
    end

    subgraph Cloud["NORTHBOUND (IT/Cloud)"]
        MQTT["MQTT Broker
(Mosquitto / EMQX)"]
        DASH["Dashboard
Sparkplug Primary App"]
        ERP["ERP / MES
Sparkplug Consumer"]
    end

    HMI -->|OPC UA| SM
    SM -->|Sparkplug B| MQTT
    MQTT --> DASH
    MQTT --> ERP

Unified Namespace (UNS) — Evoluzione Futura

Il Unified Namespace estende il pattern ibrido: tutti i dati di produzione (PLC, KUKA, Safan, HMI, Alarms, Job) vengono pubblicati in un unico namespace MQTT Sparkplug, accessibile da qualunque applicazione senza integrazioni point-to-point.

Tutti i dati in un unico namespace:
spBv1.0/sistec-lag-5315/
├── PLC/DATA       ← tag OPC UA in tempo reale
├── KUKA/DATA      ← stato robot, programma in esecuzione
├── Safan/DATA     ← stato pressa, ciclo corrente
├── Production/DATA← job attivo, pezzi prodotti, scarti
├── Alarms/DATA    ← allarmi attivi, storico
└── HMI/DATA       ← heartbeat, operatore loggato

Vantaggio: aggiungere una dashboard, un MES o un ERP = si sottoscrive al namespace. Zero nuove integrazioni.

Impatto: Nuovo componente Sistec.Stack.Cloud.SparkplugNode che implementa l'Edge Node Sparkplug con birth/death/data. Attivabile via configurazione.

In sintesi: il Cloud Connector è uno stack verticale come gli altri, non un microservizio. Si aggiunge con un NuGet package, è opzionale, e non cambia l'architettura di base.

14. CI/CD: Pipeline Unificata per Ogni Stack

Ogni repo stack ha una pipeline CI/CD identica nel pattern: build → unit test → integration test → quality control → publish NuGet. L'HMI Shell (commessa) ha una pipeline finale che produce l'EXE.

14.1 Architettura delle Pipeline

flowchart TB
    subgraph Repos["REPOS PER STACK"]
        CoreRepo["sistec-core
Sistec.Core"]
        KukaRepo["sistec-kuka-stack
Sistec.Stack.Kuka"]
        SafanRepo["sistec-safan-stack
Sistec.Stack.Safan"]
        PLCRepo["sistec-plc-stack
Sistec.Stack.PLC"]
        ProdRepo["sistec-production-stack
Sistec.Stack.Production"]
        CloudRepo["sistec-cloud-stack
Sistec.Stack.Cloud"]
    end

    subgraph Pipelines["PIPELINE TIPO per ogni stack"]
        direction TB
        P1["① Build + Restore"]
        P2["② Unit Test (NUnit)"]
        P3["③ Integration Test (Simulator)"]
        P4["④ SonarQube Analysis"]
        P5["⑤ NuGet Pack + Publish"]
        P1 --> P2 --> P3 --> P4 --> P5
    end

    subgraph Feed["NuGet Feed"]
        CorePkg["Sistec.Core 5.1.0"]
        KukaPkg["Sistec.Stack.Kuka 2.3.0"]
        SafanPkg["Sistec.Stack.Safan 2.3.0"]
        PLCPkg["Sistec.Stack.PLC 2.3.0"]
        CloudPkg["Sistec.Stack.Cloud 1.0.0"]
    end

    subgraph HMI_Release["PIPELINE HMI COMMESSA"]
        HR1["Restore NuGet packages"]
        HR2["Build + Avalonia UI"]
        HR3["Integration Test HMI"]
        HR4["SonarQube"]
        HR5["Publish EXE + DLL"]
        HR1 --> HR2 --> HR3 --> HR4 --> HR5
    end

    CoreRepo --> Pipelines
    KukaRepo --> Pipelines
    SafanRepo --> Pipelines
    PLCRepo --> Pipelines
    ProdRepo --> Pipelines
    CloudRepo --> Pipelines

    Pipelines -->|pubblica| Feed
    Feed -->|referenziato da| HMI_Release

14.2 Pipeline Tipo (YAML)

# azure-pipelines.yml — template condiviso per tutti gli stack Sistec
name: $(MajorMinor).$(DayOfYear)$(Rev:r)

trigger:
  branches:
    include:
      - main
      - develop
      - release/*
  paths:
    exclude:
      - 'docs/*'
      - '*.md'

pool:
  vmImage: 'windows-latest'

variables:
  - group: Sistec-NuGet-Auth
  - name: MajorMinor
    value: '5.1'      # aggiornato a ogni major/minor release
  - name: ProjectName
    value: 'Sistec.Stack.Kuka'

stages:
  - stage: Build
    displayName: '🔨 Build'
    jobs:
      - job: Build
        steps:
          - task: NuGetToolInstaller@1
          - task: NuGetCommand@2
            inputs:
              restoreSolution: 'src/**/*.csproj'
          - task: DotNetCoreCLI@2
            inputs:
              command: 'build'
              projects: 'src/**/*.csproj'
              arguments: '--configuration Release --no-restore'
            displayName: 'Build'

  - stage: UnitTests
    displayName: '🧪 Unit Test'
    dependsOn: Build
    condition: succeeded()
    jobs:
      - job: UnitTests
        steps:
          - task: DotNetCoreCLI@2
            inputs:
              command: 'test'
              projects: 'tests/**/*.UnitTests.csproj'
              arguments: '--configuration Release --no-restore
                          --filter "Category=Unit"
                          --collect:"XPlat Code Coverage"
                          --results-directory $(Build.ArtifactStagingDirectory)/coverage'
            displayName: 'Run NUnit Unit Tests'
          - task: PublishCodeCoverageResults@2
            inputs:
              summaryFileLocation: '$(Build.ArtifactStagingDirectory)/coverage/**/coverage.cobertura.xml'
              failIfCoverageEmpty: true

  - stage: IntegrationTests
    displayName: '🔌 Integration Test'
    dependsOn: Build
    condition: succeeded()
    jobs:
      - job: IntegrationTests
        steps:
          - task: DotNetCoreCLI@2
            inputs:
              command: 'test'
              projects: 'tests/**/*.IntegrationTests.csproj'
              arguments: '--configuration Release --no-restore
                          --filter "Category=Integration"
                          --collect:"XPlat Code Coverage"'
            displayName: 'Run Integration Tests (with Simulator)'

  - stage: QualityGate
    displayName: '🔍 SonarQube'
    dependsOn: [UnitTests, IntegrationTests]
    condition: succeeded()
    jobs:
      - job: SonarQube
        steps:
          - task: SonarQubePrepare@7
            inputs:
              SonarQube: 'SistecSonarQube'
              scannerMode: 'dotnet'
              projectKey: 'sistec-$(ProjectName)'
              projectName: '$(ProjectName)'
              extraProperties: |
                sonar.coverage.exclusions=**/tests/**
                sonar.cs.opencover.reportsPaths=$(Build.ArtifactStagingDirectory)/coverage/**/coverage.opencover.xml
                sonar.qualitygate.wait=true
          - task: SonarQubeAnalyze@7
          - task: SonarQubePublish@7
            inputs:
              pollingTimeoutSec: '300'

  - stage: Publish
    displayName: '📦 NuGet Publish'
    dependsOn: QualityGate
    condition: and(succeeded(), eq(variables['Build.SourceBranch'], 'refs/heads/main'))
    jobs:
      - job: Publish
        steps:
          - task: DotNetCoreCLI@2
            inputs:
              command: 'pack'
              projects: 'src/$(ProjectName)/$(ProjectName).csproj'
              arguments: '--configuration Release --no-build
                          -p:PackageVersion=$(MajorMinor).$(Build.BuildNumber)
                          -p:RepositoryUrl=$(Build.Repository.Uri)
                          -p:PackageReleaseNotes=$(Build.SourceVersionMessage)'
            displayName: 'NuGet Pack'
          - task: NuGetCommand@2
            inputs:
              command: 'push'
              packagesToPush: '$(Build.ArtifactStagingDirectory)/**/*.nupkg'
              publishFeedCredentials: 'SistecNuGetFeed'
              allowPackageConflicts: false
            displayName: 'NuGet Push'

14.3 Quality Gates (SonarQube)

Gates applicati a ogni build su main:

14.4 Versionamento Automatico

# Version scheme: Major.Minor.DayOfYear.Revision
# Esempio: Sistec.Stack.Kuka 2.3.215.1 (build 215 del 2026, revisione 1)
#
# Major.Minor:
#   - Si aggiorna manualmente nel file azure-pipelines.yml
#   - Major: breaking change nelle interfacce pubbliche
#   - Minor: nuova feature, backward compatible
#
# DayOfYear.Revision:
#   - Automatico: giorno dell'anno (001-366) + revisione build del giorno
#   - Garantisce versioni sempre crescenti e ordinabili

Tutti i layer di uno stack (Client, Driver, Services, UI, Simulator) condividono la stessa versione:

<!-- Directory.Build.props — stesso valore per tutti i progetti dello stack -->
<Project>
  <PropertyGroup>
    <VersionPrefix>2.3.0</VersionPrefix>
    <VersionSuffix>$(VersionSuffix)</VersionSuffix>
    <Authors>Sistec AM</Authors>
    <Company>Sistec AM</Company>
    <RepositoryType>git</RepositoryType>
    <ContinuousIntegrationBuild>true</ContinuousIntegrationBuild>
    <EmbedUntrackedSources>true</EmbedUntrackedSources>
    <DebugType>embedded</DebugType>
    <!-- Source Link per debugging NuGet -->
    <PublishRepositoryUrl>true</PublishRepositoryUrl>
    <IncludeSymbols>true</IncludeSymbols>
    <SymbolPackageFormat>snupkg</SymbolPackageFormat>
  </PropertyGroup>
</Project>

14.5 Struttura Repository per Stack

sistec-kuka-stack/
├── azure-pipelines.yml           ← Pipeline CI/CD
├── Directory.Build.props          ← Versioning condiviso
├── src/
│   ├── Sistec.Stack.Kuka.Client/     ← .csproj -> Sistec.Stack.Kuka.Client.nupkg
│   ├── Sistec.Stack.Kuka.Driver/     ← .csproj -> Sistec.Stack.Kuka.Driver.nupkg
│   ├── Sistec.Stack.Kuka.Services/   ← .csproj -> Sistec.Stack.Kuka.Services.nupkg
│   ├── Sistec.Stack.Kuka.UI/         ← .csproj -> Sistec.Stack.Kuka.UI.nupkg
│   └── Sistec.Stack.Kuka.Simulator/  ← .csproj -> Sistec.Stack.Kuka.Simulator.nupkg
├── tests/
│   ├── Sistec.Stack.Kuka.UnitTests/   ← NUnit, Category=Unit
│   ├── Sistec.Stack.Kuka.IntegrationTests/ ← NUnit, Category=Integration
│   └── Sistec.Stack.Kuka.SimulatorTests/   ← Test contro il Simulator
├── docs/
├── README.md
└── CHANGELOG.md

14.6 Pipeline HMI Commessa

Diversa dagli stack: non produce NuGet, produce l'EXE finale. Le versioni dei pacchetti NuGet sono fissate nel csproj.

# azure-pipelines-hmi.yml — per ogni commessa (es. Sistec.5315.LAG)
name: $(Build.SourceBranchName).$(DayOfYear)$(Rev:r)

trigger:
  branches:
    include:
      - main
  paths:
    include:
      - 'Sistec.5315.LAG/*'

variables:
  - group: Sistec-NuGet-Auth
  - name: HmiProject
    value: 'Sistec.5315.LAG'

stages:
  - stage: NuGetRestore
    displayName: '📦 Restore NuGet'
    jobs:
      - job: Restore
        steps:
          - task: NuGetCommand@2
            inputs:
              restoreSolution: '$(HmiProject)/$(HmiProject).csproj'
              feedsToUse: 'config'
              nugetConfigPath: '$(HmiProject)/nuget.config'

  - stage: Build
    displayName: '🔨 Build HMI'
    dependsOn: NuGetRestore
    jobs:
      - job: Build
        steps:
          - task: DotNetCoreCLI@2
            inputs:
              command: 'build'
              projects: '$(HmiProject)/$(HmiProject).csproj'
              arguments: '--configuration Release
                          -p:Version=$(Build.BuildNumber)'

  - stage: IntegrationTest
    displayName: '🔌 HMI Integration Test'
    dependsOn: Build
    jobs:
      - job: IntegrationTest
        steps:
          - script: |
              # Avvia simulatori, testa binding layout.json
              dotnet test $(HmiProject)/tests/*.IntegrationTests.csproj
            displayName: 'Run HMI Integration Tests'

  - stage: SonarQube
    displayName: '🔍 SonarQube'
    dependsOn: IntegrationTest
    jobs:
      - job: SonarQube
        steps:
          - task: SonarQubePrepare@7
            inputs:
              SonarQube: 'SistecSonarQube'
              projectKey: 'sistec-$(HmiProject)'
              projectName: '$(HmiProject)'
          - task: SonarQubeAnalyze@7
          - task: SonarQubePublish@7

  - stage: Publish
    displayName: '🚀 Deploy HMI'
    dependsOn: SonarQube
    condition: succeeded()
    jobs:
      - job: Publish
        steps:
          - task: DotNetCoreCLI@2
            inputs:
              command: 'publish'
              projects: '$(HmiProject)/$(HmiProject).csproj'
              arguments: '--configuration Release
                          --output $(Build.ArtifactStagingDirectory)/hmi-release
                          -p:Version=$(Build.BuildNumber)'
          - task: CopyFiles@2
            inputs:
              contents: |
                $(HmiProject)/manifest.json
                $(HmiProject)/layout.json
                $(HmiProject)/config/**/*
                $(HmiProject)/resources/**/*
              targetFolder: '$(Build.ArtifactStagingDirectory)/hmi-release'
          - task: PublishBuildArtifacts@1
            inputs:
              pathToPublish: '$(Build.ArtifactStagingDirectory)/hmi-release'
              artifactName: 'HMI-Release'

14.7 NuGet Feed: Organizzazione

Feed: Sistec-NuGet-Feed
├── Sistec.Core                                   5.1.0, 5.1.1, 5.2.0
├── Sistec.Controls                               4.3.0, 4.3.1
├── Sistec.UI                                     4.3.0
├── Sistec.LayoutEngine                           1.0.0, 1.1.0
├── Sistec.Configuration                          2.0.0
├── Sistec.Infra.Persistence                      2.0.0
├── Sistec.Infra.Persistence.Dapper                2.0.0
├── Sistec.Infra.Persistence.MySql                2.0.0
├── Sistec.Infra.Persistence.SqlServer            2.0.0
├── Sistec.Infra.CodeGen                          1.0.0 (dotnet tool)
├── Sistec.Library.OpcUa                          3.2.0
├── Sistec.Library.Modbus                         2.1.0
├── Sistec.Library.Bus                            1.5.0
│
├── Sistec.Stack.Kuka.Client                      2.3.0
├── Sistec.Stack.Kuka.Driver                      2.3.0       ← stessa versione
├── Sistec.Stack.Kuka.Services                    2.3.0       ← stessa versione
├── Sistec.Stack.Kuka.UI                          2.3.0       ← stessa versione
├── Sistec.Stack.Kuka.Simulator                   2.3.0       ← stessa versione
│
├── Sistec.Stack.Safan.*                          2.1.0
├── Sistec.Stack.Esa.*                            1.0.0
├── Sistec.Stack.PLC.*                            3.0.0
├── Sistec.Stack.Sinumerik.*                      2.0.0
├── Sistec.Stack.Production.*                     1.2.0
├── Sistec.Stack.JobManagement.*                  2.0.0
├── Sistec.Stack.Maintenance.*                    1.1.0
├── Sistec.Stack.Alarms.*                         2.0.0
└── Sistec.Stack.Cloud.*                          1.0.0 (optional)

14.8 Trigger e Automazione

14.9 Strumentazione Consigliata

14.10 Pipeline Best Practices

Fail Fast

I controlli più veloci vanno primi nella pipeline, per dare feedback immediato:

Stage 1: Lint + Code Style Analysis    ← 30 secondi
Stage 2: Build                          ← 1-2 minuti
Stage 3: Unit Tests                     ← 2-3 minuti
Stage 4: Quality Gate (SonarQube)       ← 3-4 minuti
Stage 5: Integration Tests              ← 5-10 minuti
Stage 6: NuGet Publish / Deploy         ← (solo su main)

Un controllo di stile bloccante va scoperto in 30 secondi, non dopo 15 minuti di integrazione. La pipeline è configurata con condition: failed() per fermarsi al primo stage che fallisce.

Caching Aggressivo

# Evita di scaricare NuGet a ogni build
- task: Cache@2
  inputs:
    key: 'nuget | "$(Agent.OS)" | **/packages.lock.json'
    path: '$(NUGET_PACKAGES)'
  displayName: 'NuGet Cache'

Il restore passa da 2-3 minuti a 5-10 secondi con la cache calda.

Target Performance Pipeline

Oltre i 20 minuti gli sviluppatori smettono di aspettare il feedback — la pipeline perde efficacia.

Quality Gate Pratico

Gate applicato automaticamente a ogni PR su main:
├── Coverage ≥ 70% su codice nuovo (unit)
├── Coverage ≥ 50% su codice nuovo (integration)
├── 0 nuovi bug critici / blocker
├── 0 vulnerabilità critiche
├── Duplicazione < 3%
└── Maintainability Rating = A

Nessun gate bypassabile manualmente. Se il gate fallisce, la PR non si merge.

14.11 Impatto sulla Roadmap

La pipeline CI/CD non è una fase separata: si costruisce insieme a ogni stack.

Fase 1: Kuka.Stack pilota
  ├── Codice: Sistec.Stack.Kuka.*
  ├── Test: NUnit UnitTests + IntegrationTests + SimulatorTests
  ├── Pipeline: azure-pipelines.yml (build → test → SQ → NuGet)
  └── SonarQube: quality gate attivo

Fase 2: Ogni nuovo stack
  ├── Template pipeline già pronto (si copia/incolla dal pilota)
  ├── Test specifici dello stack
  └── SonarQube: progetto separato per stack

Fase 6: HMI Commessa
  ├── Pipeline HMI già costruita (usa i pacchetti NuGet)
  ├── Solo Integration Test HMI (layout.json, simulatori)
  └── SonarQube: analisi del codice HMI (minimo, è solo config)

15. Testing e Qualità del Codice

La strategia di test per la nuova commessa greenfield deve garantire feedback rapido, copertura mirata e test che durano nel tempo, evitando gli errori visti nelle codebase legacy (13 copie di FakeOpcUa, pochissimi test automatici, nessun quality gate strutturato).

15.1 Test Pyramid per HMI Industriale

                  ┌──────┐
                  │ E2E  │    ← 1-2 per flusso critico (login, job completo)
                 ┌┴──────┴┐
                 │Integr. │    ← Con Simulator (Kuka, Safan, PLC)
                ┌┴────────┴┐
                │  Unit    │    ← Logica pura: Services, Driver parsing
               ┌┴──────────┴┐
               │  Static    │    ← Lint, code style, SonarQube analysis
               └────────────┘

Regola d'oro: 50-100 unit test : 5-10 integration test : 1 E2E test.

15.2 FIRST Principles per Ogni Test

AAA Pattern

[Test]
public void CalculateBendAngle_WhenValidInput_ReturnsCorrectAngle()
{
    // Arrange
    var service = new BendingCalculator();
    double thickness = 2.5;
    double radius = 8.0;

    // Act
    double result = service.CalculateBendAngle(thickness, radius);

    // Assert
    Assert.That(result, Is.EqualTo(88.3).Within(0.1));   // ← messaggio implicito
}

• Arrange: setup dello scenario (max 10 righe — altrimenti tropẹ dipendenze → refactoring)
• Act: una sola chiamata, una riga
• Assert: una asserzione logica per test, con messaggio descrittivo

Naming

method_scenario_expectedResult
oppure
should_result_when_scenario

Esempi:

• ParseKukaPayload_WhenChecksumInvalid_ThrowsChecksumException()
• ShouldReturnNull_WhenJobListIsEmpty()

15.3 Mocking Strategy

Golden Rules

Scelta del Test Double Giusto

Nella Nuova Commessa

// ✅ CORRETTO: mocko l'interfaccia che possiedo
var krcClientMock = new Mock<IKrcClient>();
krcClientMock
    .Setup(x => x.SendCommandAsync(It.IsAny<KrcCommand>(), It.IsAny<CancellationToken>()))
    .ReturnsAsync(new KrcResponse(Success: true, Payload: "OK"));

// ❌ SBAGLIATO: mocko TcpClient di System.Net.Sockets (non lo possiedo)
var tcpMock = new Mock<TcpClient>();   // fragile, legato all'implementazione

15.4 TDD: Quando Usarlo

Il ciclo RED → GREEN → REFACTOR è ideale per la logica pura (Services, Driver, algoritmi di parsing, validazione):

Ciclo baby steps:

1. RED: scrivi test che fallisce (definisce il comportamento)
2. GREEN: scrivi il minimo indispensabile per farlo passare
3. REFACTOR: migliora la struttura senza cambiare comportamento — non è opzionale

YAGNI (You Ain't Gonna Need It): scrivi solo il codice necessario a far passare il test. Niente "tanto lo aggiungo già che ci sono".

15.5 Code Quality

Metriche Target

Attenzione: coverage ≠ qualità. Il 100% di coverage non garantisce codice corretto — misura solo che ogni riga sia stata eseguita almeno una volta. Meglio 70% di test significativi che 100% di "assert al ribasso".

Anti-Pattern da Evitare

15.6 Testing Culture

Maturity Model

La nuova commessa parte dal livello 2, tendendo al 3 entro la prima release.

Definition of Done

Una feature è completa SOLO quando:

• Codice implementato
• Test unitari scritti e passano (coverage ≥ 70% sulla nuova logica)
• Test di integrazione scritti e passano
• Pipeline CI/CD verde su PR
• SonarQube quality gate superato
• Code review fatta (test inclusi nella review!)

Zero Tolleranza per Test Flaky

Un test flaky (a volte passa, a volte no):

1. Si disabilita SUBITO (non si lascia nella pipeline)
2. Si apre un bug per sistemarlo
3. Si riabilita solo quando è stabile

15.7 Contract Testing tra Stack

I layer Services degli stack verticali consumano interfacce definite in Sistec.Core e da altri stack. Quando uno stack evolve, può rompere i consumatori.

Soluzione: Contract Testing (Pact) per le interfacce pubbliche:

// Consumer (Sistec.Stack.Production) definisce il contratto
[Test]
public void Production_Expects_KukaService_Contract()
{
    var contract = new MessagePactBuilder()
        .Given("Kuka robot is online")
        .UponReceiving("a request to load panel")
        .With(Request("POST", "/kuka/load-panel", body: new { gripper = "vacuum_a" }))
        .WillRespondWith(Response(200, body: new { status = "loading" }));
    
    // Il contract viene pubblicato — Kuka.Stack deve verificarlo in CI
}

Questo evita rotture silenziose: se Kuka.Stack cambia la firma di ILoadPanelService, la pipeline di Production.Stack fallisce prima del deploy.

15.8 Testing in Contesto Safety-Critical

L'HMI comanda macchinari industriali. Alcuni principi aggiuntivi:

• Ogni bug corretto porta con sé un test di regressione — non si chiude mai un bug fix senza test
• Testare sempre i casi di errore: timeout connessione, checksum errato, risposta vuota, macchina offline
• Validazione input obbligatoria in ogni punto di ingresso (parsing protocollo, comandi utente, tag OPC UA)
• Rollback testato: se un job fallisce a metà, lo stato deve essere consistente

16. Osservabilità

L'osservabilità per un HMI industriale non è solo logging. Un sistema che deve funzionare 24/7 su PC industriali, spesso senza connessione di rete, deve poter essere diagnosticato da remoto, monitorato automaticamente e analizzato a posteriori senza intervento umano.

La sezione §9.7 ha descritto la migrazione dal logger statico a ILogger<T> via DI. Questa sezione estende il quadro a tutte e 4 le dimensioni dell'osservabilità — logs, metrics, traces, health checks — più la diagnostica di campo.

16.1 Architettura dell'Osservabilità

flowchart LR
    subgraph Stacks["STACK VERTICALI"]
        K["Sistec.Stack.Kuka"]
        S["Sistec.Stack.Safan"]
        P["Sistec.Stack.PLC"]
        A["Sistec.Stack.Alarms"]
        J["Sistec.Stack.JobMgmt"]
        Pr["Sistec.Stack.Production"]
    end

    subgraph Observability["OSSERVABILITÀ"]
        Logs["ILogger<T>
JSON strutturato"]
        Metrics["System.Diagnostics.Metrics
Counter / Histogram"]
        Traces["ActivitySource
OpenTelemetry"]
        Health["IHealthCheck
Microsoft.Extensions"]
    end

    subgraph Storage["MEMORIZZAZIONE"]
        LogFile["File JSON
rotazione giornaliera"]
        MetricsCache["Metriche in memoria
esportazione periodica"]
        TraceColl["OTLP Collector
(opzionale)"]
        HealthAgg["Health Aggregator
stato composito"]
    end

    subgraph Consumatori["CONSUMATORI"]
        Dashboard["Dashboard locale
Avalonia"]
        Cloud["Cloud.Stack
MQTT / HTTP"]
        Alert["Alerting
Critical → sveglia turnista"]
        Field["Field Diagnostics
USB key / API"]
    end

    Stacks -->|ILogger| Logs
    Stacks -->|Meter| Metrics
    Stacks -->|Activity| Traces
    Stacks -->|IHealthCheck| Health

    Logs --> LogFile
    Metrics --> MetricsCache
    Traces --> TraceColl
    Health --> HealthAgg

    LogFile --> Dashboard
    LogFile --> Field
    MetricsCache --> Dashboard
    MetricsCache --> Cloud
    TraceColl --> Cloud
    HealthAgg --> Dashboard
    HealthAgg --> Alert

16.2 Structured Logging + Industrial Event Schema

Già coperto in §9.7. Riepilogo punti chiave:

• Output JSON, non plain text
• ILogger<T> via DI, non statico
• Named placeholders {Gripper} non interpolazione $"..."
• Configurabile via appsettings.json
• Tre astrazioni unite in una sola

16.2.1 Industrial Event Schema

Ogni evento di business segue uno schema standardizzato per garantire consistenza tra stack:

public record IndustrialEvent(
    string CorrelationId,       // Sessione operatore
    string OperatorId,          // Badge operatore (se logged)
    string MachineId,           // "Kuka_0", "Safan_1"
    string EventType,           // "CommandSent", "JobStarted", "AlarmRaised"
    string Category,            // "Production", "Alarm", "Maintenance", "Security"
    IReadOnlyDictionary<string, object> Payload,
    DateTime Timestamp
);

{
  "@t": "2026-07-02T14:30:00.123Z",
  "@l": "Information",
  "EventType": "CommandSent",
  "Category": "Production",
  "MachineId": "Kuka_0",
  "CorrelationId": "a1b2c3d4e5f6",
  "OperatorId": "42",
  "Payload": {
    "command": "LoadPanel",
    "gripper": "vacuum_a",
    "duration_ms": 2340
  }
}

Questo schema permette query cross-stack: "tutti gli eventi di MachineId=Kuka_0 tra le 14:00 e le 15:00".

16.3 Correlation ID e Trace Context

16.3.1 Session Correlation

Ogni sessione operatore (dalla login alla logout) ha un Correlation ID che segue tutte le operazioni:

public class OperatorSessionMiddleware
{
    private readonly ILogger _logger;

    public void BeginSession(Employee employee)
    {
        var correlationId = Guid.NewGuid().ToString("N");
        using var _ = _logger.BeginScope(new { CorrelationId = correlationId });
        _logger.LogInformation("Session started: {OperatorId} {BadgeId}",
            employee.BadgeId, employee.BadgeId);
    }
}

Output:

{
  "@t": "2026-07-02T14:30:00.123Z",
  "@l": "Information",
  "@mt": "Loading panel with {Gripper}",
  "Gripper": "vacuum_a",
  "CorrelationId": "a1b2c3d4e5f6789012345678abcdef90",
  "OperatorId": 42,
  "MachineName": "SPV-LAG-01"
}

Vantaggio: si può tracciare esattamente cosa ha fatto un operatore durante il suo turno — "quale comando ha causato l'allarme?", "quanto tempo tra login e primo job?".

16.3.2 Trace Context Propagation

Il trace context attraversa i layer dello stack (UI → Services → Driver → Client → PLC). System.Diagnostics.Activity gestisce il propagation automaticamente se i layer sono nello stesso processo:

// Services layer
public async Task ExecuteProgramAsync(string programId)
{
    using var activity = SistecDiagnostics.ActivitySource.StartActivity("ExecuteProgram");
    activity?.SetTag("program.id", programId);

    try
    {
        await _driver.ExecuteProgramAsync(programId);
        activity?.SetStatus(ActivityStatusCode.Ok);
    }
    catch (Exception ex)
    {
        activity?.SetStatus(ActivityStatusCode.Error, ex.Message);
        throw;
    }
}

Per chiamate cross-process (API REST a MES/ERP), il trace context va propagato via W3C TraceContext header.

16.4 Livelli di Log

Regola: passare a DEBUG solo durante la risoluzione incidenti, mai permanentemente.

16.5 Cosa NON Loggare

16.6 Health Check System

16.6.1 Architettura

Ogni stack implementa IHealthCheck da Microsoft.Extensions.Diagnostics.HealthChecks. Il Composition Root aggrega tutti gli health check in un cruscotto unificato:

flowchart LR
    subgraph Stacks["HEALTH CHECKS PER STACK"]
        KUKA["KukaHealthCheck
Ping KRC TCP"]
        SAFAN["SafanHealthCheck
Stato connessione pressa"]
        PLC["PlcHealthCheck
OPC UA session state"]
        DB["DbHealthCheck
SELECT 1 su MySQL"]
        ALARM["AlarmHealthCheck
Alarm flood detector"]
    end

    AGG["HealthAggregator
Composizione risultati"]
    DASH["Dashboard locale
Avalonia HealthPage"]
    ALERT["Alert engine
Critical → azione immediata"]

    KUKA --> AGG
    SAFAN --> AGG
    PLC --> AGG
    DB --> AGG
    ALARM --> AGG
    AGG --> DASH
    AGG --> ALERT

16.6.2 Implementazione

public class KukaHealthCheck : IHealthCheck
{
    private readonly IKrcClient _krcClient;

    public async Task<HealthCheckResult> CheckHealthAsync(
        HealthCheckContext context, CancellationToken ct)
    {
        try
        {
            bool connected = await _krcClient.PingAsync(ct);
            return connected
                ? HealthCheckResult.Healthy()
                : HealthCheckResult.Unhealthy("KUKA KRC not reachable");
        }
        catch (Exception ex)
        {
            return HealthCheckResult.Unhealthy("KUKA check failed", ex);
        }
    }
}

public static IServiceCollection AddHealthChecks(this IServiceCollection services)
{
    services.AddHealthChecks()
        .AddCheck<KukaHealthCheck>("KUKA", tags: ["kuka", "robot"])
        .AddCheck<SafanHealthCheck>("Safan", tags: ["press", "critical"])
        .AddCheck<PlcHealthCheck>("PLC", tags: ["plc", "critical"])
        .AddCheck<DbHealthCheck>("Database", tags: ["infra"])
        .AddCheck<AlarmHealthCheck>("Alarms", tags: ["alarm"]);

    return services;
}

16.6.3 Health Status Mapping

Il mapping è esposto nella dashboard locale e via API REST (GET /api/v1/health).

Riferimento codebase: ReconnectAgent.cs, KrcClient.cs, ModbusConnector.cs, OpcUaClient.cs — nessuno implementa health check standardizzato.

16.7 Metrics

16.7.1 Per-Stack Counters

Ogni stack espone metriche via System.Diagnostics.Metrics. FAEL referenzia già System.Diagnostics.DiagnosticSource 10.0.6 in Directory.Packages.props:29 ma non lo usa.

public static class SistecMetrics
{
    public static readonly Meter ProductionMeter = new("Sistec.Production", "1.0.0");

    public static readonly Counter<int> PartsProduced =
        ProductionMeter.CreateCounter<int>("parts.produced",
            description: "Pezzi prodotti");

    public static readonly Histogram<double> CycleTime =
        ProductionMeter.CreateHistogram<double>("cycle.time_ms",
            unit: "ms", description: "Tempo ciclo per pezzo");

    public static readonly Counter<int> CommandsSent =
        ProductionMeter.CreateCounter<int>("commands.sent",
            description: "Comandi inviati ai macchinari");
}

// Uso in Production.Stack
public async Task RecordPartProduced(string machineId, double cycleTimeMs)
{
    SistecMetrics.PartsProduced.Add(1,
        new KeyValuePair<string, object?>("machine", machineId));
    SistecMetrics.CycleTime.Record(cycleTimeMs,
        new KeyValuePair<string, object?>("machine", machineId));
}

Con Redis opzionale, i contatori produzione usano `INCR` atomico su `sistec:{plant}:production:{counter}` (es. `parts.produced`, `scrap.count`). Due pannelli che producono simultaneamente non generano race condition. Il valore Redis viene flushato su MySQL periodicamente. La dashboard web (§19.12) legge contatori in tempo reale da Redis senza impattare il DB.

16.7.2 Metriche Raccomandate per Stack

16.7.3 Esportazione

Le metriche sono esposte in due modalità:

1. Locale — accessibili via API REST (GET /api/v1/metrics) per la dashboard HMI interna
2. Cloud — se presente Sistec.Stack.Cloud, esportate via OpenTelemetry Protocol (OTLP) o Prometheus scraping

{
  "Metrics": {
    "ExportMode": "Local",
    "OtlpEndpoint": "",
    "OtlpHeaders": {},
    "LocalPort": 5001
  }
}

Riferimento codebase: Sistec.Core/Utils/PropertyNotifier.cs già notifica cambi valore — punto di hook naturale per metriche senza modificare i consumer.

16.8 Distributed Tracing

16.8.1 OpenTelemetry Integration

public static class SistecDiagnostics
{
    public static readonly ActivitySource ActivitySource = new("Sistec", "1.0.0");
}

Ogni operazione cross-stack (UI → Services → Driver → Client → PLC) è un trace:

public async Task ExecuteProgramAsync(string programId)
{
    using var activity = SistecDiagnostics.ActivitySource.StartActivity(
        ActivityKind.Internal,
        tags: new[] {
            KeyValuePair.Create<string, object?>("program.id", programId),
            KeyValuePair.Create<string, object?>("machine.type", "Safan")
        });

    try
    {
        await _safanClient.ExecuteProgramAsync(programId);
        activity?.SetStatus(ActivityStatusCode.Ok);
    }
    catch (Exception ex)
    {
        activity?.SetStatus(ActivityStatusCode.Error);
        activity?.SetTag("error.message", ex.Message);
        throw;
    }
}

16.8.2 Span Naming Convention

{stack}.{layer}.{operation}
  kuka.driver.loadPanel
  safan.client.executeProgram
  plc.services.readTags
  production.services.recordPart

16.8.3 OTLP Collector Deployment

Il collector OpenTelemetry è opzionale. Sul PC industriale, si deploya come container Docker o processo Windows separato:

# otel-collector-config.yaml
receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317

processors:
  batch:
    timeout: 1s
  memory_limiter:
    limit_mib: 256

exporters:
  logging:
    loglevel: warn
  otlp:
    endpoint: "cloud-collector:4317"

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [memory_limiter, batch]
      exporters: [logging, otlp]

16.9 Diagnostics Mode

Gli operatori di campo (collaudatori, manutentori Sistec) hanno bisogno di diagnostica senza deployare una build speciale.

16.9.1 Implementazione

public enum DiagnosticsLevel
{
    None,       // Produzione normale — solo INFORMATION+
    Basic,      // + DEBUG per stack specifici
    Verbose,    // + TRACE per tutto
    CrashDump   // Cattura minidump su crash
}

public class DiagnosticsService
{
    private DiagnosticsLevel _level = DiagnosticsLevel.None;

    public void SetLevel(DiagnosticsLevel level, string? stackFilter = null)
    {
        _level = level;
        var switch = new LoggingLevelSwitch
        {
            MinimumLevel = level switch
            {
                DiagnosticsLevel.Verbose => LogEventLevel.Verbose,
                DiagnosticsLevel.Basic   => LogEventLevel.Debug,
                _                        => LogEventLevel.Information
            }
        };
    }
}

16.9.2 Attivazione

16.9.3 Cosa Produce

• Log JSON a livello DEBUG/TRACE
• Minidump su crash (configurabile: full o mini)
• Snapshot metriche in memoria
• Health check report completo
• Network dump dei protocolli attivi (TCP/Modbus/OPC UA)

16.10 Dead Man's Switch e Self-Diagnostics

16.10.1 Heartbeat

Ogni stack produce un heartbeat periodico. Se manca per più del timeout, scatta allarme:

public class HeartbeatService : BackgroundService
{
    private readonly ILogger<HeartbeatService> _logger;
    private readonly IHealthAggregator _health;
    private readonly TimeSpan _interval = TimeSpan.FromSeconds(30);

    protected override async Task ExecuteAsync(CancellationToken ct)
    {
        while (!ct.IsCancellationRequested)
        {
            await Task.Delay(_interval, ct);
            var status = await _health.GetCompositeStatusAsync(ct);
            _logger.LogInformation("Heartbeat: {Status} {Timestamp:R}",
                status, DateTime.UtcNow);

            if (status == CompositeHealthStatus.Unhealthy)
                _logger.LogCritical("System unhealthy: {Report}",
                    await _health.GetReportAsync(ct));
        }
    }
}

16.10.2 Self-Diagnostics Checklist

All'avvio, l'HMI esegue self-diagnostics:

1. IHealthCheck di ogni stack — tutti Healthy?
2. Disco — spazio sufficiente per log e DB?
3. Memoria — RAM ≥ requisito minimo?
4. Connessioni — KUKA, pressa, PLC raggiungibili?
5. Database — MySQL accessibile e schema aggiornato?
6. Certificati — OPC UA, HTTPS non scaduti?

Risultato: report JSON salvato in startup.diagnostics.json, visibile in dashboard.

16.11 SLO/SLI

16.12 Crash Dump Strategy

Il PC industriale deve continuare a funzionare anche dopo un crash:

public class CrashHandler
{
    public void Attach()
    {
        AppDomain.CurrentDomain.UnhandledException += (_, args) =>
        {
            var dumpPath = Path.Combine(
                AppContext.BaseDirectory, "crashdumps",
                $"crash_{DateTime.UtcNow:yyyyMMdd_HHmmss}.dmp");

            Directory.CreateDirectory(Path.GetDirectoryName(dumpPath)!);
            MiniDumpWriter.Write(dumpPath, MiniDumpType.WithDataSegs);

            _logger.LogCritical("Crash: {Exception}, dump: {Path}",
                args.ExceptionObject, dumpPath);

            if (args.IsTerminating)
                RestartApplication();
        };
    }
}

16.13 Log-Alarm Correlation

Ogni allarme in Sistec.Stack.Alarms è correlato ai log tramite CorrelationId:

public record AlarmEvent(
    string Id,
    string CorrelationId,     // ← link ai log
    DateTime RaisedAt,
    // ...
);

Flusso di diagnostica:

1. Operatore segnala allarme X
2. Dashboard: alarms/{id} → mostra log correlati
3. Filtro per CorrelationId → tutti gli eventi prima/dopo l'allarme
4. Si identifica la causa radice

16.14 Retention Policy

Cloud (opzionale): se Cloud.Stack presente, invia log critici e metriche aggregate a Elasticsearch / Prometheus.

16.15 Performance Budget

Il budget è monitorato dalle metriche (command.latency_ms) e visibile in dashboard.

16.16 8 Best Practice del Monitoring

1. Partire dall'esperienza utente — Monitorare prima cosa vede l'operatore (latenza comandi, errori UI, risposta KUKA), poi l'infrastruttura
2. Allertamento a strati — Critical (sveglia turnista): HMI offline, KUKA disconnesso. Warning (Slack): riconnessione, buffer in crescita. Info (dashboard): uptime, pezzi/h
3. Allertare sui sintomi, non sulle cause — CPU al 95% non è un problema se l'HMI risponde bene. Tasso errori in crescita (sintomo) sveglia sempre
4. Soglie significative — Basare allarmi su dati storici, non su valori arbitrari. Se il tempo ciclo medio è 12s, allarmare a 18s (50% sopra), non a 30s
5. Correlazione con i deploy — Annotare ogni deploy sulla dashboard. La maggior parte degli incidenti è causata da modifiche al sistema
6. Monitorare il monitoring — Dead man's switch: se l'agente di logging non invia heartbeat per 5 minuti, allarme
7. Pianificare i costi — Retention policy, compressione, archiviazione. Non pagare per log inutili
8. Dashboard per ruolo — Operatore: produzione, scarti. Manutenzione: allarmi, RUL. Manager: OEE, trend

17. Automazione Deploy PC Industriali con Ansible

17.1 Scenario Attuale

PC Industriale (Windows 10/11 IoT)
├── WSL2 (Debian)
│   ├── Docker Engine
│   │   ├── Container CODESYS (Next, vPLC1, vPLC2, ...)
│   │   └── Container KUKA / Sinumerik / edge
│   └── codesys.sh (script gestione)
├── HMI C# (servizio Windows / applicazione)
├── MySQL (database locale)
├── Firewall (regole manuali)
└── Utenti (configurazione manuale)

Criticità: setup manuale (2-4 ore), documentazione assente, variabilità tra PC, nessun rollback.

17.2 Architettura Ansible

flowchart LR
    subgraph Tech["Tecnico / CI/CD"]
        A1["Lancia playbook
`ansible-playbook site.yml`"]
    end

    subgraph Repo["Repository Ansible
(versionato su git)"]
        R1["inventory/hosts.ini
IP, credenziali vault"]
        R2["roles/common/
hostname, utenti, firewall"]
        R3["roles/wsl_docker/
WSL2 + Docker + CODESYS"]
        R4["roles/mysql/
MySQL install + DB + utenti"]
        R5["roles/hmi_app/
Deploy HMI + servizio Windows"]
        R6["roles/monitoring/
Heartbeat, log forwarding"]
    end

    subgraph PC["PC Industriale (WinRM)"]
        P1["Hostname + IP statico"]
        P2["Firewall + Utenti"]
        P3["WSL2 + Docker + containers"]
        P4["MySQL + database + dump"]
        P5["HMI .exe + appsettings.json + servizio"]
        P6["Certificati + monitoring"]
    end

    A1 --> Repo
    Repo -->|WinRM| PC

17.3 Componenti Automabili