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;
• verificare periodicamente la raggiungibilita' del server di backup;
• segnalare lo stato del server alla tray app.

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.

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 dalla coda;
• proporre, quando si rimuove un file dalla coda, se rimuovere solo il file o escludere dal backup la cartella che lo contiene.

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 e' il vero rsync, eseguito da Python tramite subprocess. Python deve fare da orchestratore, non da reimplementazione di rsync.

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:

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:

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.

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.

Directory candidate da includere

Esempi:

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

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

Directory da escludere

Esempi:

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

Pattern da escludere

Esempi:

  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:

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:

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;
• 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:

dist/
  BakRestWatchdog.exe
  BakRestTray.exe
  BakRestConfig.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.