commit 03ff702ad9ca73910dae61bd7391358defb13abc Author: allebonvi Date: Tue Jun 30 20:17:42 2026 +0200 Aggiunge specifiche iniziali diff --git a/SPECIFICHE.md b/SPECIFICHE.md new file mode 100644 index 0000000..ffb3535 --- /dev/null +++ b/SPECIFICHE.md @@ -0,0 +1,382 @@ +# 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 + +### 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. + +## 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`. + +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. + +## 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. + +## 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: + +```yaml +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: + +```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`; +- `logging` standard library per i log giornalieri. + +## 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 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.