Sincronização em nuvem

Como a sincronização em nuvem funciona

Kanban Pro é um aplicativo local-first. Cada projeto é uma pasta no seu sistema de arquivos contendo arquivos de tíquete Markdown e um diretório de configuração .kanban/. Não há contas, sem serviços de nuvem proprietários e sem inscrições.

Para colaborar com outros, simplesmente coloque sua pasta de projeto dentro de um diretório sincronizado pela nuvem — iCloud Drive, Dropbox, Google Drive, OneDrive ou qualquer unidade de rede. Cada participante abre a mesma pasta no Kanban Pro, e as alterações se propagam automaticamente através da sincronização de arquivos do provedor de nuvem.

Configuração de um projeto compartilhado

1. Escolha uma pasta na nuvem. Abra o Finder e navegue até o diretório de sincronização do seu provedor de nuvem (por exemplo, ~/Library/Mobile Documents/com~apple~CloudDocs/ para iCloud Drive, ~/Dropbox/ para Dropbox, ou a montagem do Google Drive / OneDrive na sua barra lateral do Finder).
2. Crie uma pasta de projeto. Crie uma nova pasta para o seu projeto, por exemplo, Team Board.
3. Abra-a no Kanban Pro. Inicie o Kanban Pro, clique em Abrir pasta e selecione a pasta que acabou de criar. O Kanban Pro inicializará o diretório .kanban/ e você pode começar a adicionar colunas e tíquetes.
4. Compartilhe a pasta. Use os recursos de compartilhamento do seu provedor de nuvem para convidar colaboradores. No iCloud Drive, clique com o botão direito na pasta e escolha Compartilhar. No Dropbox ou Google Drive, use a caixa de diálogo de compartilhamento. No OneDrive, clique com o botão direito e selecione Compartilhar → Compartilhar com OneDrive. Cada colaborador deve então abrir a mesma pasta sincronizada em sua própria cópia do Kanban Pro.

Estrutura de pasta recomendada

Quando o Kanban Pro inicializa um projeto, ele cria a seguinte estrutura dentro da pasta escolhida:

Cada tíquete é um arquivo Markdown simples com YAML frontmatter para metadados (status, prioridade, responsável, tags, campos personalizados). Você pode ler, editar ou fazer backup desses arquivos com qualquer ferramenta — incluindo agentes de codificação de IA que funcionam diretamente com o sistema de arquivos.

Sincronização em tempo real e edição sem conflitos

O Kanban Pro monitora a pasta do projeto para alterações do sistema de arquivos usando um observador de arquivo em tempo real. Quando um colaborador salva um tíquete ou atualiza a configuração do quadro, a alteração é detectada em segundos e a interface do usuário é atualizada automaticamente.

Como os conflitos são evitados

• Bloqueio de tíquetes: Quando você abre um tíquete para edição, o Kanban Pro cria um pequeno arquivo de bloqueio dentro de .kanban/locks/. Outros usuários veem o tíquete como bloqueado e não podem sobrescrever suas alterações. Os arquivos de bloqueio são sincronizados através do seu provedor de nuvem para que todos os colaboradores vejam o mesmo estado de bloqueio.
• Gravações atômicas: Cada tíquete é um arquivo Markdown único. O Kanban Pro escreve primeiro em um arquivo temporário e depois o renomeia — evitando atualizações parciais mesmo que o provedor de nuvem sincronize no meio da gravação.
• Detecção de conclusão de escrita: O Kanban Pro aguarda que os arquivos se estabilizem (2 segundos para tíquetes, 1 segundo para configuração do quadro) antes de lê-los. Isso garante que a sincronização em nuvem tenha terminado de gravar antes que o aplicativo processe a alteração.
• Última gravação vence para configuração do quadro: A ordem das colunas, as configurações e as definições de campos personalizados são armazenadas em board.json. Se dois usuários alterarem as configurações do quadro simultaneamente, a última gravação vence — mas isso é raro na prática, pois a configuração do quadro muda pouco frequentemente.

