bak-and-rest/SPECIFICHE.md

# Bak&Rest - Specifiche iniziali

## Obiettivo

Bak&Rest e' un'applicazione Windows per rilevare durante la giornata i file creati, modificati, cancellati o spostati in alcune cartelle configurate, registrarli in un elenco persistente e permettere all'utente, dalla tray area, di avviare un backup verso un computer remoto prima dello spegnimento del PC.

Il progetto dovra' essere sviluppato in Python, con interfaccia di configurazione in CustomTkinter, servizio Windows per il monitoraggio e applicazione tray per il comando manuale di backup.

## Componenti principali

### Nomi applicativi

Nomi definitivi dei componenti:

- prodotto: `Bak&Rest`;
- servizio Windows: `BakRestWatchdog`;
- descrizione servizio: `Bak&Rest Watchdog Service`;
- applicazione tray: `BakRestTray`;
- applicazione di configurazione: `BakRestConfig`;
- eseguibile servizio: `BakRestWatchdog.exe`;
- eseguibile tray: `BakRestTray.exe`;
- eseguibile configurazione: `BakRestConfig.exe`.

Gli eseguibili destinati all'utente finale non devono aprire finestre console.

### Servizio Windows watchdog

Il servizio Windows deve:

- avviarsi automaticamente all'avvio del computer, se previsto dalla configurazione;
- monitorare le directory definite nel file di configurazione;
- rilevare eventi di creazione, modifica, cancellazione e spostamento dei file;
- filtrare gli eventi in base alle estensioni configurate;
- applicare esclusioni di directory e pattern;
- registrare i file cambiati in un registro persistente;
- mantenere un log giornaliero delle operazioni;
- mantenere un log giornaliero delle operazioni.

Il servizio watchdog non deve controllare la raggiungibilita' del server di backup. Questo controllo deve essere gestito da Task Scheduler tramite notifier separato, in modo da poter mostrare avvisi nella sessione utente senza accoppiare il servizio a interfacce grafiche.

La libreria Python consigliata per il monitoraggio e' `watchdog`, perche' su Windows usa API native di sistema ed evita un polling continuo e inefficiente.

### Tray app

La tray app deve:

- avviarsi automaticamente al login dell'utente, se previsto dalla configurazione;
- mostrare un'icona nella tray area;
- mostrare lo stato generale del sistema:
  - servizio watchdog attivo/non attivo;
  - server di backup raggiungibile/non raggiungibile;
  - numero di file in attesa di backup;
  - ultimo backup eseguito;
- offrire almeno la voce di menu `Backup e spegni`;
- eseguire il backup tramite `rsync`;
- scrivere un log giornaliero dedicato;
- spegnere il computer solo se il backup termina correttamente;
- segnalare eventuali errori senza spegnere il computer.

La tray app e' il componente piu' adatto per eseguire `rsync` e richiedere lo spegnimento, perche' queste sono azioni esplicite dell'utente.

La stessa logica di backup deve essere disponibile anche senza interfaccia grafica, tramite opzione `--nogui`, per permettere l'esecuzione da Task Scheduler alla disconnessione o fine sessione. In modalita' no-GUI non devono comparire icone tray o finestre di messaggio: gli errori devono essere registrati nei log e il processo deve restituire un codice di uscita diverso da zero.

### GUI CustomTkinter

La GUI di configurazione deve permettere di:

- abilitare o disabilitare l'avvio automatico del servizio;
- abilitare o disabilitare l'avvio automatico della tray app;
- gestire le directory monitorate;
- gestire le estensioni incluse;
- gestire directory e pattern esclusi;
- configurare il server remoto;
- configurare la destinazione del backup;
- configurare il comando o percorso di `rsync`;
- visualizzare lo stato corrente;
- aprire i log giornalieri;
- eventualmente eseguire un test di raggiungibilita' del server;
- visualizzare l'elenco dei file in coda per il backup;
- rimuovere singoli file o selezioni multiple dalla coda;
- proporre, quando si rimuovono file dalla coda, se rimuovere solo i file selezionati o escludere dal backup le cartelle che li contengono.

Se un computer viene spento senza usare `Backup e spegni`, i file gia' registrati come `pending` devono restare nel registro cambiamenti e accumularsi con quelli del giorno successivo, in modo da poter essere sincronizzati al backup successivo.

## Backup

