Sincronizzazione cloud

Come funziona la sincronizzazione cloud

Kanban Pro è un'applicazione local-first. Ogni progetto è una cartella sul tuo file system contenente file di ticket Markdown e una directory di configurazione .kanban/. Non ci sono account, nessun servizio cloud proprietario e nessuna registrazione.

Per collaborare con altri, semplicemente posiziona la tua cartella di progetto all'interno di una directory sincronizzata dal cloud — iCloud Drive, Dropbox, Google Drive, OneDrive o qualsiasi unità di rete. Ogni partecipante apre la stessa cartella in Kanban Pro, e i cambiamenti si propagano automaticamente attraverso la sincronizzazione file del provider cloud.

Configurazione di un progetto condiviso

1. Scegli una cartella cloud. Apri Finder e naviga alla directory di sincronizzazione del tuo provider cloud (ad esempio, ~/Library/Mobile Documents/com~apple~CloudDocs/ per iCloud Drive, ~/Dropbox/ per Dropbox, o il mount di Google Drive / OneDrive nella tua barra laterale di Finder).
2. Crea una cartella di progetto. Crea una nuova cartella per il tuo progetto, ad esempio Team Board.
3. Aprila in Kanban Pro. Avvia Kanban Pro, fai clic su Apri cartella e seleziona la cartella che hai appena creato. Kanban Pro inizializzerà la directory .kanban/ e potrai iniziare ad aggiungere colonne e ticket.
4. Condividi la cartella. Utilizza le funzioni di condivisione del tuo provider cloud per invitare i collaboratori. Su iCloud Drive, fai clic con il pulsante destro sulla cartella e scegli Condividi. Su Dropbox o Google Drive, utilizza la finestra di dialogo di condivisione. Su OneDrive, fai clic con il pulsante destro e seleziona Condividi → Condividi con OneDrive. Ogni collaboratore dovrebbe quindi aprire la stessa cartella sincronizzata nella propria copia di Kanban Pro.

Struttura di cartella consigliata

Quando Kanban Pro inizializza un progetto, crea la seguente struttura all'interno della cartella scelta:

Ogni ticket è un file Markdown semplice con YAML frontmatter per i metadati (stato, priorità, assegnato, tag, campi personalizzati). Puoi leggere, modificare o eseguire il backup di questi file con qualsiasi strumento — inclusi gli agenti di codifica IA che funzionano direttamente con il file system.

Sincronizzazione in tempo reale e modifica senza conflitti

Kanban Pro monitora la cartella del progetto per i cambiamenti del file system utilizzando un file watcher in tempo reale. Quando un collaboratore salva un ticket o aggiorna la configurazione della board, il cambiamento viene rilevato in pochi secondi e l'interfaccia utente si aggiorna automaticamente.

Come vengono evitati i conflitti

• Blocco dei ticket: Quando apri un ticket per la modifica, Kanban Pro crea un piccolo file di blocco all'interno di .kanban/locks/. Gli altri utenti vedono il ticket come bloccato e non possono sovrascrivere le tue modifiche. I file di blocco si sincronizzano attraverso il tuo provider cloud in modo che tutti i collaboratori vedano lo stesso stato di blocco.
• Scritture atomiche: Ogni ticket è un singolo file Markdown. Kanban Pro scrive prima in un file temporaneo, quindi lo rinomina — evitando gli aggiornamenti parziali anche se il provider cloud si sincronizza a metà scrittura.
• Rilevamento del completamento della scrittura: Kanban Pro aspetta che i file si stabilizzino (2 secondi per i ticket, 1 secondo per la configurazione della board) prima di leggerli. Questo garantisce che la sincronizzazione cloud abbia terminato la scrittura prima che l'app elabori il cambiamento.
• Ultima scrittura vince per la configurazione della board: L'ordine delle colonne, le impostazioni e le definizioni dei campi personalizzati sono archiviati in board.json. Se due utenti cambiano le impostazioni della board contemporaneamente, l'ultima scrittura vince — ma questo è raro in pratica poiché la configurazione della board cambia di rado.

Comprensione dei file di blocco