Compreendendo arquivos de bloqueio

O diretório .kanban/locks/ contém arquivos de bloqueio temporários que indicam quais tíquetes estão sendo editados e por quem. Cada arquivo de bloqueio é um pequeno documento JSON:

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

Os arquivos de bloqueio são criados quando um tíquete é aberto para edição e removidos quando o editor é fechado. Eles permitem que o Kanban Pro mostre um indicador visual em tíquetes bloqueados para que os colaboradores saibam que alguém está trabalhando neles.

Resolvendo bloqueios obsoletos

Se o Kanban Pro travar ou um dispositivo ficar offline, um arquivo de bloqueio pode permanecer sem ser limpo. Isso é chamado de bloqueio obsoleto.

O Kanban Pro também detecta bloqueios com mais de 24 horas e os marca como potencialmente obsoletos na interface do usuário, dando-lhe a opção de desbloquear à força diretamente do aplicativo.

Notas sobre provedores de nuvem

Melhores práticas

• Mantenha as pastas do projeto disponíveis offline. Marque sua pasta de projeto como « Disponível offline », « Arquivos espelhados », « Manter sempre neste dispositivo » ou « Manter baixado » dependendo do seu provedor de nuvem. Isso evita atrasos causados por downloads de arquivo sob demanda.
• Mantenha a estrutura de pastas rasa. Evite diretórios profundamente aninhados — um layout plano melhora a confiabilidade da sincronização em todos os provedores.
• Verifique o status de sincronização antes de fechar seu Mac. Procure ícones de sincronização em progresso no Finder ou na barra de menus. Desligar no meio da sincronização pode deixar arquivos parciais que confundem os colaboradores.
• Manter armazenamento livre. Mantenha pelo menos 10–15% de espaço livre no seu Mac e pelo menos 20% de armazenamento em nuvem livre. O armazenamento baixo pode interromper a sincronização ou ativar a remoção de arquivos.
• Use o mesmo provedor de nuvem em toda a equipe. Misturar provedores (por exemplo, uma pessoa no iCloud, outra no Dropbox) requer que cada pessoa tenha sua própria cópia — elas não serão sincronizadas uma com a outra.

Resolução de problemas

• As alterações não aparecem: Verifique se seu provedor de nuvem está sincronizando ativamente. Procure ícones de status de sincronização no Finder ou no ícone da barra de menus do provedor de nuvem. O Kanban Pro é atualizado em segundos da detecção de uma alteração de arquivo — se o arquivo ainda não foi sincronizado, o aplicativo não consegue vê-lo.
• Tíquete preso como bloqueado: Veja a seção de bloqueios obsoletos acima. Você pode desbloquear à força do aplicativo (para bloqueios com mais de 24 horas) ou excluir manualmente o arquivo de bloqueio em .kanban/locks/.
• Tíquetes desaparecidos após sincronização: Alguns provedores de nuvem atrasam a sincronização de novos arquivos. Aguarde um pouco e verifique o status de sincronização do seu provedor. Se o problema persistir, verifique se a pasta está definida para sincronizar offline. No iCloud Drive, verifique se os arquivos não foram substituídos por arquivos de espaço reservado .icloud.
• Carregamento inicial lento: Se seu provedor de nuvem transmite arquivos sob demanda, o carregamento inicial pode levar mais tempo conforme os arquivos são baixados. Mude para modo offline ou espelhado para melhor desempenho.
• Sincronização pausada inesperadamente: Alguns provedores de nuvem pausam a sincronização quando seu Mac está funcionando com bateria ou tem pouco espaço em disco. Verifique o ícone da barra de menus do seu provedor para indicadores de pausa e retome a sincronização se necessário.
• Arquivos de cópia conflitante aparecendo: Se você vir arquivos denominados com « cópia conflitante » no Finder, provavelmente duas pessoas editaram o mesmo arquivo offline. Abra ambos os arquivos para comparar, mantenha a versão correta e exclua a cópia conflitante.