netgescon-day0/docs/support/ARCHITETTURA-STORAGE-TENANCY.md

Architettura storage e tenancy

Punto di partenza reale

• il nodo staging attuale gira su questa macchina in /var/www/netgescon/
• il backup visto in storage/app/update-backups/... e un backup tecnico del nodo applicativo, non un archivio documentale per amministratore o per stabile
• oggi il progetto e impostato come multi-tenant logico, soprattutto tramite amministratore_id e stabile_id

Distinzione importante da non perdere

Ci sono due problemi diversi:

1. Backup tecnico del nodo

Serve per:

• rollback di un aggiornamento
• snapshot pre-update
• ripristino tecnico applicazione

Questo backup puo restare a livello nodo, perche riguarda il sito installato in quella macchina.

2. Archivi documentali dei condomini/stabili

Servono per:

• documenti utenti
• bilanci
• consuntivi
• allegati ticket
• pratiche e storico per stabile

Questi invece vanno isolati in modo molto piu rigoroso per amministratore e per stabile.

Cosa si puo replicare davvero dal modello archivi MySQL visto negli screenshot

Negli screenshot il concetto utile non e "forzare MySQL a salvare la singola tabella dove vogliamo", ma questo:

• ogni archivio ha un proprio contenitore fisico riconoscibile
• dentro quel contenitore ci sono le tabelle operative di quell archivio
• il codice gestionale punta all archivio giusto tramite un codice stabile e non tramite il nome casuale del file

Su MySQL moderno la traduzione corretta e questa:

• database centrale registry condiviso per autenticazione, configurazioni globali, mapping e storico trasferimenti
• database archivio dedicato per amministratore o per stabile, nominato con il codice canonico
• storage documentale separato con lo stesso codice canonico

Esempio coerente con NetGescon:

registry condiviso:
  netgescon_core

archivi amministratore:
  ng_arch_admin_ADM0001
  ng_arch_admin_ADM0002

archivi stabile:
  ng_arch_stb_148
  ng_arch_stb_205

storage file:
  storage/app/amministratori/ADM0001/stabili/148/
  storage/app/amministratori/ADM0001/stabili/205/

Questo da un risultato molto vicino al software che hai mostrato, ma in una forma compatibile con Laravel, backup, restore e trasferimento stabile tra amministratori.

Valutazione dell idea: un Docker per ogni stabile

Fattibilita tecnica

Si, e fattibile.

Valutazione pratica

Come idea di massima e valida per l isolamento forte, ma non e il primo passo giusto per NetGescon oggi.

Motivi:

• aumenterebbe molto la complessita operativa
• obbligherebbe a gestire migrazioni, immagini, log, backup, code e monitoraggio per molti container
• renderebbe piu pesante il deploy di funzionalita comuni
• il codice attuale e ancora pensato come applicazione condivisa con separazione logica dei dati, non come fleet di micro-istallazioni per stabile

Strategia consigliata senza rivoluzionare tutto

Fase 1. Isolamento storage per amministratore e stabile

Questo e il passo giusto da fare adesso.

Struttura consigliata:

/var/www/netgescon/storage/app/tenants/
  amministratore-12/
    stabile-146/
      documenti/
      bilanci/
      ticket/
      acqua/
      consuntivi/
  amministratore-18/
    stabile-205/
      documenti/
      bilanci/
      ticket/

Vantaggi:

• isolamento fisico piu chiaro dei file
• minor rischio di accessi incrociati accidentali
• nessuna rivoluzione immediata dell architettura Laravel
• facilita backup/export/trasporto per singolo stabile
• usa da subito i codici canonici gia presenti in anagrafica unica, evitando dipendenze da ID locali

Fase 1-bis. Resolver unico dei percorsi archivio

Questo e il primo pezzo tecnico concreto da imporre nel codice:

• un solo servizio decide il path canonico per amministratore e stabile
• il path deve usare i codici canonici, non gli ID locali
• ogni comando, import, export, restore e upload deve passare da li