Il backup deve essere eseguito dalla tray app quando l'utente seleziona `Backup e spegni`.

Il motore consigliato per server Windows 10 e' `robocopy`, eseguito da Python tramite `subprocess`, verso una o piu' share SMB. `rsync` resta un'opzione secondaria solo per scenari in cui sia installato e configurato anche sul server remoto.

Il backup deve essere incrementale non distruttivo:

- creazioni e modifiche sul master generano copie verso lo slave;
- cancellazioni sul master non devono cancellare file sullo slave;
- `robocopy` non deve essere usato con `/MIR` o `/PURGE`;
- i file cancellati o non piu' presenti devono essere marcati come ignorati nella coda.
- ogni file deve essere rimosso dalla coda appena la copia di quel singolo file e' riuscita su tutte le share configurate, senza attendere la fine dell'intero backup.

La copia deve ricreare sotto ogni share di destinazione il percorso relativo rispetto alla cartella monitorata. Esempio: con cartella monitorata `D:\Lavori`, il file `D:\Lavori\Cliente\a.psd` deve essere copiato in `\\server\share\Lavori\Cliente\a.psd`.

Per la prima versione il programma non deve bloccare, intercettare o ritardare lo spegnimento normale del PC tramite menu Start o altri comandi Windows standard. Il comando `Backup e spegni` e' un percorso esplicito e consigliato, ma l'utente deve poter spegnere il computer con le vie usuali. La gestione del caso in cui l'utente dimentichi il backup prima dello spegnimento verra' progettata in una fase successiva.

Flusso previsto:

1. L'utente clicca la tray icon.
2. L'utente seleziona `Backup e spegni`.
3. La tray app verifica che il server sia raggiungibile.
4. La tray app legge il registro dei file cambiati.
5. La tray app controlla che i file da copiare siano stabili.
6. La tray app esegue `rsync`.
7. La tray app registra l'esito nel log.
8. Se il backup e' riuscito, la tray app pulisce o archivia il registro dei cambiamenti.
9. Se il backup e' riuscito, la tray app spegne il computer.
10. Se il backup fallisce, il computer non viene spento.

Se il server di backup non e' raggiungibile, la tray app deve mostrare una finestra di messaggio con testo simile a:

```text
Server non raggiungibile. E' spento?
```

## Registro dei cambiamenti

Il servizio watchdog deve registrare i cambiamenti in modo persistente, cosi' da non perdere eventi in caso di riavvio o crash.

Il registro deve contenere almeno:

- percorso completo del file;
- tipo evento: creato, modificato, cancellato, spostato;
- timestamp evento;
- vecchio percorso, se il file e' stato spostato;
- dimensione rilevata, se disponibile;
- stato del record: in attesa, copiato, errore, ignorato.

Per la prima versione si puo' usare un file di testo strutturato, JSON Lines o SQLite. SQLite e' consigliabile se vogliamo robustezza, query semplici e gestione migliore dei duplicati.

## Log giornalieri

Devono essere previsti log giornalieri per verificare malfunzionamenti e ricostruire cosa e' successo.

Struttura proposta:

```text
logs/
  2026-06-30-service.log
  2026-06-30-tray.log
  2026-06-30-backup.log
```

I log devono includere:

- avvio e arresto del servizio;
- avvio e arresto della tray app;
- configurazione caricata;
- cartelle monitorate;
- estensioni abilitate;
- esclusioni applicate;
- file rilevati;
- eventi ignorati e motivo;
- errori di accesso a file o directory;
- risultato dei test di raggiungibilita' del server;
- comando `rsync` eseguito, senza password o segreti;
- esito del backup;
- richiesta di spegnimento;
- eventuale annullamento dello spegnimento per errore.

## Raggiungibilita' del server di backup

Il sistema deve verificare periodicamente se il server remoto e' raggiungibile.

Controlli possibili:

- ping ICMP, se abilitato nella rete;
- apertura porta SSH, se si usa `rsync` via SSH;
- controllo percorso SMB, se il backup usa una share Windows;
- comando di test configurabile.

La tray app deve mostrare chiaramente se il server risulta spento o non raggiungibile.

La non raggiungibilita' del server deve essere registrata nei log giornalieri.

Poiche' un servizio Windows non deve aprire direttamente finestre nella sessione utente, la finestra di avviso deve essere mostrata dalla tray app quando legge uno stato server non raggiungibile. Il messaggio richiesto e':

