Vai al contenuto

Istruzioni per coding agent e sviluppatori

Leggere tutto prima di toccare codice o sistemi. Queste regole valgono per ogni repository del progetto MDM / qAlarm.

Ordine di lettura

  1. README.md: le sei cose da sapere.
  2. 02-architettura/README.md: componenti e flussi.
  3. La scheda del componente su cui si lavora, in 02-architettura/componenti/.
  4. 04-stato/README.md e 04-stato/rischi-e-problemi.md.
  5. L'attività del piano che si sta eseguendo, in 05-piano-operativo/attivita.md.
  6. Nel repository: README.md, AGENTS.md/CLAUDE.md se presenti, CHANGELOG.md.

Repository locali

Percorso base: C:\Users\l.mioso\Documents\GitHub\. L'origine è AWS CodeCommit (eu-west-1).

Repository Ruolo Branch rilevanti
mdm_mid_server Midserver: ponte tra pannello/qAlarm e box main (Flask 2.2.0, in prod), dev (Flask 2.4.0), refactor/v1 (v3 FastAPI, in dev, base per la prod futura)
mdm_installation Software del box installato dal cliente main (3.2.x, sul parco), stage (3.9.0, prossima versione: solo box di prova, arriva ai clienti unita in main, D22)
mdm_frigate_wrapper Ponte tra installazione e Frigate main, stage
mdm_web_panel Pannello web interno (Flutter) main (prod 1.8.0), dev
qAlarm2_be Backend qAlarm (FastAPI + Socket.IO + worker) main, deploy_dev (auto-deploy su Coolify dev)
qAlarm2_fe Frontend qAlarm (React/Vite) main, deploy_dev
protexia App mobile per i clienti (Flutter) —
api.bsq Backend PHP del vecchio sistema BSQ, usato anche da Protexia —
lambdaFunctionsPython Lambda per le notifiche push —
ewelink-integration Proxy PHP verso il cloud eWeLink (relè Sonoff) —
televigilanza-mdm Progetto di Michele (sistema vecchio): automatismi, Telegram, controllo impianti —
infra-lib Libreria infra-cli (ambienti, segreti AWS, avvio dello stack); sottomodulo external/infra-lib della linea stage del box main (v0.1.9)
monitoring Stack Grafana/Prometheus/Loki/Tempo/Alertmanager per qAlarm e midserver v3, solo su Coolify dev main, dev (su Coolify dev)

Convenzione dei branch (dove adottata): main = produzione, stage = prossima versione, con il codice più aggiornato. Il midserver usa refactor/v1, il pannello dev, qAlarm deploy_dev. Dettagli in 04-stato/versioni-e-branch.md.

Regole non negoziabili

  1. Produzione in sola lettura, salvo un'attività del piano approvata che dica il contrario. Le macchine di prod sono: ServerIT (170.10.0.108), pfSense, Proxmox, FreePBX. Niente docker compose down, niente git pull sul server, niente modifiche alle regole del firewall senza approvazione esplicita.
  2. I box dei clienti non si toccano se non tramite le procedure di aggiornamento previste (06-runbook/aggiornamento-box.md), e solo dopo il test su macchine di prova.
  3. Mai segreti nei file: niente password, token, chiavi AWS, contenuti di .env, credenziali MQTT. Se servono per un test, si usano variabili d'ambiente o AWS Secrets Manager. Alcuni segreti sono già nei repository (problema noto M1): non vanno copiati né diffusi.
  4. Niente dati dei clienti nella documentazione, nei test o nelle fixture: niente nomi, indirizzi, MAC reali, codici impianto reali.
  5. Compatibilità con i box esistenti: il parco ha versioni da 3.1.9 a 3.2.9. Ogni modifica al midserver deve continuare a rispondere agli endpoint e ai topic MQTT che quei box usano. Vedi 04-stato/parita-midserver-v3.md.
  6. Prima dev, poi prod. Ogni modifica va provata su Coolify dev (170.10.0.107, *.dev.bsqdev.uk).
  7. Nomi storti esistenti sono contratti: usercases, reponse, insallation_id, replay_to, request/erros, contianer, compilete_registration e simili non si correggono se non come modifica di compatibilità esplicita.
  8. Non dichiarare verifiche che non sono state fatte. Se un test non è stato eseguito, va scritto.

Fatti che sorprendono (e causano errori)

  • L'elenco delle installazioni non è in MySQL: è in Redis (chiave = MAC, aggiornata a ogni sync_state). La tabella MySQL installations contiene i backup delle configurazioni. Vedi 04-stato/dati-e-registro-installazioni.md.
  • I box chiamano il midserver all'IP VPN 172.16.16.253 sulle porte 5000 (HTTP) e 1883 (MQTT). Non usano domini. Quell'IP è un NAT di pfSense verso 170.10.0.108.
  • L'IP del server di streaming OME è scritto nel codice dei box (185.31.66.185:9999, problema M15).
  • api.bsqdev.uk e ome.bsqdev.uk sono scritti nel codice dell'app Protexia e del vecchio api.bsq: non si possono dismettere.
  • La v3 del midserver ascolta su 5005, la v2 su 5000: in prod serve una porta 5000 compatibile.
  • In prod Redis ha solo un volume anonimo: un compose down + up lo svuota.
  • La versione che un box dichiara (stato, pannello) viene dal file .env.build_tag montato dall'host, non dall'immagine in esecuzione. Il tag reale si legge solo con docker ps sul box.

Dopo ogni lavoro

  • Test e lint del repository (per qAlarm2_be: uv run ruff check, uv run ruff format --check, uv run pytest).
  • CHANGELOG.md del repository aggiornato.
  • Questa documentazione aggiornata: scheda del componente, 04-stato se cambia lo stato, 04-stato/decisioni.md se si è presa una decisione, stato dell'attività in 05-piano-operativo/attivita.md.