77 lines
4.3 KiB
Markdown
77 lines
4.3 KiB
Markdown
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:
|
|
```text
|
|
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:
|
|
```json
|
|
{
|
|
"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:
|
|
1. **Standard**: PEP8 obbligatorio.
|
|
2. **Naming**: Variabili, funzioni e commenti esclusivamente in **Inglese**.
|
|
3. **Modularità**: Una funzione non deve eccedere la singola responsabilità. Moduli sopra le 1000 righe devono essere rifattorizzati.
|
|
4. **UI Threading**: Le operazioni di I/O pesanti (creazione ZIP grandi) dovranno in futuro essere spostate su thread separati per non bloccare la GUI.
|
|
5. **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. |