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

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.1 Progetti Fondazione (identici in entrambi)

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

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

    subgraph FAEL_Only["SOLO 5309 FAEL"]
        KukaClient["Kuka.Client (netstandard2.1)<br/>Client TCP KRC robot<br/>11 file"]
        EsaClient["Esa.Client (netstandard2.1)<br/>Client Modbus pressa ESA<br/>6 file"]
        EasyModbus["EasyModbus (netstandard2.1)<br/>Stack Modbus TCP puro"]
        Bus["Sistec.Bus (net8.0-windows)<br/>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/<br/>Business logic"]
        CC["Controls/<br/>User controls applicativi"]
        CDB["DB/<br/>Repository implementazioni"]
        CDTO["DTO/<br/>Data Transfer Objects"]
        CDUT["DUT/<br/>Data Unit Type (OPC UA)"]
        CModel["Model/<br/>Modelli dominio applicativi"]
        CCells["Cells/<br/>Viste cella"]
        CDialogs["Dialogs/<br/>Finestre dialogo"]
        CLayout["Layout/<br/>Pagine layout"]
        CFrmHMI["FrmHMI/<br/>LogicFactory, LogicCollection"]
    end

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

Metriche comuni:

1.3 Le God Class

flowchart LR
    subgraph LAG["5315 LAG"]
        MF["MainForm<br/>19 partial file<br/>Orchestrazione centrale:<br/>PLC, KUKA, Safan,<br/>Sinumerik, Watchdog,<br/>Job, pagine, popup"]
    end
    subgraph FAEL["5309 FAEL"]
        FH["FrmHMI (AB)<br/>24 partial file, ~5.156 righe<br/>Orchestrazione centrale:<br/>PLC, KUKA, Modbus,<br/>ESA, DB, Watchdog,<br/>Produzione, Manutenzione"]
        FHC["FrmHMI (C)<br/>17 partial file, ~2.499 righe<br/>Stesso pattern,<br/>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<br/>LAG: Sistec.Core/Interfaces/IRobotLogic<br/>FAEL: (mancante, uso diretto)"]
        Client["Client TCP KRC<br/>LAG: assente (mescolato)<br/>FAEL: Kuka.Client ✅"]
        Logic["Logica Robot<br/>LAG: Common/Logic/RobotLogicKuka<br/>FAEL: Common/Logic (misto)"]
        U1["UI Controls<br/>LAG: Sistec.Controls/Robots +<br/>Common/Controls/RobotCommands"]
        U2["FAEL: AB/Robots/ +<br/>AB/FrmHMI/FrmHMI.Robot.cs"]
        Config["Config<br/>LAG: HMI/Config/Kuka.ini<br/>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.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<br/>orizzontale (condivisa)"]
        DEP_SOLID["● ──→ Dipende da layer interno<br/>dello stesso stack"]
    end

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

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

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

    style Horizontal fill:#9ff2fc,stroke:#006064,stroke-dasharray: 5 5,color:#1a1a1a

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<br/>Modelli dominio, Interfacce pure<br/>Enum, Eccezioni, Eventi<br/>netstandard2.1"]
        Controls["Sistec.Controls<br/>Controlli WinForms generici<br/>Led, Button, Container, Motors, Valves<br/>Nessuna logica di dominio"]
        SistecUI["Sistec.UI<br/>Layout pagine, menu,<br/>alarm banner, user management"]
    end

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

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

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

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

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

    subgraph CodeGen["CODE GENERATION"]
        DUTGen["Sistec.Infra.CodeGen<br/>dotnet tool<br/>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:#87ff90,stroke:#2e7d32,color:#1a1a1a
    classDef comm fill:#fce4ec,stroke:#c62828,color:#1a1a1a
    classDef machine fill:#87ff90,stroke:#2e7d32,color:#1a1a1a
    classDef app fill:#ffe285,stroke:#f57f17,color:#1a1a1a
    classDef data fill:#f3e5f5,stroke:#7b1fa2,color:#1a1a1a
    classDef infra fill:#9ff2fc,stroke:#006064,color:#1a1a1a

    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<br/>KrcClient, KrcConnectionPool"]
        Safan_Client["Sistec.Stack.Safan.Client<br/>SafanClient"]
        Plc_Client["Sistec.Stack.PLC.Client<br/>OpcUaClientCollection"]
        Sinu_Client["Sistec.Stack.Sinumerik.Client<br/>CNC OPC UA wrapper"]
        Esa_Client["Sistec.Stack.Esa.Client<br/>EsaModbusClient"]
    end

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

    style Orizzontali fill:#9ff2fc,stroke:#006064,stroke-dasharray: 5 5,color:#1a1a1a

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<br/>Composition Root +<br/>pagine specifiche LAG"]
        FAEL_AB["Sistec.5309.HMI.AB<br/>Composition Root +<br/>pagine specifiche AB"]
        FAEL_C["Sistec.5309.HMI.C<br/>Composition Root +<br/>pagine specifiche C"]
        BS["Sistec.5309.HMI.BS<br/>Composition Root +<br/>pagine specifiche BS"]
    end

    subgraph Shell["SISTEC.HMI.SHELL (shared)"]
        CR["Program.cs + FrmHMI thin<br/>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<br/>(Zebus o HTTP+Redis)"]
        RLib["Sistec.Library.Redis<br/>(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:#80c9ff,stroke:#1565c0,color:#1a1a1a
    classDef shell fill:#80c9ff,stroke:#1565c0,stroke-width:3px,color:#1a1a1a
    classDef prod fill:#ffe285,stroke:#f57f17,color:#1a1a1a
    classDef machine fill:#87ff90,stroke:#2e7d32,color:#1a1a1a
    classDef foundation fill:#87ff90,stroke:#2e7d32,color:#1a1a1a
    classDef infra fill:#f3e5f5,stroke:#7b1fa2,color:#1a1a1a

    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<br/>(dotnet tool)"]
    GEN --> POCO["Sistec.Stack.PLC.DTO (generated/)<br/>← POCO puri (senza EncodeableBase)"]
    GEN --> OPCENC["Sistec.Stack.PLC.OPCUA (generated/)<br/>← Encodeable version"]
    GEN --> TAGS["Sistec.Stack.PLC.Tags (generated/)<br/>← TagConstants.Main.ProductionValid"]
    GEN --> BIND["Sistec.Stack.PLC.Binding (generated/)<br/>← 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.

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).

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

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

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

• 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.
• 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).
• SQL injection — frmUserManagement.cs costruisce query con interpolazione diretta: $"INSERT INTO accounts ... VALUES ('{txtuserPassword.Text}')". Operazioni CRUD attualmente commentate (non funzionanti).
• 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?".
• Auto-login backdoor — File loginSistec.ls bypassa completamente l'autenticazione.
• Login dialog rudimentale — Nessun supporto per badge RFID, nessun login con tessere, nessun PIN rapido (solo password testuale).
• 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).
• 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<br/>ID | UserLevel | Password | Name_it"]
        A2["Login: scegli ruolo<br/>da ComboBox"]
        A3["Produzione: anonima<br/>nessun legame operatore"]
    end

    subgraph FUTURE["DOMANI — Utenti Reali"]
        B1["employees table<br/>BadgeId | Nome | Turno | Role"]
        B2["Login: badge RFID<br/>o selezione dipendente"]
        B3["Produzione: tracciata<br/>per operatore"]
        B4["Statistiche: pezzi/h,<br/>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.

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<br/>Versione, Variante,<br/>Stack attivi, Riferimenti"]
    end

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

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

    subgraph Rendering["RENDERING"]
        RZ["ZoneRenderer<br/>Contenitore zona →<br/>disposizione controlli"]
        RC["ControlFactory<br/>Nome controllo →<br/>istanza UserControl dallo stack"]
        RD["DialogFactory<br/>Dialoghi (manutenzione,<br/>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<br/>impianto"] --> B["Ingegnere compila<br/>manifest.json layout.json config/"]

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

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

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

    E --> F{"Tutto OK?"}
    F -->|Sì| G["Consegnato.<br/>Zero righe di codice scritte."]
    F -->|No| H["Si modifica solo<br/>layout.json o config/<br/>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

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<br/>pubblica: cicli gripper,<br/>torque giunti, ore moto<br/>via IMachineTelemetryProvider"]
        Safan["Sistec.Stack.Safan<br/>pubblica: numero pieghe,<br/>forza cilindri, errori"]
        Plc["Sistec.Stack.PLC<br/>pubblica: ore macchina,<br/>temperature motori, vibrazioni"]
    end

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

    subgraph Config["CONFIGURAZIONE"]
        Models["models/*.onnx<br/>modello addestrato<br/>per macchinario-specifico"]
        Thresholds["thresholds.json<br/>soglie RUL per<br/>ogni componente<br/>{warning, critical}"]
        SchedCfg["schedules.json<br/>manutenzione time-based<br/>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<br/>opzionale: invia features<br/>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<br/>→ posizione giunti, stato"]
        Safan["Sistec.Stack.Safan<br/>→ corsa cilindro, forza"]
        Plc["Sistec.Stack.PLC<br/>→ sensori, allarmi"]
    end

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

    subgraph UI["UI Avalonia"]
        DT_View["DigitalTwinView<br/>Control registrato in ControlRegistry<br/>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:#80c9ff,color:#1a1a1a

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<T> 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.

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<br/>netstandard2.1"]
        Controls["Sistec.Controls<br/>net8.0-windows"]
        SistecUI["Sistec.UI<br/>net8.0-windows"]
        LayoutEngine["Sistec.LayoutEngine<br/>net8.0-windows"]
        ConfigLib["Sistec.Configuration<br/>netstandard2.1"]
        Persistence["Sistec.Infra.Persistence*<br/>netstandard2.1"]

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

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

        Safan["Sistec.Stack.Safan"]
        Gade["Sistec.Stack.Gade<br/>(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:#87ff90,stroke:#2e7d32,color:#1a1a1a
    classDef optional fill:#ffe285,stroke:#f57f17,color:#1a1a1a

    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<br/>commessa"] --> B["🏗️ Ingegnere<br/>crea progetto da template<br/>`dotnet new sistec-hmi`"]

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

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

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

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

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

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

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

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

10.5 Impatto su Sviluppo e Consegna

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<br/>Core versione 4.5.*"]
        FAEL["FAEL: mileston/v3.25<br/>Core versione 3.25.*"]
        LAG -.->|API incompatibili| FAEL
    end

    subgraph Domani["DOMANI — NuGet unificato"]
        direction TB
        FEED["Feed NuGet Sistec<br/>Una sola Sistec.Core nuget"]
        LAGv2["LAG: PackageReference<br/>Sistec.Core 5.0.0"]
        FAELv2["FAEL: PackageReference<br/>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.

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<br/>(UserControl WinForms)"]
        SVC["Sistec.Stack.Kuka.Services<br/>(logica pura)"]
        DRV["Sistec.Stack.Kuka.Driver<br/>(tag provider)"]
        CLI["Sistec.Stack.Kuka.Client<br/>(TCP KRC)"]
    end

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

    subgraph Domani["DOMANI — Avalonia"]
        UI_AV2["Sistec.Stack.Kuka.UI<br/>(solo Avalonia, WinForms rimosso)"]
        SVC3["Sistec.Stack.Kuka.Services<br/>(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<br/>Avalonia su Windows/Linux<br/>→ Controllo macchine"]
    end

    subgraph Browser["WEBASSEMBLY (Browser)"]
        WASM1["PC Ufficio Tecnico<br/>sistec-hmi.local:5000<br/>→ Monitoraggio + parametri"]
        WASM2["Tablet Capoturno<br/>→ Stato produzione"]
        WASM3["TV Reparto<br/>→ 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

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<br/>Lettore USB seriale"]
        PIN["PIN rapido<br/>4-6 cifre"]
        SEL["Selezione da lista<br/>touch screen"]
    end

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

    subgraph UI["UI"]
        LOGIN["LoginPage<br/>Pick operatore + PIN"]
        DASH["DashboardStat<br/>Pezzi/h, scarti %, tempi ciclo"]
        ADMIN["AdminPage<br/>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.

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

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<br/>Sistec.HMI.exe"]
        MM_KUKA["Sistec.Stack.Kuka<br/>(DLL in-process)"]
        MM_SAFAN["Sistec.Stack.Safan<br/>(DLL in-process)"]
        MM_PLC["Sistec.Stack.PLC<br/>(DLL in-process)"]
        MM_PRODUCTION["Sistec.Stack.Production<br/>(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<br/>(processo separato)"]
        MS_SAFAN["Safan.Service<br/>(processo separato)"]
        MS_PLC["Plc.Service<br/>(processo separato)"]
        MS_PRODUCTION["Production.Service<br/>(processo separato)"]
        MS_HMI["HMI (Avalonia)<br/>(processo separato)"]
        MS_BROKER["Message Broker<br/>(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:

• Central Control Room: l'HMI non è più su un pannello locale, ma c'è un server centrale che gestisce 20 celle di produzione contemporaneamente
• Multi-tenant: lo stesso software serve 10 impianti diversi da un unico server
• 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<br/>Si sottoscrive a eventi<br/>degli altri stack"]
            MQTT["MqttPublisher<br/>Invia a broker MQTT<br/>o HTTP API"]
            Buffer["OfflineBuffer<br/>Coda locale se cloud<br/>non disponibile"]
        end
    end

    Cloud -->|MQTT / HTTPS| CloudBroker["Cloud Broker<br/>(Azure / AWS / on-prem)"]
    CloudBroker --> Dashboard["Dashboard centrale<br/>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<br/>OPC UA Server"]
        HMI["HMI<br/>OPC UA Client<br/>(real-time control)"]
        PLC -->|OPC UA Client/Server| HMI
    end

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

    subgraph Cloud["NORTHBOUND (IT/Cloud)"]
        MQTT["MQTT Broker<br/>(Mosquitto / EMQX)"]
        DASH["Dashboard<br/>Sparkplug Primary App"]
        ERP["ERP / MES<br/>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.

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<br/>Sistec.Core"]
        KukaRepo["sistec-kuka-stack<br/>Sistec.Stack.Kuka"]
        SafanRepo["sistec-safan-stack<br/>Sistec.Stack.Safan"]
        PLCRepo["sistec-plc-stack<br/>Sistec.Stack.PLC"]
        ProdRepo["sistec-production-stack<br/>Sistec.Stack.Production"]
        CloudRepo["sistec-cloud-stack<br/>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)

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

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><br/>JSON strutturato"]
        Metrics["System.Diagnostics.Metrics<br/>Counter / Histogram"]
        Traces["ActivitySource<br/>OpenTelemetry"]
        Health["IHealthCheck<br/>Microsoft.Extensions"]
    end

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

    subgraph Consumatori["CONSUMATORI"]
        Dashboard["Dashboard locale<br/>Avalonia"]
        Cloud["Cloud.Stack<br/>MQTT / HTTP"]
        Alert["Alerting<br/>Critical → sveglia turnista"]
        Field["Field Diagnostics<br/>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<br/>Ping KRC TCP"]
        SAFAN["SafanHealthCheck<br/>Stato connessione pressa"]
        PLC["PlcHealthCheck<br/>OPC UA session state"]
        DB["DbHealthCheck<br/>SELECT 1 su MySQL"]
        ALARM["AlarmHealthCheck<br/>Alarm flood detector"]
    end

    AGG["HealthAggregator<br/>Composizione risultati"]
    DASH["Dashboard locale<br/>Avalonia HealthPage"]
    ALERT["Alert engine<br/>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à:

• Locale — accessibili via API REST (GET /api/v1/metrics) per la dashboard HMI interna
• 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.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<br/>`ansible-playbook site.yml`"]
    end

    subgraph Repo["Repository Ansible<br/>(versionato su git)"]
        R1["inventory/hosts.ini<br/>IP, credenziali vault"]
        R2["roles/common/<br/>hostname, utenti, firewall"]
        R3["roles/wsl_docker/<br/>WSL2 + Docker + CODESYS"]
        R4["roles/mysql/<br/>MySQL install + DB + utenti"]
        R5["roles/hmi_app/<br/>Deploy HMI + servizio Windows"]
        R6["roles/monitoring/<br/>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

17.4 Struttura Repository

ansible-industrial-pc/
├── inventory/
│   ├── production/
│   │   ├── hosts.ini
│   │   └── group_vars/
│   │       ├── industrial_pcs.yml   # vars comuni
│   │       └── secrets.yml          # vault-crittografato
│   └── staging/
│       └── hosts.ini
├── roles/
│   ├── common/          # hostname, IP, utenti, firewall
│   ├── wsl_docker/      # WSL2 + Docker + CODESYS containers
│   ├── mysql/           # MySQL install + DB + utenti
│   ├── hmi_app/         # deploy HMI C# + servizio
│   └── monitoring/      # heartbeat, log forwarding
├── playbooks/
│   ├── site.yml         # playbook principale
│   ├── reset-demo-timer.yml
│   └── healthcheck.yml
├── ansible.cfg
├── requirements.yml
└── vault-password       # (escluso da git)

17.5 Inventory e Config

# inventory/production/hosts.ini
[industrial_pcs]
pc-linea-01 ansible_host=192.168.1.101 ansible_connection=winrm
pc-linea-02 ansible_host=192.168.1.102 ansible_connection=winrm

[industrial_pcs:vars]
ansible_user=Administrator
ansible_password=!vault |
ansible_winrm_transport=ntlm
ansible_winrm_server_cert_validation=ignore

# inventory/production/group_vars/industrial_pcs.yml
# --- Rete ---
dns_servers:
  - 192.168.1.10
# --- Firewall ---
firewall_rules:
  - { name: CODESYS OPC-UA,  port: 4840, protocol: tcp }
  - { name: MySQL,            port: 3306, protocol: tcp }
  - { name: HMI API,          port: 5000, protocol: tcp }
# --- CODESYS ---
codesys_containers:
  - { name: vPLC1, ip: 172.40.0.3, port: 4851 }
  - { name: vPLC2, ip: 172.40.0.4, port: 4852 }
  - { name: Next,  ip: 172.40.0.9, port: 4857 }
# --- HMI per commessa ---
hmi_app_name: Sistec.5315.LAG
hmi_app_path: C:\Program Files\Sistec\5315.LAG
hmi_port: 5000
hmi_nuget_version: 4.3.*

17.6 Playbook Principale

# playbooks/site.yml
- name: Configurazione completa PC industriale
  hosts: industrial_pcs
  gather_facts: yes
  roles:
    - role: common
      tags: [common, always]
    - role: mysql
      tags: [mysql]
      when: install_mysql | default(true)
    - role: hmi_app
      tags: [hmi]
      when: install_hmi | default(true)
    - role: wsl_docker
      tags: [wsl, docker, codesys]
      when: install_codesys | default(true)
    - role: monitoring
      tags: [monitoring]

17.7 Esempi Ruolo

hmi_app — Deploy HMI

- name: Installa .NET Runtime 8.0
  community.windows.win_chocolatey:
    name: dotnet-8.0-runtime
    state: present

- name: Deploy applicazione HMI
  ansible.windows.win_copy:
    src: "files/{{ hmi_app_name }}/"
    dest: "{{ hmi_app_path }}\\"
    force: yes

- name: Template appsettings.json
  ansible.windows.win_template:
    src: appsettings.json.j2
    dest: "{{ hmi_app_path }}\\appsettings.json"

- name: Installa servizio Windows
  ansible.windows.win_shell: |
    sc create {{ hmi_app_name }} binPath="{{ hmi_app_path }}\{{ hmi_app_name }}.exe --serve"
    sc failure {{ hmi_app_name }} reset=86400 actions=restart/5000/restart/10000/restart/30000

- name: Avvia servizio
  ansible.windows.win_service:
    name: "{{ hmi_app_name }}"
    state: started
    start_mode: auto

wsl_docker — CODESYS Containers

- name: Abilita WSL
  ansible.windows.win_dism:
    features:
      - VirtualMachinePlatform
      - Microsoft-Windows-Subsystem-Linux
    state: present

- name: Deploy docker-compose files
  ansible.windows.win_template:
    src: "compose.{{ item.name }}.j2"
    dest: "C:\\ProgramData\\Sistec\\codesys\\{{ item.name }}.yaml"
  loop: "{{ codesys_containers }}"

- name: Avvia container CODESYS
  ansible.windows.win_shell: |
    wsl -d Debian docker compose -f /mnt/c/ProgramData/Sistec/codesys/{{ item.name }}.yaml up -d
  loop: "{{ codesys_containers }}"

common — Hostname + Utenti + Firewall

- name: Imposta hostname
  ansible.windows.win_hostname:
    name: "{{ inventory_hostname | upper }}"

- name: Crea utenti locali
  ansible.windows.win_user:
    name: "{{ item.name }}"
    password: "{{ item.password }}"
    groups: "{{ item.groups }}"
    password_never_expires: yes
  loop: "{{ local_users }}"

- name: Regole firewall
  ansible.windows.win_firewall_rule:
    name: "{{ item.name }}"
    localport: "{{ item.port }}"
    protocol: tcp
    action: allow
  loop: "{{ firewall_rules }}"

17.8 Integrazione con CI/CD

La pipeline HMI commessa (sezione 13.6) si conclude con la pubblicazione dell'artifact. Ansible può prelevare quell'artifact e deployarlo:

flowchart LR
    CI["CI/CD: build HMI"] -->|publish artifact| Artifact["Release EXE + DLL + JSON"]
    Artifact -->|Ansible win_copy| PC1["PC Industriale 1"]
    Artifact -->|Ansible win_copy| PC2["PC Industriale 2"]
    Artifact -->|Ansible win_copy| PC3["PC Industriale 3"]

# In pipeline CI/CD (stage finale)
- task: Ansible@1
  inputs:
    playbook: 'deploy-hmi.yml'
    inventory: 'inventory/production/hosts.ini'
    args: |
      --extra-vars "hmi_version=$(Build.BuildNumber)"
      --vault-password-file vault-password

17.9 Vantaggi

17.10 Limiti

• Licenza CODESYS: attivazione manuale via License Manager (GUI, no API)
• Deploy progetto PLC: richiede CODESYS IDE
• Primo WSL: wsl --install va fatto almeno una volta a mano
• BIOS/UEFI: real-time, virtualization, wake-on-LAN manuali

L'HMI deve supportare aggiornamenti automatici sul campo: il tecnico Sistec pubblica un rilascio, i PC industriali in fabbrica si aggiornano da soli. Nessun rilascio deve mai rompere API pubbliche — ogni stack NuGet pubblicato con major uguale è 100% compatibile all'indietro.

18.1 Architettura dell'Aggiornamento

CI/CD ──► NuGet Feed ──► Release Pipeline ──► Installer ──► Update Server
              │                                              │
              │                                              ▼
              │                                       PC Industriale
              │                                       ├── HMI.exe (running)
              │                                       ├── Sistec.*.Stack.dll
              │                                       └── UpdateAgent.exe
              │
              └── NuGet versionato (SemVer) ──────────► App castiga versione

18.2 Vincolo: Nessuna Breaking Change sulle API Pubbliche

Regola assoluta: ogni pacchetto NuGet con stesso Major.Minor è backward-compatible.

Cosa NON si può mai fare in uno stesso major

❌ Rimuovere un metodo pubblico
❌ Cambiare firma di un metodo pubblico
❌ Rimuovere o rinominare una classe pubblica
❌ Cambiare tipo di una proprietà pubblica
❌ Aggiungere un parametro obbligatorio a un'interfaccia
❌ Cambiare default di un comportamento esistente

✅ Aggiungere nuovi metodi (con default implementation se interfaccia)
✅ Aggiungere nuove classi/enum/interfacce
✅ Deprecare (ma non rimuovere) con [Obsolete]
✅ Cambiare implementazione interna (se il comportamento esterno è identico)
✅ Aggiungere parametri opzionali

Enforcement in CI/CD

# Stage: ApiCompat — blocca la build se rileva breaking changes
- stage: ApiCompat
  displayName: '🔒 API Compatibility Check'
  jobs:
    - job: CheckCompat
      steps:
        - task: DotNetCoreCLI@2
          inputs:
            command: 'custom'
            custom: 'package'
            arguments: 'src/$(ProjectName)/$(ProjectName).csproj
                        -o $(Build.ArtifactStagingDirectory)/pkg'
        - script: |
            # Confronta API pubbliche con l'ultima versione pubblicata
            dotnet tool install -g Microsoft.DotNet.ApiCompat.Tool
            dotnet api-compat check --base-nuget $(ProjectName) --base-version $(LastMajor).$(LastMinor).0
          displayName: 'Check API Compatibility'

Se ApiCompat fallisce e Major non è stato incrementato → build bloccata.

18.3 Ciclo di Rilascio

┌─────────────────────────────────────────────────────────┐
│                    RILASCIO                              │
│                                                          │
│  1. Commit su main → build pipeline                      │
│  2. Test unitari + integrazione + SonarQube              │
│  3. API Compat Check (contro ultima versione NuGet)      │
│  4. Quality Gate superato? → NuGet publish               │
│     │                                                     │
│     ├── Se Major invariato → pacchetto backward-compat.  │
│     └── Se Major incrementato → breaking change          │
│         esplicito (richiede approval manuale)             │
│                                                          │
│  5. Release Pipeline:                                    │
│     ├── Aggiorna appcast.xml (versione + download URL)   │
│     ├── Crea installer .msi/.exe                         │
│     └── Pubblica su Update Server                        │
│                                                          │
│  6. PC Industriali (UpdateAgent):                        │
│     ├── Ogni ora: GET appcast.xml                        │
│     ├── Versione locale < versione remota? → download    │
│     └── Applica aggiornamento (HMI si riavvia)           │
└─────────────────────────────────────────────────────────┘

18.4 UpdateAgent — Comportamento

// UpdateAgent.exe — servizio Windows
public class UpdateAgent : BackgroundService
{
    private readonly HttpClient _http;
    private readonly IConfiguration _config;

    protected override async Task ExecuteAsync(CancellationToken ct)
    {
        while (!ct.IsCancellationRequested)
        {
            var manifest = await FetchManifestAsync(ct);
            if (manifest.Version > CurrentVersion)
            {
                _logger.LogInformation("Update found: {Old} → {New}",
                    CurrentVersion, manifest.Version);

                // Scarica nuovo installer
                var pkgPath = await DownloadAsync(manifest.DownloadUrl, ct);

                // Backup installazione corrente
                Directory.Move(InstallDir, BackupDir);

                // Esegui nuovo installer (silent)
                using var proc = Process.Start(new ProcessStartInfo
                {
                    FileName = pkgPath,
                    Arguments = "/verysilent /dir=" + InstallDir,
                    Wait = true
                });

                // Se successo → riavvia HMI
                // Se fallito → restore da backup
                if (proc.ExitCode == 0)
                {
                    RestartHmi();
                }
                else
                {
                    Rollback(BackupDir, InstallDir);
                }
            }

            await Task.Delay(CheckInterval, ct);  // default: 1 ora
        }
    }
}

18.5 Installer

18.6 Update Server

Minimal setup: un file appcast.xml su un server HTTP statico (NAS aziendale, bucket S3, o anche una share di rete).

<?xml version="1.0" encoding="utf-8"?>
<appcast>
  <item>
    <title>Sistec HMI 2.4.1</title>
    <version>2.4.1</version>
    <pubDate>2026-07-15</pubDate>
    <enclosure url="https://updates.sistec.it/hmi/Sistec.HMI.2.4.1.msi"
               length="42873621" type="application/octet-stream" />
    <releaseNotes>Bug fix reconnect KUKA, nuove statistiche operatore</releaseNotes>
    <critical>false</critical>     <!-- Se true, aggiornamento forzato -->
  </item>
</appcast>

18.7 Canali di Rilascio

// appsettings.json dell'UpdateAgent
{
  "UpdateAgent": {
    "CheckIntervalMinutes": 60,
    "UpdateServerUrl": "https://updates.sistec.it/hmi/appcast.xml",
    "Channel": "stable",             // "stable" | "beta" | "nightly"
    "AutoRestart": true,
    "AutoRestartWindow": "02:00-04:00",  // Riavvio solo in finestra notturna
    "RollbackRetention": 2               // Tiene ultime 2 versioni per rollback
  }
}

18.8 Rollback

Se un aggiornamento fallisce o viene rilevato come instabile:

Scenario:
  1. UpdateAgent scarica v2.4.1, backup v2.4.0 in C:\Sistec\HMI\previous\v2.4.0
  2. Installa v2.4.1
  3. HMI si riavvia
  4. Se HMI crasha entro 5 minuti → UpdateAgent ripristina v2.4.0 automaticamente
  5. Se HMI funziona → previous\v2.4.0 viene rimosso dopo 7 giorni

Rollback manuale (da remoto, tramite Ansible):

- name: Rollback HMI to previous version
  win_shell: |
    $backup = Get-ChildItem "C:\Sistec\HMI\previous" | Sort-Object LastWriteTime -Descending | Select-Object -First 1
    if ($backup) {
      Stop-Service SistecHmi
      Stop-Service UpdateAgent
      Remove-Item "C:\Sistec\HMI\current" -Recurse -Force
      Copy-Item $backup.FullName "C:\Sistec\HMI\current" -Recurse
      Start-Service SistecHmi
      Start-Service UpdateAgent
    }

18.9 Integrazione con CI/CD

# Aggiunto alla pipeline HMI Commessa (sezione 14.6)
  - stage: CreateInstaller
    displayName: '📦 Create Installer'
    dependsOn: Publish
    jobs:
      - job: BuildInstaller
        steps:
          - task: NuGetToolInstaller@1
          - script: |
              # Compila WiX project
              candle.exe installer/SistecHmi.wixproj
              light.exe installer/SistecHmi.wixobj -out $(Build.ArtifactStagingDirectory)/Sistec.HMI.$(Version).msi
            displayName: 'Build MSI Installer'

  - stage: UpdateAppcast
    displayName: '📰 Update Appcast'
    dependsOn: CreateInstaller
    condition: and(succeeded(), eq(variables['Build.SourceBranch'], 'refs/heads/main'))
    jobs:
      - job: UpdateAppcast
        steps:
          - script: |
              # Aggiorna appcast.xml con nuova versione + upload a S3
              $appcast = Join-Path $(Build.ArtifactStagingDirectory) "appcast.xml"
              @"
              <?xml version="1.0" encoding="utf-8"?>
              <appcast>
                <item>
                  <version>$(Version)</version>
                  <enclosure url="https://updates.sistec.it/hmi/Sistec.HMI.$(Version).msi"
                             length="$(InstallerSize)" type="application/octet-stream" />
                  <releaseNotes>$(Build.SourceVersionMessage)</releaseNotes>
                </item>
              </appcast>
              "@ | Set-Content $appcast
              aws s3 cp $appcast s3://sistec-updates/hmi/appcast.xml
              aws s3 cp "$(Build.ArtifactStagingDirectory)/Sistec.HMI.$(Version).msi" s3://sistec-updates/hmi/
            displayName: 'Publish to Update Server'

  - stage: Deploy
    displayName: '🚀 Ansible Deploy'
    dependsOn: UpdateAppcast
    jobs:
      - job: TriggerAnsible
        steps:
          - script: |
              # Ansible legge appcast.xml → deploya la nuova versione
              ansible-playbook -i inventory/hosts.ini playbooks/deploy-hmi.yml
            displayName: 'Trigger Ansible Deploy'

18.10 Roadmap

Fase 5 — Installer + Update System (3-4 settimane)
├── Setup WiX / Inno Setup project
├── UpdateAgent servizio Windows
├── appcast.xml + Update Server
├── API Compat Check nella pipeline
├── Rollback automatico e manuale
└── Canali stable/beta/nightly

Tempo stimato: 3-4 settimane, da eseguire in parallelo agli stack applicativi (Fase 3). L'UpdateAgent può essere sviluppato e testato come progetto separato fin da Fase 1 (Fondazioni) perché non dipende da nessuno stack macchina.

L'analisi approfondita delle codebase LAG e FAEL ha rivelato ulteriori aree di miglioramento non coperte nelle sezioni precedenti. Questa sezione raccoglie idee complementari all'architettura a stack verticali, verificate sul codice esistente.

19.1 Circuit Breaker (Resilienza)

Oggi: ReconnectAgent.cs (Sistec.Core/Utils/ReconnectAgent.cs:24) ha timeout 10.000ms hardcoded e retry lineare. Nessun circuit breaker. Le classi di rete (TcpClient, KrcClient, ModbusConnector) espongono solo IsConnected booleano sparso.

Proposta: Sostituire ReconnectAgent con Polly CircuitBreakerPolicy + RetryPolicy + FallbackPolicy. Health check system spostato in §16.6.

Riferimento codebase: ReconnectAgent.cs, KrcClient.cs, ModbusConnector.cs, OpcUaClient.cs — nessuno implementa circuit breaker standardizzato.

19.2 REST API per Integrazione MES/ERP

Oggi: l'HMI è un sistema completamente chiuso. Nessun HttpClient, nessun Controller, nessun [Route] in nessuna delle due codebase. Per integrarsi con un MES o ERP serve accedere direttamente al database MySQL — accoppiamento forte.

Proposta: Minimal API ASP.NET Core in-process su localhost:5000:

// Sistec.Infra.Api — leggero, esposto solo su localhost
app.MapGet("/api/v1/production/active-job", async (IJobTracker jobs) =>
    await jobs.GetActiveAsync());

app.MapGet("/api/v1/machines/kuka/status", async (IKukaRobotLogic kuka) =>
    new { connected = await kuka.IsConnectedAsync(), program = await kuka.GetCurrentProgramAsync() });

app.MapGet("/api/v1/alarms", async (IAlarmService alarms) =>
    await alarms.GetActiveAlarmsAsync());

Sistec.Bus (FAEL, Zebus 3.14.1) può fare da bus interno tra stack e API, evitando accoppiamento diretto.

Riferimento codebase: Zero API esistenti. Zebus in Sistec.Bus/ (FAEL) sarebbe il bus naturale.

19.3 Feature Flags per le Varianti HMI (Soluzione a §2.13)

Il problema aperto di §2.13 (gestione varianti AB/C/BS) è oggi risolto con progetti .csproj separati e if/else su CellType. FAEL ha PalletLogic_AB.cs vs PalletLogic_C.cs (in Common/Logic/), codici pressa diversi, logiche di produzione differenti.

Proposta: Microsoft.FeatureManagement o un IFeatureFlagService custom:

{
  "features": {
    "HasEsaPress": false,
    "HasConveyor": false,
    "HasQualityCheck": true,
    "PalletCount": 9,
    "CellType": "LAG"
  }
}

public async Task ExecuteProductionStep(StepType step)
{
    await _kuka.LoadPanel("vacuum_a");

    if (await _features.IsEnabledAsync("HasEsaPress"))
        await _esa.Press("PROG_456");
    else
        await _safan.Bend("P123", 90);

    if (await _features.IsEnabledAsync("HasConveyor"))
        await _conveyor.Advance();
}

Vantaggio: un unico progetto HMI, zero copie. Ogni commessa = file JSON, non un nuovo .csproj. Il RecipeEngine (§9.1) assorbe naturalmente questa logica.

Riferimento codebase: Common/Logic/PalletLogic_AB.cs, PalletLogic_C.cs (FAEL); if/else su CellType sparsi.

19.4 Configuration Hot-Reload

Oggi: la configurazione è letta una volta all'avvio da file INI/XML (Config/Kuka.ini, PLC.ini, PressBrake.ini). Per cambiare un parametro serve riavviare l'HMI → fermo produzione.

Microsoft.Extensions.Configuration è già referenziato da Sistec.Core/Sistec.Core.csproj:22, ma nessun codice usa IOptionsMonitor<T> o .GetReloadToken().

Proposta: File JSON con reloadOnChange: true. IOptionsMonitor<T> propaga le modifiche a caldo:

public class KukaOptions
{
    public int ReconnectTimeoutMs { get; set; } = 10000;
    public int CommandTimeoutMs { get; set; } = 5000;
}

// IOptionsMonitor notifica quando il file cambia su disco
public class KukaRobotLogic
{
    public KukaRobotLogic(IOptionsMonitor<KukaOptions> options)
    {
        options.OnChange(opt => _logger.LogInformation("Kuka options reloaded"));
    }
}

Riferimento codebase: AB/Config/Kuka.ini, PLC.ini, PressBrake.ini letti staticamente; nessun IOptionsMonitor.

19.5 Metrics e Distributed Tracing (Osservabilità)

Il contenuto di questa sezione è stato spostato in §16.7 (Metrics) e §16.8 (Distributed Tracing). La presente sezione è mantenuta come riferimento per i codebase LAG/FAEL.

Riferimento codebase: Directory.Packages.props:29 (FAEL, DiagnosticSource già presente); Sistec.Core/Utils/PropertyNotifier.cs già notifica cambi valore — punto di hook naturale per metriche senza modificare i consumer.

19.6 Async Audit: Rimuovere .Result e .Wait

LAG ha 2 violazioni in produzione che bloccano il thread pool:

• Sistec.Core/Tags/TagValue.cs:234: Task.Run(async () => { ... }).Result;
• Sistec.Opc.Ua/OpcUaTagValue.cs:212: Task.Run(async () => { ... }).Result;

FAEL ha risolto con TagValueBase<T> (coda asincrona con SemaphoreSlim), ma LAG no.

Proposta: Refactor del write path per essere async fino in fondo. Allineare LAG alla soluzione FAEL (TagValueBase<T>). Nella greenfield: vietare .Result/.Wait() con analizzatore Roslyn custom:

<Analyzer Include="$(NuGetPackageRoot)\Microsoft.CodeAnalysis.BannedApiAnalyzers\*\analyzers\*.dll">
  <BannedSymbols>Task.Result;Task.Wait;Task.GetAwaiter().GetResult</BannedSymbols>
</Analyzer>

Riferimento codebase: TagValue.cs:234 (LAG), OpcUaTagValue.cs:212 (LAG); TagValueBase.cs:29-41 (FAEL, soluzione già pronta).

19.7 Test Helpers Condivisi (Eliminare 13 FakeOpcUa)

Il documento §6.1㉑ segnala 13 copie di FakeOpcUa.cs in FAEL. La verifica ha confermato esattamente 13 file in:

• Test/ResetSeq/, Test/ProgramManagement/, Test/Maintenance/DUT/, Test/LinkedRollerTest/DVars/, Test/PalletsState/, Test/CutPlan/, Test/BS_PLC/, Test/Test_Safety_AB/FakePlc/, Test/AnalogScaling/, Test/Test_Safety/, Test/Test_DialogTemplate/, Sistec.HMI/C/FakePlc/, Sistec.HMI/BS/

Proposta: Sistec.Infra.TestHelpers (NuGet di test):

// Unico FakeOpcUa, usato da tutti
public class FakeOpcUa : IUAClient
{
    public Dictionary<string, object> Tags { get; } = new();
    public Task<bool> ConnectAsync(string endpoint) => Task.FromResult(true);
    public Task<T> ReadTagAsync<T>(string tag) => Task.FromResult((T)Tags[tag]);
    public Task WriteTagAsync<T>(string tag, T value) { Tags[tag] = value; return Task.CompletedTask; }
}

Include anche: FakeKrcClient, FakePlcClient, MockLogger<T>, FakeSynchronizationContext. [InternalsVisibleTo] nei progetti stack per mock senza reflection.

Riferimento codebase: 13 file FakeOpcUa.cs sparsi; Test/ (FAEL) ha 48 sottodirectory.

19.8 System.Threading.Channels per Scritture Tag

FAEL ha implementato una coda writes personalizzata in TagValueBase.cs:29-41 con SemaphoreSlim + _pendingWrite + segnalazione manuale. Il commento al rigo 32 dice:

"Dependency-free (no System.Threading.Channels, which is a separately-versioned framework assembly and is not in-box for netstandard2.1)"

Per net8.0 (o net10.0 per la greenfield), System.Threading.Channels è in-box. Sostituzione:

// OGGI: SemaphoreSlim custom
private readonly SemaphoreSlim _writeSignal = new(0, 1);
private T? _pendingWrite;
private bool _hasPendingWrite;

// DOMANI: Channel<T> standard
private readonly Channel<T> _writeChannel = Channel.CreateBounded<T>(
    new BoundedChannelOptions(1) { FullMode = BoundedChannelFullMode.DropOldest });

Stessa semantica latest-wins, meno codice, API standard e testata.

Riferimento codebase: TagValueBase.cs:29-41 (FAEL); note app.config binding redirects per System.Threading.Channels già presenti.

19.9 Sistec.Modbus: Eliminare Duplicazione Morta

Confermato: D:\DEV\5309_FAEL\Sistec.Modbus\ duplica D:\DEV\5309_FAEL\Esa.Client\ con varianti minori:

• Sistec.Modbus/PressBrakes.cs vs Esa.Client/PressBrakeCollection.cs
• Sistec.Modbus/PressBrakeGade29.cs vs Esa.Client/PressLogicGade29.cs
• Sistec.Modbus ha Serilog 4.2.0 (vecchio), Esa.Client non ha Serilog

Il progetto HMI AB referenzia solo Esa.Client\Esa.Client.csproj. Sistec.Modbus è morto.

Proposta: Verificare che nessun .csproj referenzi Sistec.Modbus, recuperare eventuali differenze utili (PressBrakes.cs), eliminare la directory.

Riferimento codebase: 5309_FAEL/Sistec.Modbus/ (9 file); 5309_FAEL/Esa.Client/ (implementazione attiva).

19.10 Standardizzazione: Target Framework, Serializzazione, Convenzioni

Target Framework: netstandard2.1 → net8.0+

Le librerie fondazione (Sistec.Core, Sistec.Opc.Ua, Sistec.Safan, Sistec.Sinumerik) dichiarano netstandard2.1, ma di fatto girano solo su .NET 8+ (i consumer sono net8.0-windows). netstandard2.1 è un vincolo fittizio che:

• Impedisce l'uso di System.Threading.Channels nativo
• Impone binding redirect in app.config
• Blocca required, record, primary constructors

Proposta: Portare a net8.0 (o net10.0 per la greenfield).

Serializzazione: Tre Librerie → Una Sola

Proposta: System.Text.Json per tutto (config JSON, API, persistenza). protobuf-net solo per protocollo binario. Eliminare Newtonsoft.Json.

Semantic Conventions per Log

Oggi i log sono messaggi free-text non aggregabili. Con le OpenTelemetry Semantic Conventions:

// Invece di: _logger.LogInformation("Kuka reconnect attempt {n}", n);
_logger.LogWarning("Machine connection lost, reconnecting");
_metrics.ConnectionLostCounter.Add(1, new TagList { { "sistec.machine.id", "Kuka_0" } });

Convenzioni proposte per Sistec: sistec.machine.id, sistec.cell.job_id, sistec.operator.badge, sistec.alarm.severity.

Quality Gates: .editorconfig + Directory.Build.props

Nessuna delle due codebase ha .editorconfig, Directory.Build.props, o GlobalUsings.cs. FAEL ha tracce di SonarQube (.sonarqube/out/) ma nessun quality gate integrato nel build.

Proposta:

# .editorconfig — root del repo stack
root = true

[*.cs]
indent_style = space
indent_size = 4
csharp_style_var_for_built_in_types = true:warning
csharp_style_pattern_matching_over_is_with_cast_check = true:warning
dotnet_diagnostic.CA2007.severity = none    # ConfigureAwait non necessario per HMI

<!-- Directory.Build.props — versionamento + analizzatori -->
<Project>
  <PropertyGroup>
    <VersionPrefix>2.3.0</VersionPrefix>
    <LangVersion>latest</LangVersion>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
    <AnalysisLevel>latest-all</AnalysisLevel>
    <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Include="SonarAnalyzer.CSharp" Version="*" PrivateAssets="all" />
  </ItemGroup>
</Project>

Riferimento codebase: Nessun .editorconfig, nessun Directory.Build.props; .sonarqube/out/ (FAEL) come unica traccia di analisi.

19.11 Inter-Panel Communication: HTTP + Redis (Alternativa in Parallelo a Zebus)

Oggi in FAEL, AB e C sono due pultipite distinti nella stesso impianto. Comunicano via Zebus (Sistec.Bus, Zebus 3.14.1) per scambiarsi stato produzione, job, allarmi. Zebus funziona (è in produzione) ma è un framework poco conosciuto, difficile da manutenere e diagnosticare.

Proposta: Affiancare HTTP + Redis a Zebus come alternativa parallela, non sostitutiva. Ogni commessa potrà scegliere il bus più adatto o mantenerli entrambi.

flowchart LR
    subgraph Oggi["OGGI — Zebus pub/sub"]
        AB1["Pulpito AB<br/>FrmHMI AB"] <-->|Zebus bus| C1["Pulpito C<br/>FrmHMI C"]
        BS1["Pulpito BS<br/>Form1 BS"] <-->|Zebus bus| AB1
    end

    subgraph Domani["DOMANI — Zebus + Redis opzionale"]
        AB2["Pulpito AB"] <-->|HTTP REST / SSE| Redis["REDIS<br/>(Stato condiviso<br/>Job, Allarmi,<br/>Produzione)"]
        C2["Pulpito C"] <-->|HTTP REST / SSE| Redis
        BS2["Pulpito BS"] <-->|HTTP REST / SSE| Redis
        AB2 <-->|Zebus bus| C2
        BS2 <-->|Zebus bus| AB2
    end

Architettura

Redis funge da stato condiviso in-memory accessibile da tutti i pannelli via rete locale. Ogni pannello pubblica eventi (job completato, allarme, cambio stato) via HTTP e si sottoscrive a canali Redis Pub/Sub per aggiornamenti in tempo reale.

Schema Dati in Redis

Redis Key                              → Value
─────────────────────────────────────────────────────────────
sistec:{plant}:job:active              → { "jobId": 42, ... }
sistec:{plant}:job:history             → [ {jobId: 41}, {jobId: 40} ]
sistec:{plant}:alarms:active           → [ {alarmId: 7}, {alarmId: 8} ]
sistec:{plant}:production:counter      → 1547
sistec:{plant}:machines:kuka:status    → "running"   (da ogni pannello via HTTP)
sistec:{plant}:panels:ab:last-heartbeat → 2026-07-03T10:30:00Z

Esempio: Pannello AB completa un job, C lo vede in real-time

// AB — dopo aver completato un job
public class JobCompletionPublisher(IConnectionMultiplexer redis)
{
    public async Task PublishJobCompletedAsync(JobData job)
    {
        var db = redis.GetDatabase();

        // 1. Salva job in Redis (stato condiviso)
        await db.StringSetAsync($"sistec:{_plant}:job:active", JsonSerializer.Serialize(job));

        // 2. Pubblica evento su canale Redis → tutti i pannelli ricevono notifica
        await db.PublishAsync("channel:job:completed", JsonSerializer.Serialize(new
        {
            job.Id, job.PartCount, CompletedAt = DateTime.UtcNow, CompletedBy = _currentOperator
        }));
    }
}

// C — sottoscrizione all'avvio
public class JobEventSubscriber(IConnectionMultiplexer redis)
{
    public void Subscribe()
    {
        var sub = redis.GetSubscriber();
        sub.Subscribe("channel:job:completed", (channel, message) =>
        {
            var evt = JsonSerializer.Deserialize<JobCompletedEvent>(message);
            _logger.LogInformation("C sees: Job {Id} completed by operator {Op}", evt.Id, evt.CompletedBy);
            _dispatcher.Invoke(() => _jobView.Refresh());
        });
    }
}

Gestione Heartbeat e Rilevamento Caduta Pannello

Ogni pannello scrive il proprio heartbeat ogni 5 secondi su Redis con TTL 15 secondi:

// In un BackgroundService su ogni pannello
protected override async Task ExecuteAsync(CancellationToken ct)
{
    while (!ct.IsCancellationRequested)
    {
        await _db.StringSetAsync(
            $"sistec:{_plant}:panels:{_panelId}:last-heartbeat",
            DateTime.UtcNow.ToString("O"),
            expiry: TimeSpan.FromSeconds(15));  // TTL = 15s

        await Task.Delay(5000, ct);
    }
}

Se il heartbeat scade, gli altri pannelli sanno che il pannello è offline e possono mostrare un warning.

Confronto: Zebus vs HTTP + Redis

Quando Scegliere Cosa

Attivazione in Parallelo

Fase 1: Redis side-by-side   — Zebus continua, Redis si aggiunge in lettura
Fase 2: Doppia scrittura    — Ogni evento va sia a Zebus che a Redis (opzionale, solo se servono entrambi)

Redis si attiva senza mai disabilitare Zebus. Ogni commessa sceglie la configurazione al deploy.

Riferimento codebase: D:\DEV\5309_FAEL\Sistec.Bus\ (15 file, log4net + Zebus 3.14.1); Sistec.HMI\Common\Bus.cs (227 righe) — wrapper Zebus con SafeInvoke.

19.12 Web Dashboard (HTML/React) per Monitoraggio Impianto

Le REST API esposte dall'HMI (§19.2) abilitano un caso d'uso ulteriore: una dashboard web leggibile da qualsiasi PC in azienda per monitorare lo stato dell'impianto in tempo reale, senza installare l'HMI.

Architettura

flowchart TB
    subgraph Plant["REPARTO PRODUZIONE"]
        HMI["PC Industriale<br/>HMI (Avalonia)<br/>+ REST API localhost:5000"]
        Redis["REDIS<br/>Stato condiviso<br/>(opzionale)"]
        HMI <--> Redis
    end

    subgraph Company["RETE AZIENDALE"]
        D1["PC Ufficio Tecnico<br/>React SPA su browser<br/>sistec-dashboard.local:3000"]
        D2["Tablet Capoturno<br/>React SPA<br/>stato produzione"]
        D3["TV Reparto<br/>KPI produzione<br/>(Schermo grande)"]
    end

    HMI -->|HTTP GET /api/v1/*| D1
    HMI -->|HTTP GET /api/v1/*| D2
    HMI -->|HTTP GET /api/v1/*| D3

Cosa Mostra la Dashboard

Real-time con SSE (Server-Sent Events)

Per aggiornamenti live senza polling, la dashboard si sottoscrive a un endpoint SSE:

// Endpoint SSE sull'HMI
app.MapGet("/api/v1/events", async (HttpContext ctx, ICancellationToken ct) =>
{
    ctx.Response.ContentType = "text/event-stream";
    while (!ct.IsCancellationRequested)
    {
        // Invia aggiornamento ogni volta che Redis Pub/Sub pubblica un evento
        var evt = await _eventChannel.Reader.ReadAsync(ct);
        await ctx.Response.WriteAsync($"event: {evt.Type}\ndata: {JsonSerializer.Serialize(evt.Payload)}\n\n");
        await ctx.Response.Body.FlushAsync();
    }
});

Il client React si connette con EventSource:

// React — useEventSource hook
const evtSource = new EventSource("/api/v1/events");
evtSource.addEventListener("job:completed", (e) => {
    const job = JSON.parse(e.data);
    setLastJob(job);
});
evtSource.addEventListener("alarm:raised", (e) => {
    const alarm = JSON.parse(e.data);
    setAlarms(prev => [...prev, alarm]);
});

Stack Tecnico Consigliato

Sicurezza

La dashboard è read-only — può solo leggere stato, non inviare comandi. L'autenticazione è gestita da:

Opzione A: Basic Auth + HTTPS (semplice, sufficiente per LAN di fabbrica)
Opzione B: Token JWT rilasciato dall'HMI (riusa il login operatore)
Opzione C: Nessuna autenticazione (solo se la VLAN è isolata)

Vincolo: l'endpoint SSE e le API sono esposti solo su interfaccia di rete aziendale (non su quella del PLC/macchinari). L'HMI ha due schede di rete:

Vantaggi

Cosa NON Deve Fare

La dashboard web è solo monitoraggio. Non deve mai:

❌ Inviare comandi alle macchine (start/stop/reset)
❌ Modificare parametri di produzione
❌ Sovrascrivere job in esecuzione
❌ Sostituire l'HMI come interfaccia primaria

Il confine è netto: l'HMI comanda, la dashboard osserva. Questo garantisce che un bug nella dashboard non possa mai causare danni fisici.

Riferimento codebase: Stessa REST API di §19.2; Zero codice web nelle codebase attuali — è un'aggiunta greenfield.

19.13 Redis come Data Layer Trasversale

Oltre alla comunicazione inter-pannello (§19.11), Redis può funzionare da hot data layer condiviso tra tutti gli stack verticali: stato veloce, notifiche real-time, contatori atomici. MySQL resta source of truth. Redis è un cache/distributed state layer che migliora performance e consistenza multi-pannello senza sostituire il DB.

Schema Chiavi

sistec:{plant}:{domain}:{entity}:{id}

Cosa Cambia

Libreria di Supporto

Sistec.Library.Redis
├── RedisPanelState.cs          — heartbeat + stato pannello
├── RedisSessionStore.cs        — session store operatore
├── RedisAlarmStore.cs          — stato allarmi condiviso
├── RedisProductionCounter.cs   — INCR contatori atomici
├── RedisPalletStore.cs         — Hash stato pallet
├── RedisCloudBuffer.cs         — Streams per eventi cloud
├── RedisConfigWatcher.cs       — Pub/Sub per hot-reload configurazione
└── RedisI18nCache.cs           — cache traduzioni TTL

La libreria è opzionale — ogni commessa decide quali moduli Redis attivare. I servizi cadono graceful su MySQL se Redis non è configurato (NullObject pattern).

NuGet: stackexchange.redis (900M+ download, standard industry)
Configurazione: redis.json — endpoint, porta, password, DB index
Pattern di connessione: ConnectionMultiplexer singleton, DI container

Riepilogo Impatto sulla Roadmap

Le codebase LAG (5315) e FAEL (5309) condividono la stessa architettura di fondo: un monolite WinForms cresciuto organicamente attorno a Sistec.Core, con un God Project (Common/), God Class (MainForm/FrmHMI), nessun DI container, DUT legati a OPC UA, branch divergenti, e codebase frammentate per device.

Non ha senso refattorizzarle. Le commesse esistenti rimangono in manutenzione correttiva. Questo documento è il blueprint per la prossima commessa, sviluppata greenfield:

1. Architettura a stack verticali Sistec.<Nome>.Stack.* (5 layer per dispositivo)
2. DI Container con Microsoft.Extensions.DependencyInjection
3. NuGet Packages per distribuzione e versionamento unificato
4. CI/CD pipeline per ogni stack: build → test (NUnit) → SonarQube → NuGet publish automatico
5. Testing Strategy: Test Pyramid, FIRST, TDD per logica pura, mocking rules, contract testing, zero flaky
6. Code Quality: SonarQube quality gate (coverage ≥70%, duplicazione <3%, complessità ≤10); .editorconfig + Directory.Build.props + Roslyn analyzers dalla Fase 1
7. Code Generation DUT da CODESYS
8. Layout Engine configurabile via JSON (layout.json) — consegna senza codice
9. Modern UI cross-platform (Avalonia, Linux-ready)
10. Cloud Connector opzionale per Industry 4.0
11. Logging strutturato + Metrics + Tracing (JSON, ILogger<T>, Correlation ID, OpenTelemetry)
12. Automazione deploy PC industriali con Ansible
13. Install + aggiornamenti automatici (WiX, UpdateAgent, API backward compat)
14. Utenti reali per dipendente con statistiche produzione
15. Feature Flags per varianti impianto (addio if/else su CellType)
16. Health Checks + Circuit Breaker (Polly, resilience standard)
17. REST API per integrazione MES/ERP
18. HCI/UI/UX — Principi Norman, Shneiderman, Nielsen; theme industriale; accessibilità WCAG AA; testing utente (§21)

Roadmap Greenfield

Fase 1 — Fondazioni Condivise (4-5 settimane)
    Sistec.Infra.* + Sistec.Platform.* NuGet packages
    ├── Persistence (Dapper + MySql + SqlServer)
    ├── Configuration (Options pattern + Hot-Reload)
    ├── Authentication (BCrypt + Employee/Role + statistiche)
    ├── Logging (JSON strutturato, ILogger<T>, Correlation ID)
    ├── Feature Flags (IFeatureFlagService per varianti)
    ├── CodeGen (DUT → POCO + TagConstants)
    ├── OpcUa + Modbus libraries
    ├── Controls base + Cloud MQTT
    ├── Testing infrastructure (NUnit, Moq, Simulator template)
    ├── Test Helpers condivisi (FakeOpcUa unico, FakeKrcClient)
    ├── .editorconfig + Directory.Build.props + Roslyn analyzers
    ├── Async Audit: eliminare .Result nei path esistenti
    ├── HCI: Sistec.Theme (design system industrial, colori, tipografia, spaziatura)
    ├── HCI: Sistec.Controls.Touch (touch targets ≥48px per guanti industriali)
    ├── HCI: Messaggi errore localizzati per ogni eccezione notevole
    └── SonarQube quality gate attivo dal giorno 1

Fase 2 — Stack Macchina della Commessa (2-3 settimane/stack)
    Solo gli stack necessari (Kuka, Safan, ESA, PLC, Sinumerik...)
    Ogni stack: Client → Driver → Services → UI → Simulator
    Health Check + Circuit Breaker (Polly) per ogni stack
    TDD per logica pura (Services, Driver parsing)
    Unit test + Integration test + Contract test
    SonarQube quality gate bloccante
    HCI: Vincoli di stato per ogni controllo interattivo (CanStart, CanReset, CanEdit)

Fase 3 — Applicativi + UI (3-4 settimane)
    Production, JobManagement, Maintenance, Alarms
    RecipeEngine + PalletStateMachine
    Layout Engine (layout.json → UI)
    EmployeeStatsPage (statistiche produzione per dipendente)
    Composition Root Avalonia
    REST API per MES/ERP (minimal API localhost)
    Metrics + Tracing (OpenTelemetry)
    Monitoring dashboard + dead man's switch
    HCI: Prototipazione 3 schermate core (Home, Production, Maintenance)
    HCI: Valutazione euristica interna (checklist §21.1-§21.6)
    HCI: Test con 2 operatori reali prima del rilascio
    HCI: Telemetry usabilità (tempo operazioni, errori, allarmi per operatore)

Fase 4 — Deploy + Collaudo (1-2 settimane)
    Ansible playbook per PC industriale
    Smoke test + collaudo in fabbrica
    HCI: Verifica usabilità su pannello industriale reale
    Verifica retention policy log

Fase 5 (parallela) — Installer + Aggiornamenti Automatici (3-4 settimane)
    WiX / Inno Setup project
    UpdateAgent servizio Windows
    appcast.xml + Update Server
    API Compat Check in CI/CD (NON si rompono API pubbliche)
    Rollback automatico su crash
    UpdateAgent sviluppabile già in Fase 1 (nessuna dipendenza da stack)

Fase 6 (pulizia) — Allineamento Codebase Legacy (1-2gg, non bloccante)
    Eliminare Sistec.Modbus (duplicato morto in FAEL)
    Unificare serializzazione (System.Text.Json)
    Portare Sistec.Core a net8.0+ se utile per la greenfield

--- Tempo stimato prima commessa: 14-18 settimane (con Fase 5-6 in parallelo) ---
--- Commesse successive: 7-11 settimane (riusano Fase 1) ---

Primo passo consigliato: Iniziare con la Fase 1 — Fondazioni, partendo da:

1. Sistec.Infra.Persistence (interfacce, Dapper, Unit of Work)
2. Sistec.Infra.Authentication (Employee, Role, BCrypt)
3. Sistec.Infra.FeatureFlags (IFeatureFlagService + JSON config)
4. Testing infrastructure: template NUnit + Moq + Sistec.Infra.TestHelpers (FakeOpcUa unico) + SonarQube gate attivo dal primo commit

La testing infrastructure non è opzionale: va impostata prima di scrivere codice di produzione. Questo garantisce che ogni stack nasca già con coverage, quality gate e pipeline CI/CD pronti — evitando di ritrovarsi come LAG/FAEL con 13 copie di FakeOpcUa e zero test automatici.

L'architettura a stack verticali risolve i problemi tecnici (frammentazione, coupling, testabilità), ma non garantisce che l'interfaccia sia usabile dall'operatore. Questa sezione applica i principi fondamentali dell'HCI (Human-Computer Interaction) all'HMI Sistec, identificando i gap tra le codebase legacy e la soluzione greenfield.

21.1 Principi di Norman — Mappatura ai Gap Architetturali

I 5 principi di Norman definiscono le fondamenta dell'interazione uomo-macchina. Ogni principio viene mappato allo stato attuale e alla proposta architetturale.

Implementazione nei controlli interattivi — esempio per KUKA:

// Sistec.Stack.Kuka.Services — espone stati vincolati
public interface IKukaRobotState
{
    bool CanStart { get; }
    bool CanStop { get; }
    bool CanReset { get; }
    bool CanLoadPanel { get; }
}

// binding in layout.json
{
  "control": "Kuka.Views.StartButton",
  "binding": { "enabled": "Kuka_0.CanStart" }
}

21.2 Le 8 Regole d'Oro di Shneiderman — Valutazione e Implementazione

Regola 7±2 applicata alla dashboard Home:

MASSIMO per la schermata Home:
- 5 macchine visibili (KUKA, Safan, PLC, Job, Alarmi)
- Ogni card mostra max 7 valori (stato, parametro principale, 5 indicatori)
- Navigazione sidebar: max 5 voci (Home, Produzione, Manutenzione, Alarmi, Info)

21.3 Le 10 Euristiche di Nielsen — Analisi Critica con Severità

Ogni euristica viene valutata con severità: 🔴 CRITICA (blocca l'uso), 🟠 ALTA (causa errori frequenti), 🟡 MEDIA (riduce efficienza), 🟢 BASSA (miglioramento marginale).

Implementazione ErrorRecoveryService:

public record ErrorInfo(
    string TechnicalMessage,     // per log/debug
    string UserMessage,          // per operatore ("Robot KUKA non raggiungibile")
    string SuggestedAction,      // "Verificare cavo di rete e riprovare"
    string SupportContact,       // "Contattare Sistec: +39 0XX XXXXXXX"
    ErrorSeverity Severity       // Info, Warning, Error, Critical
);

public interface IErrorRecoveryService
{
    ErrorInfo GetRecoveryInfo(Exception ex);
}

21.4 Visual Design — Avalonia Theme e Industrial Design System

Piano colori industriale consigliato:

Configurazione Avalonia — tema industriale:

<Application xmlns="https://github.com/avaloniaui"
             xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
             x:Class="Sistec.HMI.App">
    <Application.Styles>
        <FluentTheme />
        <StyleInclude Source="avares://Sistec.Theme/Industrial.axaml"/>
    </Application.Styles>
</Application>

21.5 Accessibilità WCAG AA — Contesto Industriale

Vincolo critico ambientale: I pannelli industriali tipicamente hanno touch + mouse USB. La tastiera è rara ma va supportata come fallback. Avalonia gestisce nativamente keyboard navigation con Tab, Enter, Escape, Arrow keys.

Regola pratica per touch industriale:

GESTI CONSENTITI (affidabili con guanti):
✅ Single tap (il solo gesto da usare)
✅ Long tap: NON usarlo (lento, rischio attivazione accidentale)
✅ Swipe: NON usarlo (rischio attivazione accidentale con guanti)
✅ Double tap: NON usarlo (frustrante con guanti)
✅ Pinch-to-zoom: NON usarlo (poca utilità su HMI industriale)

21.6 Interazione Pannello Industriale — Vincoli e Navigazione

Gerarchia di navigazione proposta:

Livello 0: Shell (sempre visibile)
├── Header: stato PLC, stato KUKA, stato Pressa, ora, operatore
├── Sidebar/Sotto: Home | Produzione | Manutenzione | Alarmi
└── Footer: allarme banner (se attivo)

Livello 1: Pagina (contenuto principale)
├── Home: card macchine (max 5)
├── Produzione: tabbed (Job, CutPlan, Pannelli)
├── Manutenzione: vista lista componenti con RUL
└── Alarmi: lista allarmi attivi + storico

Livello 2: Dettaglio (dialog modale)
├── Parametri macchina
├── Modifica job
├── Storico allarmi
└── Statistiche operatore

21.7 Gap Architetturali Critici per HCI

Implementazione MVVM — modello per ogni Stack.UI:

// Sistec.Stack.Kuka.UI/ViewModels/KukaInfoViewModel.cs
public partial class KukaInfoViewModel : ObservableObject
{
    private readonly IKukaRobotState _robotState;
    private readonly ILogger<KukaInfoViewModel> _logger;

    [ObservableProperty] private string _status = "Offline";
    [ObservableProperty] private bool _canStart;
    [ObservableProperty] private bool _isExecuting;

    public KukaInfoViewModel(IKukaRobotState robotState, ILogger<KukaInfoViewModel> logger)
    {
        _robotState = robotState;
        _logger = logger;

        // Reactive: stato cambia → UI si aggiorna automaticamente
        robotState.StateChanged += OnStateChanged;
    }

    [RelayCommand]
    private async Task StartAsync()
    {
        if (!CanStart) return;
        IsExecuting = true;
        try { await _robotState.StartAsync(); }
        catch (Exception ex) { _logger.LogError(ex, "Start failed"); }
        finally { IsExecuting = false; }
    }
}

21.8 Processo — Iterazione, Valutazione e Testing Utente

Processo iterativo proposto per ogni nuova vista:

1. Sketch su carta (5 minuti)
   └── Definire: cosa serve all'operatore? Quali info sono prioritarie?

2. Prototipo Avalonia XAML (1-2 ore)
   └── Versione funzionante con dati fittizi

3. Valutazione euristica interna (30 minuti, 3 persone)
   └── Applicare checklist §21.1-§21.6,documentare violazioni

4. Test con 1-2 operatori reali (30 minuti)
   └── Assegnare task: "Vuoi avviare il robot? Come fai?"
   └── Osservare dove si bloccano, cosa non capiscono

5. Raffinamento (1-2 ore)
   └── Correggere i problemi trovati

6. Integrazione in layout.json
   └── La vista diventa parte del sistema

Metriche di usabilità da raccogliere in produzione:

21.9 Raccomandazioni Prioritarie per la Roadmap

Priorità alta — da fare in Fase 1-2 (prima del codice UI):

Priorità media — da fare in Fase 3 (UI):

Priorità bassa — da fare in Fase 4+ (dopo il deploy):

21.10 Matrice di Tracciamento: Checklist → Architettura → Roadmap

21.11 High-Performance HMI — Metodologia ASM Consortium

L'ASM Consortium (Abnormal Situation Management Consortium) è il gruppo di ricerca che ha prodotto le linee guida per le High-Performance HMIs (HP-HMI), oggi lo standard de facto per i settori oil & gas, chimico, pharma e power generation. Le raccomandazioni ASM sono alla base dello standard ISA-101 e vanno oltre i suoi requisiti minimi.

Gap Attuale

Il documento §21 copre Norman, Shneiderman e Nielsen — fondamentali per l'HCI generale — ma non menziona la metodologia ASM che è specifica per HMIs industriali. La differenza è sostanziale:

I 3 Livelli di Situation Awareness (Endsley)

Il modello di Endsley è il fondamento dell'HP-HMI:

1. PERCEZIONE — "Cosa sta succedendo?"
   └── Operatore vede: KUKA Online, Pressa Running, 5 allarmi
   └── Metriche: colore, posizione, dimensione

2. COMPRENSIONE — "Cosa significa?"
   └── Operatore sa: 3 allarmi sono Emergency, 2 Warning
   └── Priorità: rosso > arancione > giallo

3. PROIEZIONE — "Cosa succederà tra 5 minuti?"
   └── Operatore sa: se la pressa non finisce il ciclo,
       il KUKA rimarrà in attesa → ritardo produzione
   └── Proiezione: trend + contesto

Obiettivo: portare l'operatore al Livello 3 di situation awareness con 1-2 secondi di osservazione.

Eccezioni: Quando Usare Colore (e Quando No)

<!-- ASM-Compliant Value Display -->
<Grid ColumnDefinitions="4, Auto, Auto">
    <!-- Banda laterale — colore solo per anomalie -->
    <Rectangle Grid.Column="0" Width="4"
               Fill="{Binding AlarmBandColor}"
               IsVisible="{Binding HasAlarm}"/>
    <!-- Nome parametro — sempre nero su grigio -->
    <TextBlock Grid.Column="1" Text="{Binding Label}"
               Foreground="#000000" Margin="4,0"/>
    <!-- Valore — nero, senza decori -->
    <TextBlock Grid.Column="2" Text="{Binding Value}"
               Foreground="#000000"/>
</Grid>

Exception-Based Display

Il principio cardine dell'HP-HMI è: mostra solo le eccezioni. In uno stato normale, l'HMI è quasi muto — l'operatore vede immediatamente ciò che è fuori norma.

flowchart TB
    subgraph StatoNormale["🔇 STATO NORMALE — Schermo muto"]
        A1["KUKA: 🟢 (grigio scuro)"]
        A2["Pressa: 🟢 (grigio scuro)"]
        A3["Produzione: 847 pezzi (testo nero)"]
        A4["Allarmi: 0 (nessun testo)"]
    end

    subgraph StatoAnomalo["🔴 ALLARME — Schermo parla"]
        B1["KUKA: 🔴 ROSSO LAMPEGGIANTE<br/>Joint 3 overload"]
        B2["Pressa: 🟢 (grigio — funziona)"]
        B3["Produzione: 847 pezzi (nero)"]
        B4["Allarmi: 1 Emergency, 2 Warning"]
    end

    StatoNormale -->|"Joint 3 overload"| StatoAnomalo
    StatoAnomalo -->|"Risolto"| StatoNormale

Regola pratica: se un elemento non richiede attenzione, deve essere visivamente quasi invisibile. Un operatore che vede tutto colorato non vede nulla.

Trend + Valore: Il Numero Istantaneo Non Basta

Le ricerche ASM mostrano che un valore numerico istantaneo non dà situation awareness: 87°C può essere normale o critico a seconda del trend.

NON ASM:
┌──────────────────┐
│ Temperatura: 87°C│  ← L'operatore sa cosa è ora, non cosa sarà
└──────────────────┘

ASM-COMPLIANT:
┌─────────────────────────┐
│  ┃ 87°C  ▁▂▃▅▇███▇▆▄▃▂ │  ← Trend ultimi 30 minuti
│  ┃      Stabile         │     + indicatore di trend
│  ┃ Soglia: 95°C         │     + contesto
└─────────────────────────┘

Implementazione:
┌──────────────────────────┐
│ Banda colore | Valore    │
│ (solo se anomalo)        │
│ o                        │
│ Banda normale (invisib.) │
└──────────────────────────┘

Metriche di Valutazione HP-HMI

Checklist: Adozione HP-HMI nella Greenfield

[ ] HMI Philosophy document cita esplicitamente Endsley SA model
[ ] Colore di sfondo unico: grigio (#E8E8E8 o #F0F0F0)
[ ] Processo normale = invisibile (grigio su grigio)
[ ] Valori numerici in nero, allineati a destra, senza cornice
[ ] Colore riservato ESCLUSIVAMENTE ad anomalie e allarmi
[ ] Ogni valore numerico ha trend (minisparkline o banda) sulla sinistra
[ ] Layout eccezioni: mostra solo ciò che è fuori specifica
[ ] Navigazione ISA-101 4 livelli: Overview → Unit → Detail → Diagnostic
[ ] Allarmi integrati nel processo (non popup separati)
[ ] Test con operatori reali: trovano l'anomalia in <2 secondi?

Impatto: $21 già copre molti concetti HP-HMI. Questa checklist trasforma i suggerimenti in vincoli di design per Fase 3 (UI). Sforzo aggiuntivo: 2-3 giorni per applicare la filosofia grigia ai template layout.json e aggiornare Sistec.Theme con le regole ASM.

L'architettura a stack verticali è già predisposta per l'integrazione di intelligenza artificiale. Il documento prevede già OnnxRuntimeEngine per predictive maintenance (§9.6) e Sistec.Stack.Cloud per analytics cloud (§13.6). Questa sezione espande il quadro con un layer AI dedicato che si aggancia naturalmente all'esistente.

22.1 Architettura del Layer AI

flowchart TB
    subgraph AI_Stack["Sistec.Stack.AI (NuGet, opzionale)"]
        direction TB
        CLI_AI["Client/AI<br/>OnnxInferenceEngine<br/>LlmClient (locale/cloud)"]
        DRV_AI["Driver/AI<br/>IModelRegistry<br/>IPromptTemplate"]
        SVC_AI["Services/AI<br/>PredictiveMaintenance<br/>AnomalyDetector<br/>ProcessOptimizer<br/>AlarmAnalyzer<br/>OperatorAssistant<br/>DocumentGenerator"]
        UI_AI["UI/AI<br/>AiInsightsPanel<br/>NaturalLanguageQuery"]
        SIM_AI["Simulator/AI<br/>AiSimulator (what-if)"]
    end

    subgraph Stacks_Esistenti["STACK ESISTENTI"]
        Kuka["Sistec.Stack.Kuka<br/>IMachineTelemetryProvider"]
        Safan["Sistec.Stack.Safan<br/>IMachineTelemetryProvider"]
        Plc["Sistec.Stack.PLC<br/>IMachineTelemetryProvider"]
        Prod["Sistec.Stack.Production<br/>IProductionAnalyticsService"]
        Job["Sistec.Stack.JobManagement<br/>IJobTracker"]
        Alarm["Sistec.Stack.Alarms<br/>IAlarmService"]
        Maint["Sistec.Stack.Maintenance"]
        Cloud["Sistec.Stack.Cloud"]
    end

    subgraph Config_AI["CONFIGURAZIONE AI"]
        Models["models/*.onnx<br/>modelli leggeri (<50MB)"]
        Prompts["prompts/*.json<br/>template prompt LLM"]
        Thresholds["thresholds.json<br/>soglie anomaly detection"]
    end

    UI_AI --> SVC_AI
    SVC_AI --> CLI_AI
    CLI_AI --> DRV_AI
    DRV_AI --> Config_AI

    Kuka -->|telemetria| SVC_AI
    Safan -->|telemetria| SVC_AI
    Plc -->|telemetria| SVC_AI
    Prod -->|statistiche| SVC_AI
    Job -->|storico job| SVC_AI
    Alarm -->|storico allarmi| SVC_AI
    Maint -->|RUL| SVC_AI
    SVC_AI -->|analytics| Cloud

    classDef ai fill:#80c9ff,stroke:#1565c0,color:#1a1a1a
    classDef stack fill:#87ff90,stroke:#2e7d32,color:#1a1a1a
    classDef config fill:#f3e5f5,stroke:#7b1fa2,color:#1a1a1a

    class CLI_AI,DRV_AI,SVC_AI,UI_AI,SIM_AI ai
    class Kuka,Safan,Plc,Prod,Job,Alarm,Maint,Cloud stack
    class Models,Prompts,Thresholds config

22.2 Stack AI — Dettaglio

22.3 Caso d'Uso 1: Operator Assistant (Linguaggio Naturale)

Problema: l'operatore deve navigare 5+ schermate per trovare informazioni semplici.

Soluzione: barra di ricerca in linguaggio naturale che interroga i dati di produzione:

Operatore: "quanti pezzi ha prodotto oggi il turno notturno?"
AI:        "Il turno notturno (00-06) ha prodotto 847 pezzi, 3.2% scarti.
            Ultimo job completato: #4521, programma P123, durata 42s."

Operatore: "qual è il tempo medio di piegatura per il programma P456?"
AI:        "Programma P456: tempo ciclo medio 38.2s (ultimi 200 cicli).
            Deviazione standard: 1.8s. Trend: in miglioramento (-2.1% vs ieri)."

Operatore: "quanti allarmi KUKA ci sono stati stanotte?"
AI:        "3 allarmi KUKA tra le 02:00 e 04:30:
            - 2x 'Joint 2 Overload' (durata media 45s)
            - 1x 'Connection timeout' (riconnesso automaticamente)"

Architettura

flowchart LR
    subgraph Input["INPUT OPERATORE"]
        NL["Barra ricerca<br/>linguaggio naturale<br/>(Avalonia TextBox)"]
    end

    subgraph NLU["NLU LAYER"]
        Intent["Intent Classifier<br/>DistilBERT quantized<br/>(ONNX, <70MB)"]
        Entities["Entity Extractor<br/>programId, timeRange,<br/>machine, shift"]
    end

    subgraph Query["QUERY BUILDER"]
        QB["QueryBuilder<br/>Intent + Entities →<br/>chiamate servizi"]
    end

    subgraph Services["SERVIZI DATI"]
        PA["IProductionAnalyticsService"]
        JA["IJobTracker"]
        AS["IAlarmService"]
        TP["IMachineTelemetryProvider"]
    end

    subgraph LLM["LLM RESPONSE"]
        Resp["Response Generator<br/>llama.cpp locale<br/>o OpenAI cloud API"]
    end

    NL --> Intent --> Entities --> QB
    QB --> PA
    QB --> JA
    QB --> AS
    QB --> TP
    PA --> Resp
    JA --> Resp
    AS --> Resp
    TP --> Resp
    Resp -->|"risposta testuale<br/>all'operatore"| NL

Intent Supportati

Sicurezza

• Solo lettura: l'OperatorAssistant non può mai inviare comandi alle macchine
• Nessun dato sensibile: PIN, badge RFID e password non compaiono mai nei prompt
• Audit log: ogni query e risposta salvata in ai_query_log tabella MySQL
• Rate limiting: max 10 query/minuto per evitare abuso

22.4 Caso d'Uso 2: Anomaly Detection su Telemetria

Differenza da predictive maintenance (§9.6): la maintenance predice quando si rompe (RUL). L'anomaly detection rileva comportamento anomalo in tempo reale, anche per componenti senza modello RUL addestrato.

Ogni stack espone IMachineTelemetryProvider (§9.6). L'AI sovrappone un modello di anomaly detection:

{
  "detectorId": "kuka_vibration_anomaly",
  "machine": "Kuka_0",
  "modelFile": "models/kuka_vibration_isolation_forest.onnx",
  "features": [
    { "tag": "Joint3.Vibration", "window": "5min", "statistic": "rms" },
    { "tag": "Joint3.Temperature", "window": "5min", "statistic": "max" },
    { "tag": "Joint3.Cycles", "window": "1h", "statistic": "sum" }
  ],
  "alertOnAnomaly": true,
  "severity": "warning",
  "suggestedAction": "Controllare lubrificazione giunto 3"
}

Modelli Consigliati per Edge

22.5 Caso d'Uso 3: Intelligent Alarm Analysis

Problema: allarmi ricorrenti senza correlazione visibile. L'operatore vede lo stesso allarme ripetersi ma non capisce la causa.

Soluzione: AlarmAnalyzer analizza pattern negli allarmi storici:

Input:  ultimi 500 allarmi (timestamp, tipo, sequenza, stato macchina)
Output: "L'allarme 'KUKA Joint 2 Overload' si verifica ogni 47±3 cicli.
         Correlazione: appare dopo 3+ pieghe consecutive a angolo > 90°.
         Suggerimento: considerare un cooldown di 5 cicli dopo pieghe acute."

flowchart LR
    subgraph Input["STORICO ALLARMI"]
        AH["IAlarmService<br/>.GetHistory(7gg)"]
        TM["IMachineTelemetryProvider<br/>.CollectFeaturesAsync()"]
    end

    subgraph Analysis["ANALYSIS ENGINE"]
        Corr["Correlation Engine<br/>sequenze, frequenza,<br/> finestre temporali"]
        LLM_A["LLM Prompt<br/>dati aggregati →<br/>analisi in linguaggio naturale"]
    end

    subgraph Output["OUTPUT"]
        Rep["Report periodico<br/>salvato in DB"]
        Not["Notifica operatore<br/>(se pattern critico)"]
        Dash["Dashboard allarmi<br/>(insights nella sidebar)"]
    end

    AH --> Corr
    TM --> Corr
    Corr --> LLM_A
    LLM_A --> Rep
    LLM_A --> Not
    LLM_A --> Dash

Output Tipico

{
  "patternId": "kuka_joint2_overload_correlation",
  "alarmType": "KUKA Joint 2 Overload",
  "frequency": "Ogni 47±3 cicli",
  "correlation": "Appare dopo 3+ pieghe a angolo > 90°",
  "rootCauseHypothesis": "Stress termico cumulativo su giunto 2",
  "suggestedAction": "Cooldown 5 cicli dopo pieghe acute > 90°",
  "confidence": 0.78,
  "dataPoints": 500,
  "timeRange": "2026-06-26 → 2026-07-03"
}

22.6 Caso d'Uso 4: Process Optimization

ProcessOptimizer analizza storico produzione e suggerisce ottimizzazioni parametriche:

// Input: storico job + parametri + esito
{
  "programId": "P123",
  "history": [
    { "params": { "speed": "fast", "pressure": 120 }, "cycleTime": 38.2, "scrapRate": 0.02 },
    { "params": { "speed": "normal", "pressure": 110 }, "cycleTime": 42.1, "scrapRate": 0.005 }
  ]
}

// Output: raccomandazione
{
  "recommendation": "Ridurre speed a 'normal' per programmi > 90°",
  "expectedImpact": "Scarti -60%, tempo ciclo +10%",
  "confidence": 0.82,
  "basedOn": "147 job storici con parametri simili"
}

Vincolo Operativo

La raccomandazione viene presentata come suggerimento, mai applicata automaticamente:

┌─────────────────────────────────────────────────┐
│  💡 Suggerimento AI — Programma P123             │
│                                                   │
│  Basandoci su 147 job storici con parametri       │
│  simili, ridurre la velocità da 'fast' a          │
│  'normal' per angoli > 90° potrebbe ridurre       │
│  gli scarti del 60% con un aumento ciclo          │
│  del 10%.                                         │
│                                                   │
│  Confidenza: 82%                                  │
│                                                   │
│  [Applica]  [Ignora]  [Dettagli]                 │
└─────────────────────────────────────────────────┘

L'operatore preme "Applica" → i parametri vengono modificati con audit trail. "Ignora" → il suggerimento viene loggato per analysis futura.

22.7 Caso d'Uso 5: Document Generator

Generazione automatica di report e documentazione:

22.8 Deploy: Edge AI su PC Industriale

Il PC industriale (Celeron/ARM) esegue inferenza ONNX locale. Nessun dato produzione esce dalla rete industriale.

PC Industriale
├── HMI.exe (Avalonia)
├── Sistec.Stack.AI.dll
│   ├── models/*.onnx              ← modelli leggeri (<50MB per anomaly/predictive)
│   ├── prompts/*.json             ← template prompt per LLM
│   ├── OnnxInferenceEngine        ← ONNX Runtime (CPU, no GPU richiesta)
│   └── LlmClient (opzionale)     ← llama.cpp per NLU + generazione locale
└── Sistec.Stack.Cloud.dll (opzionale)
    └── CloudModelUpdater          ← scarica modelli aggiornati da cloud

Specifiche Hardware Minime

22.9 Integrazione con Architettura Esistente

L'layer AI si aggancia ai componenti già definiti:

22.10 Sicurezza — Regole Fondamentali

22.11 Roadmap AI

Fase 3 (aggiornata): Stack applicativi + AI (4-5 settimane)
  ├── Sistec.Stack.Production
  ├── Sistec.Stack.RecipeEngine
  ├── Sistec.Stack.PalletTracking
  ├── Sistec.Stack.Maintenance (predictive ML ampliato §9.6)
  ├── Sistec.Stack.AI (NUOVO)
  │   ├── AnomalyDetector (Isolation Forest ONNX)        ← priorità alta
  │   ├── OperatorAssistant (NLU + query builder)          ← priorità alta
  │   ├── AlarmAnalyzer (correlation + LLM)                ← priorità media
  │   ├── ProcessOptimizer (storico + raccomandazioni)     ← priorità media
  │   ├── DocumentGenerator (report automatici)            ← priorità bassa
  │   └── AiInsightsPanel (UI Avalonia sidebar)            ← priorità alta
  └── Sistec.Stack.JobManagement, Alarms

Fase 4 (dopo deploy): Miglioramento continuo
  ├── Raccolta dati operatore su suggerimenti AI
  ├── Ri-addestramento modelli con dati reali
  ├── Aggiunta intent NLU basata su query frequenti
  └── Ottimizzazione modelli per edge (quantizzazione)

22.12 Vantaggi per il Cliente

22.13 Limiti

Le icone attuali delle codebase LAG/FAEL sono il prodotto di anni di sviluppo incrementale senza un design system unificato. Questa sezione documenta lo stato attuale, identifica i problemi e propone un'architettura greenfield conforme agli standard industriali (ISA-101, IEC 60617, WCAG 2.2).

23.1 Stato Attuale — Analisi Quantitativa

Il rapporto duplicazione è ~22:1 — per ogni icona unica esistono in media 22 copie nel filesystem (tra Sistec.Controls/Resources/, Sistec.UI/Resources/, Sistec.5315/HMI/Resources/, Sistec.HMI/C/Resources/, Sistec.HMI/AB/Resources/, e le cartelle bin/).

23.2 Problematiche Identificate

23.2.1 Formato 100% Raster PNG

Zero icone vettoriali. Ogni icona è un PNG a risoluzione fissa. Su pannelli industriali con DPI variabili o scaling Windows, le icone si pixelano. Le dimensioni non sono potenze di 2 (410x410, 254x254) — suggeriscono design per densità pixel fissa, non scalabile.

23.2.2 Dimensioni Inconsistenti

Le LED a 720x720 sono rendering 3D fotorealistici — eccessivamente complessi per HMI industriale. Il Reset a 794x794 è un outlier dimensionale. Le dimensioni miste (410, 254, 720, 794) rendono impossibile un sistema di griglia uniforme.

23.2.3 Naming Incoerente

23.2.4 Mappatura Icona-Funzione Ambigua

Analisi dei 47 bottoni critici nelle schermate principali:

Risultato: 18/47 bottoni critici (38%) hanno un'icona semanticamente ambigua. L'operatore deve ricordare cosa fa ogni pulsante perché l'icona non lo comunica.

23.2.5 Architettura Icone Fragile

23.2.6 LED Fotorealistici

Le 6 LED indicator (GrayLed.png, BlueLed.png, GreenLed.png, YellowLed.png, OrangeLed.png, RedLed.png) sono 720x720 pixel, 8-bit RGBA, ~50 KB ciascuna. Sono rendering 3D con gradienti, ombre e riflessi — eccessivamente complessi per un HMI industriale dove il LED è un semplice indicatore circolare on/off.

FAEL ha inoltre duplicati italiani identici: Led_Grigio.png, Led_Blu.png, Led_Arancio.png, Led_Verde.png, Led_Rosso.png, Led_Giallo.png — stessi identici byte delle versioni inglesi.

23.3 Standard di Riferimento

ISA-101 (HMI Design Standard)

IEC 60617 / ISO 7000 (Simboli Grafici)

Per l'HMI serv ibrido: accuratezza tecnica da IEC 60617/ISO 7000, adattata per leggibilità su schermo.

WCAG 2.2 (Accessibilità)

23.4 Design System Greenfield

23.4.1 Griglia e Dimensioni

Regola: ogni icona viene progettata su griglia 24x24 con padding 2px, poi esportata a 24/32/48/64px. Il design è sempre lo stesso, solo lo stroke scala.

Griglia 24x24 con padding 2px:

  0  1  2  3  4  5  6  7  8  9 10 11 12 13 14 15 16 17 18 19 20 21 22 23
0 ░░ ░░ ░░ ░░ ░░ ░░ ░░ ░░ ░░ ░░ ░░ ░░ ░░ ░░ ░░ ░░ ░░ ░░ ░░ ░░ ░░ ░░ ░░ ░░
1 ░░ ░░ ░░ ░░ ░░ ░░ ░░ ░░ ░░ ░░ ░░ ░░ ░░ ░░ ░░ ░░ ░░ ░░ ░░ ░░ ░░ ░░ ░░ ░░
2 ░░ ░░ ▓▓ ▓▓ ▓▓ ▓▓ ▓▓ ▓▓ ▓▓ ▓▓ ▓▓ ▓▓ ▓▓ ▓▓ ▓▓ ▓▓ ▓▓ ▓▓ ▓▓ ▓▓ ▓▓ ▓▓ ░░ ░░
3 ░░ ░░ ▓▓ ▓▓ ▓▓ ▓▓ ▓▓ ▓▓ ▓▓ ▓▓ ▓▓ ▓▓ ▓▓ ▓▓ ▓▓ ▓▓ ▓▓ ▓▓ ▓▓ ▓▓ ▓▓ ▓▓ ░░ ░░
  ...
22 ░░ ░░ ▓▓ ▓▓ ▓▓ ▓▓ ▓▓ ▓▓ ▓▓ ▓▓ ▓▓ ▓▓ ▓▓ ▓▓ ▓▓ ▓▓ ▓▓ ▓▓ ▓▓ ▓▓ ▓▓ ▓▓ ░░ ░░
23 ░░ ░░ ░░ ░░ ░░ ░░ ░░ ░░ ░░ ░░ ░░ ░░ ░░ ░░ ░░ ░░ ░░ ░░ ░░ ░░ ░░ ░░ ░░ ░░

Area utile: 20x20 px (dal pixel 2 al pixel 21)

23.4.2 Stile Visivo

Stroke width per dimensione:

Regole di design:

• Massimo 3-4 elementi visivi a 24px, 4-5 a 32px
• Nessun testo interno alle icone sotto 48px
• Forme geometriche semplici (cerchi, quadrati, triangoli, curve semplici)
• Evitare linee sottili (< 1,5px) — scompaiono su pannelli con riflessi
• Angoli arrotondati 1-2px — moderno ma non "consumer"

23.4.3 Palette Colori (Dark Theme Industriale)

Regola fondamentale ISA-101: il colore è SECONDARIO. L'icona deve essere riconoscibile per FORMA anche senza colore. Un operatore con daltonismo (8% degli uomini) deve poter distinguere tutti gli stati.

23.4.4 Rappresentazione Stati

Transizioni di stato — mapping legacy → greenfield:

23.4.5 Touch Targets e Guanti Industriali