Questo evita il problema attuale piu pericoloso: alcuni punti usano codice_amministratore, altri codice_univoco, e il filesystem rischia di divergere.

Fase 2. Disk privati dedicati e regole applicative

Dopo la struttura cartelle, il passo corretto e:

• usare solo storage privato per documenti sensibili
• servire i file via controller autorizzati
• centralizzare il path resolver per amministratore/stabile
• impedire che un path venga calcolato senza contesto stabile valido

Fase 3. Backup/export per stabile

Una volta separati i file, si puo aggiungere:

• zip esportabile per singolo stabile
• dump dati mirato per stabile
• pacchetto di trasporto o consegna per cambio gestione

Fase 3-bis. Separazione MySQL realmente utile

Se vogliamo ottenere un effetto simile agli archivi del software legacy, la scelta migliore non e una tabella fisica per ogni ditta nello stesso schema, ma una di queste due:

1. database dedicato per amministratore e tabelle interne per i suoi stabili
2. database dedicato per stabile quando serve portabilita massima

Per NetGescon oggi la scelta piu equilibrata e:

• registry centrale condiviso
• archivio MySQL dedicato almeno per amministratore
• opzionale archivio dedicato per stabile nei casi che richiedono trasporto o isolamento forte

Questa direzione e gia piu vicina al codice esistente, perche nel progetto esistono gia servizi e comandi che prevedono database_attivo e database_dedicato.

Fase 4. Nodo dedicato per amministratore o cliente grande

Qui entra in gioco Docker, ma in modo piu sensato:

• un container o stack per amministratore grande
• oppure un container dedicato per cliente enterprise
• non uno per ogni stabile come default

Questo da un vero isolamento senza moltiplicare troppo la complessita.

Raccomandazione architetturale

Default consigliato

• codice applicativo condiviso
• database condiviso con domini ben separati
• storage fisico separato per amministratore e stabile
• regole di autorizzazione strette lato applicazione

Eccezione premium o ad alta sicurezza

• stack Docker dedicato per amministratore
• database dedicato
• volume dedicato
• dominio dedicato

Questa e la soluzione piu equilibrata.

Come integrarla senza stravolgere il codice

Passo 1

Introdurre un resolver unico dei path documentali, ad esempio un servizio applicativo tipo:

• TenantStoragePathService

Compito:

• riceve amministratore_id, stabile_id, tipo archivio
• restituisce il path corretto e validato

Passo 2

Migrare progressivamente le aree piu sensibili:

• allegati ticket
• documenti stabile
• bilanci e consuntivi
• documenti acqua e ripartizioni

Passo 3

Lasciare i backup update in storage/app/update-backups/ come backup tecnici del nodo, separati dai documenti tenant.

Decisione pratica attuale

Per NetGescon oggi la scelta piu corretta e:

1. non usare un Docker per ogni stabile come configurazione standard
2. separare subito i file per amministratore e stabile
3. mantenere il nodo staging in /var/www/netgescon/ come installazione condivisa di test
4. prevedere in futuro stack Docker dedicati per amministratori o clienti che richiedono isolamento forte

Prossimo passo tecnico consigliato

Il prossimo sviluppo coerente e introdurre il layer di storage tenant-aware senza toccare ancora il modello runtime a container per stabile.

Registry centrale introdotto nel progetto

Per mettere a terra il punto 1 e stato introdotto il concetto di registry centrale archivio:

• tabella tenant_archive_registries
• modello TenantArchiveRegistry
• servizio TenantArchiveRegistryService
• comando php artisan netgescon:archive-registry-sync

Scopo:

• avere una mappa unica e rigenerabile degli archivi amministratore e stabile
• legare codice archivio, owner corrente, path storage e strategia database
• rendere piu semplice riallineare ambienti di test con dati sporchi o movimenti tra amministratori

Questo registry non sostituisce ancora la logica applicativa dei moduli, ma crea il punto centrale da cui partire per:

• pulizia dati
• export/import per stabile
• trasferimento stabile tra amministratori
• futura separazione MySQL per archivio