# Distribuzione e Aggiornamenti NetGescon

Questo documento descrive il flusso operativo reale oggi in uso e separa chiaramente cio che e gia attivo da cio che resta roadmap.

## 1. Flusso attivo oggi

La catena corretta e una sola:

1. sviluppo e verifica in Day0;
2. commit e push su Gitea `main`;
3. staging allineato dal contenuto pubblicato su Gitea;
4. controllo e applicazione aggiornamento dal pannello browser oppure via comando `php artisan`;
5. backup pre-update locale, con seconda copia opzionale o obbligatoria su Google Drive secondo configurazione del nodo.

Questo significa che Day0 e il workspace autorevole, mentre staging va trattato come nodo remoto anche quando gira sulla stessa macchina fisica.

## 2. Cosa e gia implementato

Sono gia presenti e funzionanti i seguenti componenti:

- comando `php artisan netgescon:update` per controllare e applicare un pacchetto pubblicato;
- comando `php artisan netgescon:preupdate-backup` per creare snapshot ripristinabile prima di ogni update;
- pagina browser Supporto > Modifiche, che esegue prima il backup e poi l update in background con file di progresso persistente;
- supporto Google Drive per la seconda copia del backup pre-update;
- esclusione di `.env`, `storage/` e `.git/` dalla sovrascrittura del pacchetto;
- verifica hash SHA256 e pulizia cache a fine applicazione.

## 3. Significato del canale `free`

Nel sistema attuale il canale `free` e un segnaposto tecnico di compatibilita, non una decisione commerciale definitiva.

In pratica oggi esiste una sola distribuzione operativa. La distinzione `free` e `licensed` rimane nel codice per non rompere il motore update e per preparare scenari futuri, ma non va interpretata come modello commerciale gia definito.

## 4. Preparazione baseline e backup manuale

Se serve congelare una baseline completa del nodo attuale, usare:

```bash
bash scripts/ops/netgescon-baseline-freeze.sh \
  --app-dir /var/www/netgescon \
  --version 0.8.0-baseline
```

Produce:

- archivio codice;
- copia `.env`;
- dump database best-effort;
- metadati baseline.

Per il backup pre-update applicativo usare invece:

```bash
php artisan netgescon:preupdate-backup --differential --tag=manuale
```

Con copia anche su Google Drive:

```bash
php artisan netgescon:preupdate-backup \
  --differential \
  --tag=manuale \
  --drive \
  --admin-id=ID_AMMINISTRATORE
```

Se il nodo richiede obbligatoriamente la seconda copia Drive:

```bash
php artisan netgescon:preupdate-backup \
  --differential \
  --tag=manuale \
  --drive \
  --require-drive \
  --admin-id=ID_AMMINISTRATORE
```

## 5. Pubblicazione da Day0 verso Gitea

Prima di aggiornare staging, il contenuto deve essere allineato a Gitea.

Sequenza minima:

```bash
git status
git add .
git commit -m "Messaggio coerente con il lotto Day0"
git push origin main
```

Solo dopo il push il nodo staging deve essere considerato aggiornabile tramite il suo flusso di pull/apply.

## 6. Configurazione del nodo staging

Le variabili principali sono:

```env
NETGESCON_UPDATE_URL=https://updates.netgescon.it
NETGESCON_UPDATE_CHANNEL=free
NETGESCON_NODE_CODE=staging-01
NETGESCON_PREUPDATE_DRIVE_ENABLED=true
NETGESCON_PREUPDATE_REQUIRE_DRIVE=false
NETGESCON_UPDATE_RESOLVE=
```

Note:

- `NETGESCON_UPDATE_CHANNEL=free` oggi indica il percorso operativo standard, non la licenza del cliente;
- `NETGESCON_PREUPDATE_DRIVE_ENABLED=true` abilita il tentativo di seconda copia su Drive quando l amministratore del nodo ha credenziali Google valide;
- `NETGESCON_PREUPDATE_REQUIRE_DRIVE=true` blocca l update se la seconda copia non viene completata;
- `NETGESCON_UPDATE_RESOLVE` serve solo in casi DNS particolari, ad esempio `updates.netgescon.it:443:192.168.0.53`.

## 7. Aggiornamento da browser

Il percorso operativo preferito per staging e il pannello browser in Supporto > Modifiche.

La pagina esegue questa sequenza:

1. verifica permessi utente;
2. crea backup pre-update locale;
3. se configurato, carica anche la copia Google Drive;
4. avvia `netgescon:update --apply` in background;
5. salva avanzamento e log in `storage/app/support/update-jobs/`;
6. aggiorna il riepilogo ultimo backup e l esito dell operazione.

Questo e il percorso da preferire per l accettazione operativa lato staging, perche lascia traccia applicativa e stato avanzamento leggibile da interfaccia.

## 8. Aggiornamento da comando

Se serve eseguire la stessa procedura senza browser:

```bash
php artisan netgescon:update --channel=free
php artisan netgescon:update --channel=free --apply
```

La modalita `licensed` rimane disponibile solo come compatibilita tecnica o scenario futuro:

```bash
php artisan netgescon:update --channel=licensed --apply --code=CLIENTA --auth=tokenA
```

## 9. Sicurezza minima gia coperta

- hash SHA256 del pacchetto verificato prima dell apply;
- backup `.env` locale durante l update;
- snapshot pre-update con manifest file e indice record;
- esclusione dei percorsi sensibili dalla sovrascrittura;
- `composer install --no-dev --optimize-autoloader` quando il pacchetto contiene file Composer;
- `php artisan optimize:clear` sempre a fine apply;
- `php artisan migrate --force` se il manifest dichiara `migrate_required=true`.

## 10. Roadmap reale

I passaggi sotto restano obiettivi successivi, non prerequisiti del flusso attuale:

1. firma manifest con chiave privata e verifica lato nodo;
2. audit centralizzato di download e apply;
3. packaging/release automatizzati da pipeline Gitea;
4. rollback completo codice piu database con retention formalizzata.