2025-12-23 09:31:38 +01:00

4.3 KiB

Raw Permalink Blame History

Certamente. Ho aggiornato il documento tecnico includendo le nuove componenti (Commit Dialog e logica di Import) e dettagliando meglio il protocollo di sincronizzazione tramite Manifest. Questo documento ora rappresenta lo stato dell'arte completo del progetto CodeBridge.

Progetto CodeBridge: Specifiche Tecniche e Architettura (Aggiornato)

1. Introduzione e Scopo

CodeBridge è un tool di sincronizzazione codebase progettato per scenari di sviluppo in ambienti isolati ("air-gapped"). Il software permette di colmare il gap tra una workstation offline e una collegata alla rete aziendale (SVN), automatizzando il trasferimento selettivo delle modifiche.

2. Architettura del Sistema

L'applicazione segue un pattern modulare dove la logica di gestione file è rigorosamente separata dall'interfaccia grafica (Tkinter).

Struttura dei Moduli:

codebridge/
├── __main__.py             # Entry point dell'applicazione
├── core/
│   ├── comparer.py         # Motore di confronto (Hashing SHA-256)
│   └── sync_manager.py     # Gestore I/O, ZIP e Manifest
└── gui/
    ├── main_window.py      # Dashboard principale
    ├── diff_viewer.py      # Confronto visuale side-by-side
    └── commit_dialog.py    # Dialog modale per messaggi di commit

3. Funzionalità Core

3.1 Motore di Comparazione (`comparer.py`)

Hashing: Utilizza SHA-256 per identificare modifiche nei contenuti, ignorando metadati volatili.
Ignore Logic: Filtra automaticamente file e cartelle non pertinenti (.svn, .git, __pycache__, ecc.) per ridurre il rumore visivo e il peso dei pacchetti.

3.2 Gestione Sincronizzazione (`sync_manager.py`)

Il software non si limita a copiare file, ma gestisce un "pacchetto di sincronizzazione" intelligente.

Export: Genera uno ZIP contenente solo i file Added e Modified.
Manifest: Inserisce nello ZIP un file bridge_manifest.json contenente:
- Timestamp dell'operazione.
- Messaggio di commit dell'utente.
- Lista dei file da eliminare (Deleted) nella destinazione.
Import: Legge il manifest, elimina i file rimossi nella sorgente e sovrascrive/aggiunge i nuovi file nella destinazione.

3.3 Interfaccia Utente (`gui/`)

Main Window: Gestisce il flusso principale. Visualizza i risultati del confronto con codifica a colori (Verde: Added, Arancione: Modified, Rosso: Deleted).
Diff Viewer: Implementa uno scroll sincronizzato tra due widget di testo per analizzare le differenze riga per riga prima dell'applicazione.
Commit Dialog: Garantisce che ogni pacchetto esportato sia documentato, facilitando l'operazione di commit finale su SVN.

4. Protocollo di Scambio Dati

Il file bridge_manifest.json è il cuore del trasferimento:

{
    "timestamp": "2023-10-27T10:00:00",
    "commit_message": "Fix: updated login logic and removed unused assets",
    "changes": {
        "added": ["path/to/new_file.py"],
        "modified": ["path/to/modified_file.py"],
        "deleted": ["path/to/obsolete_file.py"]
    }
}

5. Linee Guida di Sviluppo

Per garantire la manutenibilità tra diversi sviluppatori:

Standard: PEP8 obbligatorio.
Naming: Variabili, funzioni e commenti esclusivamente in Inglese.
Modularità: Una funzione non deve eccedere la singola responsabilità. Moduli sopra le 1000 righe devono essere rifattorizzati.
UI Threading: Le operazioni di I/O pesanti (creazione ZIP grandi) dovranno in futuro essere spostate su thread separati per non bloccare la GUI.
Safety: Ogni operazione di scrittura (Import) deve richiedere una conferma esplicita dell'utente.

Prossimi Step nello Sviluppo:

Affinamento Diff Viewer: Implementazione della copia selettiva di blocchi di codice.
Status Bar: Feedback visivo sul numero di file processati e operazioni pendenti.
Logging: Sistema di log su file per tracciare le operazioni di import/export effettuate nel tempo.

Cosa ne pensi? Se il documento ti soddisfa, possiamo iniziare con l'affinamento dei dettagli, partendo magari dalla Status Bar nella MainWindow per dare feedback immediato all'utente, oppure migliorando il Diff Viewer per permettere la modifica granulare. Dimmi tu da dove preferisci ripartire.

4.3 KiB Raw Permalink Blame History