```text
Accendi il server di backup o verifica che sia connesso alla rete
```

Se il flusso operativo usa solo Task Scheduler e backup no-GUI, l'avviso durante la giornata deve essere gestito da un notifier separato lanciato nella sessione utente, sempre tramite Task Scheduler. Il notifier deve controllare il server ogni 30 minuti, mostrare il messaggio una sola volta mentre il server resta non raggiungibile, e resettare l'avviso quando il server torna raggiungibile.

## Strategia di monitoraggio

Non e' consigliato monitorare tutto il disco filtrando solo per estensione, ad esempio `C:\` con filtro `.jpg`, `.png`, `.mp4`. Questo approccio puo' generare molti eventi inutili, includere directory di sistema, rallentare il sistema e creare un registro troppo rumoroso.

La strategia consigliata e':

- monitorare solo directory incluse esplicitamente;
- usare un filtro per estensione;
- applicare esclusioni forti per directory di sistema e directory non di lavoro;
- permettere all'utente di aggiungere cartelle di lavoro dalla GUI;
- prevedere una modalita' di audit per capire quali cartelle producono file rilevanti.

Se il servizio gira come `LocalSystem`, la configurazione deve supportare un utente target per l'espansione dei percorsi utente. Esempio: con `target_user = "pettirosso"`, `%USERPROFILE%\\Documents` deve essere espanso in `C:\\Users\\pettirosso\\Documents`, non nel profilo di sistema.

### Directory candidate da includere

Esempi:

```yaml
watch:
  target_user: "pettirosso"
  include_dirs:
    - "%USERPROFILE%\\Desktop"
    - "%USERPROFILE%\\Documents"
    - "%USERPROFILE%\\Pictures"
    - "%USERPROFILE%\\Videos"
    - "D:\\Lavori"
    - "E:\\ArchivioGrafica"
```

La directory `Downloads` va valutata con attenzione: puo' essere utile, ma produce spesso file temporanei e incompleti.

### Estensioni candidate

Esempi:

```yaml
  include_extensions:
    - .jpg
    - .jpeg
    - .png
    - .gif
    - .tif
    - .tiff
    - .psd
    - .ai
    - .svg
    - .pdf
    - .mp4
    - .mov
    - .avi
    - .mkv
    - .doc
    - .docx
    - .xls
    - .xlsx
```

### Directory da escludere

Esempi:

```yaml
  exclude_dirs:
    - "%WINDIR%"
    - "%PROGRAMFILES%"
    - "%PROGRAMFILES(X86)%"
    - "%APPDATA%"
    - "%LOCALAPPDATA%"
    - "%TEMP%"
    - "$Recycle.Bin"
    - "System Volume Information"
    - "node_modules"
    - ".git"
    - "__pycache__"
```

### Pattern da escludere

Esempi:

```yaml
  exclude_patterns:
    - "~$*"
    - "*.tmp"
    - "*.bak"
    - "*.crdownload"
    - "*.part"
    - "*.lock"
```

## Raccolte Windows e indicizzazione

Non e' consigliabile affidarsi solo alle Raccolte di Windows.

Le Raccolte sono viste logiche e non garantiscono che ogni file creato o modificato sul computer venga incluso. Inoltre, l'indicizzazione di Windows Search non equivale alla presenza del file in una Raccolta.

Esempi di cartelle che potrebbero non essere coperte automaticamente:

- `C:\Export`;
- `D:\Render`;
- cartelle di progetto create manualmente;
- cartelle su dischi esterni;
- cartelle usate da software grafici o video;
- directory temporanee o di cache.

Per questo motivo il sistema deve basarsi su directory configurate esplicitamente.

## Stabilizzazione dei file

Per file grandi come video, archivi, immagini pesanti o file di progetto, il watchdog puo' ricevere eventi mentre il file e' ancora in scrittura.

Prima del backup bisogna verificare che il file sia stabile:

- dimensione invariata per un intervallo configurabile;
- timestamp di modifica invariato per un intervallo configurabile;
- file apribile in lettura;
- eventuale ritardo minimo dopo l'ultimo evento.

Valori iniziali consigliati:

```yaml
stability:
  min_age_seconds: 60
  unchanged_check_interval_seconds: 5
  unchanged_checks_required: 2
```

