Pannello di controllo per-tenant del motore predittivo: pesi AHI, gradi, soglie RUL, probabilità di guasto, finestra inbox e override per tipo di asset. Tracciabilità completa via config_version.

Configurazione Predittiva

La configurazione predittiva è il pannello di controllo del motore di manutenzione predittiva. Ogni tenant regola come si calcola l'AHI, quando un asset è a rischio, quale finestra usa l'inbox unificato per consolidare alert, e la confidenza minima per interventi automatici — senza modifiche al codice né deploy.

Come funziona

La configurazione è versionata (config_version) e consumata online dalla pipeline predittiva. Le modifiche sono validate, persistite e propagate via pub/sub senza riavvio del worker.

A cosa serve

Personalizzare il motore alla tolleranza al rischio di ciascuna organizzazione.
Regolare pesi dei 5 sotto-indici AHI e soglie di gradi (A/B/C/D).
Definire breakpoint RUL (ore che separano critical/high/medium/low) e di probabilità di guasto.
Configurare la finestra di dedup dell'Alert Aggregator.
Overridere qualsiasi parametro per asset_type.
Tracciabilità completa via config_version.

Parametri configurabili

Pesi AHI (`ahi_weights`)

Sotto-indice	Default	Misura
`condition`	0.35	Stato istantaneo vs baseline
`alarm_health`	0.20	Ore-allarme ISA-18.2 accumulate
`maintenance_compliance`	0.15	Conformità piani preventivi
`trend_stability`	0.10	Direzione e r² tendenze 24h
`anomaly_pressure`	0.20	Densità rilevamenti ML recenti (7g)

La somma deve essere 1.0.

Gradi AHI (`ahi_grades`)

Parametro	Default	Significato
`grade_a`	90	AHI ≥ 90 → A
`grade_b`	70	AHI ≥ 70 → B
`grade_c`	50	AHI ≥ 50 → C
`grade_d`	30	AHI ≥ 30 → D; sotto → F

Soglie RUL (`rul_thresholds`)

Parametro	Default	Intervallo consentito	Significato
`critical_hours`	24	da 1 a 8760 (1 anno)	RUL inferiore a 24h diventa critico
`high_hours`	168	da 1 a 17520 (2 anni)	RUL inferiore a 168h (7g) diventa alto
`medium_hours`	720	da 1 a 43800 (5 anni)	RUL inferiore a 720h (30g) diventa medio

Regola di gerarchia: i tre valori devono soddisfare critical_hours <= high_hours <= medium_hours. Le richieste che violano questo ordine vengono respinte con 422. Evita errori di configurazione come critical=500 con high=100.

Gli intervalli sono stati ampliati per coprire asset industriali di lunga durata (trasformatori, recipienti in pressione) la cui vita utile si misura in anni e non in settimane.

Probabilità guasto (`failure_probability`)

Parametro	Default	Significato
`critical_ahi`	30	AHI ≤ 30 → probabilità critica
`high_ahi`	50	30 < AHI ≤ 50 → alta
`normal_ahi`	70	50 < AHI ≤ 70 → media

Alert Aggregator

Parametro	Default	Significato
`alert_dedup_window_minutes`	60	Finestra entro cui rilevamenti stesso asset collassano in una riga

Altri

Parametro	Default	Significato
`cbm_trigger_multiplier`	1.5	Metrica che supera `baseline_max × 1.5` attiva CBM
`ahi_risk_threshold`	70	AHI ≤ 70 "a rischio" per dashboard esecutive
`confidence_snapshots_ceiling`	30	Snapshot per saturare confidenza RUL al 100%

Requisiti di maturità (`maturity_requirements`)

Parametro	Default	Significato
`level_1_snapshots`	10	Snapshot per uscire dal Livello 0
`level_2_snapshots`	30	Snapshot per Livello 2
`level_2_failures`	1	Guasti registrati per Livello 2
`level_3_failures`	3	Guasti per Livello 3
`level_3_confidence`	70	Confidenza RUL minima (%) per Livello 3

Override per tipo di asset

{
  "rul_thresholds": { "critical_hours": 24, "high_hours": 168, "medium_hours": 720 },
  "asset_type_overrides": {
    "critical_pump": { "rul_thresholds": { "critical_hours": 12 } },
    "hvac_chiller":  { "rul_thresholds": { "critical_hours": 48, "high_hours": 336 } }
  }
}

`config_version` — tracciabilità di audit

Ogni update_config incrementa atomicamente config_version. Tenant nuovi partono da 0 (default di fabbrica).

Ogni documento persistito porta il config_version attivo al momento del calcolo:

_asset_health_snapshots — campo config_version per snapshot.
_asset_prognostics — campo config_version per prognostica.

Perché importa: se un tenant regola ahi_grades tre volte in 6 mesi, gli snapshot vecchi non vengono riscritti — ciascuno conserva la versione di calcolo. Un audit può ricostruire quali soglie produssero ciascun grado storico.

I caller non possono smuggle un config_version: il servizio lo rimuove — il contatore è di proprietà del sistema.

Cache

Config cacheata in memoria (TTL 5 min) e Redis se disponibile. Ogni update_config invalida il cache. Nessun restart necessario.

Come usarlo

Dashboard

Configurazione → Motore Predittivo.
Regola pesi AHI via slider.
Modifica soglie di gradi e RUL.
Configura override per asset_type.
Salva — config_version incrementa.
Ripristina Default — cancella la config del tenant.

I cambi sono loggati nell'audit trail con data, utente, valori precedenti/nuovi. Combinato con config_version, permette audit retroattivi.

Abbassare critical_hours o grade_a può generare più task urgenti automatici. Testare in staging prima della produzione.

API

GET  /api/v1/predictive-config            # ritorna config risolta
PATCH /api/v1/predictive-config           # update parziale, bumpa config_version
POST /api/v1/predictive-config/reset      # cancella config del tenant

Gli aggiornamenti sono deep-merge.

Benefici chiave

Un solo pannello per-tenant.
Granularità fine con override per asset_type.
config_version tracciabile in ogni snapshot.
Cache con invalidazione automatica.
Sistema protegge il proprio counter.
Reset idempotente.

Consumatori

health_assessment_service — pesi + gradi + anomaly_pressure.
prognostics_service — rul_thresholds + failure_probability.
maturity_calculation_service — maturity_requirements.
alert_aggregator_service — alert_dedup_window_minutes.
Briefing giornalieri WhatsApp/email — ahi_risk_threshold.

Configurazione Predittiva

In questa pagina