# 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:

```text
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:

```text
/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