## Configurazione

Il file di configurazione dovra' definire almeno:

- avvio automatico del servizio;
- avvio automatico della tray app;
- directory incluse;
- estensioni incluse;
- directory escluse;
- pattern esclusi;
- server di backup;
- destinazione remota;
- modalita' di test del server;
- percorso o comando `rsync`;
- comportamento in caso di errore;
- comportamento di spegnimento;
- posizione dei log;
- posizione del registro cambiamenti.

Esempio iniziale:

```yaml
service:
  autostart: true

tray:
  autostart: true

watch:
  include_dirs:
    - "%USERPROFILE%\\Desktop"
    - "%USERPROFILE%\\Documents"
    - "%USERPROFILE%\\Pictures"
    - "%USERPROFILE%\\Videos"
  include_extensions:
    - .jpg
    - .jpeg
    - .png
    - .pdf
    - .mp4
    - .mov
  exclude_dirs:
    - "%WINDIR%"
    - "%PROGRAMFILES%"
    - "%PROGRAMFILES(X86)%"
    - "%APPDATA%"
    - "%LOCALAPPDATA%"
    - "%TEMP%"
    - "$Recycle.Bin"
    - "System Volume Information"
    - "node_modules"
    - ".git"
  exclude_patterns:
    - "~$*"
    - "*.tmp"
    - "*.bak"
    - "*.crdownload"
    - "*.part"

backup:
  server_host: "backup-server"
  server_check:
    type: "tcp"
    port: 22
    interval_seconds: 300
  rsync_path: "rsync"
  remote_destination: "utente@backup-server:/backup/bak-rest/"
  shutdown_on_success: true
  shutdown_command: "shutdown /s /t 0"

stability:
  min_age_seconds: 60
  unchanged_check_interval_seconds: 5
  unchanged_checks_required: 2

storage:
  change_registry: "%PROGRAMDATA%\\BakRest\\changes.sqlite"
  logs_dir: "%PROGRAMDATA%\\BakRest\\logs"
```

## Scelte tecniche iniziali

Librerie candidate:

- `watchdog` per il monitoraggio file;
- `pywin32` per il servizio Windows;
- `pystray` per la tray area;
- `customtkinter` per la GUI di configurazione;
- `PyYAML` o `tomllib`/`tomli-w` per la configurazione;
- `sqlite3` standard library per il registro cambiamenti;
- `subprocess` per eseguire `rsync`;
- `robocopy` come motore predefinito per share SMB Windows;
- `logging` standard library per i log giornalieri.

Packaging candidato:

- `PyInstaller` per produrre eseguibili Windows;
- build senza console per tray app e GUI di configurazione;
- servizio Windows installabile come `BakRestWatchdog`;
- eventuale installer successivo per configurare servizio, autostart tray e cartelle dati.

Gli eseguibili finali previsti sono:

```text
dist/
  BakRestWatchdog.exe
  BakRestTray.exe
  BakRestConfig.exe
  BakRestNoGui.exe
```

## Decisioni aperte

- Scegliere formato definitivo della configurazione: YAML, TOML o JSON.
- Scegliere formato definitivo del registro cambiamenti: testo, JSON Lines o SQLite.
- Definire se il backup remoto avverra' via SSH, SMB, altro protocollo o percorso montato.
- Definire quale distribuzione di `rsync` usare su Windows.
- Definire come installare e aggiornare il servizio Windows.
- Definire come gestire credenziali e segreti senza scriverli in chiaro nei log.
- Definire se creare un installer unico o distribuire gli eseguibili con script di installazione.
- Definire se prevedere backup versionato o solo mirror.
- Definire politica per cancellazioni: propagare la cancellazione sul backup o conservarla.
- Definire comportamento in caso di file non copiabili.
- Definire se aggiungere una modalita' audit per scoprire cartelle di lavoro candidate.

## Principi guida

- Non monitorare l'intero computer senza limiti espliciti.
- Preferire directory incluse esplicitamente.
- Applicare esclusioni conservative.
- Non affidarsi solo alle Raccolte Windows.
- Non reimplementare `rsync` in Python.
- Separare servizio watchdog, tray app e GUI di configurazione.
- Spegnere il computer solo dopo un backup riuscito.
- Scrivere log chiari e giornalieri.
- Non registrare password, chiavi o segreti nei log.