Vai al contenuto

Piano di avvio operativo del progetto MDM e qAlarm

Data: 28/10/2026.

Obiettivo

Verificare che il midserver sul branch refactor/v1 possa gestire un box rappresentativo del parco attuale, prima di introdurre la linea stage e pianificare la migrazione della produzione.

Il primo task è una ricognizione in sola lettura. Si confrontano documentazione, codice e ambiente dev, si ricostruisce il flusso dei comandi asincroni e si verifica la disponibilità di un box di prova. In questa fase non si modificano codice o configurazioni e non si aggiornano i box.

La preparazione del laboratorio, le prove che inviano comandi e l'implementazione sono attività successive, con un perimetro distinto. Questo documento dettaglia l'avvio del piano generale, senza sostituirne le fasi e i gate per la produzione.

Versioni di riferimento

Componente Riferimento documentato Verifica necessaria
Midserver attuale Flask, main 2.2.0 e dev 2.4.0 Confrontare i due branch e identificare il comportamento effettivamente distribuito.
Midserver nuovo FastAPI, branch refactor/v1, indicato come v3 e 3.0.0 Verificare versione dichiarata nel codice, commit e revisione effettivamente distribuita.
Box per la prima prova Linea main, riferimento iniziale 3.2.9 Confermare release, immagine disponibile e rappresentatività rispetto al parco.
Box per la prova successiva Linea stage (oggi 3.9.0) Individuare una release candidata dopo il confronto con i fix della linea 3.2.x.

Le versioni provengono dalle schede del midserver e del software dei box. Non sono una verifica della versione attualmente in esecuzione.

La lettura MCP di Coolify svolta il 28/10 ha confermato l'applicazione refactor-v1, configurata sul branch refactor/v1, con stato running:unknown. Il branch configurato non dimostra quale commit sia in esecuzione; lo stato running:unknown non conferma la salute applicativa.

Sequenza di lavoro

Passo Attività Risultato atteso
1 Ricognizione in sola lettura Differenze confermate e proposta del primo intervento.
2 Preparazione del laboratorio Box di prova e servizi dev isolati dalla produzione.
3 Prima implementazione mirata Comando asincrono completato con un box della linea attuale.
4 Completamento della compatibilità Log, live Protexia e chiamate del pannello verificati.
5 Prova della linea stage Compatibilità e percorso di aggiornamento verificati in laboratorio.

1 Ricognizione in sola lettura

Responsabili proposti: Mattia e Lorenzo. Coinvolgere Michele per rete e operatività e i referenti del codice per i comportamenti non documentati.

  1. Individuare i repository mdm_mid_server, mdm_installation, mdm_frigate_wrapper e mdm_web_panel. Leggere le rispettive istruzioni e registrare branch, commit e modifiche locali, preservando il lavoro esistente.
  2. Confrontare la documentazione con il codice disponibile. Per il midserver distinguere l'implementazione Flask di produzione, le modifiche del branch dev e la riscrittura refactor/v1.
  3. Ricostruire il percorso di POST /common/installation/async/callback/{token}: chiamante sul box, autenticazione, payload, token, gestione della risposta e comportamento in caso di errore. Verificare nel codice se la rotta manca ancora e se esiste un percorso equivalente.
  4. Leggere da Coolify configurazione non sensibile, branch, cronologia deploy e stato delle risorse necessarie. Identificare pannello, midserver, MQTT, Redis, MySQL e OME di dev, distinguendo risorse attive e obsolete.
  5. Verificare la disponibilità di un box dedicato alle prove. Registrarvi la versione installata e le eventuali modifiche locali, se sono disponibili accessi autorizzati in sola lettura. Non aggiornarlo né riconfigurarlo.
  6. Mappare le destinazioni di HTTP, MQTT, webhook, streaming e archiviazione del box di prova, senza copiare segreti o dati dei clienti nella documentazione.

Le letture possono usare richieste MCP HTTP POST: la sola lettura dipende dallo strumento invocato. Non chiamare callback, registrazioni, sincronizzazioni di stato o comandi applicativi per provarli in questa fase, perché possono modificare lo stato.

Consegna del primo task: una nota con evidenze, riferimenti a file e commit, differenze rispetto alla documentazione, prerequisiti mancanti e proposta concreta della prima modifica. Se l'endpoint è già presente, verificare il comportamento e aggiornare il task invece di duplicarlo.

Il task è concluso quando: il flusso asincrono è ricostruito, le incertezze residue sono esplicite e la preparazione del laboratorio ha un elenco preciso di operazioni. L'assenza del box non impedisce l'analisi statica; impedisce di dichiarare verificata la compatibilità sul dispositivo.

2 Preparazione del laboratorio

