Sincronização na nuvem

Como funciona a sincronização na nuvem

Kanban Pro é uma aplicação local-first. Cada projeto é uma pasta no seu sistema de ficheiros contendo ficheiros de ticket Markdown e um directório de configuração .kanban/. Não há contas, sem serviços em nuvem proprietários e sem inscrições.

Para colaborar com outros, simplesmente coloque a sua pasta de projeto dentro de um directó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 propagam-se automaticamente através da sincronização de ficheiros do fornecedor em nuvem.

Configuração de um projeto partilhado

1. Escolha uma pasta na nuvem. Abra o Finder e navegue até ao directório de sincronização do seu fornecedor em 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 seleccione a pasta que acabou de criar. O Kanban Pro inicializará o directório .kanban/ e pode começar a adicionar colunas e tickets.
4. Partilhe a pasta. Utilize os recursos de partilha do seu fornecedor em nuvem para convidar colaboradores. No iCloud Drive, clique com o botão direito na pasta e escolha Partilhar. No Dropbox ou Google Drive, utilize a caixa de diálogo de partilha. No OneDrive, clique com o botão direito e seleccione Partilhar → Partilhar com OneDrive. Cada colaborador deve então abrir a mesma pasta sincronizada na sua própria cópia do Kanban Pro.

Estrutura de pasta recomendada

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

Cada ticket é um ficheiro Markdown simples com YAML frontmatter para metadados (estado, prioridade, atribuído, etiquetas, campos personalizados). Pode ler, editar ou fazer cópia de segurança destes ficheiros com qualquer ferramenta — incluindo agentes de codificação de IA que funcionam directamente com o sistema de ficheiros.

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

O Kanban Pro monitora a pasta do projeto para alterações do sistema de ficheiros utilizando um observador de ficheiro em tempo real. Quando um colaborador guarda um ticket ou actualiza a configuração do quadro, a alteração é detectada em segundos e a interface do utilizador é actualizada automaticamente.

Como os conflitos são evitados

• Bloqueio de tickets: Quando abre um ticket para edição, o Kanban Pro cria um pequeno ficheiro de bloqueio dentro de .kanban/locks/. Outros utilizadores veem o ticket como bloqueado e não podem sobrescrever as suas alterações. Os ficheiros de bloqueio são sincronizados através do seu fornecedor em nuvem para que todos os colaboradores vejam o mesmo estado de bloqueio.
• Escritas atómicas: Cada ticket é um ficheiro Markdown único. O Kanban Pro escreve primeiro num ficheiro temporário e depois o renomeia — evitando actualizações parciais mesmo que o fornecedor em nuvem sincronize no meio da escrita.
• Detecção de conclusão de escrita: O Kanban Pro aguarda que os ficheiros se estabilizem (2 segundos para tickets, 1 segundo para configuração do quadro) antes de os ler. Isto garante que a sincronização em nuvem tenha terminado de escrever antes que a aplicação processe a alteração.
• Última escrita ganha 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 utilizadores alterarem as configurações do quadro simultaneamente, a última escrita ganha — mas isto é raro na prática, pois a configuração do quadro muda raramente.

Compreensão de ficheiros de bloqueio

O directório .kanban/locks/ contém ficheiros de bloqueio temporários que indicam quais tickets estão a ser editados e por quem. Cada ficheiro de bloqueio é um pequeno documento JSON:

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

Os ficheiros de bloqueio são criados quando um ticket é aberto para edição e removidos quando o editor é fechado. Eles permitem que o Kanban Pro mostre um indicador visual em tickets bloqueados para que os colaboradores saibam que alguém está a trabalhar neles.

Resolução de bloqueios obsoletos

Se o Kanban Pro falhar ou um dispositivo ficar offline, um ficheiro de bloqueio pode permanecer sem ser limpo. Isto é chamado um bloqueio obsoleto.

O Kanban Pro também detecta bloqueios com mais de 24 horas e os marca como potencialmente obsoletos na interface do utilizador, dando-lhe a opção de desbloquear à força directamente da aplicação.

Notas sobre fornecedores em nuvem

Melhores práticas

• Mantenha as pastas do projecto disponíveis offline. Marque a sua pasta de projecto como « Disponível offline », « Ficheiros espelhados », « Manter sempre neste dispositivo » ou « Manter descarregado » dependendo do seu fornecedor em nuvem. Isto evita atrasos causados por descarregamentos de ficheiro sob demanda.
• Mantenha a estrutura de pasta rasa. Evite directórios profundamente aninhados — um layout plano melhora a fiabilidade da sincronização em todos os fornecedores.
• Verifique o estado de sincronização antes de fechar o seu Mac. Procure ícones de sincronização em progresso no Finder ou na barra de menus. Desligar no meio da sincronização pode deixar ficheiros 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 activar a remoção de ficheiros.
• Utilize o mesmo fornecedor em nuvem em toda a equipa. Misturar fornecedores (por exemplo, uma pessoa no iCloud, outra no Dropbox) requer que cada pessoa tenha a sua própria cópia — não serão sincronizadas uma com a outra.

Resolução de problemas

• As alterações não aparecem: Verifique se o seu fornecedor em nuvem está a sincronizar activamente. Procure ícones de estado de sincronização no Finder ou no ícone da barra de menus do fornecedor em nuvem. O Kanban Pro é actualizado em segundos da detecção de uma alteração de ficheiro — se o ficheiro ainda não foi sincronizado, a aplicação não consegue vê-lo.
• Ticket preso como bloqueado: Veja a secção de bloqueios obsoletos acima. Pode desbloquear à força da aplicação (para bloqueios com mais de 24 horas) ou eliminar manualmente o ficheiro de bloqueio em .kanban/locks/.
• Tickets desaparecidos após sincronização: Alguns fornecedores em nuvem atrasam a sincronização de novos ficheiros. Aguarde um pouco e verifique o estado de sincronização do seu fornecedor. Se o problema persistir, verifique se a pasta está definida para sincronizar offline. No iCloud Drive, verifique se os ficheiros não foram substituídos por ficheiros de espaço reservado .icloud.
• Carregamento inicial lento: Se o seu fornecedor em nuvem transmite ficheiros sob demanda, o carregamento inicial pode levar mais tempo conforme os ficheiros são descarregados. Mude para modo offline ou espelhado para melhor desempenho.
• Sincronização pausada inesperadamente: Alguns fornecedores em nuvem pausam a sincronização quando o seu Mac está a funcionar com bateria ou tem pouco espaço em disco. Verifique o ícone da barra de menus do seu fornecedor para indicadores de pausa e retome a sincronização se necessário.
• Ficheiros de cópia conflitante a aparecer: Se vir ficheiros denominados com « cópia conflitante » no Finder, provavelmente duas pessoas editaram o mesmo ficheiro offline. Abra ambos os ficheiros para comparar, mantenha a versão correcta e elimine a cópia conflitante.