Aggiunge specifiche iniziali

2026-06-30 20:17:42 +02:00
commit 03ff702ad9
1 changed files with 382 additions and 0 deletions
--- a/SPECIFICHE.md
+++ 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.