Questo passo comporta eventuali modifiche alla configurazione e va eseguito dopo la ricognizione, nel perimetro concordato del laboratorio.

  • Preferire un box di prova già sulla 3.2.9, se confermata come riferimento. Se il dispositivo ha una versione diversa, prima registrare la situazione e definire una procedura di preparazione reversibile.
  • Collegare il box esclusivamente ai servizi di test previsti. Verificare anche le destinazioni indirette: webhook BSQ, Telegram, notifiche, storage e streaming.
  • Risolvere l'isolamento di OME prima di qualsiasi prova video. La documentazione segnala un indirizzo di produzione incorporato nel codice dei box: cambiare soltanto l'URL del midserver non basta.
  • Se l'isolamento richiede una modifica al codice, trattarla come intervento esplicito e circoscritto. Le prove dipendenti restano sospese finché il problema non è risolto.
  • Salvare la configurazione iniziale del laboratorio in uno spazio riservato e definire come ripristinarla. Usare immagini e dati di prova senza informazioni dei clienti.

Il passo è concluso quando: è documentato dove finiscono comandi, eventi e video, e nessuna prova prevista coinvolge servizi o impianti di produzione.

3 Prima implementazione mirata

Il primo candidato è T3.1 del piano delle attività: completare async/callback, se l'assenza o l'incompatibilità viene confermata.

  1. Preparare una modifica limitata al contratto ricostruito, preservando path, autenticazione, payload e comportamento richiesti dai box esistenti.
  2. Aggiungere un test mirato al comportamento modificato e usare i controlli rapidi pertinenti del repository. Non introdurre refactoring o dipendenze estranee al task.
  3. Revisionare il diff e aggiornare changelog e documentazione interessata. Verificare i trigger di deploy prima di pubblicare modifiche su branch collegati a Coolify.
  4. Distribuire la modifica solo nel dev isolato e svolgere una prova funzionale circoscritta dal pannello al box, fino alla risposta asincrona.

Criterio di completamento: il comando selezionato raggiunge il box di prova della linea 3.2.x, la callback viene elaborata e il pannello riceve l'esito atteso. Un test automatico o una compilazione, da soli, non dimostrano questo percorso sul box.

4 Completamento della compatibilità

Dopo il primo flusso funzionante, affrontare in interventi separati le mancanze confermate nel codice attuale:

  1. Ricezione dei log dai box, T3.2.
  2. Pagina live utilizzata da Protexia, T3.12.
  3. Adattamenti delle chiamate del pannello, T3.3 e T3.4.

Per ogni intervento preservare anche i campi delle risposte e i nomi storici necessari alla compatibilità. Prima di pianificare il cambio in produzione, completare inoltre persistenza Redis, continuità degli eventi MQTT e gestione di più istanze secondo il piano generale.

5 Prova della linea stage

La linea stage entra nelle prove dopo aver verificato il comportamento con la linea attuale e identificato una release candidata. La documentazione segnala divergenze tra main e stage: la disponibilità di una versione più recente non ne dimostra l'idoneità.

Disponibilità Utilizzo proposto
Due box Mantenere il primo sulla 3.2.9 di riferimento e usare il secondo per la candidata della linea stage.
Un solo box Completare e registrare le prove sulla 3.2.9, salvare configurazione e procedura di ripristino, poi provare l'aggiornamento alla candidata della linea stage.

Verificare il percorso di aggiornamento oltre alla compatibilità della nuova versione. La 3.2.9 non rappresenta automaticamente tutte le versioni precedenti del parco: l'eventuale allineamento dei clienti è un'attività separata, prevista nella Fase 9a del piano generale.

Priorità organizzativa immediata

Affiancare alla ricognizione il passaggio di consegne con Michele, previsto entro il 30/10/2026 in T0.9. Raccogliere procedure per VPN, FreePBX, Raspberry, backup e ripristino; trasferire gli accessi nel gestore di password e verificare che Mattia o Lorenzo sappiano eseguire le operazioni ricorrenti.

La creazione dei backup mancanti e la prova di ripristino restano prerequisiti degli interventi sulla produzione. Non sono incluse come operazioni da eseguire durante il primo task in sola lettura.

Checklist del primo task

  • [ ] Repository, branch, commit e modifiche locali identificati.
  • [ ] Versioni documentate distinte dalle revisioni effettivamente distribuite.
  • [ ] Flusso async/callback ricostruito e mancanza verificata nel codice.
  • [ ] Componenti dev necessari identificati.
  • [ ] Disponibilità e versione del box di prova chiarite.
  • [ ] Destinazioni di rete e rischio di invio verso la produzione documentati.
  • [ ] Prima modifica proposta con perimetro e criterio di completamento.
  • [ ] Nessun codice, configurazione o dispositivo modificato durante la ricognizione.

Riferimenti