La directory .kanban/locks/ contiene file di blocco temporanei che indicano quali ticket sono attualmente in fase di modifica e da chi. Ogni file di blocco è un piccolo documento JSON:

{
  "ticket": "KAN-42",
  "user": "Alice",
  "device": "Alice-MacBook",
  "timestamp": "2026-03-09T10:30:00Z"
}

I file di blocco vengono creati quando un ticket viene aperto per la modifica e rimossi quando l'editor viene chiuso. Consentono a Kanban Pro di mostrare un indicatore visivo sui ticket bloccati in modo che i collaboratori sappiano che qualcuno sta lavorando su di essi.

Risoluzione dei blocchi non aggiornati

Se Kanban Pro si arresta o un dispositivo non è in linea, un file di blocco potrebbe rimanere senza essere pulito. Questo è chiamato un blocco non aggiornato.

Kanban Pro rileva anche i blocchi più vecchi di 24 ore e li contrassegna come potenzialmente non aggiornati nell'interfaccia utente, dandoti la possibilità di forzare lo sblocco direttamente dall'app.

Note sui provider cloud

Migliori pratiche

• Mantieni le cartelle del progetto disponibili non in linea. Contrassegna la tua cartella di progetto come « Disponibile non in linea », « Specchio file », « Mantieni sempre su questo dispositivo » o « Mantieni scaricato » a seconda del tuo provider cloud. Ciò evita i ritardi causati dai download di file su richiesta.
• Mantieni la struttura delle cartelle poco profonda. Evita le directory profondamente annidate — un layout piatto migliora l'affidabilità della sincronizzazione su tutti i provider.
• Verifica lo stato di sincronizzazione prima di chiudere il tuo Mac. Cerca le icone di sincronizzazione in corso nel Finder o nella barra dei menu. Lo spegnimento a metà della sincronizzazione può lasciare file parziali che confondono i collaboratori.
• Mantieni l'archiviazione libera. Mantieni almeno il 10–15% di spazio libero sul tuo Mac e almeno il 20% di archiviazione cloud libera. L'archiviazione bassa può arrestare la sincronizzazione o attivare la rimozione dei file.
• Utilizza lo stesso provider cloud in tutto il team. Mescolare i provider (ad esempio una persona su iCloud, un'altra su Dropbox) richiede che ogni persona abbia la propria copia — non si sincronizzeranno tra loro.

Risoluzione dei problemi

• I cambiamenti non appaiono: Verifica che il tuo provider cloud si stia sincronizzando attivamente. Cerca le icone dello stato di sincronizzazione nel Finder o nell'icona della barra dei menu del provider cloud. Kanban Pro si aggiorna in pochi secondi dal rilevamento di un cambiamento di file — se il file non è ancora stato sincronizzato, l'app non può vederlo.
• Ticket bloccato come bloccato: Vedi la sezione sui blocchi non aggiornati sopra. Puoi forzare lo sblocco dall'app (per i blocchi più vecchi di 24 ore) o eliminare manualmente il file di blocco in .kanban/locks/.
• Ticket mancanti dopo la sincronizzazione: Alcuni provider cloud ritardano la sincronizzazione dei nuovi file. Aspetta un momento e verifica lo stato di sincronizzazione del tuo provider. Se il problema persiste, verifica che la cartella sia configurata per sincronizzare non in linea. Su iCloud Drive, verifica che i file non siano stati sostituiti da file segnaposto .icloud.
• Caricamento iniziale lento: Se il tuo provider cloud trasmette i file su richiesta, il primo caricamento potrebbe richiedere più tempo durante lo scaricamento dei file. Passa alla modalità non in linea o specchio per le migliori prestazioni.
• Sincronizzazione messa in pausa inaspettatamente: Alcuni provider cloud mettono in pausa la sincronizzazione quando il tuo Mac funziona con batteria o ha poco spazio su disco. Verifica l'icona della barra dei menu del tuo provider per gli indicatori di pausa e riprendi la sincronizzazione se necessario.
• File di copia conflittuale che appaiono: Se vedi file denominati con « copia conflittuale » nel Finder, probabilmente due persone hanno modificato lo stesso file non in linea. Apri entrambi i file per confrontare, mantieni la versione corretta ed elimina la copia conflittuale.